HPE Shadowbase Programming
Manual
Abstract
This manual covers the various aspects of the HPE ShadowbaseTM for
NonStop and Other Servers user exit features and data mapping facility.
The HPE NonStop Shadowbase and Other Servers software provides
multiple programmatic entry points into the replication engine in order to
enable customers to either transform data on the fly or make business
decisions based upon data content as it flows through the replication
stream, if required.
Product Version
HPE Shadowbase Version 6.320\T1122H06^AAG
Supported Release Version Updates (RVUs)
This manual applies to all currently supported versions as described by the
Shadowbase Supported Versions Cross-Reference, unless otherwise noted by a
superseding document. Alternatively, visit the http://www.ShadowbaseSoftware.com
web site for the list of supported platforms and databases.
Part Number
Published
785431-007
March 2017
Document History
Part Number
Product Version
Published
785431-007
785431-006
785431-005
785431-004
785431-003
785431-002
785431-001
6.320/T1122H06^AAG
6.220/T1124-T1130^AAB
6.220/T1122H06^AAC
6.200/T1122H06^AAB
6.200/T1122H06^AAB
6.101/T1122H06^AAA
6.100
March 2017
June 2016
April 2016
March 2015
February 2015
November 2014
August 2014
Legal Notices
© Copyright 2017 Hewlett-Packard Enterprise Development Company, L.P.
Legal Notice
Confidential Computer Software. Valid license from HPE required for possession, use or
copying.
Consistent with FAR12.211 AND 12.212, Commercial Computer Software, Computer Software
Documentation, and Technical Data for Commercial Items are licensed to the U.S.
Government under vendor’s standard commercial license.
The information contained herein is subject to change without notice. The only warranties for
HPE products and services are set forth in the express warranty statements accompanying
such products and services or as specified in the applicable HPE license. Nothing herein
should be construed as constituting an additional warranty. HPE shall not be liable for
technical or editorial errors or omissions contained herein.
Export of the information contained in this publication may require authorization from the U.S.
Department of Commerce.
Microsoft, Windows, and Windows NT are U.S. registered trademarks of Microsoft Corporation
Intel, Pentium, and Celeron are trademarks or registered trademarks of Intel Corporation or its
subsidiaries in the United States and other countries.
Java is a registered trademark of Oracle and/or its affiliates.
All other trademarks and registered trademarks are acknowledged and are the property of
their respective companies.
HPE Shadowbase Programming Manual
Legal Notices ....................................................................................................... iii
What’s New In This Manual ....................................................................................
Notation Conventions............................................................................................ ii
Introduction ........................................................................................................... 2
Overview .................................................................................................... 2
System Requirements ................................................................................ 2
Fuzzy Replication ....................................................................................... 3
Do I Need a User Exit? .............................................................................. 4
Source-Target Platform Relationship........................................................ 5
Source-Target File/Table Relationship ..................................................... 5
Source-Target Record/Row Relationship ................................................. 6
Source-Target Field/Column Relationship ................................................ 8
Summary of When User Exits/Data Maps are NOT Needed .................... 9
User Exits vs. Data Maps ......................................................................... 9
Data Type Comparisons .......................................................................... 11
User Exits ........................................................................................................... 12
Overview .................................................................................................. 12
Best Practices for HPE NonStop Shadowbase User Exits ....................... 13
Creating a User Exit ................................................................................. 22
Step #1: Planning User Exit Processing and Designing the User Exit
Program ......................................................................................... 23
Processing Phases ................................................................................ 24
User Exit Entry Points ............................................................................ 25
User Exit Exception Entry Points ............................................................ 44
User Exit Context Checking ................................................................... 46
HPE NonStop Shadowbase User Exit Processing.................................. 48
HPE Shadowbase Other Servers User Exit Processing ......................... 52
Step #2: Coding the Program .................................................................. 59
SBCLEARUSRXCONTEXT Function ..................................................... 60
SBBEGINDDL and SBENDDDL Functions............................................. 61
SBDIDRESOLVELOCKS Function ......................................................... 63
SBCLOSE Functions .............................................................................. 64
SBGET Functions .................................................................................. 66
SBIS Functions .................................................................................... 135
SBLOG Functions ................................................................................ 154
SBNOTIFYUSRXKEYS Function ......................................................... 157
SBPUT Functions................................................................................. 159
SBRELATIVEOFFSET Function .......................................................... 174
SBREMOVECOLUMN Function ........................................................... 176
SBREPORTCOLLISION Function ........................................................ 177
SBRESOLVELOCKS Function ............................................................. 180
HPE Shadowbase Programming Manual—785431-007
i
SBSET Functions ................................................................................. 181
SBWARNINGSON Function ................................................................. 202
SBTRANSACTION Functions .............................................................. 203
Step #3: Compiling and Binding/Linking User Exits .............................. 209
Compiling and Binding User Exits in the NonStop Environment ........... 210
Compiling and Linking User Exits in the Other Servers Environment.... 213
Step #4: Configuring HPE Shadowbase Use of the User Exit ............... 232
Configuring HPE Shadowbase Use of User Exits in the NonStop
Environment ............................................................................. 232
Configuring HPE Shadowbase Use of User Exits in the Other Servers
Environment ............................................................................. 233
Step #5: Testing and Debugging the User Exit ..................................... 234
Preparing User Exit Code for sbdocrd .................................................... 235
DOC Processing Considerations .......................................................... 235
Modifying sbdocrd ................................................................................ 237
Compiling sbdocrd ............................................................................... 241
Data Mapping ................................................................................................... 242
Overview ................................................................................................ 242
Implementing the Data Mapping Facility ................................................ 242
Step #1: Planning for Data Mapping and Designing the shaddbs File .. 242
Step #2: Scripting the shaddbs File ....................................................... 243
Shaddbs File Syntax ............................................................................ 243
[DBS+] Command ................................................................................ 244
[DBS+] Command for NonStop (v5.001 and newer) ............................. 245
[NAME+] Command ............................................................................. 247
[OP-] Command ................................................................................... 247
[OP+] Command .................................................................................. 248
[WHERECLAUSE-] Command ............................................................. 249
[FLD-] Command.................................................................................. 249
[FLD+] Command ................................................................................. 250
[FLD++] Command............................................................................... 252
[FLD+]/[FLD++] using Transform Specification syntax.......................... 252
[SYSTEM+] Command ......................................................................... 256
[SYSTEM++] Command ....................................................................... 256
Step #3: Configuring HPE Shadowbase for Use of the shaddbs.ini File257
Invoking the shaddbs File..................................................................... 257
Setting the Location of the shaddbs File ............................................... 258
Configuring for the [SYSTEM+] Command ........................................... 258
Enabling User Exit Diagnostics ............................................................ 259
Step #4: Testing and Debugging the shaddbs.ini File ........................... 260
Appendix A – User Exit Supporting Files .......................................................... 261
Enhanced User Exit Processing ........................................................... 262
Appendix B – User Exit Samples ...................................................................... 264
Overview ................................................................................................ 264
COBOL Samples.................................................................................... 264
C Samples.............................................................................................. 265
HPE Shadowbase Programming Manual—785431-007
ii
Appendix C – Data Mapping Examples ............................................................ 268
Other Servers Mapping Command File (shaddbs.ini) Example.............. 268
NonStop Mapping Command File (shaddbs) Example .......................... 269
Converting DELETES to Logical DELETES ........................................... 270
Preventing a Table from Being Replicated ............................................. 271
Converting Date Based on CASE .......................................................... 272
Appendix D – Eliminating Need to Recompile COBOL User Exits .................... 274
Description of Procedure ........................................................................ 274
Appendix E – Enscribe QUEUE file Processing ................................................ 280
Enscribe QUEUE File Background ......................................................... 280
Shadowbase Support for Enscribe QUEUE Files ................................... 282
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File
Target (AUDCONSQ) ....................................................................................... 283
Introduction ............................................................................................ 283
AUDCONSQ User Exit Processing ........................................................ 284
Sample DBS Object Definitions.............................................................. 289
Mapping File Definition ........................................................................... 291
EMS Messages ...................................................................................... 291
Preparing AUDCONSQ For Use ............................................................ 310
Replication Fail-Over .............................................................................. 310
HPE Shadowbase Programming Manual—785431-007
iii
Table of Figures
Figure 1 - Fuzzy Replication ............................................................................................ 3
Figure 2 - User Exit Entry Points ................................................................................... 26
Figure 3 - USRXINIT Processing ................................................................................... 27
Figure 4 - USRXEXCEPTIONINIT Processing .............................................................. 30
Figure 5 - USRXROLL Processing ................................................................................ 32
Figure 6 - USRXSTART Processing .............................................................................. 34
Figure 7 - USRXPROCESS Processing ........................................................................ 37
Figure 8 - USRXAFTERPROCESS Processing............................................................. 43
Figure 9 - USRXEXCEPTION Processing ..................................................................... 45
Figure 10 - HPE NonStop Shadowbase User Exit Processing ....................................... 49
Figure 11 - HPE Shadowbase Other Servers User Exit Processing .............................. 52
HPE Shadowbase Programming Manual—785431-007
iv
What’s New In This Manual

6.320/T1122H06^AAG
The first phase of Shadowbase Synchronous Replication, Shadowbase
NonStop ZDL®, is now available for homogenous, unidirectional Enscribe
and SQL/MP replication over Expand. Shadowbase NonStop ZDL® is
available as a separately licensable product released upon controlled
availability. For further details, see the HPE Shadowbase Synchronous
Replication Manual
Added comment for varchar schema when using SBPUTCOLUMN the len
field must be 0 in section SBPUT Functions
Embellished [FLD+] Command section to better describe dependencies on
padding or not padding with spaces when using in FLD+ in HPNS DBS
Mapping example
Added valid OP codes for EVENT-ID/event_id to subsection
SBGETUSRXPROCESSINFO of SBGET Functions

6.220/T1124-T1131^AAB
Added comment regarding Release Option Support for OSS under section
Step #3: Compiling and Binding/Linking User Exits
Replaced corrupt graphic in Figure 9 in section User Exit Exception Entry
Points

6.220/T1122H06^AAC
Added new parameter SBGETSRCFILEINFO to section SBGET Functions
section. This parameter returns the source file information to the USEREXIT
space
Added section Appendix F – Enscribe QUEUE File Support Using a Keyed Or
Queue File Target (AUDCONSQ) for new algorithm for replication Enscribe
Queue files
Removed most of section Appendix E – Enscribe QUEUE file Processing as
previous bullet new section supersedes this old method for replicating
Enscribe QUEUE files
Added argument to SBREPORTCOLLISION Function API. Was missing in
documentation
HPE Shadowbase Programming Manual—785431-006

6.200/T1122H06^AAB
Amended ‘Supported RVUs’ on title page for L-Series L15.02 and later
Corrected spelling errors in ‘Line Spacing’ section of Notation Conventions
Support for the new HPE NonStop x86 architecture has been added. All
natively compiled objects and executables have been rebuilt targeting the
new x86 architecture. The compile, link, and installation scripts have been
updated to use the new x86-based development tools. Basic Shadowbase
operations remain the same across the H06 and L15 operating systems

6.101/T1122H06^AAA
Updated footers incorrectly labelled as ‘AUTOLOADER Manual’
Added Write-Up for Enscribe Queue file Processing as an appendix to
Document

6.100/T1122H06 Original HPE Release
HPE Shadowbase Programming Manual—785431-007
i
Notation Conventions
Hypertext Links
Blue underline is used to indicate a hypertext link within text. By clicking a
passage of text with a blue underline, you are taken to the location described.
For example:
To preserve the modification timestamp, see….on page ___.
General Syntax Notation
The following list summarizes the conventions for syntax notation and
presentation in the HPE Shadowbase manual collection.
UPPERCASE LETTERS. Uppercase letters indicate keywords and reserved
words; enter these items exactly as shown. Items not enclosed in brackets
are required For example:
PARAM SBCMDFILE
lowercase letters: Represent variable entries to be supplied by user. For
example:
<file name>
Computer type. Computer type letters within text indicate C and Open
System Services (OSS) keywords and reserved words. Type these items
exactly as show. Items not enclosed in brackets are required. For example
RUN LOADHELP
Italic computer type. Italic computer type letters within text indicate C and
Open System Services (OSS) variable items that you supply. Items not
enclosed in brackets are not required. For example:
pathname
Brackets [ ]: Enclose optional syntax. A vertically aligned group of items
enclosed in brackets represents a list of selections from which one, or
none, can be chosen. For example:
CKPTFNAME [\system.] [$volume.] [subvolume.] filename
Braces { }: Enclose required syntax. A vertically aligned group of items
enclosed in braces represents a list of selections from which exactly one
must be chosen. For example:
CHECKCONFIG
{ ON }
{ OFF }
Ellipses …: The enclosed syntax can be repeated a number of times. For
example:
KEYVALUESTART < <string> | <byte> > [, <string> |
<byte> ] ...
Punctuation: All punctuation and symbols other than those described above
must be entered precisely as show For example:
error := NEXTFILENAME ( file-name ) ;
LISTOPENS SU $process-name. #su-name
Quotation marks around a symbol such as a bracket or brace indicate the
symbol is a required character that you must type as shown. For example:
“{“ repetition-constant-list “}”
HPE Shadowbase Programming Manual—785431-007
ii
Item Spacing. Spaces shown between items are required unless one of the
items is a punctuation symbol such as a parenthesis or a comma. For
example:
CALL STEPMOM ( process-id ) ;
If there is no space between two items, spaces are not permitted. In this
example, no spaces are permitted between the period and any other
items:
$process-name.#su-name
Line Spacing. If the syntax of a command is too long to fit on a single line,
each continuation line is indented three spaces and is separated from the
preceding line by a blank line this spacing distinguishes items in a
continuation line from items in a vertical list of selections. For example:
ALTER [ / OUT file-spec / ] LINE
[ , attribute-spec ] …
HPE Shadowbase Programming Manual—785431-007
iii
HP Shadowbase Programming Manual—785431-006
1
Introduction
Overview
Introduction
Overview
This manual covers the various aspects of the HPE Shadowbase user
exit feature and data mapping facility. System requirements, user exit
preparation, user exit Application Program Interfaces (APIs), testing,
debugging, and configuration of HPE Shadowbase to incorporate the
user exit routines are discussed. How to determine if you need a user
exit is discussed in detail in the HPE NonStop Shadowbase
Installation and Planning Manual. You should carefully review that
section before formulating a user exit routine because HPE
Shadowbase may accommodate your needs without one.
This manual is written primarily from the perspective of an intermediate
level programmer with references to COBOL or C programs.
The user exit feature and data mapping facility of HPE Shadowbase
enable the user to generate data within the target database that is
formatted differently from the source data. The HPE Shadowbase
NonStop Consumer and HPE Shadowbase Shadowbase Other
Servers processes handle some dissimilarity of the source and target
schema inherently in their default processing mode (e.g., subtle syntax
variances).
However, the user exit APIs enable the developer to customize their
own transformation environment, and the data mapping facility
provides a transformation capability to the developer/DBA at the
command interpreter (CI) level.
System Requirements
In addition to the standard system requirements, outlined in the HPE
NonStop Shadowbase Installation and Planning Manual, and the
HPE Shadowbase Other Servers Target Installation Manual, you
will also need the following:


a compiler (C, COBOL, TAL, or other supported language,
depending upon the language you intended to use to code your
user exit routine(s))
a bind/make utility for compiling, binding and linking your user exit
code to the appropriate HPE Shadowbase process
HPE Shadowbase Programming Manual—785431-007
2
Introduction
Fuzzy Replication
Fuzzy Replication
In many instances, the target database must look quite different than
the source. The user exit APIs and Data Mapping Facility give you the
power to change the type and size of data fields, alter key structures,
control replication of entry sequenced file updates and deletes, control
application of SQL collations, replicate one record/row to many
records/rows in one or many target files/tables, combine data from
multiple files/tables into one file/table, etc. Because your custom code
becomes part of the HPE NonStop Shadowbase Consumer, you retain
the benefits of monitoring, controlling and protection provided with the
standard HPE Shadowbase product.
The following figure identifies the locations within the HPE
Shadowbase replication environment where the user exit API is
available for processing.
Figure 1 - Fuzzy Replication
Please note in the above diagram that the USER EXIT space is unique
to the process it is bound to. Multiple processes within the same
replication stream do not share the same USER EXIT space.
The Data Mapping facility of HPE Shadowbase (DBS Mapping)
enables the user to apply standard SQL command line syntax directly
to the replication stream data. Essentially any function you can enter at
a SQLCI, SQLPLUS, or ISQL command line may be applied to the
replication data stream through this utility. While the DBS Mapping
HPE Shadowbase Programming Manual—785431-007
3
Introduction
Do I Need a User Exit?
capability provides a quick and effective mechanism for transforming
data on the fly, there is a significant cost associated with transforming
data in this manner. Due to this constraint, consider very carefully
when choosing to implement DBS Mapping strategies over user exit
development.
If you reviewed either the HPE Shadowbase for NonStop
Installation and Planning Manual, or the HPE Shadowbase Other
Servers Target Installation Manual and are certain you need a user
exit routine to achieve the desired structure of the target database, this
manual shall provide you with the details for developing your user exit
code. It is written for systems analysts, programmers, and database
administrators who will be designing and coding transformation logic
via user exit routines for their replication threads. Before preparing
your user exit, it is highly recommended that you review this document
in entirety, in addition to obtaining a sound and thorough knowledge of
the HPE Shadowbase replication process.
Do I Need a User Exit?
There are many utilities provided by HPE Shadowbase right out of the
box. Converting UPDATES to INSERTS when the target row/record is
not found, or INSERTS to UPDATES when the target row/record
already exists are two such abilities. Additionally, certain capabilities
now exist whereby HPE Shadowbase servers are now able to
transform partial updates into FULL inserts, with NULL embedded
data, provided the target table (if SQL) is defined with NULL defaults.
Sometimes determining IF a user exit is needed is not as significant as
determining WHERE to put the code. In heterogeneous environments,
for example, user exit processing may be enabled in many different
locations. When this condition is evident, it is up to the developer to
determine where their strength lies (in developers and system
knowledge/expertise), where the most efficient process (location) to
perform the user exit processing is, and so forth.
Frequently, therefore, it generally depends on the strengths and
weaknesses of the application environment, the developers’ abilities,
and the overall familiarity with HPE Shadowbase/replication, and the
replication stream data when determining where to develop user exit
code.
If you are replicating data from the source to the target without
condition or transformation, you do not need a user exit/data map. If
you need to replicate data conditionally, you need a user exit routine.
If you need to transform source data to attain your target structure, you
HPE Shadowbase Programming Manual—785431-007
4
Introduction
Do I Need a User Exit?
will have to analyze the type and degree of transformation required
before you can decide whether you need a user exit/data map or not.
To do this you should look at four aspects of the source-target
relationship:




Platform
File/Table
Record/Row
Field/Column
Source-Target Platform Relationship
. In examining the source-target platform relationship, you need to
look at the platform on which the target database will reside. In
general, HPE Shadowbase can replicate data from the source formats
to the target formats in the following chart. These forms of replication
can also be combined to produce multiple target databases.
Database
Format
Enscribe
SQL/MP
MSSQL Server
Sybase
Oracle
DB2
DOC
MySQL
Source
Target
Y
Y
Y
Y
Y
N
Y
N
Y
Y
Y
Y
Y
Y
Y
Y
If the source and target data will be formatted the same, no user
exit/data map is needed. If the source data needs to be transformed,
you can code a user exit or create a data map that will format the data
in the desired manner before it is applied to the target database. Note
that some source data types are not supported in different target
databases. Please see the HPE Shadowbase Other Servers Target
Configuration and Installation Manual, and the HPE Shadowbase
Other Servers Operations Manual for a detailed discussion of these
differences.
Source-Target File/Table Relationship
. The source-target file/table relationship is the next highest level in
your database hierarchy. You need to look at this relationship for each
file/table you want to replicate.
HPE Shadowbase Programming Manual—785431-007
5
Introduction
Do I Need a User Exit?
One source file/table can be replicated to one or more target
files/tables (a one-to-one or one-to-many file-level relationship).
Depending upon the degree of similarity between the source and
target, you may or may not need a user exit/data map. Look at the
other relationship aspects for further determination.
Data from multiple source files/tables can be replicated to one target
file/table (a many to one file-level relationship). If all the source
files/tables are similar to each other and the target file/table is similar to
the sources, you may not need a user exit/data map. Again, you need
to look at the degree of similarity between the source and target at a
lower level to decide.
If you are combining data from multiple source files/tables that are not
similar to each other into one target (another variation of the many to
one file-level relationship), you need a user exit. If you are combining
data from multiple source files/tables that are not similar to each other
into many targets (a many to many file-level relationship), you need a
user exit.
On NonStop systems, you can change from Enscribe to SQL without
needing a user exit/data map if the source and target are similar (i.e.,
the field/column data types are similar). Look at the other relationship
aspects to see if it is necessary to have a user exit/data map. It is also
possible to go from Enscribe or SQL relative format to SQL keysequenced format without a user exit. If you wish to do this type of
transformation, the target must have a column called SYSKEY that is
the primary key on the file. Replication of entry sequenced files may
also require a user exit.
When replicating Oracle or MSSQL Server source data, you can
replicate to a supported non-Oracle or non-MSSQL Server target
database. In this case, if the source and target are similar, you may
not need user exits/data maps. Look at the other relationship aspects
to see if it is necessary to have a user exit/data map.
Source-Target Record/Row Relationship
. In evaluating the record/row relationship, you need to look at how the
data are stored in the source files/tables and how these records/rows
need to appear in the target(s). If any of the following statements
describe your record/row relationship, you need a user exit:

Records/rows are replicated conditionally (i.e., data filtering needs
to occur).
HPE Shadowbase Programming Manual—785431-007
6
Introduction
Do I Need a User Exit?

One source record/row is replicated to multiple records/rows in
multiple target files/tables (a one-to-many record-level relationship
within a one-to-many file-level relationship). See note below.

One source record/row is replicated to multiple records/rows in one
target file/table (a one-to-many record-level relationship within a
one to one file-level relationship). See note below.
NOTE: One-to-many replication does not require a user exit if
separate threads are configured.

Many records/rows from one source file/table are combined into
one record/row in one target file/table (a many-to-one record-level
relationship within a one-to-one file-level relationship).

Many records/rows from one source file/table are combined into
one record/row and written into many target files/tables (a many-toone record-level relationship within a one-to-many file-level
relationship).

Many records/rows from one source file/table are combined into
different records/rows and written to one target file/table (a manyto-many record-level relationship within a one-to-one file-level
relationship).

Many records/rows from one source file/table are combined into
many records/rows and written into many target files/tables (a
many-to-many record-level relationship within a one-to-many filelevel relationship).

Many records/rows from many source files/tables are combined into
one record/row in one target file/table (a many-to-one record-level
relationship within a many-to-one file-level relationship).

Many records/rows from many source files/tables are combined into
one record/row and written into many target files/tables (a many-toone record-level relationship within a many-to-many file-level
relationship).

Many records/rows from many source files/tables are combined into
different records/rows and written to one target file/table (a manyto-many record-level relationship within a many-to-one file-level
relationship).

Many records/rows from many source files/tables are combined into
many records/rows and written into many target files/tables (a
HPE Shadowbase Programming Manual—785431-007
7
Introduction
Do I Need a User Exit?
many-to-many record-level relationship within a many-to-many filelevel relationship).
The following two cases describe record/row relationships that may or
may not require a user exit. Further analysis of the field/column
relationship is necessary. See the next subsection.

One source record/row is replicated to one target record/row in one
target file/table (a one-to-one record-level relationship within a oneto-one file-level relationship).

One source record/row is replicated to one record/row in multiple
target files/tables (one-to-one record-level relationship within a oneto-many file-level relationship).
Source-Target Field/Column Relationship
. If the source and target(s) are similar, you do not need a user exit or
data map. Similar, in this case, means each target has the same
fields/columns as the source and they are of same name, type and
size. The target fields/columns can be in any order as long as the
primary key of the target matches that of the source.
It is also possible for a target file/table to have more fields/columns
than the source file/table. If the additional fields/columns have default
values or are null'able and those values are appropriate, you do not
need a user exit or data mapping script. If they do not have default
values or need to contain specific data, you will need a user exit or
data mapping script. Target files/tables can also have fewer
fields/columns than the source without requiring a user exit.
If your target design does not fit any of the cases already described or
you are still uncertain, ask the following questions:

Are data to be replicated conditionally?

Do any fields/columns need to contain values that come from
another source record or file?

Are the target field/column names different from the source
field/column names although there is a one to one
correspondence?

Are the target fields/columns of a different data type than the
source?
HPE Shadowbase Programming Manual—785431-007
8
Introduction
Do I Need a User Exit?

Are the target fields/columns a different size than they are in the
source?

Are figures in target being aggregated from changes to the source?
If you answered YES to any of these questions, you need a user exit.
Summary of When User Exits/Data Maps are
NOT Needed
If any of the following describe your plans for using HPE Shadowbase,
you DO NOT need a user exit or data map.

Replicate, without condition, source files/tables to identical target
files/tables.

Replicate, without condition, source files/tables to identical target
files/tables in another database.

Replicate, without condition, one source file/table to one or more
identical target files/tables.

Replicate, without condition, multiple source files/tables to one
target file/table where all sources match target.

Replicate, without condition, one source file/table to one or more
non-identical targets where target and source have the same keys.

Replicate, without condition, one source record/row to one target
record/row in one target file where target and source have the
same keys.
NOTE: Replication of NonStop entry sequenced files may necessitate
the implementation of user exits even if the aforementioned
criteria are met.
User Exits vs. Data Maps
You may have determined at this point that some external data
transformation will be needed for you to achieve your desired target
database structure. The question now is: which do we use, user exit
or data map? Data maps do not allow for all types of transformation
nor do they support conditional replication.
HPE Shadowbase Programming Manual—785431-007
9
Introduction
Do I Need a User Exit?
Below is a sample data mapping script that appends the two digit
century (i.e., 20) to a two digit year field for the target table, TABLE1:
[DBS+]TABLE1
[FLD+]DATE_COL=’20%DATE_COL%’
To accomplish the same thing in a COBOL user exit requires code
similar to:
If USRX-INSERT OF EVENT-ID OF SB-USRXPROCESS-INFO or
USRX-UPDATE OF EVENT-ID OF SB-USRXPROCESS-INFO
Move “DATE_COL” to name-part of colname
Move 6 to image-len
ENTER C "SBGETAFTERCOLUMN" IN USRXLIB USING
COLNAME, ISKEY, IMAGE-LEN, COL-DATA
GIVING RTRN-CD
move MM of COL-DATA to mm of reformat-date
move DD of COL-DATA to dd of reformat-date
move YY of COL-DATA to YEAR of reformat-Date
move 20 to CC of reformat-date
move 0 to IMAGE-LEN
ENTER C "SBPUTCOLUMN" IN USRXLIB USING
colname, IMAGE-LEN, reformat-date
GIVING RTRN-CD
End-if.
ENTER C "SBSETEXECUTE" IN USRXLIB.
HPE Shadowbase Programming Manual—785431-007
10
Introduction
Data Type Comparisons
Data Type Comparisons
Across systems, platforms, and database engines, data types may
have different names or attributes. The following figure illustrates the
different data types across the supported HPE Shadowbase database
platforms. This is an evolving document, and as a result of such, it may
not contain the latest data pertinent to a particular database instance.
To be sure, check the documentation surrounding your database in
question for the actual data type attributes.
NonStop
SQL/MX
CHAR[ACTER](n)
DATETIME
CHAR[ACTER](n) CHAR(n)
TIMESTAMP(year DATE
to second)
DATE
TIME
TIMESTAMP
TIMESTAMP,
TIMESTAMP2
DATE
TIME
TIMESTAMP
INTERVAL
DEC[IMAL](p,s)
DECIMAL(p,s)
FLOAT
FLOAT
REAL
REAL
DOUBLE PRECISION
INT[EGER]
INTERVAL
LARGEINT
NATIONAL
CHAR[ACTER]
VARYING
NCHAR(n)
NUM[ERIC](p,s)
PIC[TURE 9]
PIC[TURE X]
SMALLINT
VARCHAR[ACTER](n)
INT
CHAR(n)
LARGEINT
NVARCHAR(n)
NCHAR[n)
NUM[ERIC](p,s)
PIC[TURE 9]
PIC[TURE X]
NUMERIC(p,s)
VARCHAR(n)
BLOB
Oracle
NUMERIC(p,s)
FLOAT
DOUBLE
PRECISION
INT
CHAR(n)
NCLOB
MSSQL Server
Sybase
CHAR(n)
DATETIME,
DATETIME2
CHAR(n)
DATETIME
TIMESTAMP
TIMESTAMP
DEC[IMAL](p,s)
FLOAT
REAL(n)
DEC[IMAL](p,s)
FLOAT
REAL
INT
CHAR(n)
INT
NVARCHAR(n)
INT
CHAR(n)
NVARCHAR2
NCHAR(n)
NUMERIC(p,s)
DEC[IMAL](p,s)
NCHAR(n)
NUM[ERIC](p,s)
DEC[IMAL](P,S)
CHAR(n)
NUMERIC(p,s)
SMALLINT
LONG,VARCHAR2 VARCHAR(n)
BIT
BFILE
TEXT, IMAGE
BLOB
BINARY(n)
CLOB
LONG RAW
IMAGE,VARBINARY(
n)
MLSLABEL
RAW
IMAGE
ROWID
MONEY
MONEY,SMALLMON
EY
TEXT & IMAGE
TINYINT
NVARCHAR(n)
NCHAR(n)
NUM[ERIC](p,s)
DEC[IMAL](P,S)
SMALLINT
VARCHAR(n)
BIT
SMALLDATETIME
SMALLMONEY
TEXT
TINYINT
BIGNUM
HPE Shadowbase Programming Manual—785431-007
11
User Exits
Overview
User Exits
Overview
The User Exit feature of HPE Shadowbase enables you to have a
custom target database(s) that is very different from the source. While
some dissimilarity of the source and target databases is supported in
the basic Consumer, HPE Shadowbase supplies a group of Application
Program Interface (API) calls that allow you, through program code
you write in COBOL, C, (User Exits can sometimes be written in C++
or C# as long as they can be called from a C function and the linker will
link with the HPE Shadowbase base libraries), TAL, or certain other
languages, to thoroughly customize your target database.


On the NonStop, HPE Shadowbase supports both the nonnative compilers (e.g., C, COBOL85, and TAL), as well as the
native compilers (NMC, NMCOBOL, and pTAL) for both the
RISC (e.g., S series) and the Itanium (e.g., H series) NonStop
platforms.
On the Other Servers platforms, HPE Shadowbase supports
any language that can be called from the HPE Shadowbase C
base libraries, as long as the linker can properly link with the
HPE Shadowbase C base libraries. Hence, you can generally
write your user exits in C/C++, Cobol, etc. provided these
compilers/linkers can generate a working executable where the
main function and supporting libraries are C HPE Shadowbase
modules.
APIs give you the power to change the type and size of data fields,
alter key structures, control replication of entry sequenced file updates
and deletes, control application of SQL collations, replicate one
record/row to many records/rows in one or many target files/tables,
combine data from multiple files/tables into one file/table, normalize
non-relational source structures, etc. Because your custom code
becomes part of the HPE Shadowbase Consumer, you retain the
benefits of monitoring, control, and protection that are built into the
product.
This chapter is written for systems analysts/programmers who will be
designing and coding user exit routines. Before preparing your user
exit, it is highly recommended that you read this chapter in its entirety.
Releases of HPE NonStop Shadowbase provide sample C user exit
code in the USRXC file, and sample Cobol user exit code in the
USRXCOB file.
HPE Shadowbase Programming Manual—785431-007
12
User Exits
Best Practices for HPE NonStop Shadowbase User Exits
Best Practices for HPE NonStop
Shadowbase User Exits
Prior to having you dive into the details for coding user exits, as
mentioned in the above ‘Introduction’ section, below are 14 points
considered the ‘Best Practices’ to help you in developing NonStop
User Exits, which have been gleaned over time from helping our
customers.
1. Determine if you ‘Really Need User Exits’ at all, and ‘Where to
Enable Them’.
Since User Exits add processing effort for the events that they
process, avoid them if possible (see comments in the Summary of
When User Exits/Data Maps are NOT Needed section for whether
this is feasible for your environment).
Determine if you want to use coded user exits (more powerful), or
the HPE Shadowbase data mapping facility (easier to use, no
coding required). However, the HPE Shadowbase coded user exits
are generally significantly more efficient than the data mapping
facility is.
User exits are enabled in a NonStop configuration via the DBS
parameter USEREXITID, and for the Other Servers via the
shadparm.ini parameter SHAD_USRX_PROCESSING=1.
Develop your user exits on either the source or target side. This is
generally a customer business decision (e.g., where the experience
is). However, it is generally best to have the filtering logic on the
sending side.
2. Develop your NonStop User Exits in Native Mode, and Use Native
Processes Whenever Possible.
For NonStop user exits, use a native development environment
wherever possible, and build native Consumers. Native Consumer
(CONS) programs are significantly faster and less CPU-intensive
than non-native programs when performing the same task.
Depending on the nature of the work being done in the user exit,
we have noticed CPU usage differences of several hundred percent
when native vs. non-native user exits are compared.
HPE Shadowbase Programming Manual—785431-007
13
User Exits
Best Practices for HPE NonStop Shadowbase User Exits
If you must use non-native user exits, be sure to AXCEL (S series)
or OCA (H series) the Consumer object.
3. Leverage the HPE Shadowbase User Exit Entry Points.
The following are the user exit entry points, with a few comments
about each:







USRXINIT – Called once at HPE Shadowbase process startup.
Do process initialization work in here. Consider opening
files/tables here and avoiding opening/closing files/tables as
events are processed (if appropriate).
USRXEXCEPTIONINIT – Called at HPE Shadowbase process
startup for allowing certain error condition overrides (e.g., what
to do when bad data for a column is detected).
USRXROLL – Can be called to request a DOC roll in a
DOC/TRS environment, (in the Other Servers environment only)
USRXSTART – Called once per DBS. Do anything specific to
this DBS.
USRXPROCESS – Called once per replication event before it is
processed (e.g., insert, update, delete, commit, abort, etc.).
USRXAFTERPROCESS – Called once per replication event
after it is processed (e.g., insert, update, delete, commit, abort,
etc.) (in the Other Servers environment only).
USRXEXCEPTION – Called for the processing exceptions
enabled via the USRXEXCEPTIONINIT call.
4. Test all User Exit API Return Codes!
Make sure that you have code to test the user exit API return
codes. Your code should have exception logic handling for all
abnormal return codes, and should generally log error messages
when it detects abnormal situations via the SBLOGEVENT API call.
5. Logging Messages from User Exits.
Use the SBLOGEVENT API to log errors from the user exits into
EMS, when logging messages from user exits. Generally do not
open the home terminal directly (or indirectly via a C language
printf() or a Cobol DISPLAY statement) as this can cause the HPE
Shadowbase programs to run very slowly or to fail (the home
terminal may no longer exist, may be slow, etc.). In addition to this,
HPE Shadowbase C user exits by default, are compiled with
NOSTDFILES, so the use of printf() and other stdin, stdout and
stderr functions will cause the user exit to trap.
HPE Shadowbase Programming Manual—785431-007
14
User Exits
Best Practices for HPE NonStop Shadowbase User Exits
Also, consider logging unusual (for example unexpected lowvolume) situations as this may indicate a configuration or user exit
coding problem (e.g., the user exit may not be selecting the files or
all the data event types that you expect it to). Keep in mind though
that logging too many messages into EMS can impede the
performance of the HPE Shadowbase processes.
6. Suppressing Insert, Update, or Delete Events
HPE Shadowbase allows you to determine the I/O event types that
it processes – for example, you can decide to suppress any/all of
the insert, update, and/or delete events. These can be configured
in the DBS object (e.g., SET INSERTS OFF).
When set to OFF, the Collector will not forward these events thru
the replication engine, and this can provide some efficiency for
unneeded events.
Note:
HPE Shadowbase will always pass thru the backout
events for transaction I/O, as this is necessary to reverse
an aborted transaction. A user exit should test an event
for SBISUNDO(), and if true, pass that event along (do
not suppress it). Contact HPE Shadowbase support if
you believe you need to individually suppress aborted
events.
It is important to understand that suppressing these non-UNDO
events at the DBS level is generally dangerous, for a variety of
reasons:



Even if you are convinced that your application(s) do not do
certain event types, you should still pass them thru (although
you may want to log them). It may be that you are just
wrong (and a new application does issue the event type you
want to suppress), or it may be that a database operation
(like an online partition split) or the file system may be
issuing those event types on your behalf and they should not
be suppressed.
Online partition operations, such as partition splits, can issue
DELETE and INSERT events.
For unique indices or alternate key files, the file system may
issue “reversing” updates (for an update) or reversing
deletes (for an insert) when the original operation fails due to
a duplicate key condition on the unique index/alternate key
file.
HPE Shadowbase Programming Manual—785431-007
15
User Exits
Best Practices for HPE NonStop Shadowbase User Exits
Hence, even when you believe you need to suppress an event
(e.g., you are maintaining an archive database and don’t want to
apply deletes), you should generally NOT suppress it in the DBS
and carefully review what you need to suppress in a user exit and
in most cases still pass it thru (yet log it for review and possible
refinement of your user exit filtering criteria).
7. Processing the “Before” and “After” Values for Transaction Events.
There is no “before” image for an insert, and there is no “after”
image for a delete. So, by default, HPE Shadowbase processes
the “after” events for inserts and updates, and the “before” events
for deletes.
Do not enable the DBS setting for BEFOREVALUES unless you
really want to process the “before” field/column images for
UPDATE events. Enabling this parameter when not needed
doubles the data that must flow from the Collector to the Consumer
for UPDATE events.
Only use the “get after” (e.g., SBGETAFTERxxx()) API functions for
updates and inserts (deletes do not have an “after” image). Calling
these functions for deletes will slow the HPE Shadowbase
processes and will result in errors being returned.
Only use the “get before” (e.g., SBGETBEFORExxx()) API
functions for deletes and updates and only for updates if the related
DBS object BEFOREVALUES parameter is set to ON (inserts do
not have a “before” image). Calling these functions for inserts will
slow the HPE Shadowbase processes and will result in errors being
returned.
8. Processing Committed and Aborted Transactions and Transaction
Events.
Be aware that your user exit may or may not see aborted
transaction events, depending on the overall Consumer
configuration (the actual rules are complex, but in general the
CONS ABORTTRANS ON, or any of the CONS
RESOLVELOCKSxxx parameters will cause aborted events to be
passed into the Consumer and your user exits will receive them).
In general, always program your user exit to expect aborted
transaction events, and to process and forward them (see below).
Note that all of the insert, update, and delete events can be “DO”
events (events that are committed or before a transaction abort
HPE Shadowbase Programming Manual—785431-007
16
User Exits
Best Practices for HPE NonStop Shadowbase User Exits
occurs), or “UNDO” events for aborted transactions. Use the
SBISUNDO() API call to determine the difference.
You can use the DBS specification INSERTS, UPDATES, or
DELETES ON/OFF to process or suppress these events from being
sent into your user exit. However, even when set to OFF, HPE
Shadowbase will still send the UNDO of these event types, as
these are needed in the target for transactions that abort. In
general, you need to process and forward these UNDO events to
the target and apply them even if you are suppressing the “DO”
insert, update, or delete events.
Note: This is important for NonStop and Other Servers direct writer
targets only, as Other Servers DOC/TRS target
environments will not process aborted transactions.
9. Mapping Source to Target Field/Column Names and Data Types.
Whenever possible, try to use common column/field names
between the SOURCEFILE and TARGETFILE. Otherwise, HPE
Shadowbase (or the user exit) has to map the names and this
consumes additional CPU cycles.
Note: The Enscribe dash (-) will be automatically mapped to/from
the SQL underscore (_) as needed when replicating from
Enscribe to SQL).
Whenever possible, try to use the same data type definitions for
columns/fields between the SOURCEFILE and
TARGETFILE. Otherwise, HPE Shadowbase (or a supplied user
exit) has to convert the data and this consumes additional CPU
cycles
Only use the “put open” API functions if you need to generate freeform type statement content for column/fields that are not defined in
your TARGETFILE, or you do not have a TARGETFILE defined.
Depending upon your final target when replicating to Other Servers
environment target tables (e.g., Oracle tables), it might not be
necessary to use a “dummy” TARGETFILE on a NonStop source.
This is required if any reformatting of the data is necessary. User
exits would otherwise generally be required if the column/field
definitions of the SOURCEFILE don’t match the final Other
Serverstarget table. If a TARGETFILE is not specified because a
user exit is not required, the statements sent to the Other
HPE Shadowbase Programming Manual—785431-007
17
User Exits
Best Practices for HPE NonStop Shadowbase User Exits
Serversenvironment will be built based up the SOURCEFILE
schema (SOURCEREC for Enscribe).
Try to minimize the length of your column/field names if possible.
Replication is more efficient with smaller column/field names.
Code your “gets” and “puts” to use uppercase alphanumeric
characters and underscores (instead of hyphens). The CONS
internal schema definitions for both SQL tables and Enscribe
records are stored internally in uppercase with underscores (not
hyphens). You can then either set the CONS
USEREXITCOLCHECK parameter to OFF or call the
SBSETCHECKOFF API function to turn off the default CONS logic
that up-shifts the names and replaces hyphens with underscores
(by default, the CONS runs with this logic enabled). The CONS
user exit processing overhead can be reduced slightly by running
with this logic disabled.
Whenever possible, code your “gets” in the order in which the
columns/fields exist in the SOURCEFILE schema (i.e., “get” the
columns/fields based on their ordinal position in the schema).
Whenever possible, code your “puts” in the order in which the
columns/fields exist in the TARGETFILE schema (i.e., “put” the
columns/fields based on their ordinal position in the schema).
Only perform “gets”/“puts” for columns/fields that need to be
evaluated, reformatted, or to generate an appropriate target
WHERE clause for updates and deletes. By calling these functions
for columns/fields that are not needed it increases CONS CPU
utilization.
For number fields that contain decimal places, try to maintain the
same number of decimal places in the final target table to eliminate
the need for reformatting through a HPE Shadowbase or a user
exit.
In general, coding user exits to map and transform field/column
data is more efficient than using the HPE Shadowbase data
transformation scripting language.
Make sure that you allocate the appropriate length data area in
your user exits to receive records, columns, and other structures
you retrieve from HPE Shadowbase. Otherwise, unpredictable
results may occur within the CONS process if these boundaries are
overwritten.
HPE Shadowbase Programming Manual—785431-007
18
User Exits
Best Practices for HPE NonStop Shadowbase User Exits
The API functions to “get record” and “put record” for Enscribe
source and/or target files can be very helpful when you are “getting”
and/or “putting” many fields. For example, it is often beneficial to
“get record” to get the entire Enscribe record image, and then
selectively “put” only those fields or columns that you need to
manipulate. A “get record” or a “put record” moves the entire
record in one move statement. So, avoid using the “get record” and
“put record” API functions if you only have a few columns/fields to
evaluate, scrub, or manipulate (especially if the records are larger).
Avoid calling the “get” or “put” API calls for fields/columns that do
not exist in the source or target schema. This can be difficult when
processing audit compressed UPDATEs, so consider turning
AUDIT COMPRESS off for the files or tables being replicated.
Note: Audit compression for Enscribe works differently than it does
for SQL. For Enscribe, the records are viewed by TMF’s
audit compression as a string of bytes, and the audit
compress format uses an offset/length fragment pairing
format.
For SQL/MP, the column boundary is used – if any byte
changes in the column, the entire column appears in the
audit event. However, as of the G06+ operating system, if
the column appears in the program’s UPDATE statement,
that column appears in the audit compressed audit trail
event regardless if the before and after values changed.
Since many SQL/MP programs code their UPDATE
statements to include all columns, using audit compression
may use more CPU and generate larger audit trail events
than if it is turned off for a table.
10. Mapping Source to Target Key Structures
Each record or row updated via the source transaction generates
an event to be sent to the target. In general, the keys between the
source and target files/tables should match. Be careful when they
do not, as incomplete or ambiguous keys at the target may update
or delete far more rows than expected. For example, if you notice
that UPDATE or DELETE statements start “slowing down” as the
target table size increases, check to make sure you have an index
on the target table and that the key being generated (see the
Consumers IOTRACE capability) matches what the actual target
index fields are; otherwise, table scans may be occurring for each
update or delete statement executed.
HPE Shadowbase Programming Manual—785431-007
19
User Exits
Best Practices for HPE NonStop Shadowbase User Exits
Whenever possible, try to use the same key columns/fields for the
TARGETFILE as defined for the SOURCEFILE. Otherwise, HPE
Shadowbase (or the user exit) has to build the new WHERE key
clause and this consumes additional CPU cycles.
To ensure an appropriate where clause for the target update and
delete statements, use the SBNOTIFYUSRXKEYS API function
and do “put where” calls for all columns/fields that you desire to
make up the target where clause.
Note: That if a column is defined as a key column/field in a
TARGETFILE, you must call the “put where” API function,
and not just the “put after” API function.
11. User Exit Processing and Data Normalization
Each database specification (DBS object) having a USEREXITID
parameter associated with a SOURCEFILE will cause HPE
Shadowbase to call the USRXPROCESS function for handling for
each audit trail event that satisfies the SOURCEFILE file/table
selection clause. Unique USEREXITID(s) can define which path
should be taken in the user exit code (for example, call function x()
for user exit id value y, else call function z()).
More specifically, say you have an Enscribe source with several
different record definitions. A field in the record defines which
definition is to be used (e.g., the data content of this field defines
the structure to use when parsing this record). With HPE
Shadowbase, you could define a DBS for each different DDL
definition (SOURCEREC) with the same SOURCEFILE but a
different TARGETFILE. A unique USEREXITID value should be
defined for each DBS. The user exit code would then get the field
value to determine if the target should be written for the
USEREXITID (USEREXITID can identify the target that might be
involved). It would then tell HPE Shadowbase to execute the event
to the target (via SBSETEXECUTE) or ignore this iteration because
it doesn't apply to this DBS (via SBSETIGNORE).
Note: That a similar strategy can be used to write many target
rows from a repeating group in an Enscribe source (i.e., to
normalize the data). You would have a DBS for each
possible occurrence in the source record.
12. Avoid Initializing User Exit Variables on Each Call and Extraneous
Data Movement Commands
HPE Shadowbase Programming Manual—785431-007
20
User Exits
Best Practices for HPE NonStop Shadowbase User Exits
For all user exits, particularly those written in COBOL, avoid
initialization assignments (for COBOL, avoid the VALUE clause,
INITIALIZE verb, and unnecessary MOVE statements if possible)
for data items that do not need them. This can waste considerable
CPU utilization during each invocation of the user exit (particularly
the USRXPROCESS function).
13. Stopping and/or Abending the User Exit Process
Never directly terminate the user exit process (e.g., via a call to
PROCESS_STOP() or PROCESS_ABEND()) from inside a user
exit. Instead, use the SBSETABEND() API call and then return to
the HPE Shadowbase process so that it can perform any internal
shutdown processing that it needs (it will log a message describing
that the process termination was requested by the user exit).
14. Testing, Tracing, and Debugging of your User Exits
To debug you user exits, generally use the Consumer’s DEBUG
ONSTART parameter, and set your breakpoints at the user exit
function names (e.g., USRXINIT, USRXSTART, USRXPROCESS,
etc.).
During your user exit coding and debugging phase of development,
use the Consumer’s user exit and I/O tracing features to ensure the
proper operation of your user exit code and the events that the
Consumer generates:

Enable the User Exit tracing via the Consumer. Set CONS
USERTRACE ON, CONS IOTRACE 5 (for all events), and
IOTRACEFILE (USERTRACEFILE if using a version prior to
4.040C) to a file name, as well as set DBS USERTRACE ON for
the DBS’s you want to trace (the DBS needs a USEREXITID to
be traced).

Enable the Consumer statement I/O generation tracing in the
Consumer. This will capture the actual statements being
generated, along with the data values for each of the columns
being processed. Enable this via the Consumer IOTRACExxx
parameters.
Review the trace contents by FTPing (binary) the trace files to your
PC and use your favorite editor program (e.g., Code Wright) to look
at the contents (or use NOTEPAD). The trace files are formatted
for PC-type editors, and are not in the NonStop “EDIT” file format.
HPE Shadowbase Programming Manual—785431-007
21
User Exits
Creating a User Exit
15. Additional HPE Shadowbase User Exit Performance Comments
Refer to the HPE Shadowbase Performance Section training slides
as well as the HPE Shadowbase Softdocs and manuals for more
details, this section will touch on some overall items to be aware of.
For example, make sure you are running in “turbo mode”, that you
are blocking as many events as possible into your data blocks that
are sent across the communications channels, and that you are
using the caching versions of the HPE Shadowbase Other Servers
software.
The HPE NonStop Shadowbase releases from Version 3.960 thru
Version 3.980 added some important Collector and Consumer
performance improvements related to user exit processing, so
consider upgrading if you are running on a previous version. These
enhancements are enabled by default, and include:





The Collector was enhanced (V3.964A) to add in subvolume
prescreening to speed file selection logic. This approach
improves Collector file selection logic when non-wild carded
subvolume(s) or filename(s) are used in the DBS SOURCEFILE
parameters (see the TACL parameter SBCOLLSVOLSCREEN
for more information).
The Collector was enhanced (V3.964A) to add in filename
prescreening to speed file selection logic. This approach
improves Collector file selection logic when wild carded
subvolume(s) or filename(s) are used in the DBS SOURCEFILE
parameters (see the TACL parameter SBCOLLOPTIMIZE for
more information).
The Consumer was enhanced (V3.964A) to improve its overall
user exit processing environment to make it more efficient.
The Consumer was enhanced (V3.980C) to improve the
methods used for field and column name searching for large
DDL and SQL Schema definitions. An AVL tree (a form of a fast
tree data structure) was added to the least recently used (LRU)
linked list approach previously employed (see the TACL
parameter SBCONSUSRXAVLNUM for more information).
The Consumer was enhanced (V3.980C) to eliminate the
automatic field/column name up shift and dash-to-underscore
translation mapping when the new CONS
USEREXITCOLCHECK parameter is set to OFF (the default is
on). Make sure your user exits are programmed appropriately
before enabling this feature.
Creating a User Exit
HPE Shadowbase Programming Manual—785431-007
22
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
The main goal of any user exit is to produce accurate target data
customized appropriately. Because the user exit is manipulating data
into a reflection of what occurred in the source database, you must
proceed carefully. Thorough planning, coding, and testing are very
important. The sections that follow will guide you through the process
of creating a user exit.
As with creating any program, there are five major steps for creating a
user exit:
1. Plan user exit processing and design the user exit program.
2. Code the program.
3. Compile and bind/link the program.
4. Configure HPE Shadowbase use of the user exit.
5. Test and debug the program.
The result of the plan processing/design program phase will be a
layout of all the processing your user exit will do. This may be in the
form of a flowchart, pseudo-code or whatever presentation format
works for you. You may also want to include how you will test the user
exit in these plans. Next, you will code your user exit routine. This is
followed by compiling it and binding it into the Consumer. When the
new Consumer is prepared, configure and start HPE Shadowbase.
Finally, begin testing and debugging the program.
Step #1: Planning User Exit Processing
and Designing the User Exit Program
Before you start to code your user exit, you need to understand how
the user exit fits into the HPE Shadowbase environment. The sections
below describe how the HPE NonStop Shadowbase Consumer and
the HPE Shadowbase Other Servers interact with the user exit facility.
In the planning/design phase, you will lay out the processing that is to
be performed by your user exit and prepare to code the program.
What follows is a discussion of the structure of the user exit program
file as it relates to the main processing of HPE Shadowbase and
guidelines for design of the processing.
Once you are aware of the structure of the user exit API and how it
relates to the processing done in HPE Shadowbase, it is time to focus
on the design of your user exit processing as related to each HPE
Shadowbase entry point.
HPE Shadowbase Programming Manual—785431-007
23
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
Remember that each entry point is a separate program (for COBOL
development, each entry point contains its own PROGRAM-ID, and for
C, TAL, etc. each entry point is a standalone function with no main)
contained in one program file, or library, that is compiled and bound
into the main Consumer object module. As such, each entry point
should be considered an independent program module, structured in
the way that corresponds to the language in which it will be coded.
Processing Phases
HPE Shadowbase processes (NonStop Consumer or Other Servers)
have three processing phases:

Initialization

Event Processing

Shutdown
Initialization Phase
During initialization, the HPE Shadowbase process (NonStop
Consumer or Other Servers) enters the API so you may complete
tasks you need to perform only at process start up (e.g., global variable
initialization).
Event Processing Phase
The event processing phase covers the time the HPE Shadowbase
process (NonStop Consumer or Other Servers) is actively processing
events (insert, update, delete or commit/abort of transaction), including
any error handling.
During this phase the HPE NonStop Shadowbase Consumer is
receiving messages from the Collector, processing them and writing
them to the target database. Event messages are received from the
Collector, are processed and either executed or ignored depending on
whether or not they were of use within the programmer developed API
code. Event processing errors (i.e., insert fails due to invalid data in a
column value) and application-generated errors (e.g., HPE
Shadowbase API function SBGETBEFORE COLUMN called with
invalid parameter value fails, invalid return code is passed back to
application) must be considered when coding one’s user exit logic. It is
important to note that all SB… user exit API functions return a status
value indicating the success/failure of the operation executed.
During this phase the HPE Shadowbase Other Server process is
reading and processing messages from the source and is
HPE Shadowbase Programming Manual—785431-007
24
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
subsequently performing transmission, transformation, and or
database storage and forwarding of these events.
Shutdown Phase
Upon receiving a message to shutdown, the HPE Shadowbase
process (NonStop Consumer or Other Servers) enters the shutdown
phase where it finishes processing its current transaction, flushes all
buffers, closes any file handles, and terminates normally.
User Exit Entry Points
The following diagram identifies the general processing flow into and
out of the user exit entry points.
HPE Shadowbase Programming Manual—785431-007
25
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
Figure 2 - User Exit Entry Points
HPE Shadowbase Programming Manual—785431-007
26
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
The following user exit functions are entered by HPE Shadowbase:

USRXINIT

USRXROLL (Other Servers environment only)

USRXEXCEPTIONINIT

USRXEXIT (Other Servers environment only)

USRXSTART

USRXSTOP ( Other Servers environment only)

USRXPROCESS

USRXAFTERPROCESS (Other Servers environment only)

USRXADDDBS
Each user exit function is detailed in the sections that follow.
USRXINIT
The USRXINIT function is called when a HPE Shadowbase process
(NonStop Consumer or Other Servers) is started. Its purpose is to
perform any initializations that are “global” to all user exits.
NOTE: To exercise the use of "globals" within the COBOL
environment, declare your variables here first in EXTENDED
STORAGE with the GLOBAL EXTENDED attribute. For ‘C’
declarations, simply make them here and initialize, etc.
Figure 3 - USRXINIT Processing
USRXINIT is entered by the HPE Shadowbase process when the HPE
Shadowbase process starts. Nothing is passed to the program when it
is entered. In the program, you can perform any initializations needed.
HPE Shadowbase Programming Manual—785431-007
27
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
Nothing is passed back to the HPE Shadowbase process when the
function is exited.
HPE Shadowbase Programming Manual—785431-007
28
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
Accessing Processes
The USRXINIT function is entered by the following HPE Shadowbase
processes:

NonStop Consumer

Other Servers DOC Writer

Other Servers Direct Writer

Other Servers TRS

Other Servers OPCOL

Other Servers TFS
USRXEXCEPTIONINIT
The USRXEXCEPTIONINIT function is called when a HPE
Shadowbase process (NonStop Consumer or Other Servers) is
started. The purpose is to specify SQL error code ranges (usually
"data exceptions") that require special handling. When HPE
Shadowbase detects any errors defined in USRXEXCEPTIONINIT, it
will route to the USRXEXCEPTION program (see description of entry
point below) for user-coded handling of the error. You can also specify
the number of times that HPE Shadowbase retries a specific error
before abending. The default number of retries is 10. See section
below on USRXEXCEPTION for additional information.
HPE Shadowbase Programming Manual—785431-007
29
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
Figure 4 - USRXEXCEPTIONINIT Processing
Before coding, you need to establish how data exceptions will be
handled. The default handling of defined SQL errors in HPE
Shadowbase is to ignore the error (no target I/O). Under certain
circumstances, you may want to do special processing of specific
errors rather than allow the I/O to fail. For example, in the HPE
NonStop environment, if you are replicating an Enscribe file to an
SQL table and receive an -8405 (decimal data encountered with some
nonnumeric digits) SQL error, you may want to fix the data in the field
and have HPE Shadowbase try applying it to the SQL table again.
In USRXEXCEPTIONINIT, you define for the HPE Shadowbase
process the SQL error codes that require special handling. These are
HPE Shadowbase Programming Manual—785431-007
30
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
expressed as ranges of error numbers (e.g., 8405 through 8509). You
also establish the number of SQL code ranges to be handled and the
number of times HPE Shadowbase should try SQL operations. To do
this, load the appropriate values into the fields that will be sent to HPE
Shadowbase and call the API function, SBSETEXCEPTIONCODES.
See the API description later in this chapter for more details of the
values passed to this function.
Accessing Processes
The USRXEXCEPTIONINIT function is entered by the following HPE
Shadowbase processes:

NonStop Consumer

Other Servers DOC Writer

Other Servers Direct Writer

Other Servers TRS

Other Servers OPCOL

Other Servers TFS
USRXEXIT
The USRXEXIT(int reasonCode, int exitCode) function is called just
prior to process termination (calls to exit()) when a HPE Shadowbase
process has experienced a logical or physical processing error other
than a run-time fault. The purpose of this function is to enable
programmatic notification to the User Exit (UE) API layer that process
termination is about to occur. This UE API is designed to empower UE
processing with the ability to perform ‘house-keeping’ tasks prior to
process termination and should not be used in a manner that extends
processing longer than is deemed absolutely necessary.
When the USRXEXIT API is invoked, a reasonCode and an exitValue
values are supplied that correspond to the reason behind the
invocation and the argument being supplied to the exit() call about to
be made respectively. The arguments are passed by value. The
following table expresses the reasonCode values supported.
reasonCo
de
<0
0
1
>1
Description
If experienced contact HPE Shadowbase support.
A processing error has occurred and exit() will be called with a nonzero value.
A processing error has occurred and exit(0) will be called.
If experienced contact HPE Shadowbase support.
USRXROLL
HPE Shadowbase Programming Manual—785431-007
31
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
The USRXROLL entry point is called within an Other Servers process
(DOC Writer or Other Servers Collector) when DOC processing is
configured and a DOC roll is requested. One would program for these
events if, for example, their Other Servers Transaction Replay Server
(TRS) is configured to read only closed DOC files. When the
USRXROLL entry point is called, one would program a notification
scheme to inform the TRS about the upcoming availability of a new
closed DOC to read.
Open Server
OPCOL
Process
USRXROLL
Send
notification to
TRS/TFS that
DOC about to
ROLL, etc.
EXIT to OPCOL
Figure 5 - USRXROLL Processing
Accessing Processes
The USRXROLL function is entered by the following HPE Shadowbase
processes:

Open DOC Writer

Open OPCOL
USRXSTART
HPE Shadowbase Programming Manual—785431-007
32
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
USRXSTART gives you an opportunity to set up any one-time items
that might be needed. Someone coding their user exit in C or COBOL
might call this function to load a set of conditional testing codes into
globals that would later be used during user exit processing. See the
USRXSTART section of USRXCOB for code sample.
In the NonStop environment for releases prior to 4.092, for either
SQL/MP, SQL/MX, or Enscribe data, the USRXSTART function is
called when a database specification (DBS) configured with a
USEREXITID parameter is starting within the Consumer process. For
post 4.092 releases of HPE Shadowbase, USRXSTART only gets
called once the first event is identified (event selected by the SBCOLL
process based upon the DBS MXSOURCETABLE parameter for
SQLMX, or selected based upon the DBS SOURCEFILE value by the
AUDCOLL(N) process and shipped to the AUDCONS(N) process).
In the Other Servers environment, the USRXSTART function is
called when an Other Servers process is started with the
SHAD_USRX_PROCESSING parameter set to 1 (in the shadparm.ini
file).
HPE Shadowbase Programming Manual—785431-007
33
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
Start Shadowbase process
Shadowbase
process
(NonStop
consumer or Open
server)
USRXSTART Processing
SBGETUSRXSTARTINFO
Load Globals, etc.
Shadowbase
process
(NonStop
consumer or Open
server)
...Continues Processing
Figure 6 - USRXSTART Processing
USRXSTART is entered by a HPE Shadowbase process (NonStop
Consumer or Other Servers) whenever a user exit is started.
In the NonStop environment it is called once for each non-zero
USEREXITID in your configuration. The program should first call the
SBGETUSRXSTARTINFO API. HPE Shadowbase will supply the
USEREXITID value, the SOURCEFILE name and the TARGETFILE
name. The program can then load the appropriate values based on
the values returned. See the API description below for details about
calling this API.
HPE Shadowbase Programming Manual—785431-007
34
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
Accessing Processes
The USRXSTART function is entered by the following HPE
Shadowbase processes:

NonStop Consumer

Other Servers DOC Writer

Other Servers Direct Writer

Other Servers TRS

Other Servers OPCOL

Other Servers TFS
USRXADDDBS
The USRXADDDBS entry-point function is called by the Consumer during
ADD/CAPTURE DBS processing to allow user exit code to perform tasks
associated with a DBS object during the configuration stage. For example,
one might call SBGETPARAM to obtain a DBS parameter value to setup
global information about various DBS objects to support other user exit
processing. See the USRXCOB file for a COBOL skeleton and the USRXC
file for a C skeleton.
USRXSTOP
The USRXSTOP(int reasonCode) function is called when a HPE
Shadowbase process is stopped by request from the SBMON command
interface. The purpose of this function is to enable programmatic
notification to the User Exit (UE) API layer that a STOP request has been
received and shutdown processing is about to commence. This UE API is
designed to empower UE processing with the ability to perform ‘housekeeping’ tasks prior to process termination and should not be used in a
manner that extends processing longer than is deemed absolutely
necessary.
When the USRXSTOP API is invoked, a reasonCode value is supplied
that corresponds to the reason behind the invocation. The
reasonCode argument is passed by value. The following table
expresses the reasonCode values supported.
reasonCode
<= 0
1
>1
Description
Reserved. Contact HPE Shadowbase support.
A STOP Request from SBMON has been received.
Reserved. Contact HPE Shadowbase support.
USRXPROCESS
HPE Shadowbase Programming Manual—785431-007
35
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
The USRXPROCESS function is called when a source event is
determined to have a user exit associated with it (via the NonStop DBS
USEREXITID parameter set greater than 0 or Other Servers
SHAD_USRX_PROCESSING parameter set to 1). This is where you
will write your custom code to prepare the target data for HPE
Shadowbase to write. In your code, you will use the application
program interface calls (APIs), described in the User Exit APIs section,
to perform the customized processing. Please refer to the
USRXPROCESS program sample in USRXCOB for more information.
USRXPROCESS is entered when the HPE Shadowbase process
(NonStop Consumer or Other Servers) receives an event message
from the source environment. In the NonStop environment, the
Consumer looks at the DBS associated with the SOURCEFILE of the
event and if there is a USEREXITID value set greater than zero,
USRXPROCESS is entered. In the Other Servers environment, if
the SHAD_USRX_PROCESSING parameter is set to 1 for the Other
Servers process, USRXPROCESS is entered. Your code in
USRXPROCESS will then manipulate the data as needed and control
will return to the main HPE Shadowbase processing.
HPE Shadowbase Programming Manual—785431-007
36
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
The flowchart below summarizes the general processing steps for
USRXPROCESS.
SBGETUSRXPROCESSINFO
(first time init only)
SHAD_USRX_PROCESSING = 0?
or
USEREXITID = 0 ?
First time call, no
value set. Perform
any context
loading., etc.
(Insert Event)
EVENT-ID = 0?
SBGETAFTER...
Transform DATA
SBPUT… with
SBSETEXECUTE
or SBSETIGNORE
EXIT to Shadowbase
process
(NonStop consumer
or Open server)
(Update Event)
EVENT-ID = 1?
SBGET...
Transform DATA,
SBSET,
SBNOTIFY, ...
SBPUT… with
SBSETEXECUTE
or SBSETIGNORE
EXIT to Shadowbase
process
(NonStop consumer
or Open server)
(Delete Event)
SBGETBEFORE
Transform DATA
SBPUT… with
SBSETEXECUTE
or SBSETIGNORE
EXIT to Shadowbase
process
(NonStop consumer
or Open server)
EXIT to Shadowbase
process
(NonStop consumer
or Open server)
Figure 7 - USRXPROCESS Processing
Before coding, you need to have a clear picture of how the data from
the source files/tables need to be manipulated before they can be
applied to the target files/tables. From there, you can develop the logic
for your USRXPROCESS program.
The logic of USRXPROCESS is roughly analogous to a data
conversion type program. In a typical data conversion program, the
logic would follow these steps:
1. Other Servers input and output files.
2. Read from input.
3. Manipulate input data into output format.
4. Write to output file.
5. Go back to read next record until the end of the input file.
6. When done, close files and terminate.
Because USRXPROCESS is an integral part of the HPE Shadowbase
process (NonStop Consumer or Other Servers), the input and output
HPE Shadowbase Programming Manual—785431-007
37
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
files, in the example above, are replaced by the main HPE
Shadowbase process. In other words, the input to your code is
obtained from and the output is done to the HPE Shadowbase process
with the HPE Shadowbase process controlling the transactions. This
does not mean that you cannot do I/O on database files/tables. It just
means that your code must interact with the HPE Shadowbase
process. Therefore, the general logic of USRXPROCESS is:
1. When USRXPROCESS is entered, get and evaluate event
information from the HPE Shadowbase process (logically similar to
read from input step #2, above).
2. If appropriate, get data from the HPE Shadowbase process
(logically similar to read from input step #2, above).
3. Manipulate data into output format (step #3, above).
4. Return control to the HPE Shadowbase process (logically similar to
write to output step #4, above).
Each of these steps is examined in the paragraphs that follow.
#1 Getting and Evaluating Event Information
When USRXPROCESS is entered from the HPE Shadowbase
process, your code starts executing at the beginning of the program.
In COBOL, that means at the beginning of the Procedure Division.
The very first thing you need to do is get and evaluate event
information from the HPE Shadowbase process.
Getting the event information is done by using the
SBGETUSRXPROCESSINFO API function. In the NonStop
environment, it is logically similar to a Pathway server reading
$RECEIVE. When you call this function, the HPE NonStop Consumer
will return the value of the USEREXITID set in the DBS, the current
event type (insert, update, delete, commit or abort) and the original
event type. In the Other Servers environment, when you call this
function, the Other Servers process will return the current event type
(insert, update, delete, commit or abort) and the original event type.
Once you acquire this information, you need to begin evaluating it.
See API description later in this chapter for details about this function.
In the NonStop environment, generally, each source/target pair will
require its own path through the logic of the user exit code because the
fields/columns and the manipulations necessary to prepare the data for
application to the target are unique to that pair. Thus, each
source/target pair that requires a user exit will usually be identified by a
unique USEREXITID number that is set via the USEREXITID
parameter within the pair’s DBS. Therefore, the first evaluation you
need to do is, determine the value of the USEREXITID. You then
HPE Shadowbase Programming Manual—785431-007
38
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
branch to other parts of the program code and perform the processing
that is appropriate for that USEREXITID. While each source/target
pair may require specific, unique handling within the code, it is also
possible that some of the work to be done for each will overlap. To
handle these overlaps, you may want to develop common subroutines
that will perform the work.
Also in the NonStop environment, you need to code for the fact that
USRXPROCESS will be called with a USEREXITID equal to 0 when a
transaction completion event is encountered for a transaction that was
previously handled by a user exit. This permits you to release any
context you are keeping for a transaction. In some instances, you may
need to keep transaction context to format the target data, however it
is highly recommended that you avoid keeping context within your user
exit code. You can also take no action and just return control to the
Consumer when USEREXITID = 0, if appropriate.
Next, in the HPE NonStop environment, evaluate the event type
values to determine how you will get the data into your user exit,
thereby determining which APIs you will use. As stated above,
SBGETUSRXPROCESSINFO returns both the current event type and
the original event type. In most cases, the original and the current
event type will be the same. However, if UPDATEDUPLICATE is on
for the DBS, the original event maybe an insert and the current event
may be an update; or, if INSERTNOTFOUND is on, the original event
may be an update and the current event may be an insert. Whether
either of these cases requires special processing depends upon your
individual needs.
In the Other Servers environment you will also need to evaluate the
event type values to determine how you will get the data into your user
exit and determine which APIs you will use. Use
SBGETUSRXPROCESSINFO to obtain the current event type and the
original event type. In most cases, the original and the current event
type will be the same. However, if the Insert Not Found option is on,
the original event may be an update and the current event may be an
insert. Whether this case requires special processing depends upon
your individual needs.
#2 Getting Data from HPE Shadowbase
After you have determined the event type to be processed,
USRXPROCESS needs to get data from the HPE Shadowbase
process. In most cases, you will only need to get the field/column
values that need to be altered and those whose values will drive
conditional replications. (All fields/columns that have the same name
HPE Shadowbase Programming Manual—785431-007
39
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
and data type in the source and target files will be written
automatically.) To get the data you need, you will use the various
SBGET API functions. These functions are detailed later in this
chapter. In the NonStop environment, you can obtain before and
after images of fields/columns; before and after images of Enscribe
records; SOURCEFILE and TARGETFILE names; connection
information for use in replication to Other Servers environments;
relative record addresses; and information about the transaction of
which the event is a part with the SBGET functions. In the Other
Servers environment, you can obtain before and after images of
fields/columns, target file names, information about the transaction of
which the event is a part, etc. with the SBGET functions.
In most cases, user exit code will need to get the field/column data
first. How you get this data (which SBGET... API you use) depends
upon the event type because certain data is only available for specific
event types. For insert events, only after image data (i.e., the value of
the field after it has changed on the source) is available. For deletes,
only before image data (i.e., the value of the field before it is changed)
can be obtained. In the NonStop environment, for Enscribe updates,
before and after image data at the record and field level is available;
for SQL updates, you can only obtain the before and after images of
the columns that changed. In the Other Servers environment, for
updates, you can only obtain the after image of the columns that
changed.
For optimal performance, code your user exit to get field/column values
in the order that they occur in the source. You should also be sure to
get only those fields/columns you need.
#3 Manipulating Data into the Output Format
Once you have all the data from the HPE Shadowbase process
(NonStop Consumer or Other Servers) that you need, manipulate data
into the output format. This is when you need to have a clear
understanding of the processing to be done. Manipulation may require
accessing data in other files/tables, doing calculations, splitting records
to multiple targets, etc.
One thing that will affect the building of the output format is whether
the HPE Shadowbase process or the user exit is responsible for writing
to the target. While it is possible for the user exit routine to perform the
I/O on the target file, it is preferable to have the main body of the HPE
Shadowbase process perform those operations. The reason for this is
that HPE Shadowbase is designed to accurately deliver the data to the
target and avoid corruption of the target database. Doing the I/O within
HPE Shadowbase Programming Manual—785431-007
40
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
the user exit will necessitate the introduction of complexity and
transaction context into the code so that accuracy can be assured.
Again, it is possible to do this, but you must proceed very carefully.
Assume for this discussion that you will have the HPE Shadowbase
process perform the I/O on the target. Once you have formatted the
data as required, you need to put it back into the HPE Shadowbase
process so that it can be applied to the target. To do this you will use
the SBPUT... API functions. These are described in detail later in this
chapter. The SBPUT... functions permit you to put altered key and
non-key fields/columns back into the HPE Shadowbase process.
Any fields/columns that have the same name and data type in the
source and target will be written in the target automatically. Therefore,
if you have not altered them in some way, you do not need to put them
back. You can also tell the HPE Shadowbase process not to write
certain columns that would otherwise automatically be written via the
SBREMOVECOLUMN API described below. Fields/columns that
appear in the source and not in the target do not need to be removed.
They are skipped automatically.
In certain instances, you may want to have the HPE Shadowbase
process write to a target other than the one defined in your
configuration. This is known as a target override. To do this, you will
need to use the SBSETTARGET function. This API is discussed later
in this chapter. Because the HPE Shadowbase process does not
know the layout of targets that are not defined within HPE
Shadowbase, you must put all fields/columns.
For optimal performance, put columns back into the HPE Shadowbase
process in the order they appear in the source. Only put those
columns requiring some form of modification. As long as the user exit
has not overridden the target, HPE Shadowbase will map common
columns (by column name), from the source to the target
automatically. Try to keep the column and field names the same
between the source and target where possible so they can be mapped
automatically thus reducing the amount of user exit code that needs to
be executed.
#4 Return Control to HPE Shadowbase
After the necessary data manipulations are performed, return control to
the HPE Shadowbase process. In COBOL, this is done by exiting the
program. When you have returned control, the next time the HPE
Shadowbase process enters USRXPROCESS it will be back at the
beginning of the logic effectively waiting for the next event message.
HPE Shadowbase Programming Manual—785431-007
41
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
In the NonStop environment, it is also possible to have multiple
USEREXITIDs associated with a single SOURCEFILE. Whenever
HPE Shadowbase encounters an event for the SOURCEFILE,
USRXPROCESS will be called for each DBS associated with that
SOURCEFILE. The user exit must be coded to allow for the possibility
that it took all necessary action when it was first called and that
subsequent calls are to be ignored. For example, you have one
Enscribe source with several different DDL record definitions where
each definition corresponds to a different TARGETFILE. A field’s
value determines which definition is used and which target is written to.
Within HPE Shadowbase, define a DBS for each different DDL
definition (SOURCEREC) with the same SOURCEFILE, a different
TARGETFILE (corresponding to the SOURCEREC) and a unique
USEREXITID. The user exit code would “get” the determining field
value and decide if the corresponding target should be written. The
user exit then tells HPE Shadowbase to execute the event to the target
or ignore this iteration because it doesn't apply. A similar strategy can
be used to write many target SQL rows from a repeating group in an
Enscribe source. You would have a DBS for each occurrence in the
source record.
Accessing Processes
The USRXPROCESS function is entered by the following HPE
Shadowbase processes:

NonStop Consumer

Other Servers DOC Writer

Other Servers Direct Writer

Other Servers TRS

Other Servers OPCOL

Other Servers TFS
HPE Shadowbase Programming Manual—785431-007
42
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
USRXAFTERPROCESS
The USRXAFTERPROCESS entry point is called after the statement is
applied by the Other Servers process. From this entry point, you can
check, for example, to see if a commit or a delete has occurred.
Open Server TRS/
TFS Process
USRXPROC
ESS
Exit to TRS/TFS
Process, continue
processing, apply
data to target.
USRXAFTER
PROCESS
Check on
Commit…
etc.
Exit to TRS/TFS
Process
Figure 8 - USRXAFTERPROCESS Processing
The statement must have been passed into USRXPROCESS and
acted upon by any of the SBGET…, SBPUT…, or SBREMOVE…
functions to have this entry point accessed.
HPE Shadowbase Programming Manual—785431-007
43
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
Accessing Processes
The USRXAFTERPROCESS function is entered by the following HPE
Shadowbase processes:

Other Servers DOC Writer

Other Servers Direct Writer

Other Servers TRS

Other Servers OPCOL

Other Servers TFS
User Exit Exception Entry Points
The USRXEXCEPTION user exit function is entered by the HPE
Shadowbase process (NonStop Consumer or Other Servers) upon
exception in the user exit.
USRXEXCEPTION
This function is called when an SQL error is detected having a value
that is within the range of the codes set in the USRXEXCEPTIONINIT
function. This gives you the opportunity to recover from the error in a
custom manner or to ignore it. The function can also tell HPE
Shadowbase to log the key of the source event to the error log file.
Use the APIs described later in this chapter to interact with HPE
Shadowbase. The default handling of defined SQL errors in HPE
Shadowbase is to ignore the error (no target I/O) and log the source
key to the error log file.
Before coding, you need to establish how data exceptions (SQL errors)
will be handled. The default handling of defined SQL errors in HPE
Shadowbase is to ignore the error (no target I/O), log the source key
and continue processing. This pattern will be followed unless
USRXEXCEPTIONINIT and USRXEXCEPTION are coded to take
different action.
HPE Shadowbase Programming Manual—785431-007
44
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
Shadowbase process
(NonStop consumer
or Other server)
Error codes defined in
USRXEXCEPTIONINIT
Determine what error
code was encountered
plus additional info
SBGETUSRXEXCEPTI
ONINFO
CASE on error
code
Error X
Manipulate data for
error X
Error Y
Manipulate data for
error Y
Re-apply
statement?
No
SBSETIGNORE
Yes
SBSETEXECUTE
EXIT
Figure 9 - USRXEXCEPTION Processing
In the NonStop environment, suppose you are replicating an
Enscribe file to an SQL table and decide that when –8405 (Decimal
data encountered with some nonnumeric digits) SQL errors occur you
will correct the data and have HPE Shadowbase retry the I/O. To do
this you set the –8405 code value in the USRXEXCEPTIONINIT
program. Then you add code to USRXEXCEPTION to fix that data.
Next, to override the default mode of “ignore the error,” you must tell
the Consumer to try to reapply the event by using the
SBSETEXECUTE API call before exiting USRXEXCEPTION.
Accessing Processes
The USRXEXCEPTION function is entered by the following HPE
Shadowbase processes:

NonStop Consumer

Other Servers DOC Writer

Other Servers Direct Writer

Other Servers TRS

Other Servers OPCOL

Other Servers TFS
HPE Shadowbase Programming Manual—785431-007
45
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
User Exit Context Checking
HPE Shadowbase processes events in the order they are inserted into
the source table. It is therefore possible, and highly likely, that any two
events processed sequentially within the user exit will not be related to
one another (e.g., not related to the same source and/or target
files/tables).
It is not recommended, therefore, that users attempt to maintain
context between calls to the user exit space. The use of global
variables should be deployed to minimize redundant I/O and/or
unnecessary code iterations. Using global variables (e.g., declaring
variables within COBOL as GLOBAL EXTENDED in each program
module, or for C declaring them above any function declarations within
the program module) should be deployed for maintaining whatever
variables are required routinely for process execution.
An exception to this rule exists in the HPE NonStop environment
under the following circumstances: In NonStop to NonStop replication,
the user has the ability to configure the environment in the following
manner. Suppose you are doing an UPDATE and the target
row/record does not exist. By setting the DBS parameter
INSERTNOTFOUND for the target system DBS specification to ON,
HPE Shadowbase will reprocess the UPDATE, turning it into an
INSERT. You might want to permit for the USRXPROCESSING
context to carry over in this scenario if possible based upon the
following discussion.
A call to SBGETUSRXPROCESSINFO results in returning the
SB_USRX_PROCESS_INFO data structure. There are three
elements of this structure:

USRX_ID:
Identifies the DBS this
event corresponds to.

EVENT_ID: Is 1 for an update, 0 for an
insert, etc.

ORIGINAL_EVENT_ID:
Maintains the original
EVENT_ID for subsequent calls to the user
exit processing.
With INSERTNOTFOUND set to ON, the first call to the user exit code
will result in EVENT_ID being set to 1 (update). When the UPDATE
fails, the event is converted into an INSERT and the user exit code is
called again. For this subsequent call, EVENT_ID is now set to 0
(INSERT), and the ORIGINAL_EVENT_ID is set to 1 (UPDATE).
Therefore, you have the ability to isolate this condition, and possibly
HPE Shadowbase Programming Manual—785431-007
46
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
carry over the user exit context and apply the original UPDATE log
results to the INSERT should you desire to do so.
The UPDATEDUPLICATE DBS parameter enables HPE Shadowbase
to convert UPDATE events into INSERT events if the record/row does
not exist on the target. This is another example whereby one might
wish to apply context checking to reduce user exit processing.
HPE Shadowbase Programming Manual—785431-007
47
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
HPE NonStop Shadowbase User Exit
Processing
In the NonStop environment, as changes are made to source
files/tables that you have integrated into your replication stream,
messages about those changes are sent to the Consumer process.
The Consumer is responsible for applying those changes to the
indicated target database. All user exit code is contained in one
program module file that is bound (via a BIND command) into the
Consumer and therefore becomes part of the Consumer processing.
Because the user exit code is part of the Consumer, it is necessary to
understand how the Consumer process works so your code can be
integrated appropriately.
Upon startup, if a NonStop Consumer process finds a DBS
specification with a USEREXITID set greater than zero during
initialization, it will enter (execute) the INIT (USRXINIT,
USRXEXCEPTIONINIT, USRXSTART) portions of the user exit code.
The user exit API is then called again for each qualifying event
(USRXPROCESS, USRXEXCEPTION).
The following figure depicts the HPE Shadowbase control points for
configuring user exit processing. Notice the correlation between DBS
specification and Consumer. The DBS specification parameter
USRXEXITID relates the replication path’s SOURCEFILE and
TARGETFILE to the appropriate point in the user exit code via its
value. A unique value should be used for each DBS specification
requiring custom code within the user exit APIs.
HPE Shadowbase Programming Manual—785431-007
48
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
AUDCOM config
These command
parameters enable user
access to AUDCOM,
register components of
Shadowbase within
AUDMON
OPEN $SBDVB
OBEY PASSWORD
START AUD
CONsumer Specification
RESET CONS
SET CONS DEBUG ONSTART
SET CONS …
ADD CONS CONS1
Start your CONsumer in
DEBUG to check your
transformation processing,
RETURN CODES, etc.
DBS specification
In order to associate
USEREXIT processing
with a Source/Target FILE,
the DBS Spec must set a
unique USEREXIT ID
RESET DBS
SET DBS USEREXITID 1
SET DBS …
ADD DBS DBS1
AUDCOM Activation of
ENV
Failure to execute these
general AUDCOM
commands will prohibit
your Shadowbase
environment from
executing
CAPTURE DBS *
START CONS *
START COLL *
RUN
Figure 10 - HPE NonStop Shadowbase User Exit Processing
NonStop Consumer User Exit Processing
The sections that follow detail user exit processing with respect to the
NonStop Consumer process (AUDCONS or AUDCONSN). The
NonStop Consumer user exit entry points and user exit exception entry
points are listed below.
HPE Shadowbase Programming Manual—785431-007
49
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
NonStop Consumer User Exit Entry Points
The following user exit functions are entered by the NonStop
Consumer.

USRXINIT

USRXEXCEPTIONINIT

USRXSTART

USRXPROCESS
NonStop Consumer User Exit Exception Entry Points
The USRXEXCEPTION user exit function is entered by the DOC
Writer upon exception in the user exit.
User Exits in a HPE NonStop “active-active” Bidirectional Environment
In a "active-active" bidirectional replication environments, if the
ACTIVETARGET DBS parameter is set to ON and there is a non-zero
USEREXITID for the related DBS object, events associated with
duplicate errors will be recycled back through the user exit in an
iterative manner. An UPDATEDUPLICATE iteration could be
processed and if a duplicate error occurs on the update (would occur
on a unique alternate key or index), another iterative cycle will occur
with an attempt on the original insert event type. If a duplicate error
occurs on an insert as the result of an INSERTNOTFOUND for an
update, another iterative cycle will occur with an attempt on the original
update event.
A user exit can determine the current event type and original event
type from calling SBGETUSRXPROCESSINFO. It can also determine
if a duplicate error occurred on the prior event and take an appropriate
action to resolve the situation. This action is dependent upon
application requirements associated with the "active-active"
environment.
IMPORTANT: IT IS THE USER EXIT'S RESPONSIBILITY TO
ENSURE THAT THIS DOES NOT RESULT IN AN
ENDLESS LOOP IN THE CONSUMER. THE USER
EXIT SHOULD EITHER PRODUCE AN
APPROPRIATE EVENT THAT RESOLVES THE
DUPLICATE ERROR OR BYPASS THE EVENT. THIS
IS NECESSARY BECAUSE THE CONSUMER WILL
CONTINUE TO ATTEMPT A TARGET OPERATION
AND RECALL USRXPROCESS AS LONG AS THE
DUPLICATE ERROR OCCURS WHEN
HPE Shadowbase Programming Manual—785431-007
50
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
ACTIVETARGET IS SET TO ON AND USEREXITID IS
NON-ZERO.
HPE Shadowbase Programming Manual—785431-007
51
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
Upgrading to a New Version of HPE NonStop
Shadowbase
In the NonStop environment, if you have user exits developed with
COBOL, you must recompile the programs so that the latest version of
USRXLIBO or USRXLIBN (the native library) is added to the resulting
object file that will subsequently be included in the final bind or link.
After compiling the user exits (if necessary as discussed above), run
BINDUSRX or LINKUSRX to generate the custom Consumer
(AUDCONS or AUDCONSN). Note that this should be done after the
standard install is run.
HPE Shadowbase Other Servers User Exit
Processing
The Other Servers process environment is subtly different than the
HPE NonStop Consumer environment. User exit processing can be
bound into any one of a number of different HPE Shadowbase
processes in the Other Servers environment. What process the user
exit logic is bound to depends on the nature of the Other Servers
configuration and the logic surrounding the HPE Shadowbase
implementation strategy. Consider the following figure:
Resides in
$SHAD_BASE/data
directory
SHADPARM.INI
file
Read SHADPARM.INI upon startup:
If SHAD_USRX_PROCESSING=1
Then process user exit API
Resides in
$SHAD_BASE/bin
directory
SBnnnn
Process
Could be
sbocons
sborapre
sborcol
sbnskfw
sbopenfw
Figure 11 - HPE Shadowbase Other Servers User Exit Processing
During startup, each process reads the shadparm.ini file. See the HPE
Shadowbase Other Servers Operations Manual for details. The
process reads all [GENERAL] section parameters. If the process finds
HPE Shadowbase Programming Manual—785431-007
52
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
a [SECTION] pertaining to its name, as defined when it was added in
sbmon, that section is processed as well. If the parameter
SHAD_USRX_PROCESSING=1 is set, then the process enables the
user exit entry points defined for each process type listed in this
section.
HPE Shadowbase Other Servers releases provide a user exit shell
program and header file (usrxopen.c, usrxlib.h respectively) to be used
create your custom user exit processing logic. The source code
header file (usrxlib.h) specifies the user exit API function prototypes for
all the user exit functionality provided by HPE Shadowbase.
After coding your user exit logic, compile via the supplied make file
(referenced in the next section). The resulting object file must be
linked with the select HPE Shadowbase Other Servers object chosen
to perform the custom user exit processing.
DOC Writer User Exit Processing
The sections that follow detail user exit processing with respect to the
DOC Writer process (sbocons). The DOC Writer user exit entry points
and user exit exception entry points are listed below.
NOTES:

SBPUT calls that are made in USRXPROCESS and are included in
sbocons (DOC writer), have no effect on the statements written to
the DOC. If you need to change column values and put items, this
code should be incorporated into the Transaction Replay Server
(TRS).

User exits work with DOC Writers, but the results written to the
DOC are not modified to prevent data inconsistency issues.
DOC Writer User Exit Entry Points
The following user exit functions are entered by the DOC Writer.

USRXINIT

USRXEXCEPTIONINIT

USRXROLL

USRXSTART

USRXPROCESS

USRXAFTERPROCESS
DOC Writer User Exit Exception Entry Points
The USRXEXCEPTION user exit function is entered by the DOC
Writer upon exception in the user exit.
HPE Shadowbase Programming Manual—785431-007
53
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
Direct Writer User Exit Processing
The sections that follow detail user exit processing with respect to the
Direct Writer process (sbmssql, sborapre, or sbsypre).
NOTE: When using a statement caching Direct Writer (sboracle or
sbsybase) user exits and data mapping cannot be used. The
non-statement caching object (sborapre or sbsypre) must be
used.
The Direct Writer user exit entry points and user exit exception entry
points are listed below.
Direct Writer User Exit Entry Points
The following user exit functions are entered by the Direct Writer.

USRXINIT

USRXEXCEPTIONINIT

USRXSTART

USRXPROCESS

USRXAFTERPROCESS
Direct Writer User Exit Exception Entry Points
The USRXEXCEPTION user exit function is entered by the Direct
Writer upon exception in the user exit.
Transaction Replay Server User Exit Processing
The sections that follow detail user exit processing with respect to the
TRS process (sbmswrt, sborcol, or sbsywrt).
NOTE: When using a statement caching TRS (sborwrt) user exits and
data mapping cannot be used. The non-statement caching
object (sborcol) must be used.
The TRS user exit entry points and user exit exception entry points are
listed below.
Transaction Replay Server User Exit Entry Points
The following user exit functions are entered by the TRS.

USRXINIT

USRXEXCEPTIONINIT

USRXSTART
HPE Shadowbase Programming Manual—785431-007
54
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program


USRXPROCESS
USRXAFTERPROCESS
Transaction Replay Server User Exit Exception Entry Points
The USRXEXCEPTION user exit function is entered by the TRS upon
exception in the user exit.
HPE Shadowbase Programming Manual—785431-007
55
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
Transaction Forwarding Server User Exit Processing
The sections that follow detail user exit processing with respect to the
TFS process (sbopenfw or sbnskfw). The TFS user exit entry points
and user exit exception entry points are listed below.
NOTE: User exits work with TFSs, but the results sent to the remote
system are not modified to prevent data inconsistency issues.
Transaction Forwarding Server User Exit Entry Points
The following user exit functions are entered by the TFS.

USRXINIT

USRXEXCEPTIONINIT

USRXSTART

USRXPROCESS

USRXAFTERPROCESS
Transaction Forwarding Server User Exit Exception Entry Points
The USRXEXCEPTION user exit function is entered by the TFS upon
exception in the user exit.
Open Collector External Procedure User Exit
Processing
The sections that follow detail user exit processing with respect to the
OPCOL external procedure process (sbmscol or sborcol). The
OPCOL external procedure user exit entry points and user exit
exception entry points are listed below.
Open Collector External Procedure User Exit Entry Points
The following user exit functions are entered by the OPCOL external
procedure.

USRXINIT

USRXEXCEPTIONINIT

USRXROLL

USRXSTART

USRXPROCESS

USRXAFTERPROCESS
External Procedure User Exit Exception Entry Points
The USRXEXCEPTION user exit function is entered by the OPCOL
external procedure upon exception in the user exit.
HPE Shadowbase Programming Manual—785431-007
56
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
HPE Shadowbase Programming Manual—785431-007
57
User Exits
Step #1: Planning User Exit Processing and Designing the User Exit Program
Converting the Event Type in the Other Servers
Environment
In the Other Servers environment when converting the event from one
type to another (i.e., converting inserts to updates), there are several
points to take into consideration. These points are detailed below.

If you change an update to a delete in your user exit and your Other
Servers is configured to convert an update to an insert when the
row is not found, the Other Servers will attempt to apply it. If this
action results in a “row not found” condition, the Other Servers will
convert the original update statement into an insert and execute the
action. At that point, the USRXPROCESS will be entered again for
this event and you may convert the event into a delete.

Also, statistics (number of inserts, updates and deletes) reported by
the Other Servers reflect the original event type. Therefore if you
convert a delete into an update within the user exit, for example,
the number of deletes will be incremented and the number of
updates will not.
HPE Shadowbase Programming Manual—785431-007
58
User Exits
Step #2: Coding the Program
Step #2: Coding the Program
User exit design and development almost imperatively will require the
usage of the API functions provided with the product release. These
APIs were designed to provide the developer with a concise and
straightforward method for accessing event replication data while ‘in
flight’. These API functions will enable you to interact directly with the
Consumer’s main body.
There are many categories of user exit API functions. Some are unique
to the NonStop environment, some are unique to the Other Servers
environment; many are inherent to both operating environments.
Not all processes within the HPE Shadowbase environment contain
user exit interfaces. On NonStop systems, only the Consumer enables
the user exit API. The Other Servers processes each have different
user exit capabilities. Reference the previous sections to understand
what functionality is available for each.
The HPE Shadowbase user exit APIs into the categories listed below:
SBCLEARUSRXCONTEXT function for clearing all previous
SBPUT... and SBREMOVECOLUMN calls.
SBGET…
functions for getting the data from HPE
Shadowbase into the user exit for
manipulation.
SBISUNDOEVENT
function for finding out if the event is the result
of a backout.
SBLOGEVENT
function for generating EMS messages.
SBNOTIFYUSRXKEYS
SBPUT…
function for telling HPE Shadowbase that
user exit is going to formulate the SQL
“where” clause to define keys for updates
and deletes.
functions for putting the manipulated data back
into HPE Shadowbase.
SBREMOVECOLUMN function called to tell HPE Shadowbase not to
“put” a column that is common to both the
source and target files that would otherwise
automatically be “put.”
HPE Shadowbase Programming Manual—785431-007
59
User Exits
Step #2: Coding the Program
SBSET…
functions that tell HPE Shadowbase special
execution instructions.
The specific function calls for each category are discussed on the
following pages. Each API is listed within a category, in the level of
detail pertaining to the platform(s) for which they are available.
NOTES:

In the descriptions that follow, all sample calls are given in COBOL
and C. After each sample call, the parameters the call is using are
described. It is very important that each API be called using the
parameters, as described, for that API. Most APIs also give a
return code indicating a successful completion of the call or giving
some indication of the reason for failure. If you are having any
problems with your user exit, please check the return code values
after the calls and verify the parameters being used.

There are differences in the operation of the user exits on some
platforms. Some capabilities are available on HPE NonStop
systems that are not available on Other Servers systems and vice
versa. The Considerations sections for the individual calls explain
the differences on various platforms.
SBCLEARUSRXCONTEXT Function
The SBCLEARUSRXCONTEXT function is used to clear all previous
SBPUT and SBREMOVECOLUMN calls. The
SBCLEARUSRXCONTEXT function is detailed below.
This function can be called from USRXPROCESS or
USRXEXCEPTION to clear all previous SBPUT and
SBREMOVECOLUMN calls.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C "SBCLEARUSRXCONTEXT" IN USRXLIB
Syntax for C Programmers
HPE Shadowbase Programming Manual—785431-007
60
User Exits
Step #2: Coding the Program
SBCLEARUSRXCONTEXT();
Parameters
None
Considerations

SBCLEARUSRXCONTEXT is only available in the NonStop
environment.
SBBEGINDDL and SBENDDDL Functions
DDL operations against audited files and tables usually record an
event in the audit trail. Certain DDL operations are not associated with
TMF transaction ID’s in the audit trail, for example a FUP ALTER
command.
In a bi-directional environment, the HPE Shadowbase ping-pong “cutoff” algorithm typically uses the TMF transaction id to know what
events to replicate and which ones to discard. For the DDL events that
do not have an associated TMF transaction id, you need to tell the
HPE Shadowbase replication engine whether the event should be
replicated back to the source or not. These SB function entry points
are used to do that.
For purposes of user exit customization, if “ping-pong” avoidance is
necessary for DDL events processed via user exit, the user exit API
functions SBBEGINDDL and SBENDDDL can be used. SBBEGINDDL
is called before the DDL operation is executed by the user exit and
SBENDDDL is called after the DDL operation has been performed by
the user exit. Note that a single audit trail event should be wrapped by
these calls because the peer Collector will only skip a single event.
So, if multiple operations are necessary resulting in multiple audit trail
events, each individual step should be preceded by a call to
SBBEGINDDL, and following the DDL operation, a call to SBENDDDL
should be performed.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
The following are code usage examples for these API functions. Refer
to the usrxlib.h file for more information.
HPE Shadowbase Programming Manual—785431-007
61
User Exits
Step #2: Coding the Program
C Usage Example:
#include "usrxlib.h"
char ddl_file_name[36];
long long transid;
long coll_clear_timer = 600;
short ddl_op = ALTER_OP;
short rtrn_cd;
/*file name DDL performed against*/
/*TRANSID returned, passed to SBENDDDL*/
/*COLL can clear if not seen after 10 mins*/
/*should be one of types in usrxlib.h:
*/
/*ALTER_OP, CREATE_OP, PURGE_OP or
*/
/*PURGEDATA_OP. */
/*return code from API function. */
/*
SBBEGINDDL possible values: */
/*
-2 = file name not set
*/
/*
-1 = invalid event type */
/*
0 = bidirectional translog */
/*
not being used */
/*
1 = OK */
/*
SBENDDDL possible values: */
/*
-4 = volume name format error in */
/*
file name */
/*
-3 = transid from SBBEGINDDL not */
/*
set */
/*
-2 = file name not set */
/*
-1 = invalid event type */
/*
0 = bidirectional translog */
/*
not being used */
/*
1 = OK */
short ddl_not_ok = 0;
short ddl_ok = 1;
.
.
.
strcpy((char *)&ddl_file_name,
/*file name sample only*/
"\\SYS1.$DATA1.MYSVOL.MYFILE"); /*null terminate*/
rtrn_cd = SBBEGINDDL((char *)&ddl_file_name,coll_clear_timer,
ddl_op,&transid);
if (rtrn_cd != 1) {
SBSETABEND();
/*what to do here is dependent on your own needs*/
return;
}
.
.
.
/* DO YOUR DDL OPERATION HERE. */
if (ddl_op_finished_in_error) {
/*
rtrn_cd = SBENDDDL(transid,(char *)&ddl_file_name,ddl_op,ddl_not_ok);
.
/*handling is dependent on your needs*/
.
.
}
else {
rtrn_cd = SBENDDDL(transid,(char *)&ddl_file_name,ddl_op,ddl_ok);
}
if (rtrn_cd != 1) {
SBSETABEND();
/*what to do here is dependent on your own needs*/
return;
}
.
.
.
SBSETIGNORE(); /* tells SB that event was processed here */
return;
HPE Shadowbase Programming Manual—785431-007
62
User Exits
Step #2: Coding the Program
COBOL Usage Example:
WORKING-STORAGE.
01
WS-ITEMS.
05 DDL-FILE-NAME
05
05
05
05
05
TRANSID
COLL-CLEAR-TIMER
DDL-OP
RTRN-CD
DDL-OUTCOME
PIC X(36)
VALUE “\SYS1.$DATA1.MYSVOL.MYFILE
NATIVE-8.
NATIVE-4 VALUE 600.
NATIVE-2 VALUE USRX-ALTER.
NATIVE-2.
NATIVE-2.
”.
PROCEDURE DIVISION.
.
.
.
INSPECT DDL-FILE-NAME REPLACE ALL “ “ WITH LOW-VALUES.
ENTER C "SBGETKEYSPECIFIER" IN USRXLIB
GIVING WS-KEY-SPECIFIER.
ENTER C “SBBEGINDDL” IN USRXLIB
USING DDL-FILE-NAME, COLL-CLEAR-TIME, DDL-OP, TRANSID
GIVING RTRN-CD.
.
.
.
* DO YOUR DDL OPERATION HERE AND SET DDL-OUTCOME ACCORDINGLY.
ENTER C “SBENDDDL” IN USRXLIB
USING TRANSID, DDL-FILE-NAME, DDL-OP, DDL-OUTCOME
GIVING RTRN-CD.
ENTER C “SBSETIGNORE”.
.
.
.
SBDIDRESOLVELOCKS Function
The SBDIDRESOLVELOCKS function is used to determine whether or
not the current transaction required a RESOLVELOCKS (meaning a
transaction precommit sequence) to be performed. The
SBDIDRESOLVELOCKS function is detailed below.
This function can be called from USRXPROCESS or
USRXEXCEPTION to determine whether or not the current transaction
required a RESOLVELOCKS to be performed.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C "SBDIDRESOLVELOCKS" IN USRXLIB
GIVING RETURN-CODE.
HPE Shadowbase Programming Manual—785431-007
63
User Exits
Step #2: Coding the Program
Syntax for C Programmers
short SBDIDRESOLVELOCKS(void);
Parameters
RETURN-CODE
returned value

This function will return 1 if the current transaction required a
RESOLVELOCKS to be performed. The value zero (0) is returned
if a RESOLVELOCKS was not performed.
Examples
COBOL Example
WORKING-STORAGE SECTION.
01 RETURN-CODE
PIC 9(4) COMP.
PROCEDURE DIVSION.
ENTER C "SBDIDRESOLVELOCKS" IN USRXLIB GIVING RETURN-CODE.
C Example
short return_code;
return_code = SBDIDRESOLVELOCKS();
Considerations

SBDIDRESOLVELOCKS is only available in the HPE NonStop
environment.
SBCLOSE Functions
SBCLOSEENSCRIBE
The SBCLOSEENSCRIBE user exit API can be called to have the CONS
close Enscribe target files. Options are available to close all target files (0),
close all target files associated with a named DBS object (1), and close a
named target file (2). The value 1 is returned for a successful outcome. -2 is
returned if an invalid option is found. -1 is returned if the name parameter is
not specified (0 length or pointer is 0). 0 is returned if the DBS object or
target file is not found. For option 0 to close all files, call the function with the
name parameter set to 0. Note that the name parameter must be null
terminated.
COBOL Usage Example:
HPE Shadowbase Programming Manual—785431-007
64
User Exits
Step #2: Coding the Program
WORKING-STORAGE.
01 WS-ITEMS.
05 WS-DBS-OBJECT.
10 WS-DBS-NAME
10 WS-DBS-NULL_TERM
05 WS-TARGET-FILE.
10 WS-FILE-NAME
10 WS-FILE-NULL_TERM
05 WS-CLOSE-ALL-ADDR
05 WS-CLOSE-OPTION
88 CLOSE-ALL-FILES
88 CLOSE-DBS-FILES
88 CLOSE-FILE
05 WS-RTRN-CD
PIC X(10) VALUES “DBS-OBJ-01”
PIC X(1) VALUES LOW-VALUES.
PIC
PIC
PIC
PIC
X(25) VALUE “\S1.$DATA5.MYSVOL.FILE001”.
X(1) VALUES LOW-VALUES.
S9(8) COMP VALUE 0.
S9(4).
VALUE 0.
VALUE 1.
VALUE 2.
PIC S9(4) COMP.
PROCEDURE DIVISION.
*CLOSE ALL FILES.
MOVE 0 TO WS-CLOSE-OPTION.
ENTER C “SBCLOSEENSCRIBE” IN USRXLIB
USING WS-CLOSE-OPTION, WS-CLOSE-ALL-ADDR
GIVING WS-RTRN-CD.
*CLOSE ALL FILES RELATED TO A DBS.
MOVE 1 TO WS-CLOSE-OPTION.
ENTER C "SBCLOSEENSCRIBE” IN USRXLIB
USING WS-CLOSE-OPTION, WS-DBS-OBJECT
GIVING WS-RTRN-CD.
*CLOSE A SPECIFIC FILE.
MOVE 2 TO WS-CLOSE-OPTION.
ENTER C "SBCLOSEENSCRIBE” IN USRXLIB
USING WS-CLOSE-OPTION, WS-TARGET-FILE
GIVING WS-RTRN-CD.
C Usage Example:
#include "usrxlib.h"
short rtrn_cd;
/* close all files */
rtrn_cd = SBCLOSEENSCRIBE(0,0);
/* close all files related to a DBS */
rtrn_cd = SBCLOSEENSCRIBE(1,”DBS-OBJ-01”);
/* close a specific file */
rtrn_cd = SBCLOSEENSCRIBE(2,”\\S1.$DATA5.MYSVOL.FILE001”);
SBCLOSESQL
The SBCLOSESQL user exit API can be called to have the CONS close all of
its SQL target tables.
COBOL Usage Example:
HPE Shadowbase Programming Manual—785431-007
65
User Exits
Step #2: Coding the Program
WORKING-STORAGE.
PROCEDURE DIVISION.
ENTER C "SBCLOSESQL” IN USRXLIB.
C Usage Example:
#include "usrxlib.h"
SBCLOSESQL();
SBGET Functions
The SBGET functions are used for getting the data from the HPE
Shadowbase object (NonStop Consumer or Other Servers) into the
user exit for evaluation and or manipulation. The SBGET functions are
detailed below.
General Considerations for SBGET Functions:

Performance has been improved for user exits calling
SBGETBEFORECOLUMN and SBGETAFTERCOLUMN to retrieve
column data from inserts, uncompressed updates, and deletes for
SQL tables when the columns are not retrieved in the order they
appear in the schema. However, if the user exit accesses the columns
in strict schema order, the new algorithm introduces un-needed
overhead for performing the random lookups. The new algorithm can
be disabled and the overhead eliminated on a DBS by DBS basis
using the new DBS parameter USERGETSINORDER.

The new algorithm will not be enabled for a Consumer until a
SBGETxxxCOLUMN is made that gets a column out of schema order.
When an out of order “get” is detected, the algorithm will be globally
enabled for all schemas that do not have the USERGETSINORDER
parameter set.

Note that even with the performance enhancements, it is still more
efficient to get the columns in schema order than in an arbitrary order.
SBGETAFTERCOLUMN
This function is used in USRXPROCESS or USRXEXCEPTION to
retrieve the value for a field or column after it has been modified by an
application (yields the “after-image” of the field or column).
Product
Availability
Calling Module Usage
HPE Shadowbase Programming Manual—785431-007
66
User Exits
Step #2: Coding the Program
Product
HPE NonStop
Server
Other Servers
Availability
Yes
Yes
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
USRXPROCESS
USRXEXCEPTION
Syntax for COBOL Programmers
ENTER C "SBGETAFTERCOLUMN" IN USRXLIB
USING COL, IS-KEY, LEN, VAL
GIVING RETURN-CODE.
Syntax for C Programmers
short SBGETAFTERCOLUMN(char *col, short *is_key, short *len, char *val)
Parameters
RETURN-CODE
returned value

indicates whether call completed successfully or encountered an
error:
-1 = not available (can occur if Enscribe record is short or if API call
is used for a delete event). May also occur if update statement
does not contain column being captured by the SBGETAFTER call.
This is possible, for example, if AUDITCOMPRESS is enabled.
-2 = schema not available
-3 = bad column name format (column name must be null
terminated in API call)
-4 = column name not found in schema
0 = found null value (for SQL sources)
1 = value returned

If a column for an SQL source table has a null value, the length
returned is set to -1 and 0 is returned.
COL
input

Null terminated

Value in DDL or SQL format

Is the name of the field in the DDL record definition defined with the
DBS SOURCEREC parameter or the SQL column name.
IS-KEY
output

indicates whether field/column value returned is part of a record
key: 0 = column not part of a key, 1 = column is part of a key
LEN
output
HPE Shadowbase Programming Manual—785431-007
67
User Exits
Step #2: Coding the Program

Length of the field/column value returned.
VAL
output

data type must match that of field/column sought

size must be large enough to hold maximum returned value

The “after image” of the field/column sought.
Considerations

A value of -1 will be returned if attempting to read from a column
which is not involved in an auditcompressed update event.

Call the API with a null-terminated field or column name.

Field or column name can be in DDL (e.g., ABC-DEF) or SQL (e.g.,
ABC_DEF) format.

For Enscribe source files, auditcompress must be off.

For Enscribe source files, a DBS SOURCEREC DDL definition
must be configured.

Make sure that the data area for the value returned is large enough
to hold the entire contents of the returned column and that it is the
correct data type.

Not valid for delete events.
C Example
short return_code = 0;
short iskey = 0;
short len = 0;
char col[MAX_COLUMN_NAME];
char val[MAX_VALUE_LENGTH];
/* assign column name */
sprintf(col,”%s”,”ABC_COL1”);
return_code = SBGETAFTERCOLUMN (col,&iskey,&len,val);
SBGETAFTERCOLUMNINDEX
This API is used in USRXPROCESS or USRXEXCEPTION to retrieve
the value for a specified column via its ordinal position within the SQL
statement. This function differs from SBGETAFTERCOLUMN in that
you supply the ordinal index of the column whose value you wish to
retrieve from the statement rather than the column name. The ordinal
indices are relative to 1. Therefore, to retrieve the value of the first
column in the statement, you supply 1 as the desired ordinal index;
supply 2 for the second column value, and so on.
Product
HPE NonStop
Server
Other Servers
Availability
No
Yes
Calling Module Usage
N/A
USRXPROCESS
USRXEXCEPTION
HPE Shadowbase Programming Manual—785431-007
68
User Exits
Step #2: Coding the Program
Syntax for C Programmers
short SBGETAFTERCOLUMNINDEX(short idx,
char *col,
short *iskey,
short *len,
char *val);
Parameters
return_code
output

indicates whether call completed successfully or encountered an
error:
-4 = column not found in statement
0 = found null value (for SQL sources)
1 = value returned
idx

input
ordinal value of record to be returned
col

output
returns NULL terminated column name
iskey

returns 1 if column is part of primary key
len

val

output
output
returns the length in bytes of column value (val)
output
returns the character representation of the column value
Considerations

SBGETAFTERCOLUMNINDEX is only available in the Other
Servers environment.

SBGETAFTERCOLUMNINDEX supports insert, update and delete
events (begin, commit, abort events are not supported).

The column ordinal indices are relative to 1. To retrieve the value
of the first ordinal column in the statement, specify 1 as the index
parameter; specify 2, to retrieve the second ordinal column value,
and so on.

The column name that is returned is null terminated.
HPE Shadowbase Programming Manual—785431-007
69
User Exits
Step #2: Coding the Program




Where the ordinal column represents a key column, the iskey
parameter will return with a non-zero value.
Make sure that the val argument is defined large enough to hold the
maximum value that could be returned plus 1 (null byte).
If you attempt to retrieve a column value that is out of range,
return_code will be set to -4 (not found).
If the ordinal column value of the statement is found to be set to
NULL, the len parameter will return with -1 and the return code
value will be 0.
C Example
short return_code = 0;
short idx = 0;
short iskey = 0;
short len = 0;
char col[MAX_COLUMN_NAME];
char val[MAX_VALUE_LENGTH];
/* assign column ordinal index */
idx = 1;
return_code = SBGETAFTERCOLUMNINDEX (idx,col,&iskey,&len,val);
SBGETAFTERRECORD
This function can be called from USRXPROCESS or
USRXEXCEPTION to retrieve an after image of an Enscribe record
and its length into the user exit data space.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C "SBGETAFTERRECORD" IN USRXLIB
USING RECLEN, RECVALUE
GIVING RETURN-CODE.
Syntax for C Programmers
short SBGETAFTERRECORD(short *reclen ,char *recvalue)
Parameters
RETURN-CODE
returned value
HPE Shadowbase Programming Manual—785431-007
70
User Exits
Step #2: Coding the Program

Indicates whether call completed successfully or encountered an
error. Possible values: -1 = is not available,
1 = record returned.
RECLEN
output

The length of the record returned by HPE Shadowbase.
RECVALUE

Record returned by HPE Shadowbase.
output
Considerations

SBGETAFTERRECORD is only available in the NonStop
environment.

Only retrieve entire record if absolutely necessary. It is more
efficient to retrieve only the fields/columns you need.

Auditcompress must be off for the related source file.

Make sure that the data area for the returned record is large
enough.

Not valid for delete events

Enscribe only.
SBGETBEFORECOLUMN
This function can be called from USRXPROCESS or
USRXEXCEPTION to retrieve the value for a field or column before it
was altered by an application (yields before image of column).
Product
HPE NonStop
Server
Other Servers
Availability
Yes
Yes
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
USRXPROCESS
USRXEXCEPTION
Syntax for COBOL Programmers
ENTER C "SBGETBEFORECOLUMN" IN USRXLIB
USING COL, IS-KEY, LEN, VAL
GIVING RETURN-CODE.
Syntax for C Programmers
short SBGETBEFORECOLUMN(char *col, short *is_key, short *len, char *val)
Parameters
HPE Shadowbase Programming Manual—785431-007
71
User Exits
Step #2: Coding the Program
RETURN-CODE
returned value

indicates whether call completed successfully or encountered an
error:
-1 = not available
-2 = schema not available
-3 = bad column name format
-4 = column name not found in schema
0 = found null value (for SQL sources)
1 = value returned

If a column for an SQL source table has a null value, the length
returned is set to -1 and 0 is returned.
COL
input

Null terminated

Value in DDL or SQL format

The name of the field in the DDL record definition defined with the
DBS SOURCEREC parameter or the SQL column name.
IS-KEY
output

indicates whether field/column value returned is part of a record
key: 0 = column not part of a key, 1 = column is part of a key
LEN

Length of the field/column value returned.
output
VAL
output

The “before image” of the field/column sought.

must be large enough to hold the maximum value returned
Considerations

Called with a null-terminated field or column name.

A value of -1 will be returned if attempting to read from a column
which is not involved in an auditcompressed update event.

Column name in DDL (e.g., ABC-DEF) or SQL (e.g., ABC_DEF)
format.

BEFOREVALUES DBS parameter must be set to ON for the
related DBS.

Auditcompress must be off for Enscribe source files.

For Enscribe source files, DBS SOURCEREC DDL definition must
be configured.

The data area for the returned column value must be large enough
to hold the entire value and be the correct data type.

Not valid for insert events.
SBGETBEFORECOLUMNINDEX
HPE Shadowbase Programming Manual—785431-007
72
User Exits
Step #2: Coding the Program
This API is used in USRXPROCESS or USRXEXCEPTION to retrieve
the value for a specified column via its ordinal position within the SQL
statement. This function differs from SBGETBEFORECOLUMN in that
you supply the ordinal index of the column whose value you wish to
retrieve from the statement rather than the column name. The ordinal
indices are relative to 1. Therefore, to retrieve the value of the first
column in the statement, you supply 1 as the desired ordinal index;
supply 2 for the second column value, and so on.
Product
HPE NonStop
Server
Other Servers
Availability
No
Yes
Calling Module Usage
N/A
USRXPROCESS
USRXEXCEPTION
Syntax for C Programmers
short SBGETBEFORECOLUMNINDEX(short idx,
char *col,
short *iskey,
short *len,
char *val);
Parameters
return_code
output

indicates whether call completed successfully or encountered an
error:
-4 = column not found in statement
0 = found null value (for SQL sources)
1 = value returned
idx

input
ordinal value of record to be returned
col

output
returns NULL terminated column name
iskey

returns 1 if column is part of primary key
len

output
output
returns the length in bytes of column value (val)
HPE Shadowbase Programming Manual—785431-007
73
User Exits
Step #2: Coding the Program
val

output
returns the character representation of the column value
Considerations

SBGETBEFORECOLUMNINDEX is only available in the Other
Servers environment.

SBGETBEFORECOLUMNINDEX supports insert, update and
delete events (begin, commit, abort events are not supported).

The column ordinal indices are relative to 1. To retrieve the value
of the first ordinal column in the statement, specify 1 as the index
parameter; specify 2, to retrieve the second ordinal column value,
and so on.

The column name that is returned is null terminated.

Where the ordinal column represents a key column, the iskey
parameter will return with a non-zero value.

Make sure that the val argument is defined large enough to hold the
maximum value that could be returned plus 1 (null byte).

If you attempt to retrieve a column value that is out of range,
return_code will be set to -4 (not found).

If the ordinal column value of the statement is found to be set to
NULL, the len parameter will return with -1 and the return code
value will be 0.
C Example
short return_code = 0;
short idx = 0;
short iskey = 0;
short len = 0;
char col[MAX_COLUMN_NAME];
char val[MAX_VALUE_LENGTH];
/* assign column ordinal index */
idx = 1;
return_code = SBGETBEFORECOLUMNINDEX (idx,col,&iskey,&len,val);
SBGETBEFORERECORD
This API can be called from USRXPROCESS or USRXEXCEPTION to
retrieve the “before image” value of an Enscribe record and the
record’s length into the user exit.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
HPE Shadowbase Programming Manual—785431-007
74
User Exits
Step #2: Coding the Program
ENTER C "SBGETBEFORERECORD" IN USRXLIB
USING RECLEN, RECVALUE
GIVING RETURN-CODE.
Syntax for C Programmers
short SBGETBEFORERECORD(short *reclen, char *recvalue)
Parameters
RETURN-CODE
returned value

indicates whether call completed successfully or encountered an
error. Possible values:
-1 = is not available
0 = BEFOREVALUES not set to ON
1 = record returned
RECLEN
output

The length of the record returned by HPE Shadowbase.


RECVALUE
output
Data area must be large enough to hold entire record value.
The returned record.
Considerations

SBGETBEFORERECORD is only available in the NonStop
environment.

The BEFOREVALUES parameter must be set to ON for the related
DBS to make before records available.

Auditcompress must be off for the related source file.

Make sure that the data area for the return record is large enough.

Not valid for insert events.

Enscribe only.
SBGETCOLLISIONHANDLER
This function can be called to determine the value of the
COLLISIONHANDLER parameter associated with the DBS related to the
current event being processed by the user exit.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
Calling Module Usage
All
No
N/A
HPE Shadowbase Programming Manual—785431-007
75
User Exits
Step #2: Coding the Program
Syntax for COBOL Programmers
ENTER C "SBGETCOLLISIONHANDLER" IN USRXLIB
GIVING RETURN-CODE.
Syntax for C Programmers
s return_code = SBGETCOLLISIONHANDLER()
Parameters
RETURN-CODE
returned value
The function will return a 16-bit return code. The value 0, 1, or 2 may be
returned based upon the COLLISIONHANDLER value configured.
COBOL Usage Example:
.
WORKING-STORAGE
01 WS-ITEMS.
05 RETURN-CODE
PIC S9(4) COMP.
.
.
PROCEDURE DIVISION.
.
.
.
ENTER C "SBGETCOLLISIONHANDLER" IN USRXLIB
GIVING RETURN-CODE.
.
.
C Usage Example:
.
.
.
#include "usrxlib.h"
short return_code;
.
.
return_code = SBGETCOLLISIONHANDLER();
.
.
Considerations

SBGETCOLLISIONHANDLER is only available in the NonStop
environment.
SBGETCOLUMNOPEN
HPE Shadowbase Programming Manual—785431-007
76
User Exits
Step #2: Coding the Program
This API is used in USRXPROCESS or USRXEXCEPTION to retrieve
the value for a specified column.
Product
HPE NonStop
Server
Other Servers
Availability
No
Yes
Calling Module Usage
N/A
USRXPROCESS
USRXEXCEPTION
Syntax for C Programmers
short SBGETCOLUMNOPEN(char *col, short *iskey, short *len, char
*val);
Parameters
RETURN-CODE
output

indicates whether call completed successfully or encountered an
error:
-4 = column name not found in schema
0 = found null value (for SQL sources)
1 = value returned
col


input
column name
must be NULL terminated
iskey

returns 1 if column is part of primary key
len

val

output
output
returns the length in bytes of column value (val)
output
returns the character representation of the column value
Considerations

SBGETCOLUMNOPEN is only available in the Other Servers
environment.

SBGETCOLUMNOPEN supports insert, update and delete events
(begin, commit, abort events are not supported).

Make sure that the val argument is defined large enough to hold the
maximum value that could be returned plus 1 (null byte).
HPE Shadowbase Programming Manual—785431-007
77
User Exits
Step #2: Coding the Program


If you attempt to retrieve a column value for a column that is does
not exist in the underlying statement, the return code -4 (not found)
is returned.
If the specified column’s value for the statement is found to be set
to NULL, the len parameter will return with -1 and the return code
value will be 0.
SBGETCOLUMNOPENINDEX
This API is used in USRXPROCESS or USRXEXCEPTION to retrieve
the value for a specified column via its ordinal position within the SQL
statement. This function differs from SBGETCOLUMNOPEN in that
you supply the ordinal index of the column whose value you wish to
retrieve from the statement rather than the column name. The ordinal
indices are relative to 1. Therefore, to retrieve the value of the first
column in the statement, you supply 1 as the desired ordinal index;
supply 2 for the second column value, and so on.
Product
HPE NonStop
Server
Other Servers
Availability
No
Yes
Calling Module Usage
N/A
USRXPROCESS
USRXEXCEPTION
Syntax for C Programmers
short SBGETCOLUMNOPENINDEX(short index,
char *col,
short *iskey,
short *len,
char *val);
Parameters
RETURN-CODE
output

indicates whether call completed successfully or encountered an
error:
-4 = column not found in statement
0 = found null value (for SQL sources)
1 = value returned
index

ordinal value of record to be returned
input
HPE Shadowbase Programming Manual—785431-007
78
User Exits
Step #2: Coding the Program
col

output
returns NULL terminated column name
iskey

returns 1 if column is part of primary key
len

val

output
output
returns the length in bytes of column value (val)
output
returns the character representation of the column value
Considerations

SBGETCOLUMNOPENINDEX is only available in the Other
Servers environment.

SBGETCOLUMNOPENINDEX supports insert, update and delete
events (begin, commit, abort events are not supported).

The column ordinal indices are relative to 1. To retrieve the value
of the first ordinal column in the statement, specify 1 as the index
parameter; specify 2, to retrieve the second ordinal column value,
and so on.

The column name that is returned is null terminated.

Where the ordinal column represents a key column, the iskey
parameter will return with a non-zero value.

Make sure that the val argument is defined large enough to hold the
maximum value that could be returned plus 1 (null byte).

If you attempt to retrieve a column value that is out of range, the
return code -4 (not found) is returned.

If the ordinal column value of the statement is found to be set to
NULL, the len parameter will return with -1 and the return code
value will be 0.
SBGETCONNECTIONTYPE
This API is used by a user exit function to retrieve the
CONNECTIONTYPE CONS parameter setting. The value returned
tells whether the Consumer is a DIRECT Consumer (i.e., writes to
NonStop targets directly) or an Other Servers Consumer (i.e., sends
SQL statement text via TCP/IP on a network).
For Other Servers implementations, this API returns 1 = Other Servers
environment always.
Product
HPE NonStop
Server
Availability
Yes
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
HPE Shadowbase Programming Manual—785431-007
79
User Exits
Step #2: Coding the Program
Product
Other Servers
Availability
Yes
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
Syntax for COBOL Programmers
ENTER C "SBGETCONNECTIONTYPE" IN USRXLIB
GIVING RETURN-CODE.
Syntax for C Programmers
short SBGETCONNECTIONTYPE(void)
Parameters
RETURN-CODE
returned value

Indicates whether call completed successfully or encountered an
error. Possible values:
0 = direct environment,
1 = Other Servers environment
Examples
C Example
short return_code;
return_code = SBGETCONNECTIONTYPE();
SBGETDBSNAME
This user exit API will return the DBS object name value associated with the
current event. The value will be null-terminated. The short return value will
be the length, excluding the null terminator. If a DBS is not in focus at this
time, 0 will be returned for the length. Note that the DBS object name can be
up to 16 bytes. Allocate one extra byte for the null terminator.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
All
Calling Module Usage
No
N/A
COBOL Usage Example:
HPE Shadowbase Programming Manual—785431-007
80
User Exits
Step #2: Coding the Program
WORKING-STORAGE.
01 WS-ITEMS.
05 WS-DBS-NAME-LEN
05 WS-DBS-NAME
PIC S9(4) COMP.
PIC X(17).
PROCEDURE DIVISION.
ENTER C "SBGETDBSNAME" IN USRXLIB
USING WS-DBS-NAME
GIVING WS-DBS-NAME-LEN.
C Usage Example:
#include "usrxlib.h"
short dbs_name_len;
char dbs_name[17];
dbs_name_len = SBGETDBSNAME(&dbs_name);
SBGETDBSPARM
The SBGETDBSPARM function returns the configured text value for a DBS
parameter. Typically, it would be called from the USRXADDDBS entry-point
function, but can be called from USRXPROCESS as well. Note that
SBGETDBSNAME can be called to determine which DBS object is current.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXADDDBS
USRXPROCESS
N/A
Syntax for COBOL Programmers
HPE Shadowbase Programming Manual—785431-007
81
User Exits
Step #2: Coding the Program
WORKING-STORAGE.
01 WS-ITEMS.
05 DBS-OBJECT-NAME
05 DBS-OBJECT-NAME-LEN
05 DBS-SRCFILE-PNAME.
10 DBS-SRCEFILE-PNAME-VAL
10 FILLER
05 DBS-SRCFILE-RETURN.
10 DBS-SRCFILE-TEXT-VAL
10 DBS-SRCFILE-TEXT-VAL-LEN
10 DBS-SRCFILE-TEXT-VAL-MAX
PIC X(18).
PIC S9(4) COMP.
PIC X(10) VALUE “SOURCEFILE”.
PIC X
VALUE LOW-VALUES.
PIC X(40) VALUE LOW-VALUES.
PIC S9(4) COMP.
PIC S9(4) COMP VALUE 36.
05 RTRN-CD NATIVE-2.
PROCEDURE DIVISION.
.
.
.
ENTER C “SBGETDBSNAME” IN USRXLIB
USING DBS-OBJECT-NAME
GIVING WS-RTRN-CD.
.
.
.
ENTER C “SBGETDBSPARM” IN USRXLIB
USING DBS-SRCFILE-NAME, DBS-SRCFILE-TEXT-VAL-MAX,
DBS-SRCFILE-TEXT-VAL, DBS-SRCFILE-TEXT-VAL-LEN
GIVING RTRN-CD.
.
.
.
Syntax for C Programmers
char
short
dbs_object_name[18];
dbs_object_name_len;
char
short
dbs_srcfile_text_val[40];
dbs_srcfile_text_val_len;
short
rtrn_cd;
.
.
.
rtrn_cd = SBGETDBSNAME(dbs_object_name,&dbs_object_name_len);
.
.
.
rtrn_cd = SBGETDBSPARM(“SOURCEFILE”,sizeof(dbs_srcfile_text_val),
dbs_srcfile_text_val,&dbs_srcfile_text_val_len);
.
.
.
Parameters
DBS-PARM-NAME
input
The name of the DBS parameter for which the configured value is to be
returned.
MAX-RETURN-VAL-LEN
input
HPE Shadowbase Programming Manual—785431-007
82
User Exits
Step #2: Coding the Program
The maximum length to be returned.
DBS-PARM-VAL
The returned parameter text value.
output
DBS-PARM-VAL-LEN
The length of the returned value.
output
RETURN-CODE
The outcome of the SBGETDBSPARM call:
-4 = Parameter name is not a DBS parameter.
-1 = Parameter content is not available now.
0 = Parameter text value returned but truncated because maximum
length not enough.
1 = Parameter text value returned along with the length.
Considerations

At this time, the following parameters are not available from
SBUSRXPROCESS (during replication): PULSEFILEPURGE,
ROOTPARTITION, SOLVMGRNAME, SOURCEFILEEXTENT, and
TARGETFILEEXTENT. The return code will be set to -1.
SBGETENV
This user exit API will return the value of the environment variable specified in
the argument. It will first look in the SHADPARM.INI file, if the variable is not
present, it will check the session’s environment variables. If not found, it will
return NULL. See the note below for specific considerations on the NonStop.
Product
HPE NonStop
Server
Other Servers
Availability
No
Calling Module Usage
N/A
Yes
All
C Usage Example:
#include "usrxlib.h"
char
char
param_name[17];
*param_val;
param_val = SBGETENV(param_name);
Considerations

For NonStop environment variables, reference the API call
SBGETDBSPARM for a DBS level specific mechanism for passing
HPE Shadowbase Programming Manual—785431-007
83
User Exits
Step #2: Coding the Program
PARAM values into User Exits. TACL PARAM methodology is also
supported by some programming languages on the NonStop as
well.
SBGETEVENTADTDATA
This user exit API function was added in release 3.970 in September
2005. Call this function from a user exit to obtain information about a
TMF audit trail event. It will return the following information: audit trail
prefix (i.e., “AA” for master or “BB” through “PP” for an auxiliary), audit
trail event sequence number, audit trail event relative byte address
(now 64 bits), related master audit trail sequence number, related
master audit trail relative byte address, event transaction identifier, and
audit trail event Greenwich mean timestamp.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
Calling Module Usage
All
No
N/A
Syntax for COBOL Programmers
ENTER C "SBGETEVENTADTDATA" IN USRXLIB
USING PREFIX OF ADT-EVENT-INFO,
SEQNO OF ADT-EVENT-INFO,
RBA OF ADT-EVENT-INFO,
MAT-SEQNO OF ADT-EVENT-INFO,
MAT-RBA OF ADT-EVENT-INFO,
TRANSID OF ADT-EVENT-INFO,
TIMESTAMP OF ADT-EVENT-INFO.
.
Syntax for C Programmers
SBGETEVENTADTDATA(&prefix,&seqno,&rba,&mat_seqno,&mat_rba,
&transid,&timestamp);
Parameters
COBOL Usage Example:
HPE Shadowbase Programming Manual—785431-007
84
User Exits
Step #2: Coding the Program
WORKING-STORAGE.
01 WS-ITEMS.
05 ADT-EVENT-INFO.
10 PREFIX
PIC XX.
10 SEQNO
PIC S9(6) COMP.
10 RBA
PIC S9(18) COMP.
10 MAT-SEQNO
PIC S9(6) COMP.
10 MAT-RBA
PIC S9(18) COMP.
10 TRANSID
PIC S9(18) COMP.
10 TIMESTAMP
PIC S9(18) COMP.
.
PROCEDURE DIVISION...
.
.
.
ENTER C "SBGETEVENTADTDATA" IN USRXLIB
USING PREFIX OF ADT-EVENT-INFO,
SEQNO OF ADT-EVENT-INFO,
RBA OF ADT-EVENT-INFO,
MAT-SEQNO OF ADT-EVENT-INFO,
MAT-RBA OF ADT-EVENT-INFO,
TRANSID OF ADT-EVENT-INFO,
TIMESTAMP OF ADT-EVENT-INFO.
.
.
.
C Usage Example:
.
.
#include "usrxlib.h"
char
prefix[2];
long
seqno;
long long rba;
long
mat_seqno;
long long mat_rba;
long long transid;
long long timestamp;
.
.
.
SBGETEVENTADTDATA(&prefix,&seqno,&rba,&mat_seqno,&mat_rba,
&transid,&timestamp);
.
.
.
Considerations

SBGETEVENTADTDATA is only available in the NonStop
environment.
SBGETEVENTSYSTEMNO
This function can be called to determine the 32-bit system number for
the audit trail event associated with the original source file or table.
Product
HPE NonStop
Server
Availability
Yes
Calling Module Usage
All
HPE Shadowbase Programming Manual—785431-007
85
User Exits
Step #2: Coding the Program
Product
Other Servers
Availability
No
Calling Module Usage
N/A
Syntax for COBOL Programmers
ENTER C "SBGETEVENTSYSTEMNO" IN USRXLIB
GIVING SYSTEM-NO.
Syntax for C Programmers
system_no = SBGETEVENTSYSTEMNO();
Parameters
SYSTEM-NO
returned value
The system number or -1 is returned if this function is called when an
event is not within its scope.
COBOL Usage Example:
.
.
WORKING-STORAGE.
COPY SB-USRXPROCESS-INFO OF "USRXCOPY".
COPY SB-COLUMN-INFO OF "USRXCOPY".
01 WS-ITEMS.
05 SYSTEM-NO
PIC S9(9) COMP.
.
.
.
.
PROCEDURE DIVISION.
.
.
ENTER C "SBGETEVENTSYSTEMNO" IN USRXLIB
GIVING SYSTEM-NO.
.
.
C Usage Example:
.
.
.
#include "usrxlib.h"
long system_no;
.
.
system_no = SBGETEVENTSYSTEMNO();
.
.
Considerations

SBGETEVENTSYSTEMNO is only available in the NonStop
environment.
HPE Shadowbase Programming Manual—785431-007
86
User Exits
Step #2: Coding the Program
SBGETEVENTTIME
This function can be called from USRXPROCESS or
USRXEXCEPTION to obtain the original event timestamp as read from
the audit trail.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C "SBGETEVENTTIME" IN USRXLIB
GIVING EVENT-TIMESTAMP.
Syntax for C Programmers
long long SBGETEVENTTIME(void)
Parameters
EVENT-TIMESTAMP
returned value

Time the event occurred as appears in audit trail
Considerations

SBGETEVENTTIME is only available in the HPE NonStop
environment.

Returns the 64-bit integer (NATIVE-8) Greenwich Mean Time in the
function return argument.

Guardian call for interpreting timestamp is
INTERPRETTIMESTAMP.
SBGETFILECLOSEDELAY
The user exit API function SBGETFILECLOSEDELAY is used to
retrieve the CONS FILECLOSEDELAY parameter value.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
All
Calling Module Usage
No
N/A
Syntax for COBOL Programmers
HPE Shadowbase Programming Manual—785431-007
87
User Exits
Step #2: Coding the Program
ENTER C "SBGETFILECLOSEDELAY" IN USRXLIB
GIVING WS-RETURN-VAL.
Syntax for C Programmers
short SBGETFILECLOSEDELAY (void)
Examples
COBOL Example
WORKING-STORAGE.
01 WS-ITEMS.
05 WS-RETURN-VAL
PIC S9(4) COMP.
PROCEDURE DIVISION.
ENTER C "SBGETFILECLOSEDELAY" IN USRXLIB
GIVING WS-RETURN-VAL.
C Example
#include "usrxlib.h"
short return_val;
return_val=SBGETFILECLOSEDELAY();
Considerations

SBGETFILECLOSEDELAY is only available in the NonStop
environment.
SBGETFILEDDLDELAY
The user exit API function SBGETFILEDDLDELAY is used to retrieve
the CONS FILEDDLDELAY parameter value.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
All
Calling Module Usage
No
N/A
Syntax for COBOL Programmers
ENTER C " SBGETFILEDDLDELAY " IN USRXLIB
GIVING WS-RETURN-VAL.
HPE Shadowbase Programming Manual—785431-007
88
User Exits
Step #2: Coding the Program
Syntax for C Programmers
Short
SBGETFILEDDLDELAY (void)
Examples
COBOL Example
WORKING-STORAGE.
01 WS-ITEMS.
05 WS-RETURN-VAL
PIC S9(4) COMP.
PROCEDURE DIVISION.
ENTER C "SBGETFILEDDLDELAY" IN USRXLIB
GIVING WS-RETURN-VAL.
C Example
#include "usrxlib.h"
short return_val;
return_val=SBGETFILEDDLDELAY();
Considerations

SBGETFILEDDLDELAY is only available in the NonStop
environment.
SBGETFILEDDLRETRIES
The user exit API function SBGETFILEDDLRETRIES is used to
retrieve the CONS FILEDDLRETRIES parameter value.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C " SBGETFILEDDLRETRIES " IN USRXLIB
GIVING WS-RETURN-VAL.
Syntax for C Programmers
HPE Shadowbase Programming Manual—785431-007
89
User Exits
Step #2: Coding the Program
Short
SBGETFILEDDLRETRIES (void)
Examples
COBOL Example
WORKING-STORAGE.
01 WS-ITEMS.
05 WS-RETURN-VAL
PIC S9(4) COMP.
PROCEDURE DIVISION.
ENTER C "SBGETFILEDDLRETRIES" IN USRXLIB
GIVING WS-RETURN-VAL.
C Example
#include "usrxlib.h"
short return_val;
return_val=SBGETFILEDDLRETRIES();
Considerations

SBGETFILEDDLRETRIES is only available in the NonStop
environment.
SBGETKEYSPECIFIER
The SBGETKEYSPECIFIER user exit API function is used to obtain
the DBS KEYSPECIFIER parameter value (a 2-byte value). It returns
a short (2-byte) value.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C " SBGETKEYSPECIFIER " IN USRXLIB
GIVING WS-RETURN-VAL.
Syntax for C Programmers
HPE Shadowbase Programming Manual—785431-007
90
User Exits
Step #2: Coding the Program
short ws_key_specifier;
ws_key_specifier = SBGETKEYSPECIFIER (void);
Examples
COBOL Example
WORKING-STORAGE.
01 WS-ITEMS.
05 WS-KEY-SPECIFIER
PIC S9(4) COMP.
PROCEDURE DIVISION.
ENTER C "SBGETKEYSPECIFIER" IN USRXLIB
GIVING WS-KEY-SPECIFIER.
C Example
#include "usrxlib.h"
short key_specifier;
key_specifier=SBGETKEYSPECIFIER();
Considerations

SBGETKEYSPECIFIER is only available in the NonStop
environment.
SBGETMAPTOFILE
The user exit API function SBGETMAPTOFILE has been added to
identify the MAPTOFILE value as set on the HPE NonStop source
node. Note that SBGETMAPTOFILE will return the source file name if
a MAPTOFILE DBS parameter is not used.
Product
HPE NonStop
Server
Other Servers
Server
Availability
Yes
All
Calling Module Usage
No
N/A
Syntax for COBOL Programmers
ENTER C "SBGETMAPTOFILE" IN USRXLIB
USING FILE-ATTR.
GIVING FILE-NAME-LENGTH.
Syntax for C Programmers
HPE Shadowbase Programming Manual—785431-007
91
User Exits
Step #2: Coding the Program
short SBGETMAPTOFILE (SB_FILE_ATTRIBUTES_DEF *file_attr)
Parameters
FILE-NAME-LENGTH
returned value

The <file name length> is the length of the file name.
FILE-ATTR
output

consists of the following:
o File name: The file name is in external NonStop format (i.e.,
the file name that has periods to separate the node, volume,
subvolume, and file name)
o File type: Valid values include the following:
-1 = unknown
0 = Enscribe file
1 = SQL table
o File subtype: Valid values include the following:
-1 = unknown
0=
unstructured file
1 = relative file
2 = entry-sequenced file
3 = key sequenced
Examples
COBOL Example
WORKING-STORAGE.
COPY SB-FILE-ATTRIBUTES OF "USRXCOPY".
01
SB-FILE-NAME-LENGTH
PIC S9(4) COMP.
PROCEDURE DIVISION.
ENTER C "SBGETMAPTOFILE" IN USRXLIB
USING SB-FILE-ATTRIBUTES
GIVING SB-FILE-NAME-LENGTH.
C Example
SB_FILE_ATTRIBUTES_DEF sb_file;
short
sb_file_name_length;
sb_file_name_length =
SBGETMAPTOFILE((SB_FILE_ATTRIBUTES_DEF *)&sb_file);
Considerations

SBGETEVENTTIME is only available in the NonStop environment.
HPE Shadowbase Programming Manual—785431-007
92
User Exits
Step #2: Coding the Program





SBGETMAPTOFILE will fill in the content of SB-FILE-ATTRIBUTES
for COBOL programs and SB_FILE_ATTRIBUTES_DEF for C
programs.
The file name is in external NonStop format (i.e., the file name that
has periods to separate the node, volume, subvolume, and file
name). See the files USRXCOPY and USRXLIBH in your
installation subvolume for the content of these structures.
The file name returned by SBGETMAPTOFILE will contain the
node name.
Note that SBGETMAPTOFILE will return the value 0 if it can't
determine the MAPTOFILE file name. Otherwise, it returns the
length of the file name.
Also note that the file name is padded with blanks and not null
terminated.
SBGETMXPATHNAME
The user exit API function SBGETMXPATHNAME has been added to obtain
the DBS MXPATHNAME parameter value that is associated with the current
event being processed by a Consumer.
A null-terminated path name is returned along with the length of the string in
the function return. -1 will be returned for the length if MXPATHNAME is not
set for the related DBS object. Make sure that you have defined enough space
for the string to be returned to your program.
Product
HPE NonStop
Server
Other Servers
Server
Availability
Yes
All
Calling Module Usage
No
N/A
Syntax for COBOL Programmers
ENTER C "SBGETMXPATHNAME" IN USRXLIB USING PATH-NAME
GIVING PATH-NAME-LEN.
Syntax for C Programmers
path_name_len = SBGETMXPATHNAME((char *)&path_name);
COBOL Usage Example:
HPE Shadowbase Programming Manual—785431-007
93
User Exits
Step #2: Coding the Program
.
.
WORKING-STORAGE.
01 WS-ITEMS.
05 PATH-NAME-LEN
05 PATH-NAME
PIC S9(4) COMP.
PIC X(387).
PROCEDURE DIVISION.
.
.
.
ENTER C "SBGETMXPATHNAME" IN USRXLIB USING PATH-NAME
GIVING PATH-NAME-LEN.
.
.
.
C Usage Example:
#include "usrxlib.h"
short path_name_len;
char path_name[387];
.
.
.
path_name_len = SBGETMXPATHNAME((char *)&path_name);
.
.
.
Considerations

SBGETMXPATHNAME is only available in the NonStop
environment.
SBGETMXSOURCE
The user exit API function SBGETMXSOURCE has been added to obtain the
DBS MXSOURCETABLE parameter value that is associated with the current
event being processed by a Consumer.
A null-terminated table name is returned along with the length of the string in
the function return. -1 will be returned for the length if MXSOURCETABLE is
not set for the related DBS object. Make sure that you have defined enough
space for the string to be returned to your program.
Product
HPE NonStop
Server
Other Servers
Server
Availability
Yes
Calling Module Usage
All
No
N/A
Syntax for COBOL Programmers
HPE Shadowbase Programming Manual—785431-007
94
User Exits
Step #2: Coding the Program
ENTER C "SBGETMXSOURCE" IN USRXLIB USING SRC-NAME
GIVING SRC-NAME-LEN.
Syntax for C Programmers
src_name_len = SBGETMXSOURCE((char *)&src_name);
COBOL Usage Example:
.
.
WORKING-STORAGE.
01 WS-ITEMS.
05 SRC-NAME-LEN
05 SRC-NAME
PIC S9(4) COMP.
PIC X(387).
PROCEDURE DIVISION.
.
.
.
ENTER C "SBGETMXSOURCE" IN USRXLIB USING SRC-NAME
GIVING SRC-NAME-LEN.
.
.
.
C Usage Example:
#include "usrxlib.h"
short src_name_len;
char src_name[387];
.
.
.
src_name_len = SBGETMXSOURCE((char *)&src_name);
.
.
.
Considerations

SBGETMXSOURCE is only available in the NonStop environment.
SBGETMXTARGET
The user exit API function SBGETMXTARGET has been added to obtain the
DBS MXTARGETTABLE parameter value that is associated with the current
event being processed by a Consumer.
A null-terminated table name is returned along with the length of the string in
the function return. -1 will be returned for the length if MXTARGETTABLE is
HPE Shadowbase Programming Manual—785431-007
95
User Exits
Step #2: Coding the Program
not set for the related DBS object. Make sure that you have defined enough
space for the string to be returned to your program.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
Calling Module Usage
All
No
N/A
Syntax for COBOL Programmers
ENTER C "SBGETMXTARGET" IN USRXLIB USING TRG-NAME
GIVING TRG-NAME-LEN.
Syntax for C Programmers
trg_name_len = SBGETMXTARGET((char *)&trg_name);
COBOL Usage Example:
.
.
WORKING-STORAGE.
01 WS-ITEMS.
05 TRG-NAME-LEN
05 TRG-NAME
PIC S9(4) COMP.
PIC X(387).
PROCEDURE DIVISION.
.
.
.
ENTER C "SBGETMXTARGET" IN USRXLIB USING TRG-NAME
GIVING TRG-NAME-LEN.
.
.
.
C Usage Example:
#include "usrxlib.h"
short trg_name_len;
char trg_name[387];
.
.
.
trg_name_len = SBGETMXTARGET((char *)&trg_name);
.
.
.
Considerations

SBGETMXTARGET is only available in the NonStop environment.
HPE Shadowbase Programming Manual—785431-007
96
User Exits
Step #2: Coding the Program
SBGETNEXTAFTERCOLUMNINFO
Related to an SQL after image for a compressed update, this function will fill in
SB_COLUMN_INFO_DEF with the schema information about the first key or
change fragment associated with the audit trail event. For C, see the usrxlibh
file for the content of the new SB_COLUMN_INFO_DEF structure. For
COBOL, see the usrxcopy file for the content of the new SB-COLUMN-INFO
definition. Note that the col_name field (COL-NAME for COBOL) will be null
terminated and can subsequently be used to call other SBGET...COLUMN...
functions. Also, note that the content is filled in from the schema associated
with the related SQL table.
SQL compressed updates only contain the key columns and columns that
have changed. This function is designed to return the first or next key or
change fragment (column). To get the first fragment, set the column number
to -1 as input in the SB_COLUMN_INFO_DEF structure from usrxlib.h (you
pass a pointer to the structure defined in your user exit code space). To get
the next fragment, don't set the column number prior to calling
SBGETNEXTAFTERCOLUMNINFO. When no more fragments are available
(i.e., after they have all been returned), the return code will be 0. Note that
you can call SBISSQLSOURCE and SBISCOMPRESSEDUPDATE to
determine if an event is an SQL compressed update.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C "SBGETNEXTAFTERCOLUMNINFO" IN USRXLIB
USING SB-COLUMN-INFO
GIVING CI-RETURN-CODE.
Syntax for C Programmers
ci_return_code = SBGETNEXTAFTERCOLUMNINFO(&usrx_col_info);
Parameters
CI-RETURN-CODE
returned value
The function will return a 16-bit return code. The following values are
possible:
-4 = the current event is not an SQL compressed update.
-3 = the after image is not available.
-2 = schema is not available.
HPE Shadowbase Programming Manual—785431-007
97
User Exits
Step #2: Coding the Program
-1 = invalid col_num specified in SB_COLUMN_INFO_DEF on input.
0 = no more fragments to return.
1 = column information returned in SB_COLUMN_INFO_DEF.
SB-COLUMN-INFO

Gives column information returned.
output
COBOL Usage Example:
.
.
WORKING-STORAGE.
COPY SB-USRXPROCESS-INFO OF "USRXCOPY".
COPY SB-COLUMN-INFO OF "USRXCOPY".
01 WS-ITEMS.
05 CI-RETURN-CODE
PIC S9(4) COMP
PROCEDURE DIVISION.
MOVE 1 TO CI-RETURN-CODE.
MOVE -1 TO COL-NUM OF SB-COLUMN-INFO.
PERFORM 0300-GET-AFTER-FRAGMENT THRU 0399-EXIT
UNTIL CI-RETURN-CODE < 1.
0300-GET-AFTER-FRAGMENT.
ENTER C "SBGETNEXTAFTERCOLUMNINFO" IN USRXLIB
USING SB-COLUMN-INFO
GIVING CI-RETURN-CODE.
IF CI-RETURN-CODE LESS THAN 1
GO TO 0399-EXIT.
0399-EXIT.
EXIT.
C Usage Example:
HPE Shadowbase Programming Manual—785431-007
98
User Exits
Step #2: Coding the Program
.
..
#include "usrxlib.h"
SB_COLUMN_INFO_DEF usrx_col_info;
short ci_return_code;
.
.
usrx_col_info.col_num = -1;
ci_return_code = 1;
while (ci_return_code > 0) {
ci_return_code = SBGETNEXTAFTERCOLUMNINFO(&usrx_col_info);
if (ci_return_code < 1) { /* error situation */ }
if (ci_return_code == 0) { /* no more to return */ }
if (ci_return_code > 1) { /* info returned */ }
.
.
++usrx_col_info.col_num;
}
Considerations

SBGETNEXTAFTERCOLUMNINFO is only available in the
NonStop environment.
SBGETNEXTBEFORECOLUMNINFO
Related to an SQL before image for a compressed update, this function will fill
in SB_COLUMN_INFO_DEF with the schema information about the first key
or change fragment associated with the audit trail event. For C, see the
usrxlibh file for the content of the new SB_COLUMN_INFO_DEF structure.
For COBOL, see the usrxcopy file for the content of the new SB-COLUMNINFO definition. Note that the col_name field (COL-NAME for COBOL) will be
null terminated and can subsequently be used to call other
SBGET...COLUMN... functions. Also, note that the content is filled in from the
schema associated with the related SQL table.
SQL compressed updates only contain the key columns and columns that
have changed. This function is designed to return the first or next key or
change fragment (column). To get the first fragment, set the column number
to -1 as input in the SB_COLUMN_INFO_DEF structure from usrxlib.h (you
pass a pointer to the structure defined in your user exit code space). To get
the next fragment, don't set the column number prior to calling
SBGETNEXTBEFORECOLUMNINFO. When no more fragments are
available
(i.e., after they have all been returned), the return code will be 0. Note that
you can call SBISSQLSOURCE and SBISCOMPRESSEDUPDATE to
determine if an event is an SQL compressed update.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
HPE Shadowbase Programming Manual—785431-007
99
User Exits
Step #2: Coding the Program
Syntax for COBOL Programmers
ENTER C "SBGETNEXTBEFORECOLUMNINFO" IN USRXLIB
USING SB-COLUMN-INFO
GIVING CI-RETURN-CODE
Syntax for C Programmers
ci_return_code = SBGETNEXTBEFORECOLUMNINFO(&usrx_col_info);
Parameters
CI-RETURN-CODE
returned value
The function will return a 16-bit return code. The following values are
possible:
-4 = the current event is not an SQL compressed update.
-3 = the before image is not available.
-2 = schema is not available.
-1 = invalid col_num specified in SB_COLUMN_INFO_DEF on input.
0 = no more fragments to return.
1 = column information returned in SB_COLUMN_INFO_DEF.
SB-COLUMN-INFO

Gives column information returned.
output
COBOL Usage Example:
HPE Shadowbase Programming Manual—785431-007
100
User Exits
Step #2: Coding the Program
.
.
WORKING-STORAGE.
COPY SB-USRXPROCESS-INFO OF "USRXCOPY".
COPY SB-COLUMN-INFO OF "USRXCOPY".
01 WS-ITEMS.
05 CI-RETURN-CODE
PIC S9(4) COMP
PROCEDURE DIVISION.
MOVE 1 TO CI-RETURN-CODE.
MOVE -1 TO COL-NUM OF SB-COLUMN-INFO.
PERFORM 0200-GET-BEFORE-FRAGMENT THRU 0299-EXIT
UNTIL CI-RETURN-CODE < 1.
0200-GET-BEFORE-FRAGMENT.
ENTER C "SBGETNEXTBEFORECOLUMNINFO" IN USRXLIB
USING SB-COLUMN-INFO
GIVING CI-RETURN-CODE.
IF CI-RETURN-CODE LESS THAN 1
GO TO 0299-EXIT.
0299-EXIT.
EXIT.
C Usage Example:
.
..
#include "usrxlib.h"
SB_COLUMN_INFO_DEF usrx_col_info;
short ci_return_code;
.
.
usrx_col_info.col_num = -1;
ci_return_code = 1;
while (ci_return_code > 0) {
ci_return_code = SBGETNEXTBEFORECOLUMNINFO(&usrx_col_info);
if (ci_return_code < 1) {
if (ci_return_code != 0) /* error situation? */
}
continue;
}
++usrx_col_info.col_num;
}
Considerations

SBGETNEXTBEFORECOLUMNINFO is only available in the
NonStop environment.
SBGETOPENID
HPE Shadowbase Programming Manual—785431-007
101
User Exits
Step #2: Coding the Program
For Other Servers environment Consumers, this function is called by a
user exit to retrieve the NETADDRESS and NETPORT parameter
settings. This might be used to identify a particular node in a network
for selective shadowing purposes.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
All
Calling Module Usage
Yes
All
Syntax for COBOL Programmers
ENTER C "SBGETOPENID" IN USRXLIB
USING OPEN-ID-INFO
GIVING RETURN-CODE.
Syntax for C Programmers
short SBGETOPENID(SB_OPEN_ID_DEF *open_id_info)
Parameters
RETURN-CODE
returned value

Indicates whether call completed successfully or encountered an
error. Possible values:
-1 = is not Other Servers environment,
1 = information returned.
-100 = Functionality ‘Not Implemented’.
OPEN-ID-INFO

Contains IP address and net port address.
output
SB-OPEN-ID-INFO.
05 NET-IP-ADDR
PIC X(50).
05 NET-PORT PIC X(5).
typedef struct {
char net_ip_addr[50];
char net_port[5];
} SB_OPEN_ID_DEF;
Examples
C Example
HPE Shadowbase Programming Manual—785431-007
102
User Exits
Step #2: Coding the Program
short
rtrn_cd;
SB_OPEN_ID_DEF sb_open_id;
rtrn_cd = SBGETOPENID(&sb_open_id);
Considerations

For COBOL callers it returns the SB-OPEN-ID-INFO data area that
can be copied from the USRXCOPY file.

For C callers, it returns a structure of type SB_OPEN_ID_DEF that
is included from the USRXLIBH file.

For Other Servers, this API has no implementation. It always
returns with SB_RC_NOT_IMPLEMENTED (-100).
SBGETPATHNAME
This user exit API function will return the DBS PATHNAME parameter value
associated with the current event. The value will be null-terminated. The
short return value will be the length, excluding the null terminator. If a
PATHNAME is not in focus at this time or does not have a value, 0 will be
returned for the length. Note that the PATHNAME value can be up to 80
bytes. Allocate one extra byte for the null terminator.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
Calling Module Usage
All
No
N/A
COBOL Usage Example:
WORKING-STORAGE.
01 WS-ITEMS.
05 WS-PATHNAME-LEN
05 WS-PATHNAME
PIC S9(4) COMP.
PIC X(81).
PROCEDURE DIVISION.
ENTER C "SBGETPATHNAME" IN USRXLIB
USING WS-PATHNAME
GIVING WS-PATHNAME-LEN.
C Usage Example:
#include "usrxlib.h"
short pathname_len;
char pathname[81];
pathname_len=SBGETPATHNAME((char *)&pathname);
SBGETPURGEIFEXISTS
HPE Shadowbase Programming Manual—785431-007
103
User Exits
Step #2: Coding the Program
The user exit API function SBGETPURGEIFEXISTS is used to retrieve
the CONS PURGEIFEXISTS parameter value.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
Calling Module Usage
All
No
N/A
Syntax for COBOL Programmers
ENTER C "SBGETPURGEIFEXISTS" IN USRXLIB
GIVING WS-RETURN-VAL.
Syntax for C Programmers
short SBGETPURGEIFEXISTS (void)
Examples
COBOL Example
WORKING-STORAGE.
01 WS-ITEMS.
05 WS-RETURN-VAL
PIC S9(4) COMP.
PROCEDURE DIVISION.
ENTER C "SBGETPURGEIFEXISTS" IN USRXLIB
GIVING WS-RETURN-VAL.
C Example
#include "usrxlib.h"
short return_val;
return_val=SBGETPURGEIFEXISTS();
Considerations

SBGETPURGEIFEXISTS is only available in the NonStop
environment.
SBGETREALSOURCE
SBGETREALSOURCE will fill in the content of SB-FILE-ATTRIBUTES
for COBOL programs and SB_FILE_ATTRIBUTES_DEF for C
programs.
HPE Shadowbase Programming Manual—785431-007
104
User Exits
Step #2: Coding the Program
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C "SBGETREALSOURCE" IN USRXLIB
USING SB-FILE
GIVING SB-FILE-NAME-LENGTH.
Syntax for C Programmers
short SBGETREALSOURCE (SB_FILE_ATTRIBUTES_DEF *sb_file)
Parameters
SB-FILE-NAME-LENGTH
returned value

returns length of file name or 0 if it cannot determine the real
source file name

Returns file name, file type (-1=unknown or SQL/MX table,
0=Enscribe, 1=SQL), and file subtype (-1=unknown,
0=unstructured, 1=relative, 2=entry-sequenced, 3=key sequenced)
SB-FILE
output
SB-FILE-ATTRIBUTES.
05 FILE-NAME PIC X(36).
05 FILE-TYPE PIC S9(4) COMP.
88 UNKNOWN-FILE-TYPE VALUE -1.
88 ENSCRIBE-FILE VALUE 0.
88 SQL-TABLE VALUE 1.
05 FILE-SUBTYPE PIC S9(4) COMP.
88 UNKNOWN-FILE-SUBTYPE VALUE -1.
88 UNSTRUCTURED-TYPE VALUE 0.
88 RELATIVE-TYPE VALUE 1.
88 ENTRY-SEQUENCED-TYPE VALUE 2.
88 KEY-SEQUENCED-TYPE VALUE 3.
typedef struct {
char file_name[36];
short file_type;
short file_subtype;
} SB_FILE_ATTRIBUTES_DEF;
HPE Shadowbase Programming Manual—785431-007
105
User Exits
Step #2: Coding the Program
Examples
COBOL Example
WORKING-STORAGE.
COPY SB-FILE-ATTRIBUTES OF "USRXCOPY".
01 SB-FILE-NAME-LENGTH
PIC S9(4) COMP.
PROCEDURE DIVISION.
ENTER C "SBGETREALSOURCE" IN USRXLIB
USING SB-FILE-ATTRIBUTES
GIVING SB-FILE-NAME-LENGTH.
C Example
SB_FILE_ATTRIBUTES_DEF
short
sb_file;
sb_file_name_length;
sb_file_name_length =
SBGETREALSOURCE((SB_FILE_ATTRIBUTES_DEF)&sb_file);
Considerations

SBGETREALSOURCE is available in the NonStop environment
only.

The file name is in external NonStop format (i.e., the file name that
has periods to separate the node, volume, subvolume, and file
name). See the files USRXCOPY and USRXLIBH in your
installation subvolume for the content of these structures.

Note that SBGETREALSOURCE will return the value 0 if it cannot
determine the real source file name. Otherwise, it returns the
length of the file name.

Also note that the file name is padded with blanks and not null
terminated
SBGETREALTARGET
The SBGETREALTARGET identifies the target file name. Note that
this can be different than the target identified by SBGETTARGET,
particularly when configuring HPE Shadowbase to replicate
dynamically created Enscribe files. This environment requires using
the MAPFROMSOURCE and PATHNAME parameters and possibly
the MAPTOFILE parameter. See the HPE Shadowbase manuals for
more information about these parameters.
Product
HPE NonStop
Server
Availability
Yes
Calling Module Usage
All
HPE Shadowbase Programming Manual—785431-007
106
User Exits
Step #2: Coding the Program
Product
Other Servers
Availability
No
Calling Module Usage
N/A
Syntax for COBOL Programmers
ENTER C "SBGETREALTARGET" IN USRXLIB
USING SB-FILE
GIVING SB-FILE-NAME-LENGTH.
Syntax for C Programmers
short SBGETREALTARGET (SB_FILE_ATTRIBUTES_DEF *sb_file)
Parameters
SB-FILE-NAME-LENGTH
returned value

returns length of file name or 0 if it cannot determine the real target
file name
SB-FILE
output

Returns file name, file type (-1=unknown or SQL/MX table,
0=Enscribe, 1=SQL), and file subtype (-1=unknown,
0=unstructured, 1=relative, 2=entry-sequenced, 3=key sequenced)
88
88
88
88
88
88
88
88
SB-FILE-ATTRIBUTES.
05 FILE-NAME PIC X(36).
05 FILE-TYPE PIC S9(4) COMP.
UNKNOWN-FILE-TYPE VALUE -1.
ENSCRIBE-FILE VALUE 0.
SQL-TABLE VALUE 1.
05 FILE-SUBTYPE PIC S9(4) COMP.
UNKNOWN-FILE-SUBTYPE VALUE -1.
UNSTRUCTURED-TYPE VALUE 0.
RELATIVE-TYPE VALUE 1.
ENTRY-SEQUENCED-TYPE VALUE 2.
KEY-SEQUENCED-TYPE VALUE 3.
typedef struct {
char file_name[36];
short file_type;
short file_subtype;
} SB_FILE_ATTRIBUTES_DEF;
Examples
COBOL Example
HPE Shadowbase Programming Manual—785431-007
107
User Exits
Step #2: Coding the Program
WORKING-STORAGE.
COPY SB-FILE-ATTRIBUTES OF "USRXCOPY".
01 SB-FILE-NAME-LENGTH
PIC S9(4) COMP.
PROCEDURE DIVISION.
ENTER C "SBGETREALTARGET" IN USRXLIB
USING SB-FILE-ATTRIBUTES
GIVING SB-FILE-NAME-LENGTH.
C Example
SB_FILE_ATTRIBUTES_DEF sb_file;
short
sb_file_name_length;
sb_file_name_length =
SBGETREALTARGET ((SB_FILE_ATTRIBUTES_DEF *)&sb_file);
Considerations

SBGETREALTARGET is only available in the NonStop
environment.





SBGETREALTARGET will identify the target file name as derived
from the TARGETFILE and PATHNAME parameters. It will fill in
the content of SB-FILE-ATTRIBUTES for COBOL programs and
SB_FILE_ATTRIBUTES_DEF for C programs.
The file name is in external NonStop format (i.e., the file name that
has periods to separate the node, volume, subvolume, and file
name). See the files USRXCOPY and USRXLIBH in your
installation subvolume for the content of these structures.
The file name returned by SBGETREALTARGET will contain the
node name.
Note that SBGETREALTARGET will return the value 0 if it can't
determine the real target file name. Otherwise, it returns the length
of the file name.
Also note that the file name is padded with blanks and not null
terminated.
SBGETRELATIVEADDR
This function is used from USRXPROCESS or USRXEXCEPTION to
retrieve the relative record number or SYSKEY of the current record. It
returns the number in the function return argument.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
HPE Shadowbase Programming Manual—785431-007
108
User Exits
Step #2: Coding the Program
Syntax for COBOL Programmers
ENTER C "SBGETRELATIVEADDR" IN USRXLIB
GIVING RETURN-CODE.
Syntax for C Programmers
long SBGETRELATIVEADDR(void)
Parameters
RETURN-CODE
returned value

Indicates whether call completed successfully or encountered an
error. Possible values:
<0
=
is not available
>-1
=
relative record number or SYSKEY.
-2 = format 1 Enscribe entry-sequenced file. (Use
SBGETRELATIVEADDR64 for Enscribe entrysequenced files).
-3 = wrong API used for Format 2 file. (Use
SBGETRELATIVEADDR64 for Format 2 files).
Considerations

SBGETRELATIVEADDR is only available in the NonStop
environment.

In COBOL, relative record addresses are relative to 1; otherwise,
they are zero-relative.

Can only be used for Format 1 Enscribe files. Use
SBGETRELATIVEADDR64 for Format 2 Enscribe files.
SBGETRELATIVEADDR64
This function is used from USRXPROCESS or USRXEXCEPTION to
retrieve the relative record number or SYSKEY of the current record
from a Format 2 ("big") Enscribe file. It returns the number in the
function return argument.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
HPE Shadowbase Programming Manual—785431-007
109
User Exits
Step #2: Coding the Program
ENTER C "SBGETRELATIVEADDR64" IN USRXLIB
GIVING RETURN-CODE.
Syntax for C Programmers
long long SBGETRELATIVEADDR64(void)
Parameters
RETURN-CODE
returned value

Indicates whether call completed successfully or encountered an
error. Possible values:
<0
=
is not available
>-1
=
relative record number or SYSKEY.
Considerations

SBGETRELATIVEADDR64 is only available in the HPENonStop
environment.

In COBOL, relative record addresses are relative to 1; otherwise,
they are zero-relative.
SBGETSOURCE
This function is called from USRXPROCESS or USRXEXCEPTION to
obtain the source file name and file type information associated with
the current event.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C "SBGETSOURCE" IN USRXLIB
USING SB-FILE-ATTR.
Syntax for C Programmers
void SBGETSOURCE (SB_FILE_ATTRIBUTES_DEF *sb_file_attr)
Parameters
HPE Shadowbase Programming Manual—785431-007
110
User Exits
Step #2: Coding the Program

Returns file name, file type (-1=unknown or SQL/MX table,
0=Enscribe, 1=SQL), and file subtype (-1=unknown,
0=unstructured, 1=relative, 2=entry-sequenced, 3=key sequenced)
SB-FILE-ATTR
88
88
88
88
88
88
output
01 SB-FILE-ATTRIBUTES.
05 FILE-NAME PIC X(36).
05 FILE-TYPE PIC S9(4) COMP.
UNKNOWN-FILE-TYPE VALUE -1.
ENSCRIBE-FILE VALUE 0.
SQL-TABLE VALUE 1.
05 FILE-SUBTYPE
PIC S9(4) COMP.
UNKNOWN-FILE-SUBTYPE
VALUE -1.
RELATIVE-TYPE VALUE 1.
KEY-SEQUENCED-TYPE
VALUE 3.
typedef struct {
char file_name[36];
short file_type;
short file_subtype;
} SB_FILE_ATTRIBUTES_DEF;
Considerations

SBGETSOURCE is only available in the NonStop environment.

For COBOL callers, it returns SB-FILE-ATTRIBUTES data area that
can be copied from the USRXCOPY file.

For C callers, it returns a structure of type
SB_FILE_ATTRIBUTES_DEF that is included from the USRXLIBH
file.

Format of filename returned is:
\<node>.$<vol>.<subvol>.<filename>.

The filename is padded with spaces not null terminated.
SBGETSOURCECOLUMNINFO (NonStop)
Given a column number as input in the SB_COLUMN_INFO_DEF
structure from usrxlib.h (you pass a pointer to the structure defined in
your user exit code space), this function will fill in
SB_COLUMN_INFO_DEF with information about the source schema
column. For C, see the usrxlibh file for the content of the new
SB_COLUMN_INFO_DEF structure. For COBOL, see the usrxcopy file
for the content of the new SB-COLUMN-INFO definition.
For SQL, the information about the source schema column comes from
the SQL catalog tables which are described in the HPE SQL Reference
HPE Shadowbase Programming Manual—785431-007
111
User Exits
Step #2: Coding the Program
Manual. There are defines in the NonStop $system.system.sqlh file for
the various data types.
Examples are:
#define
*/
#define
*/
#define
*/
#define
*/
#define
*/
_SQLDT_ASCII_F
0
/* CHAR datatype
_SQLDT_ASCII_F_UP
1
/* CHAR datatype, UPSHIFTed
_SQLDT_DOUBLE_F
2
/* DOUBLE CHAR datatype
_SQLDT_ASCII_V
64
/* VARCHAR datatype
_SQLDT_ASCII_V_UP
65
/* VARCHAR datatype, UPSHIFted
For Enscribe, the information about the source schema column comes from
the related DDL dictionary configured for the HPE Shadowbase DBS objects.
These records are described in the HPE DDL Manual in appendix D. The
content for the data type comes from the DICTOBL STRUCTURE field. The
values are defined in the HPE manual in Table D-11. There is no file for HPE
Shadowbase to retreive defines for the values on the NonStop. It should be
noted that the Enscribe values are different than the SQL types.
Note that the col_name field (COL-NAME for COBOL) will be null terminated
and can subsequently be used to call other SBGET...COLUMN... functions.
Also, note that the content is filled in from the schema associated with the
related SQL table or Enscribe DDL.
Note that this function could be used by a generic user exit facility when
column names are not known. You would start at column number 0 and
subsequently increment the input by 1 for each call to the function until you
receive a return code value of 0.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C "SBGETSOURCECOLUMNINFO" IN USRXLIB
USING SB-COLUMN-INFO
GIVING CI-RETURN-CODE.
Syntax for C Programmers
ci_return_code = SBGETSOURCECOLUMNINFO(&usrx_col_info)
HPE Shadowbase Programming Manual—785431-007
112
User Exits
Step #2: Coding the Program
Parameters
CI-RETURN-CODE
returned value
The function will return a 16-bit return code. The following values are
possible:
-2 = schema is not available.
-1 = invalid col_num specified in SB_COLUMN_INFO_DEF on input.
0 = col_num specified in SB_COLUMN_INFO_DEF on input not found in the
schema.
1 = column information returned in SB_COLUMN_INFO_DEF.
SB-COLUMN-INFO

Gives column information returned.
output
COBOL Usage Example:
.
.
WORKING-STORAGE.
COPY SB-USRXPROCESS-INFO OF "USRXCOPY".
COPY SB-COLUMN-INFO OF "USRXCOPY".
01 WS-ITEMS.
05 CI-RETURN-CODE
PIC S9(4) COMP.
PROCEDURE DIVISION.
MOVE 1 TO CI-RETURN-CODE.
PERFORM 0100-GET-COLUMN THRU 0199-EXIT
VARYING COL-NUM OF SB-COLUMN-INFO FROM 0 BY 1
UNTIL CI-RETURN-CODE < 1.
0100-GET-COLUMN.
ENTER C "SBGETSOURCECOLUMNINFO" IN USRXLIB
USING SB-COLUMN-INFO
GIVING CI-RETURN-CODE.
IF CI-RETURN-CODE LESS THAN 1
GO TO 0199-EXIT.
0199-EXIT.
EXIT.
C Usage Example:
HPE Shadowbase Programming Manual—785431-007
113
User Exits
Step #2: Coding the Program
#include "usrxlib.h"
SB_COLUMN_INFO_DEF usrx_col_info;
short ci_return_code;
.
usrx_col_info.col_num = 0;.
ci_return_code = 1;
while (ci_return_code > 0) {
ci_return_code = SBGETSOURCECOLUMNINFO(&usrx_col_info);
if (ci_return_code < 1) {
if (ci_return_code != 0) /* error situation? */
}
continue;
}
++usrx_col_info.col_num;
}
Considerations

This version of SBGETSOURCECOLUMNINFO is only available in
the NonStop environment.
SBGETSOURCECOLUMNINFO (Other Servers)
Given a specified column name as input this function populates an
SB_SOURCE_COLUMN_INFO_DEF with column attributes found for the
specified column. The data returned corresponds to how the sender formatted
the data for the column. This may not be the format of the target databases
column.
Note: see the file usrxlib.h for the description of the
SB_SOURCE_COLUMN_INFO_DEF structure and function prototype.
Product
HPE NonStop
Server
Other Servers
Availability
No
Yes
Calling Module Usage
N/A
USRXPROCESS
USRXEXCEPTION
Syntax for C Programmers
Short SBGETSOURCECOLUMNINFO(char *col,
SB_SOURCE_COLUMN_INFO_DEF *info)
Parameters
The function will return a 16-bit return code. The following values are
possible:
1 = column information returned in SB_SOURCE_COLUMN_INFO_DEF.
HPE Shadowbase Programming Manual—785431-007
114
User Exits
Step #2: Coding the Program
-4 = column not found.
col


input
column name
must be NULL terminated
info
output

returns SB_SOURCE_COLUMN_INFO_DEF populated according
to
column specified by col parameter.
Considerations

This version of SBGETSOURCECOLUMNINFO is only available in
the HPE Shadowbase Other Servers environment.
C Usage Example:
#include “usrxlib.h”
SB_COLUMN_INFO_DEF info;
short rc;
char colname[MAX_COL_NAME];
sprintf(colname, “%-s”, “COLUMN_A”);
rc = SBGETSOURCECOLUMNINFO(colname,&info);
if (rc == -4) {
report_err(); /* column not found in current statement */
}
Considerations

This version of SBGETSOURCECOLUMNINFO is only available in
the Other Servers environment.
SBGETSQLCAFSCODE
This function is called from USRXPROCESS or USRXEXCEPTION to
obtain the last file system error number associated with a NonStop
SQL error.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
Yes
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
USRXPROCESS
USRXEXCEPTION
Syntax for COBOL Programmers
ENTER C "SBGETSQLCAFSCODE" IN USRXLIB
GIVING FS-ERROR-NO.
HPE Shadowbase Programming Manual—785431-007
115
User Exits
Step #2: Coding the Program
Syntax for C Programmers
short SBGETSQLCAFSCODE (void)
Parameters
FS-ERROR-NO

the file system error number
01
FS-ERROR-NO
returned value
PIC S9(4) COMP VALUE 0.
Examples
C Example
short fs_err_no;
fs_err_no = SBGETSQLCAFSCODE();
SBGETSQLTARGETCOLUMN
Related to an SQL target row that was pre-read by the Consumer because
USEREXITPREREAD was ON, this function can be called to obtain the data for
a particular column. Note that only update and deletes result in an attempt to
pre-read the target row. Like with the other SBGET...COLUMN... functions, it is
the responsibility of the custom user exit code to allocate sufficient space for the
data to be returned. Failure to allocate enough space could yield unpredictable
results.
Note that generic code can determine the maximum column size by calling
SBGETTARGETCOLUMNINFO or by evaluating the schema information
returned from SBGETNEXTBEFORECOLUMNINFO or
SBGETNEXTAFTERCOLUMNINFO. Also, note that the column name returned
in SB_COLUMN_INFO_DEF by SBGETTARGETCOLUMNINFO,
SBGETNEXTBEFORECOLUMNINFO, and SBGETNEXTAFTERCOLUMNINFO
can be used as input to SBGETSQLTARGETCOLUMN.
Input to SBGETSQLTARGETCOLUMN is the null-terminated column name for
which data is to be returned. The function will return the associated data, a
primary key indicator, and the data length.
Note that TRUE (value 1) will be returned in the primary key indicator if the
column is part of the primary key. If the column data is a null value, -1 will be
returned in the length and the return code will contain 0.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
HPE Shadowbase Programming Manual—785431-007
116
User Exits
Step #2: Coding the Program
Syntax for COBOL Programmers
ENTER C "SBGETSQLTARGETCOLUMN" IN USRXLIB
USING COL-NAME OF SB-COLUMN-INFO,
CD-PRIM-KEY-IND,
CD-LEN,
CD-COL-DATA
GIVING CI-RETURN-CODE.
Syntax for C Programmers
cd_return_code = SBGETSQLTARGETCOLUMN(
(char *)&usrx_col_info.col_name,
(short *)&cd_prim_key_ind,
(short *)&cd_len,
(char *)&cd_col_data);
Parameters
CD-RETURN-CODE
returned value
The function will return a 16-bit return code. The following values are
possible:
-11 = column not found in schema.
-10 = bad column name format on input.
-9 = schema not available.
-8 = event image not available.
-7 = not allowed for Enscribe. Use SBGETTARGETRECORD.
-6 = record not read.
-5 = source and target schema definitions do not contain the same primary
key columns.
-4 = event is not an update or a delete.
-3 = not used.
-2 = USEREXITPREREAD parameter is OFF.
-1 = row not found during pre-read.
0 = found a null value.
1 = value returned. Check the length returned.
CD-PRIM-KEY-IND
output
TRUE (value 1) will be returned in the primary key indicator if the column is
part of the primary key.
CD-LEN
The data length.
output
CD-COL-DATA
output
If the column data is a null value, -1 will be returned in the length and the
return code will contain 0.
COBOL Usage Example:
HPE Shadowbase Programming Manual—785431-007
117
User Exits
Step #2: Coding the Program
.
.
WORKING-STORAGE.
COPY SB-USRXPROCESS-INFO OF "USRXCOPY".
COPY SB-COLUMN-INFO OF "USRXCOPY".
01 WS-ITEMS.
05 CI-RETURN-CODE
PIC S9(4) COMP.
05 CD-RETURN-CODE
PIC S9(4) COMP.
05 CD-PRIM-KEY-IND
PIC S9(4) COMP.
88 IS-NOT-PRIM-KEY VALUE 0.
88 IS-PRIM-KEY
VALUE 1.
05 CD-LEN
PIC S9(4) COMP.
05 CD-COL-DATA
PIC X(100).
.
.
PROCEDURE DIVISION.
.
.
MOVE 1 TO CI-RETURN-CODE.
PERFORM 0100-GET-COLUMN THRU 0199-EXIT
VARYING COL-NUM OF SB-COLUMN-INFO FROM 0 BY 1
UNTIL CI-RETURN-CODE < 1.
.
.
.
0100-GET-COLUMN.
ENTER C "SBGETTARGETCOLUMNINFO" IN USRXLIB
USING SB-COLUMN-INFO
GIVING CI-RETURN-CODE.
IF CI-RETURN-CODE LESS THAN 1
GO TO 0199-EXIT.
0199-EXIT.
EXIT.
ENTER C "SBGETSQLTARGETCOLUMN" IN USRXLIB
USING COL-NAME OF SB-COLUMN-INFO,
CD-PRIM-KEY-IND,
CD-LEN,
CD-COL-DATA
GIVING CD-RETURN-CODE
.
.
0199-EXIT.
EXIT.
C Usage Example:
HPE Shadowbase Programming Manual—785431-007
118
User Exits
Step #2: Coding the Program
.
..
#include "usrxlib.h"
SB_COLUMN_INFO_DEF usrx_col_info;
short ci_return_code;
short cd_return_code;
short cd_prim_key_ind;
short cd_len;
char cd_col_data[100];
.
.
.
usrx_col_info.col_num = 0;
ci_return_code = 1;
while (ci_return_code > 0) {
ci_return_code = SBGETTARGETCOLUMNINFO(&usrx_col_info);
if (ci_return_code < 1) {
if (ci_return_code != 0) /* error situation? */
.
.
}
continue;
}
cd_return_code = SBGETSQLTARGETCOLUMN(
(char *)&usrx_col_info.col_name,
(short *)&cd_prim_key_ind,
(short *)&cd_len,
(char *)&cd_col_data);
.
.
++usrx_col_info.col_num;
}
Considerations

SBGETSQLTARGETCOLUMN is only available in the NonStop
environment.
SBGETSRCFILEINFO
This API is used in USRXPROCESS or USRXEXCEPTION to retrieve
information about the source file.
Product
HP NonStop
Server
Other Servers
Availability
Yes
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
No
Syntax for C Programmers
short SBGETSRCFILEINFO(char *src_file_name, short *file_type, short
*file_subtype, short *record_length, short *key_offset, short *key_length);
Parameters
RETURN-CODE
output

indicates whether call completed successfully or encountered an error:
HPE Shadowbase Programming Manual—785431-007
119
User Exits
Step #2: Coding the Program
-1 = Parameter content is not available.
0 = Successful.
src_file_name

Returns source file name if available

Returns an empty string otherwise
output
file_type

-1 = Unknown

0 = Enscribe file

1 = SQL table
output
file_subtype

-1 = Unknown

0 = Unstructured file

1 = Relative file

2 = Entry-sequenced file

3 = Key-sequenced file
output
record_length
output

Returns the record length if the source is an Enscribe file.

Returns -1 otherwise.
key_offset
output

Returns the key offset if the source is an Enscribe key-sequenced file.

Returns -1 otherwise.
key_length
output

Returns the key length if the source is an Enscribe key-sequenced file.

Returns -1 otherwise.
SBGETTARGET
This function is called from USRXPROCESS or USRXEXCEPTION to
obtain the target file name and file type information associated with the
current event.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
Yes
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
USRXPROCESS
USRXEXCEPTION
Syntax for COBOL Programmers
HPE Shadowbase Programming Manual—785431-007
120
User Exits
Step #2: Coding the Program
ENTER C "SBGETTARGET" IN USRXLIB
USING SB-FILE-ATTR.
Syntax for C Programmers
void SBGETTARGET (SB_FILE_ATTRIBUTES_DEF *sb_file_attr)
Parameters

Returns file name, file type (-1=unknown or SQL/MX table,
0=Enscribe, 1=SQL), and file subtype (-1=unknown,
0=unstructured, 1=relative, 2=entry-sequenced, 3=key sequenced)
SB-FILE-ATTR
88
88
88
88
88
88
output
01 SB-FILE-ATTRIBUTES.
05 FILE-NAME PIC X(36).
05 FILE-TYPE PIC S9(4) COMP.
UNKNOWN-FILE-TYPE VALUE -1.
ENSCRIBE-FILE VALUE 0.
SQL-TABLE VALUE 1.
05 FILE-SUBTYPE
PIC S9(4) COMP.
UNKNOWN-FILE-SUBTYPE
VALUE -1.
RELATIVE-TYPE VALUE 1.
KEY-SEQUENCED-TYPE
VALUE 3.
typedef struct {
char file_name[36];
short file_type;
short file_subtype;
} SB_FILE_ATTRIBUTES_DEF;
Considerations

For COBOL callers, it returns the SB-FILE-ATTRIBUTES data area
that can be copied from the USRXCOPY file.

For C callers, it creates a structure of type
SB_FILE_ATTRIBUTES_DEF that is included from the USRXLIBH
file.

The filename is returned in the format:
$<vol>.<subvol>.<filename>.

When replicating to an Other Servers system, if no TARGETFILE
DBS parameter is specified, spaces will be returned.

The filename is padded with spaces not null terminated.
SBGETTARGETCOLUMNINFO
HPE Shadowbase Programming Manual—785431-007
121
User Exits
Step #2: Coding the Program
Given a column number as input in the SB_COLUMN_INFO_DEF structure from
usrxlib.h (you pass a pointer to the structure defined in your user exit code
space), this function will fill in SB_COLUMN_INFO_DEF with information about
the target schema column. For C, see the usrxlibh file for the content of the new
SB_COLUMN_INFO_DEF structure. For COBOL, see the usrxcopy file for the
content of the new SB-COLUMN-INFO definition
Note that the col_name field (COL-NAME for COBOL) will be null terminated and
can subsequently be used to call other SBGET...COLUMN... functions. Also,
note that the content is filled in from the schema associated with the related SQL
table or Enscribe DDL.
Note that this function could be used by a generic user exit facility when column
names are not known. You would start at column number 0 and subsequently
increment the input by 1 for each call to the function until you receive a return
code value of 0.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C "SBGETTARGETCOLUMNINFO" IN USRXLIB
USING SB-COLUMN-INFO
GIVING CI-RETURN-CODE.
Syntax for C Programmers
ci_return_code = SBGETTARGETCOLUMNINFO(&usrx_col_info);
Parameters
CI-RETURN-CODE
returned value
The function will return a 16-bit return code. The following values are
possible:
-2 = schema is not available.
-1 = invalid col_num specified in SB_COLUMN_INFO_DEF on input.
0 = col_num specified in SB_COLUMN_INFO_DEF on input not found in the
schema.
1 = column information returned in SB_COLUMN_INFO_DEF.
SB-COLUMN-INFO
Gives column information returned.
output
COBOL Usage Example:
HPE Shadowbase Programming Manual—785431-007
122
User Exits
Step #2: Coding the Program
.
.
WORKING-STORAGE.
COPY SB-USRXPROCESS-INFO OF "USRXCOPY".
COPY SB-COLUMN-INFO OF "USRXCOPY".
01 WS-ITEMS.
05 CI-RETURN-CODE
PIC S9(4) COMP.
PROCEDURE DIVISION.
MOVE 1 TO CI-RETURN-CODE.
PERFORM 0100-GET-COLUMN THRU 0199-EXIT
VARYING COL-NUM OF SB-COLUMN-INFO FROM 0 BY 1
UNTIL CI-RETURN-CODE < 1.
0100-GET-COLUMN.
ENTER C "SBGETTARGETCOLUMNINFO" IN USRXLIB
USING SB-COLUMN-INFO
GIVING CI-RETURN-CODE
IF CI-RETURN-CODE LESS THAN 1
GO TO 0199-EXIT.
0199-EXIT.
EXIT.
C Usage Example:
.
..
#include "usrxlib.h"
SB_COLUMN_INFO_DEF usrx_col_info;
short ci_return_code;
.
.
usrx_col_info.col_num = 0;
ci_return_code = 1;
while (ci_return_code > 0) {
ci_return_code = SBGETTARGETCOLUMNINFO(&usrx_col_info);
if (ci_return_code < 1) {
if (ci_return_code != 0) /* error situation? */
}
continue;
}
++usrx_col_info.col_num;
}
Considerations

SBGETTARGETCOLUMNINFO is only available in the NonStop
environment.
SBGETTARGETRECORD
HPE Shadowbase Programming Manual—785431-007
123
User Exits
Step #2: Coding the Program
The SBGETTARGETRECORD function is called from
USRXPROCESS or USRXEXCEPTION to have the related current
Enscribe DBS TARGETFILE record returned to the caller. Note that
the TARGETFILE must have the same attributes as the SOURCEFILE
(i.e., file types, primary key offsets, primary key lengths, and record
lengths must match). Also note that you should allocate enough space
for the largest possible record size.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C "SBGETTARGETRECORD" IN USRXLIB
USING TARGET-REC MAX-REC-LEN REC-LEN
GIVING RETURN-CODE.
Syntax for C Programmers
short SBGETTARGETRECORD(char *target_rec, short max_rec_len, short *rec_len)
Parameters
RETURN-CODE
returned value

SBGETTARGETRECORD will return a 16-bit return code. The
following values are possible:
-6 = The MAXFILEOPENS parameter is set to 0.
-5 = The SOURCEFILE and TARGETFILE aren't the same
structure.
-4 = The event type is not a delete or update.
-3 = SBGETTARGETRECORD is only supported for Enscribe.
-2 = The related DBS parameter USEREXITPREREAD is OFF.
-1 = The SOURCEFILE record event key is not in the
TARGETFILE.
1=
The SOURCEFILE record event key is in the TARGETFILE
and is returned.
TARGET-REC
output

The address of the record area in your program space where the
record will be moved. For example,
05
TARGET-REC
PIC X(100).
HPE Shadowbase Programming Manual—785431-007
124
User Exits
Step #2: Coding the Program
REC-LEN
output

The address of a short integer in your program space where the
actual record length will be returned. For example,
05
REC-LEN
PIC 9(4) COMP.
MAX-REC-LEN
input

A short integer containing the maximum record size that can be
returned. For example,
05
MAX-REC-LEN
PIC 9(4) COMP.
Examples
COBOL Example
WORKING-STORAGE SECTION.
01 GET-REC-PARMS.
05 TARGET-REC
PIC X(100).
05 MAX-REC-LEN
PIC 9(4) COMP.
05 REC-LEN PIC 9(4) COMP.
05 RETURN-CODE
PIC 9(4) COMP.
PROCEDURE DIVISION.
ENTER C "SBGETTARGETRECORD" IN USRXLIB
USING TARGET-REC, MAX-REC-LEN, REC-LEN
GIVING RETURN-CODE.
C Example
char target_rec[100];
short rec_len;
short return_code;
return_code = SBGETTARGETRECORD((char *)&target_rec,
sizeof(target_rec), (short *)&rec_len);
Considerations

SBGETTARGETRECORD is only available in the NonStop
environment.

Set the USEREXITPREREAD DBS parameter to ON to make the
target record available to the user exit. By default,
USEREXITPREREAD is set to OFF.
SBGETTRANSIDADT
This function can be called from USRXPROCESS or
USRXEXCEPTION to obtain the TM/MP transaction identifier for the
event as read from the audit trail.
Product
Availability
Calling Module Usage
HPE Shadowbase Programming Manual—785431-007
125
User Exits
Step #2: Coding the Program
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C “SBGETTRANSIDADT” IN USRXLIB
GIVING ADT-TRANS-ID.
Syntax for C Programmers
long long SBGETTRANSIDADT(void)
Parameters
ADT-TRANS-ID

TM/MP transaction ID from the audit trail.
returned value
Considerations

SBGETTRANSIDADT is only available in the NonStop
environment.

Returns the 64-bit integer (NATIVE-8) transaction ID in the function
return argument.

Transaction ID returned is in internal format. For example,
221550600235412654.

To convert internal format to display (external) format, use the
INTERPRETTRANSID Guardian procedure call.
SBGETTRANSIDCONS
This function is called from USRXPROCESS or USRXEXCEPTION to
obtain the TM/MP transaction identifier pertaining to the Consumer
shadowing of the original transaction.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
HPE Shadowbase Programming Manual—785431-007
126
User Exits
Step #2: Coding the Program
ENTER C “SBGETTRANSIDCONS” IN USRXLIB
GIVING CONS-TRANS-ID.
Syntax for C Programmers
long long SBGETTRANSIDCONS(void)
Parameters
ADT-TRANS-ID

TM/MP transaction ID from the audit trail.
returned value
Considerations

SBGETTRANSIDCONS is only available in the NonStop
environment.

Returns the 64-bit integer (NATIVE-8) transaction ID in the function
return argument.

Transaction ID returned is in internal format. For example,
221550600235412654.

To convert internal format to display (external) format, use the
INTERPRETTRANSID Guardian procedure call.
SBGETTRANSTAG
This function is called from USRXPROCESS or USRXEXCEPTION to
obtain the current TMF transaction identifier tag. This is the value to
be used to call RESUMETRANSACTION if it is non-zero.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C “SBGETTRANSTAG” IN USRXLIB
GIVING TRANS-TAG.
Syntax for C Programmers
long SBGETTRANSTAG (void)
Parameters
HPE Shadowbase Programming Manual—785431-007
127
User Exits
Step #2: Coding the Program
TRANS-TAG

TMF transaction identifier tag.
returned value
Considerations

SBGETTRANSTAG is only available in the NonStop environment.

Returns the 64-bit integer (NATIVE-8) transaction ID in the function
return argument.

Transaction ID returned is in internal format. For example,
221550600235412654.

To convert internal format to display (external) format, use the
INTERPRETTRANSID Guardian procedure call.
SBGETUSRXEXCEPTIONINFO
This function is called from USRXEXCEPTION to obtain information
about an SQL error that is one of those defined within the
USRXEXCEPTIONINIT program.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
Calling Module Usage
USRXEXCEPTION
Yes
USRXEXCEPTION
Syntax for COBOL Programmers
ENTER C "SBGETUSRXEXCEPTIONINFO" IN USRXLIB
USING SB-USRXEXCEPTION-INFO.
Syntax for C Programmers
SBGETUSRXEXCEPTIONINFO(&sb_usrxexception_info);
Parameters
SB-USRXEXCEPTION-INFO
output

Contains information about an SQL error that is one of those
defined within the USRXEXCEPTIONINIT program.
SB-USRXEXCEPTION-INFO.
05 EXC-EVENT-ID PIC 9(4) COMP.
88 USRX-INSERT VALUE 0.
88 USRX-UPDATE VALUE 1.
88 USRX-DELETE VALUE 2.
05 EXC-CNT
NATIVE-2.
05 EXC-SQLCODE NATIVE-2.
HPE Shadowbase Programming Manual—785431-007
128
User Exits
Step #2: Coding the Program
05 EXC-SOURCE-FILE
05 EXC-TARGET-FILE
PIC X(36).
PIC X(36).
typedef struct {
short exc_event_id;
short exc_cnt;
short exc_sqlcode;
char exc_source_file[36];
char exc_target_file[36];
} SB_USRXEXCEPTION_INFO_DEF;
where

exc_event_id is 0=insert, 1=update, 2=delete

exc_cnt is the number of data exceptions for the event

exc_sqlcode is the sql error code for the data exception

exc_source_file is the source file related to the exception

exc_target_file is the target file related to the exception
Considerations

For COBOL callers, it returns the SB-USRXEXCEPTION-INFO
data area that can be copied from the USRXCOPY file.

For C callers, it returns a structure of type
SB_USRXEXCEPTION_INFO_DEF that is included from the
USRXLIBH file.

EXC-EVENT-ID contains a one digit code indicating the type of
event (insert, update or delete) being attempted on the target when
the SQL error occurred.

EXC-CNT indicates the number of times the event has been retired.

EXC-SQLCODE contains the actual SQL error code; usually a
negative number.

EXC-SOURCE-FILE is the name of the SOURCEFILE involved in
the event.

EXC-TARGET-FILE is the name of the TARGETFILE.
SBGETUSRXOPTION
The SBGETUSRXOPTION API is being provided to support
programmatic configuration of HPE Shadowbase replication features
from within the UE environment. HPE Shadowbase Other Servers
version 4.040E introduces this API and supports a limited set of
options at the outset.
This function is used to retrieve HPE Shadowbase feature option
settings. The function may be used from within any USRX API. The
user of this API is cautioned to allocate enough space to hold the
maximum byte length of the corresponding options returned value. A
HPE Shadowbase Programming Manual—785431-007
129
User Exits
Step #2: Coding the Program
listing of the supported options and their correspond value limits can
be found in the SBSETUSRXOPTION Function description.
Product
HPE NonStop
Server
Other Servers
Availability
No
N\A
Calling Module Usage
Yes
All
Syntax for C Programmers
short SBGETUSRXOPTION (int option, void *value)
Parameters
return_code
returned value

indicates whether call completed successfully or encountered an
error:
-1 = Invalid Option supplied.
0 = call completed successfully.
option
input

Must be one from the set of supported HPE Shadowbase USRX
options.
value
output

size must be large enough to hold maximum returned value

Type must correspond to option value being requested.
C Example
unsigned short;
/* assign option */
option = PROC_EVENT_TYPE;
return_code = SBGETUSRXOPTION (option,
&value);
Considerations

Only available in the Other Servers Environment.

Must specify option from the set of HPE Shadowbase USRX
options.

value must point to space large enough to store data corresponding
to option.

Use of a character buffer (array) for the value argument is
recommended, but not required. Data type conversion should be
performed after the call when/if needed or desired.
HPE Shadowbase Programming Manual—785431-007
130
User Exits
Step #2: Coding the Program
SBGETUSRXPROCESSINFO
This function is called to obtain information about the current event
from USRXPROCESS or USRXEXCEPTION.
In the HPE NonStop Shadowbase environment, it returns the
USEREXITID to which the current event pertains. In the HPE
Shadowbase Other Servers environment, it returns –1 in the
USEREXITID field.
It identifies the current source file operation (i.e., insert, update, delete,
commit, or abort) and the original event type.
Valid operations which may be returned in the EVENT-ID/event_id field
are as follows.
For the HPNS environment:
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
INSERT_OP
UPDATE_OP
DELETE_OP
COMMIT_OP
ABORT_OP
BEGIN_OP
CREATE_OP
PURGE_OP
PURGEDATA_OP
ALTER_OP
NOTDEFINED_OP
0
1
2
3
4
5
6
7
8
9
-1
For SBOS:
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
NOTDEFINED_OP
INSERT_OP
UPDATE_OP
DELETE_OP
COMMIT_OP
ABORT_OP
BEGIN_OP
CREATE_OP
PURGE_OP
PURGEDATA_OP
NEXTDOC_OP
NOMOREDATA_OP
-1
0
1
2
3
4
5
6
7
8
9
10
When the INSERTNOTFOUND DBS parameter is set to the value of
on and the Consumer gets a “record not found” error while trying to
apply an update to the target, the event will be changed into an insert
and USRXPROCESS entered again. In this case, the original event
type is update and the current event type is an insert.
If the UPDATEDUPLICATE DBS parameter is set to on and the
Consumer gets a “duplicate record” error during an insert operation it
will apply the change as an update. Therefore, the original event type
HPE Shadowbase Programming Manual—785431-007
131
User Exits
Step #2: Coding the Program
would be insert and the current event type would be update the second
time USRXPROCESS is called for the event.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
Yes
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
USRXPROCESS
USRXEXCEPTION
Syntax for COBOL Programmers
ENTER C "SBGETUSRXPROCESSINFO" IN USRXLIB
USING SB-USRXPROCESS-INFO.
Syntax for C Programmers
void SBGETUSRXPROCESSINFO(&sb_usrxprocess_info);
Parameters
SB-USRXPROCESS-INFO
output

Contains information about the current event.
88
88
88
88
88
88
88
88
88
88
SB-USRXPROCESS-INFO.
05 USRX-ID
NATIVE-2.
05 EVENT-ID PIC 9(4) COMP.
USRX-INSERT
VALUE 0.
USRX-UPDATE
VALUE 1.
USRX-DELETE
VALUE 2.
USRX-COMMIT
VALUE 3.
USRX-ABORT
VALUE 4.
05 ORIGINAL-EVENT-ID
PIC 9(4) COMP.
USRX-INSERT
VALUE 0.
USRX-UPDATE
VALUE 1.
USRX-DELETE
VALUE 2.
USRX-COMMIT
VALUE 3.
USRX-ABORT
VALUE 4.
sb_usrxprocess_info:
typedef struct {
short usrx_id;
short event_id;
short original_event_id;
} SB_USRXPROCESS_INFO_DEF;
HPE Shadowbase Programming Manual—785431-007
132
User Exits
Step #2: Coding the Program
Where

usrx_id is the value of the USEREXITID parameter

event_id is 0=insert, 1=update, 2=delete, 3=commit, 4=abort

original_event_id 0=insert, 1=update, 2=delete, 3=commit,
4=abort
For the Other Servers environment, the SBGETUSRXPROCESSINFO
call returns the source system transaction id as well:
typedef struct {
short
usrx_id;
short
event_id;
short
original_event_id;
SSBLongLong trans_id;
} SB_USRXPROCESS_INFO_DEF;
Where

usrx_id is not used

event_id is 0=insert, 1=update, 2=delete, 3=commit,
4=abort
original_event_id is 0=insert, 1=update, 2=delete,
3=commit, 4=abort
trans_id is the source system transaction id


Considerations

For COBOL callers, it returns the SB-USRXPROCESS-INFO data
area that can be copied from the USRXCOPY file.

For C callers, it returns a structure of type
SB_USRXPROCESS_INFO_DEF that is included from the
USRXLIBH file.

ORIGINAL_EVENT_ID contains the type of event based upon the
event in the audit trail.

EVENT_ID contains the current event type.

EVENT_ID may contain a different value than
ORIGINAL_EVENT_ID if the INSERTNOTFOUND and/or
UPDATEDUPLICATE attributes for a DBS object are enabled. See
the description at the beginning of the
SBGETUSRXPROCESSINFO section, above, for more details.
SBGETUSRXSTARTINFO
This function is called to obtain information about a particular user exit
that is starting and may require some form of initialization processing.
It is typically called from the USRXSTART function. In the HPE
NonStop Shadowbase environment, SBGETUSRXSTARTINFO will
return the current USEREXITID and the associated source file and
HPE Shadowbase Programming Manual—785431-007
133
User Exits
Step #2: Coding the Program
target file. In the HPE Shadowbase Other Servers environment,
SBGETUSRXSTARTINFO initializes the instance of the
SB_USRXSTART_INFO_DEF setting the usrx_id element to –1 and
the source_file and target_file elements to null.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
Calling Module Usage
USRXSTART
Yes
USRXSTART
Syntax for COBOL Programmers
ENTER C "SBGETUSRXSTARTINFO" IN USRXLIB
USING SB-USRXSTART-INFO.
Syntax for C Programmers
void SBGETUSRXSTARTINFO(SB_USRXSTART_INFO_DEF *info);
Parameters
SB-USRXSTART-INFO
output

Contains information about the current event.
SB-USRXSTART-INFO.
01 SB-USRXSTART-INFO.
05 USRX-ID NATIVE-2.
05 SOURCE-FILE PIC X(36).
05 TARGET-FILE
PIC X(36).
sb_usrxprocess_info:
typedef struct {
short usrx_id;
char source_file[36];
char target_file[36];
} SB_USRXSTART_INFO_DEF;
Where

usrx_id is the value of the USEREXITID parameter

source_file is the value of the SOURCEFILE DBS parameter

target_file is the value of the TARGETFILE DBS parameter
Considerations

For COBOL callers, returns the SB-USRXSTART-INFO data area
that can be copied from the USRXCOPY file.
HPE Shadowbase Programming Manual—785431-007
134
User Exits
Step #2: Coding the Program

For C callers, returns a structure of type
SB_USRXSTART_INFO_DEF that is included from the USRXLIBH
file.
SBIS Functions
The SBIS functions are used to determine information about the event.
The SBIS functions are detailed below.
SBISABENDONMISMATCH
This function can be called to determine if the DBS parameter
ABENDONMISMATCH related to the current audit trail event is ON.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C "SBISABENDONMISMATCH" IN USRXLIB
GIVING RETURN-CODE.
Syntax for C Programmers
return_code = SBISABENDONMISMATCH();
Parameters
RETURN-CODE
returned value
The function will return a 16-bit return code. The following values are
possible:
0 (false) = is not set to ON.
1 (true) = is set to ON.
COBOL Usage Example:
.
.
WORKING-STORAGE
01 WS-ITEMS.
HPE Shadowbase Programming Manual—785431-007
135
User Exits
Step #2: Coding the Program
05 RETURN-CODE
PIC S9(4) COMP.
.
.
.
PROCEDURE DIVISION
.
.
.
ENTER C "SBISABENDONMISMATCH" IN USRXLIB
GIVING RETURN-CODE.
.
.
C Usage Example:
.
.
.
#include "usrxlib.h"
short return_code;
.
.
return_code = SBISABENDONMISMATCH();
.
.
Considerations

SBISABENDONMISMATCH is only available in the NonStop
environment.
SBISCOMPRESSEDUPDATE
This function can be called to determine if the current audit trail event being
processed by the user exit is a compressed update event. Note that all
column data is not present for a compressed update. See the descriptions for
SBGETNEXTBEFORECOLUMNINFO and
SBGETNEXTAFTERCOLUMNINFO below to find out how to determine the
columns that are present in an SQL compressed update event.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
All
Calling Module Usage
No
N/A
Syntax for COBOL Programmers
ENTER C "SBISCOMPRESSEDUPDATE" IN USRXLIB
GIVING RETURN-CODE.
Syntax for C Programmers
return_code = SBISCOMPRESSEDUPDATE()
HPE Shadowbase Programming Manual—785431-007
136
User Exits
Step #2: Coding the Program
Parameters
RETURN-CODE
returned value
The function will return a 16-bit return code. The following values are
possible:
0 (false) = is not a compressed update event.
1 (true) = is a compressed update event.
COBOL Usage Example:
WORKING-STORAGE
01 WS-ITEMS.
05
RETURN-CODE
PIC S9(4) COMP.
PROCEDURE DIVISION
ENTER C "SBISCOMPRESSEDUPDATE" IN USRXLIB
GIVING RETURN-CODE
C Usage Example:
#include "usrxlib.h"
short return_code;
return_code = SBISCOMPRESSEDUPDATE()
Considerations

SBISCOMPRESSEDUPDATE is only available in the NonStop
environment.
SBISDUPERROR
The SBISDUPERROR API is called from USRXPROCESS or
USRXEXCEPTION during iterative situations (e.g., related to
UPDATEDUPLICATES, etc.) to determine if the previous target I/O
attempt resulted in a duplicate record error. It returns FALSE(0) if
there was no duplicate error. It returns TRUE(1) if there was a
duplicate error, along with the contents of
SB_DUPLICATE_ERROR_INFO_DEF or SB-DUPLICATE-ERRORINFO. A flag is set to indicate if the error occurred on a primary or
secondary key. The event type is identified along with either a key
specifier for Enscribe or the related filename for an SQL table. Note
that the key specifier will contain nulls if the error occurred on the
primary key for an Enscribe file or on a SQL table. For SQL tables, the
HPE Shadowbase Programming Manual—785431-007
137
User Exits
Step #2: Coding the Program
filename returned can be either the primary table name or an index.
The "primary secondary flag" indicates what is contained in the
filename. Note that the filename is not null terminated. It is padded
with spaces in the unused space.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C "SBISDUPERROR" IN USRXLIB
USING DUP-INFO
GIVING RETURN-CODE.
Syntax for C Programmers
short SBISDUPERROR(SB_DUPLICATE_ERROR_INFO_DEF *dup_info)
Parameters
RETURN-CODE
returned value

indicates whether there was a duplicate error or not.
DUP-INFO

Gives information on the error.
output
01 SB-DUPLICATE-ERROR-INFO.
05 PRIMARY-SECONDARY-FLAG PIC 9(4) COMP.
88 DUPLICATE-ON-PRIMARY-KEY
VALUE 0.
88 DUPLICATE-ON-SECONDARY-KEY VALUE 1.
05 LAST-EVENT-ID
PIC S9(4) COMP.
88 USRX-NONE
VALUE -1.
88 USRX-INSERT
VALUE 0.
88 USRX-UPDATE
VALUE 1.
88 USRX-DELETE
VALUE 2.
05 KEY-SPECIFIER
PIC X(2).
05 FILE-NAME
PIC X(36).
typedef struct {
short primary_secondary_flag;
short last_event_id;
char key_specifier[2];
char file_name[36];
HPE Shadowbase Programming Manual—785431-007
138
User Exits
Step #2: Coding the Program
} SB_DUPLICATE_ERROR_INFO_DEF;
Examples
COBOL Example
.
.
WORKING-STORAGE.
01 DUP-ERROR-FLAG
PIC S9(4).
88 DUP-ERROR-NO
VALUE 0.
88 DUP-ERROR-YES VALUE 1.
COPY SB-DUPLICATE-ERROR-INFO OF "USRXCOPY".
.
.
PROCEDURE DIVISION.
.
.
ENTER C "SBISDUPERROR" IN USRXLIB
USING SB-DUPLICATE-ERROR-INFO
GIVING DUP-ERROR-FLAG
.
C Example
.
..
#include "usrxlib.h"
SB_DUPLICATE_ERROR_INFO_DEF dup_info;
short dup_error_flag;
.
.
.
dup_error_flag = SBISDUPERROR(&dup_info);
.
.
.
Considerations

SBISDUPERROR is only available in the HPE NonStop
environment.
SBISENSCRIBESOURCE
This function can be called to quickly determine if the source
associated with the audit trail event is an Enscribe file.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
All
Calling Module Usage
No
N/A
Syntax for COBOL Programmers
HPE Shadowbase Programming Manual—785431-007
139
User Exits
Step #2: Coding the Program
ENTER C "SBISENSCRIBESOURCE" IN USRXLIB
GIVING RETURN-CODE.
Syntax for C Programmers
return_code = SBISENSCRIBESOURCE()
Parameters
RETURN-CODE
returned value
The function will return a 16-bit return code. The following values are
possible:
0 (false) = is not an Enscribe file.
1 (true) = is an Enscribe file.
COBOL Usage Example:
WORKING-STORAGE
01 WS-ITEMS.
05
RETURN-CODE
PIC S9(4) COMP.
PROCEDURE DIVISION
ENTER C "SBISENSCRIBESOURCE" IN USRXLIB
GIVING RETURN-CODE
C Usage Example:
#include "usrxlib.h"
short return_code
return_code = SBISENSCRIBESOURCE()
Considerations

SBISENSCRIBESOURCE is only available in the NonStop
environment.
SBISENSCRIBETARGET
This function can be called to quickly determine if the target being replicated
to, associated with the audit trail event, is an Enscribe file.
HPE Shadowbase Programming Manual—785431-007
140
User Exits
Step #2: Coding the Program
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C "SBISENSCRIBETARGET" IN USRXLIB
GIVING RETURN-CODE.
Syntax for C Programmers
return_code = SBISENSCRIBETARGET();
Parameters
RETURN-CODE
returned value
The function will return a 16-bit return code. The following values are
possible:
0 (false) = is not an Enscribe file.
1 (true) = is an Enscribe file.
COBOL Usage Example:
WORKING-STORAGE
01 WS-ITEMS.
0
05 RETURN-CODE
PIC S9(4) COMP.
PROCEDURE DIVISION.
ENTER C "SBISENSCRIBETARGET" IN USRXLIB
GIVING RETURN-CODE.
C Usage Example:
#include "usrxlib.h"
short return_code;
return_code = SBISENSCRIBETARGET();
Considerations

SBISENSCRIBETARGET is only available in the NonStop
environment.
HPE Shadowbase Programming Manual—785431-007
141
User Exits
Step #2: Coding the Program
SBISKEEPLONGERRECORD
This function can be called to determine if the DBS parameter
KEEPLONGERRECORD related to the current audit trail event is ON.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
All
Calling Module Usage
No
N/A
Syntax for COBOL Programmers
ENTER C "SBISKEEPLONGERRECORD" IN USRXLIB
GIVING RETURN-CODE.
Syntax for C Programmers
return_code = SBISKEEPLONGERRECORD();
Parameters
RETURN-CODE
returned value
The function will return a 16-bit return code. The following values are
possible:
0 (false) = is not set to ON.
1 (true) = is set to ON.
COBOL Usage Example:
.
.
WORKING-STORAGE
01 WS-ITEMS.
05 RETURN-CODE
PIC S9(4) COMP.
.
.
.
PROCEDURE DIVISION
.
.
.
ENTER C "SBISKEEPLONGERRECORD" IN USRXLIB
GIVING RETURN-CODE.
.
.
C Usage Example:
HPE Shadowbase Programming Manual—785431-007
142
User Exits
Step #2: Coding the Program
.
.
.
#include "usrxlib.h"
short return_code;
.
.
return_code = SBISKEEPLONGERRECORD();
.
.
Considerations

SBISKEEPLONGERRECORD is only available in the NonStop
environment.
SBISLOADEREVENT
Given a transaction identifier as input, this function can be called to determine
if the current audit trail event is a HPE Shadowbase LOADER event.
NOTE: You can determine this if you configure LOADER with a HPE
Shadowbase command file and configure a DBS object for this command file
and set the SBCMDFILE parameter to ON.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
Calling Module Usage
All
No
N/A
Syntax for COBOL Programmers
ENTER C "SBISLOADEREVENT" IN USRXLIB
GIVING RETURN-CODE.
Syntax for C Programmers
return_code = SBISLOADEREVENT();
Parameters
RETURN-CODE
returned value
The function will return a 16-bit return code. The following values are
possible:
0 (false) = is not a LOADER event.
1 (true) = is a LOADER event.
COBOL Usage Example:
.
.
WORKING-STORAGE
01 WS-ITEMS.
HPE Shadowbase Programming Manual—785431-007
143
User Exits
Step #2: Coding the Program
05
05
EVENT-TRANSID
RETURN-CODE
NATIVE-8
PIC S9(4) COMP.
.
.
.
PROCEDURE DIVISION
.
.
.
ENTER C "SBGETTRANSIDADT" IN USRXLIB
GIVING EVENT-TRANSID.
ENTER C "SBISLOADEREVENT" IN USRXLIB
GIVING RETURN-CODE.
.
.
C Usage Example:
.
.
.
#include "usrxlib.h"
long long event_transid;
short
return_code;
.
.
event_transid = SBGETTRANSIDADT();
return_code = SBISLOADEREVENT();
.
.
Considerations

SBISLOADEREVENT is only available in the NonStop
environment.
SBISREJECTLOG
This function can be called to determine if the CONS parameter
REJECTLOG is enabled.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
Calling Module Usage
All
No
N/A
Syntax for COBOL Programmers
ENTER C "SBISREJECTLOG" IN USRXLIB
GIVING RETURN-CODE.
Syntax for C Programmers
HPE Shadowbase Programming Manual—785431-007
144
User Exits
Step #2: Coding the Program
return_code = SBISREJECTLOG();
Parameters
RETURN-CODE
returned value
The function will return a 16-bit return code. The following values are
possible:
0 (false) = is not set to ON.
1 (true) = is set to ON.
COBOL Usage Example:
.
WORKING-STORAGE
01 WS-ITEMS.
05 RETURN-CODE
PIC S9(4) COMP.
.
.
PROCEDURE DIVISION.
.
.
.
ENTER C "SBISREJECTLOG" IN USRXLIB
GIVING RETURN-CODE.
.
.
C Usage Example:
.
.
.
#include "usrxlib.h"
short return_code;
.
.
return_code = SBISREJECTLOG();
.
.
Considerations

SBISREJECTLOG is only available in the NonStop environment.
SBISREJECTLOGLOADER
This function can be called to determine if the CONS parameter
REJECTLOGLOADER is enabled.
Note that this parameter will be used in a future release.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
All
Calling Module Usage
No
N/A
Syntax for COBOL Programmers
HPE Shadowbase Programming Manual—785431-007
145
User Exits
Step #2: Coding the Program
ENTER C "SBISREJECTLOGLOADER" IN USRXLIB
GIVING RETURN-CODE.
Syntax for C Programmers
return_code = SBISREJECTLOGLOADER();
Parameters
RETURN-CODE
returned value
The function will return a 16-bit return code. The following values are
possible:
0 (false) = is not set to ON.
1 (true) = is set to ON.
COBOL Usage Example:
.
WORKING-STORAGE
01 WS-ITEMS.
05 RETURN-CODE
PIC S9(4) COMP.
.
.
PROCEDURE DIVISION.
.
.
.
ENTER C "SBISREJECTLOGLOADER" IN USRXLIB
GIVING RETURN-CODE.
.
.
C Usage Example:
.
.
.
#include "usrxlib.h"
short return_code;
.
.
return_code = SBISREJECTLOGLOADER();
.
.
Considerations

SBISREJECTLOGLOADER is only available in the NonStop
environment.
SBISREJECTSKIP
This function can be called to determine if the CONS parameter REJECTSKIP
is enabled.
Product
Availability
Calling Module Usage
HPE Shadowbase Programming Manual—785431-007
146
User Exits
Step #2: Coding the Program
Product
HPE NonStop
Server
Other Servers
Availability
Yes
All
Calling Module Usage
No
N/A
Syntax for COBOL Programmers
ENTER C "SBISREJECTSKIP" IN USRXLIB
GIVING RETURN-CODE.
Syntax for C Programmers
return_code = SBISREJECTSKIP();
Parameters
RETURN-CODE
returned value
The function will return a 16-bit return code. The following values are
possible:
0 (false) = is not set to ON.
1 (true) = is set to ON.
COBOL Usage Example:
.
WORKING-STORAGE
01 WS-ITEMS.
05 RETURN-CODE
PIC S9(4) COMP.
.
.
PROCEDURE DIVISION.
.
.
.
ENTER C "SBISREJECTSKIP" IN USRXLIB
GIVING RETURN-CODE.
.
.
C Usage Example:
.
.
.
#include "usrxlib.h"
short return_code;
.
.
return_code = SBISREJECTSKIP();
.
.
Considerations

SBISREJECTSKIP is only available in the NonStop environment.
HPE Shadowbase Programming Manual—785431-007
147
User Exits
Step #2: Coding the Program
SBISSBCMDFILE
This function can be called to determine if the DBS parameter SBCMDFILE
related to the current audit trail event is ON.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
All
Calling Module Usage
No
N/A
Syntax for COBOL Programmers
ENTER C "SBISSBCMDFILE" IN USRXLIB
GIVING RETURN-CODE.
Syntax for C Programmers
return_code = SBISSBCMDFILE();
Parameters
RETURN-CODE
returned value
The function will return a 16-bit return code. The following values are
possible:
0 (false) = is not set to ON.
1 (true) = is set to ON.
COBOL Usage Example:
.
.
WORKING-STORAGE
01 WS-ITEMS.
05 RETURN-CODE
PIC S9(4) COMP.
.
.
PROCEDURE DIVISION.
.
.
.
ENTER C "SBISSBCMDFILE" IN USRXLIB
GIVING RETURN-CODE.
.
.
C Usage Example:
HPE Shadowbase Programming Manual—785431-007
148
User Exits
Step #2: Coding the Program
.
.
.
#include "usrxlib.h"
short return_code;
.
.
return_code = SBISSBCMDFILE();
.
.
Considerations

SBISSBCMDFILE is only available in the NonStop environment.
SBISSQLMXSOURCE
This function can be called to quickly determine if the source
associated with the audit trail event is an SQL/MX table.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C "SBISSQLMXSOURCE" IN USRXLIB
GIVING SRC-TYPE-RTRN-CODE.
Syntax for C Programmers
src_type_rtrn_code = SBISSQLMXSOURCE()
Parameters
SRC-TYPE-RTRN-CODE
returned
value
The function will return a 16-bit return code. The following values are
possible:
0 (false) = is not an SQL/MX table.
1 (true) = is an SQL/MX table.
COBOL Usage Example:
HPE Shadowbase Programming Manual—785431-007
149
User Exits
Step #2: Coding the Program
WORKING-STORAGE
01 WS-ITEMS.
05 SRC-TYPE-RTRN-CODE
88 SRC-IS_NOT_SQLMX
88 SRC-IS_SQLMX
PIC S9(4) COMP.
VALUE 0.
VALUE 1.
PROCEDURE DIVISION.
ENTER C "SBISSQLMXSOURCE" IN USRXLIB
GIVING SRC-TYPE-RTRN-CODE.
C Usage Example:
#include "usrxlib.h"
short src_type_rtrn_code;
src_type_rtrn_code = SBISSQLMXSOURCE();
Considerations

SBISSQLMXSOURCE is only available in the NonStop
environment.
SBISSQLMXTARGET
This function can be called to quickly determine if the target associated
with the audit trail event is an SQL/MX table.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C "SBISSQLMXTARGET" IN USRXLIB
GIVING TGT-TYPE-RTRN-CODE.
Syntax for C Programmers
tgt_type_return_code = SBISSQLMXTARGET()
HPE Shadowbase Programming Manual—785431-007
150
User Exits
Step #2: Coding the Program
Parameters
TGT-TYPE-RTRN-CODE
returned
value
The function will return a 16-bit return code. The following values are
possible:
0 (false) = is not an SQL/MX table.
1 (true) = is an SQL/MX table.
COBOL Usage Example:
WORKING-STORAGE
01 WS-ITEMS.
05 TGT-TYPE-RTRN-CODE
88 TGT-IS_NOT_SQLMX
88 TGT-IS_SQLMX
PIC S9(4) COMP.
VALUE 0.
VALUE 1.
PROCEDURE DIVISION.
ENTER C "SBISSQLMXTARGET" IN USRXLIB
GIVING TGT-TYPE-RTRN-CODE.
C Usage Example:
#include "usrxlib.h"
short tgt_type_rtrn_code;
tgt_type_rtrn_code = SBISSQLMXTARGET();
Considerations

SBISSQLMXTARGET is only available in the NonStop
environment.
SBISSQLSOURCE
This function can be called to quickly determine if the source
associated with the audit trail event is an SQL/MP table.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
All
Calling Module Usage
No
N/A
Syntax for COBOL Programmers
HPE Shadowbase Programming Manual—785431-007
151
User Exits
Step #2: Coding the Program
ENTER C "SBISSQLSOURCE" IN USRXLIB
GIVING RETURN-CODE.
Syntax for C Programmers
return_code = SBISSQLSOURCE()
Parameters
RETURN-CODE
returned value
The function will return a 16-bit return code. The followingvalues are
possible:
0 (false) = is not an SQL table or is a SQL/MX table.
1 (true) = is an SQL table.
COBOL Usage Example:
WORKING-STORAGE
01 WS-ITEMS.
05 RETURN-CODE
PIC S9(4) COMP.
PROCEDURE DIVISION.
ENTER C "SBISSQLSOURCE" IN USRXLIB
GIVING RETURN-CODE.
C Usage Example:
#include "usrxlib.h"
short return_code;
return_code = SBISSQLSOURCE();
Considerations

SBISSQLSOURCE is only available in the NonStop environment.
SBISSQLTARGET
This function can be called to quickly determine if the target being replicated
to, associated with the audit trail event, is an SQL/MP table.
Product
Availability
Calling Module Usage
HPE Shadowbase Programming Manual—785431-007
152
User Exits
Step #2: Coding the Program
Product
HPE NonStop
Server
Other Servers
Availability
Yes
All
Calling Module Usage
No
N/A
Syntax for COBOL Programmers
ENTER C "SBISSQLTARGET" IN USRXLIB
GIVING RETURN-CODE.
Syntax for C Programmers
return_code = SBISSQLTARGET();
Parameters
RETURN-CODE
returned value
The function will return a 16-bit return code. The following values are
possible:
0 (false) = is not an SQL table or is an SQL/MX table.
1 (true) = is an SQL table.
COBOL Usage Example:
WORKING-STORAGE
01 WS-ITEMS.
05 RETURN-CODE
PIC S9(4) COMP.
PROCEDURE DIVISION.
ENTER C "SBISSQLTARGET" IN USRXLIB
GIVING RETURN-CODE.
C Usage Example:
#include "usrxlib.h""
s hort return_code;
return_code = SBISSQLTARGET();
Considerations

SBISSQLTARGET is only available in the NonStop environment.
HPE Shadowbase Programming Manual—785431-007
153
User Exits
Step #2: Coding the Program
SBISUNDOEVENT
This function is called from USRXPROCESS or USRXEXCEPTION to
determine if the event is the result of a TM/MP back-out (“undo” or
aborted transaction) or not.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C “SBISUNDOEVENT” IN USRXLIB
GIVING RETURN-CODE.
Syntax for C Programmers
short SBISUNDOEVENT (void)
Parameters
RETURN-CODE
returned value

Indicates the event is a backout event or not. Possible values: 0 =
FALSE, event is not a backout event or 1 = TRUE, event is a
backout event.
Considerations

SBISUNDOEVENT is only available in the NonStop environment.

Returns 2 byte integer (NATIVE-2) in the function return argument.

HPE Shadowbase does not ignore backout events by default. It
replays them.

If Consumer parameter ABORTTRANS is set to ON, use this
function to determine if event is result of backout. Use
SBSETIGNORE to ignore backout events and speed up processing
of aborted transactions.
SBLOG Functions
The SBLOG functions are used to enable the user exit to generate
messages. The SBLOG functions are detailed below.
SBLOGEVENT
HPE Shadowbase Programming Manual—785431-007
154
User Exits
Step #2: Coding the Program
This function is called from USRXPROCESS or USRXEXCEPTION to
enable the user exit to generate EMS messages (in the NonStop
environment) or error log messages (in the Other Servers
environment) using the HPE Shadowbase library functions.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
Yes
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
All
Syntax for COBOL Programmers
ENTER C "SBLOGEVENT" IN USRXLIB
USING CRITICAL-EVENT, EVENT-NO, NEED-OPERATOR, MSG-TEXT.
Syntax for C Programmers
void SBLOGEVENT(short critical_event,
short event_no,
short need_operator,
char *msg_text)
Parameters
CRITICAL-EVENT
input

Determines how critical the message is that displays in EMS.
Possible values are: 0 = informative event, 1 = critical event.
EVENT-NO
input

Determines the event number displayed in the EMS message. See
considerations below for more details on setting this number.
NEED-OPERATOR
input

Further determines criticality by indicating whether operator
intervention is required or not. Possible values:
0 = No operator intervention required
1 = Operator intervention is required.
MSG-TEXT
input

Character 1 to 3230 bytes in length (prior to HPE NonStop
Shadowbase release 3.964C, only permitted 1 to 128 bytes in
length).

Must be null terminated.

This is the actual text that displays in EMS. For example:
05 EVENT-MSG.
HPE Shadowbase Programming Manual—785431-007
155
User Exits
Step #2: Coding the Program
10 MSG-TEXT PIC X(29)
VALUE “ERROR OCCURRED GETTING
COLUMN”
10 FILLER
PIC X VALUE LOW-VALUES.
Considerations

Setting event number to 0 will cause the default HPE Shadowbase
event number of 2043 (for user generated EMS messages) to be
used.

HPE Shadowbase currently uses event numbers 2000 through
2052. Event numbers higher than this may be used in the future.

The maximum length of the message text is 3230 characters.
Longer messages will be truncated.

If your message text needs to be longer than 3230 characters, use
multiple SBLOGEVENT calls.

The message text must be null terminated.
Related Manuals

For more information on reporting events in EMS see the NonStop
EMS Manual.
SBLOGTRACEMSG
This function can be called from any user exit function to add your own
messages to the user trace file.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C "SBLOGTRACEMSG" IN USRXLIB
USING MESSAGE, NEW-LINE
GIVING RETURN-CODE
Syntax for C Programmers
short SBLOGTRACEMSG(char *message, short new_line)
Parameters
RETURN-CODE
returned value

The following are the meanings for the return values:
HPE Shadowbase Programming Manual—785431-007
156
User Exits
Step #2: Coding the Program
0 = an error occurred,
1 = no error
MESSAGE
input

The <message> is addressed to the text that you want logged.
The message must be null terminated.
NEW-LINE
input

Set <output newline> to 0 if a newline character is not to be output
or set to 1 if a newline character is to be output.
Considerations

SBLOGTRACEMSG is only available in the NonStop environment.
SBNOTIFYUSRXKEYS Function
The SBNOTIFYUSRXKEYS function is used to inform HPE
Shadowbase to use a “where” clause that has been formatted by the
user exit instead of using one built by the product. The
SBNOTIFYUSRXKEYS function is detailed below.
For SQL target tables, this function is called from USRXPROCESS or
USRXEXCEPTION to inform HPE Shadowbase to use a “where”
clause that has been formatted by the user exit instead of using one
built by the product.
In the HPE NonStop Shadowbase environment, when the Consumer
needs to apply an update or delete to an SQL target table, it must build
a “where” clause to identify the row to be processed before trying the
operation. It normally builds this “where” clause based on the source
key data from the audit trail.
In the HPE Shadowbase Other Servers environment, the “where”
clause built by the product is based on the key structure of the source
table.
If the key columns are different in the target than the source, you must
use SBNOTIFYUSRXKEYS to notify HPE Shadowbase that the keys
are different and then use SBPUTWHERECOLUMN to build the new
key structure (build custom “where” clause).
Product
HPE NonStop
Server
Other Servers
Availability
Yes
Yes
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
USRXPROCESS
HPE Shadowbase Programming Manual—785431-007
157
User Exits
Step #2: Coding the Program
Product
Availability
Calling Module Usage
USRXEXCEPTION
Syntax for COBOL Programmers
ENTER C "SBNOTIFYUSRXKEYS" IN USRXLIB
Parameters
None
Returns
None
HPE Shadowbase Programming Manual—785431-007
158
User Exits
Step #2: Coding the Program
Syntax for C Programmers
void SBNOTIFYUSRXKEYS(void)
Parameters
None
Considerations

Not applicable to Enscribe targets.

Key columns in the source or target are ignored when preparing the
SQL statement “where” clause and the columns that were set when
the user exit called SBPUTWHERECOLUMN or
SBPUTWHERECOLUMNOPEN are used instead.

There are no parameters or arguments associated with this call.
SBPUT Functions
The SBPUT functions are used for putting the manipulated data back
into the HPE Shadowbase object (NonStop Consumer or Other
Servers). The SBPUT functions are detailed below.
General Considerations for all SBPUT Functions:

SBPUT calls that are made in USRXPROCESS and are included
in sbocons (DOC writer), have no effect on the statements
written to the DOC. If you need to change column values and
put items, this code should be incorporated into the Transaction
Replay Server (TRS).

The last SBPUT will be the one that is used if a user exit
executes multiple SBPUT calls for the same column during the
processing of a single event. This is even the case if the first
SBPUT call was performed in USRXPROCESS and a
subsequent SBPUT call was performed in USRXEXCEPTION.

With previous versions, the Consumer appended data “put” by a user
exit in the order that user exit “put” it. If the ordering by the user exit
was not consistent, the Consumer generated multiple equivalent SQL
statements whose only difference was the order of the columns in the
statement. Each of the equivalent statements was treated as a
different statement, affecting statement caching on the Other Servers
system.

The CONS will now generate statement column data (list and data) in
a consistent order regardless of the order of user exit “puts” for insert
and update events, and optionally for delete events. This order is
HPE Shadowbase Programming Manual—785431-007
159
User Exits
Step #2: Coding the Program
driven from the target column order in the schema definition. Note that
consistent ordering of column data for deletes is optional since it
requires more overhead than with the previous version. Column
ordering for deletes is enabled by setting the DBS parameter
ORDERCOLSFORDEL to ON. Additionally, the column ordering logic
can be disabled for all operations by setting the TACL PARAM
SBCONSORDERCOLS 0.
SBPUTCOLUMN
This function is called from USRXPROCESS or USRXEXCEPTION to
modify a column value before it is applied to a target file/table. When
used in conjunction with SBSETTARGET (to override the target name),
it is possible to write to target SQL tables that HPE Shadowbase does
not know about. See SBSETTARGET API description below for
information on overriding targets.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C "SBPUTCOLUMN" IN USRXLIB
USING COL-NAME, COL-LEN, COL-VALUE
GIVING RETURN-CODE.
Syntax for C Programmers
short SBPUTCOLUMN (char *col_name, short col_len, char *col_value)
Parameters
RETURN-CODE
returned value

Indicates whether call completed successfully or encountered an
error. Possible values:
-1
=
can't use for Other Servers environment unless the
column is in the schema (not a target override)
-2
=
target override is not set for an unknown column
(column length > 0 or column name doesn’t exist in target)
-3
=
bad column name request format
-4
=
column not found in schema
-5
=
bad length value supplied or not a nullable column
HPE Shadowbase Programming Manual—785431-007
160
User Exits
Step #2: Coding the Program
-6
=
must put a key column for an SQL override update or
delete event with
SBPUTWHERECOLUMN
1
=
success, column put recorded
COL-NAME
input

1 to 30 bytes long

null terminated

in SQL or DDL format

Name of the field/column being put. For example:
COLUMN-NAME.
05 FULL-NAME PIC X(11) VALUE "RECORD_TYPE.”
05 FILLER
PIC X VALUE LOW-VALUES.
COL-LEN
input

Length of the field/column being “put.” Valid values (see
Considerations for more details):
-1 = set column to null
0 = use target column length in schema (except for VARCHAR
columns, see consideration below)
>0 = must equal column length defined in schema (if not a target
override)
COL-VALUE
input

Must be in internal (TM/MP storage) format

Size = <col-len>

The value of the field/column to be “put” into target
Considerations

SBPUTCOLUMN is only available in the NonStop environment.

On return from the user exit, any "put items" will replace data in the
source file/table.

The user exit should pass the internal form (TM/MP stored form) of
the data to this function (not the text/display format). See TM/MP
Application Programmer’s Manual for more information on internal
formats.

HPE Shadowbase does not validate the data to make sure it is the
proper type. Improper data may result in a data exception error
that will force an abend or call to the USRXEXCEPTION user exit.

For replication to an Other Servers system, if a TARGETFILE
parameter is specified (HPE Shadowbase has the schema) and the
target file is not overridden by an SBSETTARGET call, use
SBPUTCOLUMN and SBPUTWHERECOLUMN to replace column
values.

For replication to an Other Servers system when the schema is not
known (i.e., no TARGETFILE parameter is specified and the user
HPE Shadowbase Programming Manual—785431-007
161
User Exits
Step #2: Coding the Program











exit is overriding), use SBPUTCOLUMNOPEN and
SBPUTWHERECOLUMNOPEN and the "external form.”
When overriding the target (SBSETTARGET called), you must put
all non-key target column values by calling SBPUTCOLUMN... and
put the where clause columns (key columns) by calling
SBPUTWHERECOLUMN....
The SBPUTCOLUMN function can be used to repair bad data in
the USRXEXCEPTION process because any SBPUTCOLUMN
items previously processed during USRXPROCESS are retained
and the repaired items will overlay the bad values.
If nulling an Enscribe field, HPE Shadowbase will initialize the
target field based upon the field's data type (i.e., set to zeros or
spaces).
If nulling an SQL column, the column must be defined as nullable
Make sure that the values for columns you put are the appropriate
length. If you set the column length field greater than zero when
you call SBPUTCOLUMN, it must be the same value as the actual
fixed length of the column.
If you are not overriding the target (via SBSETTARGET) or putting
a varchar column, set the column length in the call to
SBPUTCOLUMN to zero.
Must provide the length for all columns you put for a target override
(overridden by SBSETTARGET call).
The extra length bytes in a varchar should be ignored. Use just the
string of characters and the length of that string.
When you "put" SQL DATETIME and INTERVAL columns, the
values you pass to SBPUTCOLUMN must be in internal form (i.e.,
integer values of the correct TM/MP structure). See TM/MP
Application Programmers Guide for more details in internal format.
When you need to “put” any primary key columns, use
SBPUTWHERECOLUMN or SBPUTWHERECOLUMNOPEN.
When applied to a VARCHAR column, COL-LEN must be set to the
length of the data being put. If 0 is used, then a 0-length value will
be used for the column.
Related Manuals

For information on the DATETIME and INTERVAL column internal
forms, see the DATETIME and INTERVAL Fields discussion in
section 5 of the NonStop TM/MP Application Programmer's Guide
for D30.
SBPUTCOLUMNOPEN
This function can be called from USRXPROCESS or
USRXEXCEPTION to modify a non-key column value in an SQL
statement generated by HPE Shadowbase replication to an Other
HPE Shadowbase Programming Manual—785431-007
162
User Exits
Step #2: Coding the Program
Servers system. On return from the user exit, HPE Shadowbase will
use any "put items" instead of the data in the source file/table.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
Yes
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
USRXPROCESS
USRXEXCEPTION
Syntax for COBOL Programmers
ENTER C "SBPUTCOLUMNOPEN" IN USRXLIB
USING COL-NAME, COL-LEN, COL-VALUE, STORE-TYPE
GIVING RETURN-CODE
Syntax for C Programmers
short SBPUTCOLUMNOPEN (char *col_name,
short col_len,
char *col_value,
short store_type);
Parameters
RETURN-CODE
returned value

Indicates whether call completed successfully or encountered an
error. Possible values:
-1
=
can't use for direct environment
-2
=
target override is not set for unknown column
-3
=
bad column name request format
-4
=
column not found in schema
-5
=
bad length value supplied
-6
=
must put a key column for an SQL override update or
delete event with
SBPUTWHERECOLUMN
-8
=
store_type parameter is invalid (NonStop only)
1
=
column put recorded
COL-NAME
input

1 to 30 bytes long

null terminated

in SQL or DDL format

Name of the field/column being put. For example:
COLUMN-NAME.
05 FULL-NAME PIC X(11) VALUE "RECORD_TYPE.”
05 FILLER
PIC X VALUE LOW-VALUES.
COL-LEN
input
HPE Shadowbase Programming Manual—785431-007
163
User Exits
Step #2: Coding the Program

Length of the field/column being “put.” Valid values (see
Considerations for more details):
-1 = set column to null
0 = use target column length in schema
>0 = must equal column length defined in schema (if not a target
override)
COL-VALUE
input

Field/column size = <col-len>

In internal or external format depending on <store type>

the value to be “put” into target
STORE-TYPE
input

Storage type (internal or external) of the <colvalue> of the
field/column being “put.”
0
=
column is in internal format & is present in target
schema
1
=
value is an external string (quotes will be added to
value)
2
=
value is an external non-string value (no quotes will
be added)
Considerations

The user exit should pass the external form of the data to this
function (text format) if the <store type> parameter is set greater
than 0.

If <store type> is set to 0, the internal format (TM/MP storage
format) should be utilized.

A 0 <store type> can only be used if the column is defined in the
target schema.

Unless overriding the TARGETFILE (via SBSETTARGET call), the
column must be defined in the target schema for all <store types>.

When replicating to an Other Servers system, if a TARGETFILE
parameter is specified (HPE Shadowbase has the schema) and
you are not overriding the target, use SBPUTCOLUMN and
SBPUTWHERECOLUMN.

In replication to an Other Servers system, when the schema is not
known (i.e., no TARGETFILE parameter is specified or the user exit
is overriding), use SBPUTCOLUMNOPEN and
SBPUTWHERECOLUMNOPEN and the "external form.”

When overriding the TARGETFILE, you must put all target column
values by calling SBPUTCOLUMNOPEN for each non-key column
and put the key (“where” clause) columns by calling
SBPUTWHERECOLUMNOPEN.

Use the SBPUTCOLUMNOPEN function to repair bad data in
USRXEXCEPTION when replicating to an Other Servers system.
HPE Shadowbase Programming Manual—785431-007
164
User Exits
Step #2: Coding the Program








Any SBPUTCOLUMNOPEN items previously processed during
USRXPROCESS are retained and the repaired items will overlay
the bad values.
Set the length parameter to -1 before calling
SBPUTCOLUMNOPEN to initialize an Enscribe target field or to set
a null value in an SQL column. For SQL, the column must be
defined as nullable.
Make sure that the values for columns you "put" are the appropriate
length. If you set the length field greater than zero when you call
SBPUTCOLUMNOPEN, the length value must be the same as the
actual fixed length of the column.
If you are not overriding the target (via SBSETTARGET) or putting
a varchar column, set the length in the call to
SBPUTCOLUMNOPEN to zero.
Must provide the length for all columns you put for a target override
(declared with an SBSETTARGET call).
The extra length bytes in a varchar should be ignored. Use just the
string of characters and the length of that string.
When you "put" SQL DATETIME and INTERVAL columns, the
values you pass to SBPUTCOLUMNOPEN must be in internal form
(i.e., integer values of the correct TM/MP structure).
When you need to “put” key columns, use
SBPUTWHERECOLUMN or SBPUTWHERECOLUMNOPEN.
SBPUTCOLUMNOPEN should be reserved for situations where a
dummy target schema is not used. This API causes strings to be
appended to statements resulting in the caching Other Servers
treating them as new statements. This causes an excessive
number of statement context switches. Instead, SBPUTCOLUMN
should be used.
Related Manuals

For information on the DATETIME and INTERVAL column internal
forms, see the DATETIME and INTERVAL Fields discussion in
section 5 of the NonStop TM/MP Application Programmer's Guide
for D30.
SBPUTRECORD
This function is called from USRXPROCESS or USRXEXCEPTION to
put an entire record image to be used by HPE Shadowbase I/O to an
Enscribe target file when a target override has been set by a call to
SBSETTARGET. This function can also be used to put Enscribe
records when you are changing field data; however in that case, it is
more efficient to just put the individual fields that are different. See
SBSETTARGET for more information on target overrides.
HPE Shadowbase Programming Manual—785431-007
165
User Exits
Step #2: Coding the Program
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C "SBPUTRECORD" IN USRXLIB
USING REC-LEN, REC-DATA
GIVING RETURN-CODE.
Syntax for C Programmers
short SBPUTRECORD(short rec_len, char *rec_data)
Parameters
RETURN-CODE
returned value

Indicates whether call completed successfully or encountered an
error. Possible values:
-1 = can't use for Other Servers environment
-2 = target override is not set
-3 = bad length value supplied
0 = target override not established
1 = record has been put for shadowing
REC-LEN

The length of the record being “put.”
REC-DATA

Length must match <reclen> value.

the entire record image.
input
input
Considerations

SBPUTRECORD is only available in the NonStop environment.

SBPUTRECORD must be called if a target override has been
established and can only be called for target overrides.

Enscribe only.
SBPUTRELATIVEADDR
This function is called from USRXPROCESS or USRXEXCEPTION to
set the relative record number for a relative Enscribe file. It would be
used in cases where you need to control the relative record numbers
HPE Shadowbase Programming Manual—785431-007
166
User Exits
Step #2: Coding the Program
within a file. On return to HPE Shadowbase from the user exit, this is
the number that will be used for executing the I/O to the target.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C "SBPUTRELATIVEADDR" IN USRXLIB
USING REC-ADDR
GIVING <return code>.
Syntax for C Programmers
short SBPUTRELATIVEADDR(long rec_addr)
Parameters
RETURN-CODE
returned value

Indicates whether call completed successfully or encountered an
error. Possible values:
-1 = bad record number
-2 = incorrect source file type (must be Enscribe relative)
1 = relative record number set
-3 = wrong API used for Format 2 file. (Use
SBPUTRELATIVEADDR64 for Format 2
files.)
REC-ADDR

The relative record number value to set.
input
Considerations

SBPUTRELATIVEADDR is only available in the NonStop
environment.

In COBOL, relative record numbers are relative to 1; otherwise, it is
zero-relative.

Enscribe only.
SBPUTRELATIVEADDR64
This function is called from USRXPROCESS or USRXEXCEPTION to
set the relative record number for a Format 2 relative Enscribe file. It
would be used in cases where you need to control the relative record
HPE Shadowbase Programming Manual—785431-007
167
User Exits
Step #2: Coding the Program
numbers within a Format 2 file. On return to HPE Shadowbase from
the user exit, this is the number that will be used for executing the I/O
to the target.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C "SBPUTRELATIVEADDR64" IN USRXLIB
USING REC-ADDR
GIVING RETURN-CODE.
Syntax for C Programmers
short SBPUTRELATIVEADDR64(long long rec_addr)
Parameters
RETURN-CODE
returned value

Indicates whether call completed successfully or encountered an
error. Possible values:
-1 = bad record number
-2 = incorrect source file type (must be Enscribe relative)
1 = relative record number set
REC-ADDR

The relative record number value to set.
input
Considerations

SBPUTRELATIVEADDR64 is only available in the NonStop
environment.

In COBOL, relative record numbers are relative to 1; otherwise, it is
zero-relative.

Enscribe only.
SBPUTWHERECOLUMN
Whenever a process is going to delete or update an SQL table, it must
build a where clause to use to access the affected SQL row. This
function is called from USRXPROCESS or USRXEXCEPTION to
customize the where clause for a delete or update operation against an
HPE Shadowbase Programming Manual—785431-007
168
User Exits
Step #2: Coding the Program
SQL target table. You must use this whenever a key column is being
changed. Before calling this function, you must call
SBNOTIFYUSRXKEYS to alert HPE Shadowbase to the fact that you
are customizing the “where” clause and that it should not build one of
its own. On return from the user exit, HPE Shadowbase will use any
"where items" to generate the “where clause” in the SQL statement.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C "SBPUTWHERECOLUMN" IN USRXLIB
USING COL-NAME, COL-LEN, COL-VALUE
GIVING RETURN-CODE.
Syntax for C Programmers
short SBPUTWHERECOLUMN (char *col_name, short col_len, char *col_value)
Parameters
RETURN-CODE
returned value

Indicates whether call completed successfully or encountered an
error. Possible values:
-1 = can't use for Other Servers environment unless the column is
in the schema (not a target override)
-2 = target override is not set for an unknown column
-3 = bad column name request format
-4 = column not found in schema
-5 = bad length value supplied or not a nullable column
-7 = must use SBPUTCOLUMN for an insert operation
1 = column put recorded
COL-NAME
input

One to 30 bytes long

in SQL (ABC_DEF) format

Must be null terminated

name of the field to put. For example:
COLUMN-NAME.
05 FULL-NAME PIC X(11) VALUE "RECORD_TYPE.”
05 FILLER
PIC X VALUE LOW-VALUES.
HPE Shadowbase Programming Manual—785431-007
169
User Exits
Step #2: Coding the Program
COL-LEN
input

byte integer (NATIVE-2)

length of the field/column being put. Valid values (see
Considerations for more details):
-1 = set column value to null
0 = use target column length in schema
>0 = must equal column length defined in schema (if not a target
override)
COL-VALUE

Field size = <col-len> value.

in internal format (TM/MP storage format)

the value to be “put” into target;
input
Considerations

SBPUTWHERECOLUMN is only available in the NonStop
environment.

If you want a completely customized “where clause,” you should
call SBNOTIFYUSRXKEYS, first, to indicate this to HPE
Shadowbase. Then do an SBPUTWHERECOLUMN for each
column constituting the key.

If you do not call SBNOTIFYUSRXKEYS, HPE Shadowbase will
append the custom "where items" to the end of the standard “where
clause” that the Consumer will build based on the key information
contained in the audit trail.

Pass the internal form (TM/MP storage format) of the data to this
function (not text format).

If a TARGETFILE parameter is specified (HPE Shadowbase has
the schema) and you are not overriding the target (via
SBSETTARGET), use SBPUTCOLUMN and
SBPUTWHERECOLUMN.

When the schema is not known (i.e., no TARGETFILE parameter is
specified and the user exit is overriding), use
SBPUTCOLUMNOPEN and SBPUTWHERECOLUMNOPEN and
the "external form" of the data.

When overriding the target, you must put all non-key target column
values by calling SBPUTCOLUMN and put the “where” clause
columns (key columns) by calling SBPUTWHERECOLUMN.

Use the SBPUTWHERECOLUMN function to repair bad data in
USRXEXCEPTION. Any SBPUT… items previously processed
during USRXPROCESS are retained and the repaired items will
overlay the bad values.

Set the length parameter to -1 before calling
SBPUTWHERECOLUMN to initialize an Enscribe target field or to
HPE Shadowbase Programming Manual—785431-007
170
User Exits
Step #2: Coding the Program







set a null value in an SQL column. For SQL, the column must be
defined as nullable.
The value for columns you put must be the correct length.
Except for varchar columns, if you set the length field greater than
zero when you call SBPUTWHERECOLUMN, it must be the same
value as the actual fixed length of the column.
If you are not overriding the target (via SBSETTARGET) or putting
a varchar column, set the column length in the call to
SBPUTWHERECOLUMN to zero.
For target override, set the length for all columns you put.
If overriding an SQL target table and you want to put a varchar
column value, the actual length of the value being put must be
included in the first two bytes (binary) of the column value passed
as the parameter for the data (passed in <colvalue> below). You
also must add 2 to the column length value parameter (<col-len>
below) to account for the varchar length in the data.
When you put SQL DATETIME and INTERVAL columns, the
values you pass to SBPUTWHERECOLUMN must be in internal
form (i.e., integer values of the correct TM/MP structure).
Not for use with Enscribe targets.
Related Manuals

For information on the DATETIME and INTERVAL column internal
forms, see the DATETIME and INTERVAL Fields discussion in
section 5 of the NonStop TM/MP Application Programmer's Guide
for D30
SBPUTWHERECOLUMNOPEN
For replication to an Other Servers system, this function is called from
USRXPROCESS or USRXEXCEPTION to modify the “where clause”
for a delete or update event. On return from the user exit, HPE
Shadowbase will use any "where" items to generate the “where" clause
in the text SQL statement sent to an Other Servers environment.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
Yes
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
USRXPROCESS
USRXEXCEPTION
Syntax for COBOL Programmers
HPE Shadowbase Programming Manual—785431-007
171
User Exits
Step #2: Coding the Program
ENTER C "SBPUTWHERECOLUMNOPEN" IN USRXLIB
USING COL-NAME, COL-LEN, COL-VALUE, STORE-TYPE
GIVING RETURN-CODE.
Syntax for C Programmers
short SBPUTWHERECOLUMNOPEN (char *col_name,
short
col_len,
char
*col_value,
short
store_type)
Parameters
RETURN-CODE
returned value

indicates whether call completed successfully or encountered an
error. Possible values:
-1 = can't use for direct environment
-2 = target override is not set for unknown column
-3 = bad column name request format
-4 = column not found in schema
-5 = bad length value supplied
-7 = must use SBPUTCOLUMNOPEN for an insert operation
-8 = store_type parameter is invalid (NonStop only)
1 = column put recorded
COL-NAME
input

1 to 30 bytes long

null terminated

in SQL or DDL format

name of the field/column being put. For example:
COLUMN-NAME.
05 FULL-NAME
PIC X(11) VALUE "RECORD_TYPE.”
05 FILLER PIC X VALUE LOW-VALUES.
COL-LEN
input

length of the field/column being “put.” Valid values (see
Considerations for more details):
-1 = set column to null
0 = use target column length in schema
>0 = must equal column length defined in schema (if not a target
override)
COL-VALUE
input

Field/column size = <col-len>

In internal or external format depending on <store type>
HPE Shadowbase Programming Manual—785431-007
172
User Exits
Step #2: Coding the Program

the value to be “put” into target.
STORE-TYPE
input

storage type (internal or external) of the <colvalue> of the
field/column being “put.”
0 = column is in internal format & is present in target schema
1 = value is an external string (quotes will be added to value)
2 = value is an external non-string value (no quotes will be added)
Considerations

Use any time you need to modify a key column.

To customize a “where clause” (modify keys), first call
SBNOTIFYUSRXKEYS to indicate this then put all key columns.

If you do not call SBNOTIFYUSRXKEYS, the custom "where items"
are appended to the end of the standard “where clause.”

Pass the external form of the data to this function (string format) if
the <store type> parameter is greater than 0.

If it is set to 0, the internal format (TM/MP storage format) should
be utilized. A 0 <store type> can only be used if the column is
present in the target schema.

Unless overriding the target (via SBSETTARGET), the column must
be present in the target schema for all <store types>.

Use the SBPUTWHERECOLUMNOPEN function to repair bad data
in USRXEXCEPTION. Note that any
SBPUTWHERECOLUMNOPEN items previously processed during
USRXPROCESS are retained and the repaired items will overlay
the bad values.

Set the length parameter to -1 before calling
SBPUTWHERECOLUMNOPEN to initialize an Enscribe target field
or to set a null value in an SQL column. For SQL, the column must
be defined as nullable.

Make sure that the values for columns you "put" are the appropriate
length.

Except for varchar columns, if you set the length field greater than
zero when you call SBPUTWHERECOLUMNOPEN, it must be the
same value as the actual length of the column.

If you are not overriding the target (via SBSETTARGET) or putting
a varchar column, set the column length in the call to
SBPUTWHERECOLUMNOPEN to zero.

Must provide the length for all columns you put for a target override.

If overriding an SQL target table and you want to put a varchar
column value, the actual length of the value being put must be
included in the first two bytes (binary) of the column value passed
as the parameter for the data (passed in <colvalue> below). You
also must add 2 to the column length value parameter (<col-len>
below) to account for the varchar length in the data.
HPE Shadowbase Programming Manual—785431-007
173
User Exits
Step #2: Coding the Program


When you put SQL DATETIME and INTERVAL columns, the
values you pass to SBPUTWHERECOLUMN must be in internal
form (i.e., integer values of the correct TM/MP structure).
SBPUTWHERECOLUMNOPEN should be reserved for situations
where a dummy target schema is not used. This API causes
strings to be appended to statements resulting in the caching Other
Servers treating them as new statements. This causes an
excessive number of statement context switches. Instead,
SBPUTWHERECOLUMN should be used.
Related Manuals

For information on the DATETIME and INTERVAL column internal
forms, see the DATETIME and INTERVAL Fields discussion in
section 5 of the NonStop TM/MP Application Programmer's Guide
for D30.
SBRELATIVEOFFSET Function
As of Version 3.980B released in March, 2006 the
SBRELATIVEOFFSET user exit API function was added. The function
returns the byte offset between two addresses (i.e., the base address
and the element address for which the offset is to be returned) that are
passed as parameters. The offset is the difference between the
element address and the base address, in bytes. Note that the offset
is returned as a 0-based number, i.e., the first element in the
substructure is at offset 0.
This function is useful in certain programming environments (such as
COBOL) to determine the byte offset of a structure member from the
base of that structure.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
COBOL Usage Example:
WORKING-STORAGE.
01 WS-ITEMS.
05 ABC-INFO.
10 A
10 B
10 C
05 BYTE-OFFSET
PIC XX.
PIC S9(6) COMP.
PIC S9(18) COMP.
NATIVE-4 VALUE 0.
HPE Shadowbase Programming Manual—785431-007
174
User Exits
Step #2: Coding the Program
PROCEDURE DIVISION.
.
.
.
ENTER C "SBRELATIVEOFFSET" IN USRXLIB
USING ABC-INFO OF WS-ITEMS,
A OF ABC-INFO
GIVING BYTE-OFFSET.
* this will return a BYTE-OFFSET of 0
.
.
.
ENTER C "SBRELATIVEOFFSET" IN USRXLIB
USING ABC-INFO OF WS-ITEMS,
B OF ABC-INFO
GIVING BYTE-OFFSET.
* this will return a BYTE-OFFSET of 2
.
.
.
Syntax for C Programmers
C Usage Example:
.
.
.
#include "usrxlib.h"
struct {
char
a[2];
long
b;
long long c;
} abc_info;
long byte_offset;
.
.
.
byte_offset=SBRELATIVEOFFSET((Char*)&abc_info,
(Char*)&abc_info.a);
.
.
.
Parameters
BYTE-OFFSET
returned value

Indicates whether call completed successfully or encountered an
error. Possible values:
Offset between the element address and the base address, in bytes
-1 is returned if the base address is invalid.
-2 is returned if the element address is invalid.
-3 is returned if the element address is less than the base address
(i.e., not contained inside the structure).
HPE Shadowbase Programming Manual—785431-007
175
User Exits
Step #2: Coding the Program
Considerations

SBRELATIVEOFFSET is only available in the NonStop
environment.
SBREMOVECOLUMN Function
The SBREMOVECOLUMN function is used to tell HPE Shadowbase
not to move a particular common column value from the source to the
target. The SBREMOVECOLUMN function is detailed below.
This function is called from USRXPROCESS or USRXEXCEPTION to
tell HPE Shadowbase not to move a particular common column value
from the source to the target.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
Yes
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
USRXPROCESS
USRXEXCEPTION
Syntax for COBOL Programmers
ENTER C "SBREMOVECOLUMN" IN USRXLIB
USING FIELD-NAME
GIVING RETURN-CODE.
Syntax for C Programmers
short return_code;
return_code = SBREMOVECOLUMN(“COL_NAME”);
Parameters
RETURN-CODE
returned value

Indicates whether call completed successfully or encountered an
error. Possible values:
-2 = schema not available
-3 = bad column name format
-4 = column name not found in schema
1 = column move from source to target removed
FIELD-NAME
input

1 to 30 bytes in length

null terminated

name of field or column to be removed. For example:
HPE Shadowbase Programming Manual—785431-007
176
User Exits
Step #2: Coding the Program
01 COLUMN-NAME.
05 FULL-NAME PIC X(11) VALUE "RECORD_TYPE.”
05 FILLER
PIC X VALUE LOW-VALUES.
Considerations

For Enscribe target inserts, the value for a removed column will be
set to zeros for numeric fields and spaces for alphanumeric fields.

For SQL target inserts, the associated columns must be defined
with a default value when the table is created otherwise, an SQL
error will result.

When you put a column using an SBPUT... function, HPE
Shadowbase will use the put data rather than move data from the
source to the target for the related field/column. There is no need
to remove a column before putting it.

You do not need to call SBREMOVECOLUMN to remove fields and
columns that are in the source but not in the target. HPE
Shadowbase only moves data for names that are common between
the source and target (unless you have called SBSETTARGET).
SBREPORTCOLLISION Function
This function can be called to have a collision event reported in the
REJECTFILE. There are parameters to instruct SBREPORTCOLLISION
what should be reported.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C "SBREPORTCOLLISION" IN USRXLIB
USING BEFORE-FLAG,
AFTER-FLAG,
TARGET-FLAG,
APPLY-FLAG,
REJECT-TYPE,
LOADER-FLAG,
MESSAGE-LEN,
MISMATCH-MSG
GIVING RETURN-CODE.
Syntax for C Programmers
HPE Shadowbase Programming Manual—785431-007
177
User Exits
Step #2: Coding the Program
return_code = SBREPORTCOLLISION(before_flag,
after_flag,
target_flag,
apply_flag,
reject_type,
loader_flag,
message_len,
&not_found_msg);
Parameters
RETURN-CODE
returned value
The function will return a 16-bit return code. Possible values:
-1 = indicates that the related target record is locked if the user
exit instructed SBREPORTCOLLISION to log the target
record content and the Consumer could not read it
1 = indicates success
BEFORE-FLAG
input
When value is 1, SBREPORTCOLLISION will log the before image or SQL
statement if applicable to the event type.
AFTER-FLAG
input
When value is 1, SBREPORTCOLLISION will log the after image or SQL
statement if applicable to the event type.
TARGET-FLAG
input
When value is 1, SBREPORTCOLLISION will log the target record or a SQL
statement containing the target data if applicable to the event type.
APPLY-FLAG
future
Parameter may be used in a future release.
REJECT-TYPE
input
See REJECTH File for some settings you might use for REJECT-TYPE.
LOADER-FLAG
future
Parameter will be used in a future release.
MESSAGE-LEN
future
Parameter will be used in a future release.
MISMATCH-MSG
output
A null terminated text message is also passed to be logged into the reject file.
This is a sample of a NULL-TERMINATED Collision Message: “TARGET
MISMATCH".
The following are usage examples with comments to explain that parameters.
HPE Shadowbase Programming Manual—785431-007
178
User Exits
Step #2: Coding the Program
COBOL Usage Example:
.
.
WORKING-STORAGE.
01 WS-ITEMS.
05 RETURN-CODE
PIC S9(4) COMP.
* WHEN BEFORE-FLAG IS 1, SBREPORTCOLLISION WILL LOG THE
BEFORE.
* IMAGE OR SQL STATEMENT IF APPLICABLE TO THE EVENT TYPE..
05 BEFORE-FLAG
PIC S9(4) COMP VALUE 1..
* WHEN AFTER-FLAG IS 1, SBREPORTCOLLISION WILL LOG THE
AFTER
* IMAGE OR SQL STATEMENT IF APPLICABLE TO THE EVENT TYPE.
05 AFTER-FLAG
PIC S9(4) COMP VALUE 1.
* WHEN TARGET-FLAG IS 1, SBREPORTCOLLISION WILL LOG THE
TARGET
* RECORD OR A SQL STATEMENT CONTAINING THE TARGET DATA IF
* APPLICABLE TO THE EVENT TYPE.
05 TARGET-FLAG
PIC S9(4) COMP VALUE 1.
* APPLY-FLAG MAY BE USED IN A FUTURE RELEASE.
05 APPLY-FLAG
PIC S9(4) COMP VALUE 0.
* SEE REJECTH FOR SOME SETTINGS YOU MIGHT USE FOR REJECTTYPE.
05 REJECT-TYPE
PIC S9(4) COMP.
* LOADER-FLAG WILL BE USED IN A FUTURE RELEASE.
05 LOADER-FLAG
PIC S9(4) COMP VALUE 0.
* SAMPLE OF A NULL-TERMINATED COLLISION MESSAGE.
05 MISMATCH-MSG.
10 FILLER
PIC X(15) VALUE "TARGET MISMATCH".
10 M-MSG-TERM PIC S9(4) COMP VALUE 0.
.
.
.
PROCEDURE DIVISION.
.
.
* NOTE FOR SIMPLICITY IN THIS EXAMPLE THAT ALL FLAGS ARE SET
* ON. SBREPORTCOLLISION WILL DETERMINE WHAT IS AVAILABLE
* BASED UPON THE EVENT TYPE AND WILL LOG ACCORDINGLY.
MOVE 3 TO REJECT-TYPE.
ENTER C "SBREPORTCOLLISION" IN USRXLIB
USING BEFORE-FLAG,
AFTER-FLAG,
TARGET-FLAG,
APPLY-FLAG,
HPE Shadowbase Programming Manual—785431-007
179
User Exits
Step #2: Coding the Program
REJECT-TYPE,
LOADER-FLAG,
MESSAGE-LEN,
MISMATCH-MSG
GIVING RETURN-CODE.
.
.
C Usage Example:
.
..
#include "usrxlib.h"
short before_flag = 1;
short after_flag = 1;
short target_flag = 1;
short apply_flag = 0;
short reject_type;
short loader_flag = 0;
short message_len,
short return_code;
static char not_found_msg[] = {"TARGET REC NOT FOUND"};
.
.
reject_type = 2;
return_code = SBREPORTCOLLISION(before_flag,
after_flag,
target_flag,
apply_flag,
reject_type,
loader_flag,
message_len,
&not_found_msg);
.
.
Considerations

SBREPORTCOLLISION is only available in the NonStop
environment.
SBRESOLVELOCKS Function
The SBRESOLVELOCKS function is used by a user exit to have the Consumer
perform “resolvelocks” processing to resolve inter-transaction locking issues. This
might be used by a user exit that does its own target I/O and detects lock errors.
The SBRESOLVELOCKS function is detailed below.
HPE Shadowbase Programming Manual—785431-007
180
User Exits
Step #2: Coding the Program
This function can be called from USRXPROCESS or USRXEXCEPTION to perform
“resolvelocks” processing.
Product
HPE NonStop Server
Availability
Yes
Other Servers
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
ALLSyntax for COBOL Programmers
ENTER C "SBRESOLVELOCKS" IN USRXLIB.
Syntax for C Programmers
SBRESOLVELOCKS();
Parameters
None
Considerations


SBRESOLVELOCKS should only be called in the NonStop environment.
The related DBS object RESOLVELOCKS parameter must be set to ON.
SBSET Functions
The SBSET functions are used for giving the HPE Shadowbase object
(NonStop Consumer or Other Servers) special execution instructions.
The SBSET functions are detailed below.
SBSETABEND
This function is called from USRXINIT, USRXPROCESS,
USRXSTART, or USRXEXCEPTION to inform HPE Shadowbase to
abend on return from the user exit program. There are no parameters
or arguments associated with this call.
Product
HPE NonStop
Server
Availability
Yes
Other Servers
Yes
Calling Module Usage
USRXINIT
USRXSTART
USRXPROCESS
USRXEXCEPTION
USRXINIT
HPE Shadowbase Programming Manual—785431-007
181
User Exits
Step #2: Coding the Program
Product
Availability
Calling Module Usage
USRXSTART
USRXPROCESS
USRXEXCEPTION
Syntax for COBOL Programmers
ENTER C "SBSETABEND" IN USRXLIB.
Syntax for C Programmers
void SBSETABEND(void)
Parameters
None.
Considerations

On NonStop before abending, the Consumer will log an EMS
message 2017 “Consumer abending due to user exit request.”
SBSETABENDONERROR
This function can be called from USRXPROCESS or
USRXEXCEPTION to indicate that the Consumer should abend if any
TARGETFILE error occurs on the next I/O operation.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
ENTER C "SBSETABENDONERROR" IN USRXLIB
Syntax for C Programmers
void SBSETABENDONERROR(void)
HPE Shadowbase Programming Manual—785431-007
182
User Exits
Step #2: Coding the Program
Parameters
None.
Examples
COBOL Example
PROCEDURE DIVSION.
ENTER C "SBSETABENDONERROR".
C Example
SBSETABENDONERROR();
Considerations

SBABENDONERROR is only available in the NonStop
environment.
SBSETCHECKON
The Consumer process requires column names for “get’s” and “put’s”
to be in upper case with “_” (underscore) characters instead of “-”
(hyphen) characters.
In Version 3.980C released in April, 2006 this function was added to
enable the “scan and fix-up” logic. This API call will override the
USEREXITCOLCHECK parameter setting.
Note that the last API call remains in effect until the other API function
is called.
The following are programming usage examples.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
COBOL Usage Example:
PROCEDURE DIVISION.
.
.
.
HPE Shadowbase Programming Manual—785431-007
183
User Exits
Step #2: Coding the Program
ENTER C "SBSETCHECKON” IN USRXLIB.
.
.
.
Syntax for C Programmers
C Usage Example:
.
.
.
#include "usrxlib.h"
.
.
.
SBSETCHECKON();
.
.
.
Parameters
None.
Considerations

SBSETCHECKON is only available in the NonStop environment.
SBSETCHECKOFF
The Consumer process requires column names for “get’s” and “put’s”
to be in upper case with “_” (underscore) characters instead of “-”
(hyphen) characters.
In Version 3.980C released in April, 2006 this function was added to
disable the “scan and fix-up” logic. This API call will override the
USEREXITCOLCHECK parameter setting.
Note that the last API call remains in effect until the other API function
is called.
The following are programming usage examples.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
N/A
Syntax for COBOL Programmers
HPE Shadowbase Programming Manual—785431-007
184
User Exits
Step #2: Coding the Program
COBOL Usage Example:
PROCEDURE DIVISION.
.
.
.
ENTER C "SBSETCHECKOFF” IN USRXLIB.
.
.
.
Syntax for C Programmers
C Usage Example:
.
.
.
#include "usrxlib.h"
.
.
.
SBSETCHECKOFF();
.
.
Parameters
None.
Considerations

SBSETCHECKOFF is only available in the NonStop environment.
SBSETDDLALLPTNS
The SBSETDDLALLPTNS should be called if a user exit is directly applying
DDL events to a target. It is needed for bi-directional replication environments to
prevent a reversing Collector (COLL) from ping-ponging events. It should be
called before calling the SBBEGINDDL user exit API function. This function
informs the Consumer that subsequent DDL processing is pertinent to all
partitions for the related target.
This function can be called from USRXPROCESS.
Product
HPE NonStop Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
N/A
HPE Shadowbase Programming Manual—785431-007
185
User Exits
Step #2: Coding the Program
Syntax for COBOL Programmers
ENTER C "SBSETDDLALLPTNS" IN USRXLIB.
Syntax for C Programmers
SBSETDDLALLPTNS();
Parameters
None
Considerations


SBSETDDLALLPTNS should only be called in the NonStop environment.
SBSETDDLALLPTNS is applicable to alter, create, purge, and purgedata
operations.
SBSETDDLNOALTERS
Certain DDL operations result in alter audit events being generated. The
SBSETDDLNOALTERS should be called if a user exit is directly applying
DDL events to a target. It is needed for bi-directional replication environments to
prevent a reversing Collector (COLL) from ping-ponging events. To prevent pingpong, it should be called before calling the SBBEGINDDL user exit API function.
This function informs the Consumer that all alter events should be ignored by the
reversing Collector, that are generated between the SBBEGINDDL and
SBENDDDL records.
This function can be called from USRXPROCESS.
Product
HPE NonStop Server
Other Servers
Availability
Yes
No
Calling Module Usage
USRXPROCESS
N/A
Syntax for COBOL Programmers
ENTER C "SBSETDDLNOALTERS" IN USRXLIB.
Syntax for C Programmers
SBSETDDLNOALTERS();
Parameters
None
HPE Shadowbase Programming Manual—785431-007
186
User Exits
Step #2: Coding the Program
Considerations


SBSETDDLNOALTERS should only be called in the NonStop environment.
SBSETDDLNOALTERS is applicable to alter, create, purge, and purgedata
operations.
SBSETEXCEPTIONCODES
This function is called from USRXEXCEPTIONINIT to set the number of
tries per event and the range of SQL error codes to be detected as
exceptions. If one of these errors is detected when the Consumer applies
the event to an SQL target table, it will call USRXEXCEPTION for
"exception processing." HPE Shadowbase will abend if it reaches the
"number of tries per event" if the try count is greater than zero. See
USRXEXCEPTION in the provided source shells for an example of this
call.
Product
HPE NonStop
Server
Other Servers
Availability
Calling Module Usage
Yes
USRXEXCEPTIONINIT
Yes
USRXEXCEPTIONINIT
Syntax for COBOL Programmers
ENTER C "SBSETEXCEPTIONCODES" IN USRXLIB
USING MAX-TRIES, NUM-RANGES, ERROR-RANGE
GIVING RETURN-CODE.
Syntax for C Programmers
short SBSETEXCEPTIONCODES(short max_tries,
short num_ranges,
short *error_range)
Parameters
RETURN-CODE
returned value

indicates whether call completed successfully or encountered an error.
Possible values:
-1 = SQLCODE range values are invalid
0 = invalid number of SQL error ranges
1 = settings executed
-100 = Functionality ‘Not Implemented’.
HPE Shadowbase Programming Manual—785431-007
187
User Exits
Step #2: Coding the Program
MAX-TRIES
input

Defaults to 10

specifies number of times an event that results in an identified error
code is tried.
NUM-RANGES
input

number of error code ranges included in <error-range>
ERROR-RANGE
input

two integers: lower and upper end of range

Occurs depending on <num-ranges> value. For example,
01 NUM-RANGES
NATIVE-2 VALUE 2.
01 ERROR-RANGES.
05 FIRST-RANGE.
10 LOW-ERROR
NATIVE-2 VALUE 8405.
10 HIGH-ERROR
NATIVE-2 VALUE 8406.
05 SECOND-RANGE.
10 LOW-ERROR
NATIVE-2 VALUE 8409.
10 HIGH-ERROR
NATIVE-2 VALUE 8415.
Considerations

SQL error code values must be sent as positive numbers.

The following are the default code ranges supplied in HPE
Shadowbase. When these errors are encountered, HPE Shadowbase
will call USRXEXCEPTION for special processing.
8401 - 8401
8405 - 8406
8410 - 8412
8417 - 8418
8423 - 8428
You can specify other ranges if you wish.

For Other Servers, this API has no implementation. It always returns
with SB_RC_NOT_IMPLEMENTED (-100).
SBSETEXECUTE
This function is called from USRXPROCESS or USRXEXCEPTION to tell
HPE Shadowbase to execute the current event on return from the user
exit program. This is the default mode of operation. Therefore, in most
cases you will not need to use this function. In a NonStop implementation,
this serves to retry the event after USRXEXCEPTION has corrected the
data. In an Other Servers implementation there is no retry capability,
therefore, use of this function within USRXEXCEPTION will have no
effect. There are no parameters or arguments associated with this call.
HPE Shadowbase Programming Manual—785431-007
188
User Exits
Step #2: Coding the Program
Product
HPE NonStop
Server
Other Servers
Availability
Calling Module Usage
Yes
USRXPROCESS
USRXEXCEPTION
Yes
USRXPROCESS
USRXEXCEPTION
Syntax for COBOL Programmers
ENTER C "SBSETEXECUTE" IN USRXLIB
Syntax for C Programmers
void SBSETEXECUTE(void)
Parameters
None.
Considerations

HPE Shadowbase is set "to execute" before calling USRXPROCESS.
SBSETIGNORE
This function is called from USRXPROCESS or USRXEXCEPTION to tell
HPE Shadowbase to skip the current event and not do the I/O on the
target. You should use this if USRXPROCESS is performing target I/O.
In an Other Servers implementation there is no retry capability, therefore,
use of this function within USRXEXCEPTION will have no effect. There
are no parameters or arguments associated with this call.
Product
HPE NonStop
Server
Other Servers
Availability
Calling Module Usage
Yes
USRXPROCESS
USRXEXCEPTION
Yes
USRXPROCESS
Syntax for COBOL Programmers
ENTER C "SBSETIGNORE" IN USRXLIB
Syntax for C Programmers
HPE Shadowbase Programming Manual—785431-007
189
User Exits
Step #2: Coding the Program
void SBSETIGNORE(void)
Parameters
None.
Considerations

This is the default mode for “data exception” handling.
SBSETLOGOFF
This function is called from USRXEXCEPTION to tell HPE Shadowbase to
not log the error condition and key associated with a "data exception" that
has occurred and has been processed by USRXEXCEPTION. There are
no parameters or arguments associated with this call. In an Other Servers
implementation, this function may be called at any time to disable log file
output.
Product
HPE NonStop
Server
Other Servers
Availability
Calling Module Usage
Yes
USRXEXCEPTION
Yes
All
Syntax for COBOL Programmers
ENTER C "SBSETLOGOFF" IN USRXLIB
Syntax for C Programmers
void SBSETLOGOFF(void)
Parameters
None.
SBSETLOGON
This function is called from USRXEXCEPTION to tell HPE Shadowbase to
log the error condition and key associated with a "data exception" that has
occurred and has been processed by USRXEXCEPTION. There are no
parameters or arguments associated with this call. In an Other Servers
implementation, this function may be called at any time to enable log file
output.
HPE Shadowbase Programming Manual—785431-007
190
User Exits
Step #2: Coding the Program
Product
HPE NonStop
Server
Other Servers
Availability
Calling Module Usage
Yes
USRXEXCEPTION
Yes
All
Syntax for COBOL Programmers
ENTER C "SBSETLOGON" IN USRXLIB
Syntax for C Programmers
void SBSETLOGON(void)
Parameters
None.
Considerations

This is the default mode for “data exception” handling.
SBSETPATHNAME
SBSETPATHNAME is called to set a PATHNAME value to be used in the SQL
statement sent to the Other Servers. The PATHNAME value must be null
terminated and can be a maximum of 80 characters. The value 1 is returned if
the request is valid. -1 is returned if a PATHNAME value is not supplied (length
is 0). -2 is returned if the PATHNAME is more than 80 characters. Version
5.000 has been enhanced to permit larger ANSI names to be specified for
SQL/MX target tables, and now allows up to 386 characters; 2 is returned if the
PATHNAME is more than 386 characters. -3 is returned if the environment is not
associated with an Other Servers.
Product
HPE NonStop
Server
Other Servers
Availability
Calling Module Usage
Yes
USRXPROCESS
USRXEXCEPTION
No
N/A
COBOL Usage Example:
HPE Shadowbase Programming Manual—785431-007
191
User Exits
Step #2: Coding the Program
WORKING-STORAGE.
01 WS-ITEMS.
05 WS-PATHNAME
10 FILLER
10 NULL-TERM
05 WS-RTRN-CD
PIC X(8) VALUE “MYTAB001”.
PIC X
VALUE LOW-VALUES.
PIC S9(4) COMP.
PROCEDURE DIVISION.
ENTER C "SBSETPATHNAME" IN USRXLIB
USING WS-PATHNAME
GIVING WS-RTRN-CD.
C Usage Example:
#include "usrxlib.h"
static char pathname[] = {“MYTAB001”};
short
rtrn_cd;
rtrn_cd = SBSETPATHNAME(&pathname);
SBSETRESTARTPOINT
The SBSETRESTARTPOINT API is being provided to support
programmatic control over the restart point from within the UE
environment.
This function is used to control the restart point used by HPE Shadowbase
in the event of a restart of processing. The function may be used from
within any USRX API. This function will only have an effect if the HPE
Shadowbase Option USER_RESTART_CTRL has been set to
USER_RESTART_CTRL_L1 or USER_RESTART_CTRL_L3 in a call to
SBSETUSRXOPTION(). If USER_RESTART_CTRL has not been
enabled, the function returns with error code -1 indicating support for the
SBSETRESTARTPOINT() feature has not be enabled. The HPE
Shadowbase restart point and the granularity of the restart point are based
on Transaction boundaries.
Product
HPE NonStop
Server
Other Servers
Availability
No
N/A
Yes
Calling Module Usage
USRXPROCESS
USRXEXCEPTION
Syntax for C Programmers
short SBSETRESTARTPOINT (void)
HPE Shadowbase Programming Manual—785431-007
192
User Exits
Step #2: Coding the Program
Parameters
return_code
returned value

indicates whether call completed successfully or encountered an error:
-1 = feature not enabled.
0 = call completed successfully.
1 = Physical fault; Failed to safe-store restart point.
C Example
return_code = SBSETRESTARTPOINT ();
Considerations

Only available in the Other Servers environment.

Must perform
SBSETUSRXOPTION(USER_RESTART_CTRL_L1 or
USER_RESTART_CTRL_L3., USER_RESTART_ON) to
enable SBSETRESTARTPOINT() use.

May be executed within any OTHER SERVERS USRX API.

Granularity of Restart Point safe-stored is controlled by the
Shadparm.ini parameter SHAD_CHECKPOINT_EVENTS.

Calling this function after every event successfully processed versus
calling this function only after processing Commit events successfully
will produce no net difference in the restart point set. Restart points
are always committed transaction boundaries.

For writing the restart point on an event other than insert, update or
delete you need to expressly identify the event through utilization of the
SBSETUSRXOPTION API. The PROC_EVENT_TYPE option can be
set to return user exit control on begin, abort and commit events for
this purpose.
SBSETSTATEMENTTYPE
This function is called from USRXPROCESS or USRXEXCEPTION to
override the target operation to be applied for the current event. For
example, you might want to change an insert to an update or an update to
an insert or a delete to an update. On return from the user exit, this
operation will be applied to the target file, instead of the original operation
as it occurred on the source database.
Product
HPE NonStop
Server
Other Servers
Availability
Calling Module Usage
Yes
USRXPROCESS
USRXEXCEPTION
Yes
USRXPROCESS
USRXEXCEPTION
HPE Shadowbase Programming Manual—785431-007
193
User Exits
Step #2: Coding the Program
Syntax for COBOL Programmers
ENTER C "SBSETSTATEMENTTYPE" IN USRXLIB
USING STMNT-TYPE
GIVING RETURN-CODE.
Syntax for C Programmers
short SBSETSTATEMENTTYPE(short stmnt_type)
Parameters
RETURN-CODE
returned value

indicates whether call completed successfully or encountered an error.
Possible values:
-1 = update event is auditcompressed
0 = bad override operation type
1 = override operation has been set
STMNT-TYPE
input

value to change the original operation to. Valid values:
0 = insert for SQL or write for Enscribe
1 = update for SQL or read/rewrite for Enscribe
2 = delete for SQL or read/rewrite (0 length) for Enscribe
Considerations

You cannot change an auditcompressed update to an insert.

If you change a statement type in USRXEXCEPTION, you must follow
it with a call to SBSETEXECUTE in order to override the default
processing of “do no I/O, log the error, and continue processing.”
SBSETTARGET
This function is called from USRXPROCESS or USRXEXCEPTION to
override or set the name of the target table/file that the HPE Shadowbase
process is configured to update. The new target you set must exist.
In the HPE NonStop Shadowbase environment, the Consumer process
dynamically prepares and executes SQL statements or writes to Enscribe
targets (for Enscribe sources) for target overrides.
Product
HPE NonStop
Server
Availability
Calling Module Usage
Yes
USRXPROCESS
USRXEXCEPTION
HPE Shadowbase Programming Manual—785431-007
194
User Exits
Step #2: Coding the Program
Product
Other Servers
Availability
Calling Module Usage
Yes
USRXPROCESS
USRXEXCEPTION
Syntax for COBOL Programmers
ENTER C "SBSETTARGET" IN USRXLIB
USING TARGET-NAME
GIVING RETURN-CODE.
Syntax for C Programmers
short SBSETTARGET(char *target_name)
Parameters
RETURN-CODE
returned value

indicates whether call completed successfully or encountered an error.
Possible values:
-1 = invalid selection of SQL/MX table
0 = invalid file name format
1 = target override has been set
TARGET-NAME
input

Must be null terminated.

NonStop external file name for target override or SQL define for SQL
targets or table name for Other Servers environment. For example,
01 TARGET-NAME.
05 FULL-NAME
PIC X(16) VALUE "$D2.TARGDB.FILE1”.
05 FILLER PIC X VALUE LOW-VALUES.
Considerations

Both SQL and Enscribe targets are supported.

DDL definition (schema) is not used to insure that any columns or
records put by the user exit are valid.

All columns for a target override must be put.

The format of the put data and column names for SQL must be valid.

It is best to have the user exit make decisions and have HPE
Shadowbase perform the I/O. It is not recommended that the user exit
write to targets directly and inform HPE Shadowbase to ignore the
event, but it is possible to do this.

Use SBSETTARGET to declare a TARGETFILE when one is not
specified in the HPE Shadowbase configuration.

If you set to an Enscribe target and tell HPE Shadowbase to execute
an event, you must call SBPUTRECORD with the record data to be
written (if not a delete).
HPE Shadowbase Programming Manual—785431-007
195
User Exits
Step #2: Coding the Program




HPE Shadowbase assumes an Enscribe-to-Enscribe environment if
you do not specify a TARGETFILE in a DBS.
In Enscribe to SQL replication, HPE Shadowbase will only permit you
to override the TARGETFILE if you specified an SQL TARGETFILE in
the DBS.
If your SOURCEFILE in a DBS is an SQL table, you cannot override
the TARGETFILE with an Enscribe filename. If you need to do this,
code USRXPROCESS to do the I/O on the Enscribe file and have HPE
Shadowbase ignore the event.
For replication to an Other Servers system, SBSETTARGET sets the
table name that is used within the related SQL statement text HPE
Shadowbase generates. It overrides the TARGETFILE and
PATHNAME parameter settings.
SBSETUSERTRACEOFF
This function can be called from any user exit function to allow user exit
code to disable user exit tracing programmatically.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
All
No
Calling Module Usage
N/A
Syntax for COBOL Programmers
ENTER C "SBSETUSERTRACEOFF" IN USRXLIB
GIVING <return code>
Syntax for C Programmers
short SBSETUSERTRACEOFF(void)
Parameters
RETURN-CODE
returned value

The following are the meanings for the return code values for the API
functions: 0 = an error occurred, 1 = no error
Examples
COBOL Example
HPE Shadowbase Programming Manual—785431-007
196
User Exits
Step #2: Coding the Program
WORKING-STORAGE SECTION.
01
RETURN-CODE
PIC 9(4) COMP.
PROCEDURE DIVSION.
ENTER C "SBSETUSERTRACEOFF" IN USRXLIB GIVING RETURN-CODE.
C Example
short return_code;
return_code = SBSETUSERTRACEOFF();
Considerations

SBSETUSERTRACEOFF is only available in the NonStop
environment.
SBSETUSERTRACEON
This function can be called from any user exit function to allow user exit
code to enable user exit tracing programmatically. Note that the
IOTRACEFILE (USERTRACEFILE prior to 4.040C) must have a disk file
name setting to enable tracing programmatically.
Product
HPE NonStop
Server
Other Servers
Availability
Yes
All
No
Calling Module Usage
N/A
Syntax for COBOL Programmers
ENTER C "SBSETUSERTRACEON" IN USRXLIB
USING CLEAR-FILE
GIVING RETURN-CODE
Syntax for C Programmers
short SBSETUSERTRACEON(short clear_file)
Parameters
RETURN-CODE
returned value

The following are the meanings for the return code values for the API
functions:
-1 = IOTRACEFILE (or USERTRACEFILE prior to 4.040C) is not set
0 = an error occurred
1 = no error
HPE Shadowbase Programming Manual—785431-007
197
User Exits
Step #2: Coding the Program
CLEAR-FILE
input

Setting the parameter to 1 causes the user trace file to be cleared.
Examples
C Example
short return_code;
short clear_file;
return_code = SBSETUSERTRACEON(clear_file);
Considerations

SBSETUSERTRACEOFF is only available in the NonStop
environment.
SBSETUSRXOPTION
The SBSETUSRXOPTION API is being provided to support programmatic
configuration of HPE Shadowbase replication features from within the UE
environment. HPE Shadowbase Other Servers version 4.040E introduces
this API and supports a limited set of options at the outset.
This function is used to specify HPE Shadowbase feature options. The
function may only be used within the USRXINIT API. After USRXINIT
returns control back to the caller, the SBSETUSRXOPTION() API will
have no effect on any feature option for the duration of program execution.
Product
HPE NonStop
Server
Other Servers
Availability
No
N/A
Yes
Calling Module Usage
USRXINIT
Syntax for C Programmers
short SBSETUSRXOPTION (int option, char *value)
Parameters
return_code
returned value

indicates whether call completed successfully or encountered an error:
-1 = Invalid option supplied.
0 = call completed successfully.
1 = Invalid value supplied for option.
2 = Function not authorized outside of USRXINIT
HPE Shadowbase Programming Manual—785431-007
198
User Exits
Step #2: Coding the Program
option
input

Must be one from the set of supported HPE Shadowbase USRX
options.
value
input

Must be in data range corresponding to USRX option specified
The following are the available HPE Shadowbase USRXOPTIONs and
their associated range of values.
USER_RESTART_CTRL
The USER_RESTART_CTRL option enables and disables user control
over the HPE Shadowbase restart point. This option must be enabled in
order for the SBSETRESTARTPOINT() API to be available for successful
use. This option is implemented as a double byte numeric.
The following table describes the values supported.
Options
USER_RESTART_
CTRL
Values
Hexadecimal
Named Constant
Data
Type
USER_RESTART_CTRL_L0
Unsigned
Short
Unsigned
Short
Unsigned
Short
Unsigned
Short
USER_RESTART_CTRL_L1
USER_RESTART_CTRL_L2
USER_RESTART_CTRL_L3
Decimal
0x0000
0
0x0001
1
0x0002
2
0x0003
3
Default
Yes
The USER_RESTART_CTRL option constants have the following description
and effect.
Constant
Description/Effect
USER_RESTART_CTRL_L0


USER_RESTART_CTRL_L1


USER_RESTART_CTRL_L2


USER_RESTART_CTRL_L3


Internal HPE Shadowbase controlled
restart point safe-store.
No restart point safe-store on
Shutdown
User requested restart point safe-store
control
No restart point safe-store on
Shutdown
Internal HPE Shadowbase controlled
restart point safe-store.
Restart point safe-store performed on
Shutdown
User requested restart point safe-store
control
Restart point safe-store performed on
HPE Shadowbase Programming Manual—785431-007
199
User Exits
Step #2: Coding the Program
Shutdown
The following is a truth table expressing the subservient relationship
USER_RESTART_CTRL option has with the SHAD_RESTART_CTRL_LEVEL
shadparm.ini parameter.
SHAD_RESTART_CTRL_LEVEL
Setting
0
0
0
0
1
1
1
1
USER_RESTART_CTRL
Constant
USER_RESTART_CTRL_L
0
USER_RESTART_CTRL_L
1
USER_RESTART_CTRL_L
2
USER_RESTART_CTRL_L
3
USER_RESTART_CTRL_L
0
USER_RESTART_CTRL_L
1
USER_RESTART_CTRL_L
2
USER_RESTART_CTRL_L
3
Effect




















Internal Restart Point generation enabled
Save Restart Point on Shutdown disabled
User Restart Point control enabled
Save Restart Point on Shutdown disabled
Disallowed;USER_RESTART_CTRL_L0
set in response
Internal Restart Point generation enabled
Save Restart Point on Shutdown disabled
Disallowed;USER_RESTART_CTRL_L1
set in response
User Restart Point control enabled
Save Restart Point on Shutdown disabled
Disallowed;USER_RESTART_CTRL_L2
set in response
Internal Restart Point generation enabled
Save Restart Point on Shutdown enabled
Disallowed;USER_RESTART_CTRL_L3
set in response
User Restart Point control enabled
Save Restart Point on Shutdown enabled
Internal Restart Point generation enabled
Save Restart Point on Shutdown enabled
User Restart Point control enabled
Save Restart Point on Shutdown enabled
PROC_EVENT_TYPE
The PROC_EVENT_TYPE option enables and disables submission of
HPE Shadowbase replication events to the UE environment. By default,
only Insert, Update, and Delete events are submitted to the UE
environment. Users can now enable or disable selectively the HPE
Shadowbase events they desire to process within the UE environment.
This option is implemented as an unsigned double byte numeric
representing a bit field. Because this option is processed as a bit field,
there are certain criteria that must be met when setting (enabling) and
clearing (disabling) event options.


Considerations:
Setting or clearing event(s) effects only the select event(s).
Do not combine ‘ON’ named constants with ‘OFF’ named constants using
the logical OR.
Setting Event Options ON
Setting an event option ON, means “setting” the corresponding option bit
(set to 1).
You may use the logical OR to combine ‘ON’ named constants and set
multiple events in a single call to SBSETUSRXOPTION().
HPE Shadowbase Programming Manual—785431-007
200
User Exits
Step #2: Coding the Program
Example:
In this example, Abort, Begin, and Commit events are enabled.
unsigned short value;
value = (ABORT_TX_ON | BEGIN_TX_ON | COMMIT_TX_ON);
rc = SBSETUSRXOPTION(PROC_EVENT_TYPE, &value);
Setting Event Options OFF
Setting an event option OFF, means “clearing” the corresponding option
bit (set to 0).
You may NOT use the logical OR to combine ‘OFF’ named constants in
order to clear multiple events in a single call to SBSETUSRXOPTION().
To disable events, one of the following techniques must be used.
1.
Clear each event one at a time using the corresponding ‘OFF’
named constant in a call to SBSETUSRXOPTION().
Example:
unsigned short value;
value = DELETE_OFF;
rc = SBSETUSRXOPTION(PROC_EVENT_TYPE, &value);
2.
Clear multiple events using the logical OR technique against the
‘ON’ named constants and then taking the “NOT” of the resultant.
Example:
unsigned short value;
value = ~(INSERT_ON | UPDATE_ON | DELETE_ON);
rc = SBSETUSRXOPTION(PROC_EVENT_TYPE, &value);
The following table describes the values supported.
Options
Named Constant
PROC_EVENT_TYPE
ABORT_TX_ON
ABORT_TX_OFF
BEGIN_TX_ON
BEGIN_TX_OFF
COMMIT_TX_ON
COMMIT_TX_OFF
DELETE_ON
DELETE_OFF
INSERT_ON
INSERT_OFF
UPDATE_ON
UPDATE_OFF
NEXTDOC_ON
NEXTDOC_OFF
NOMOREDATA_ON
NOMOREDATA_OFF
ALL_EVENTS_ON
ALL_EVENTS_OFF
Values
Hexadecimal
0x0001
0xFFFE
0x0002
0xFFFD
0x0004
0xFFFB
0x0008
0xFFF7
0x0010
0xFFEF
0x0020
0xFFDF
0x0040
0xFFBF
0x0080
0xFF7F
0xFFFF
0x0000
Decimal
1
65534(~1)
2
65533(~2)
4
65531(~4)
8
65527(~8)
16
65519(~16)
32
65503(~32)
64
65471(~64)
128
65407(~128)
65535
0
HPE Shadowbase Programming Manual—785431-007
201
Default
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
User Exits
Step #2: Coding the Program
C Example
int option;
unsigned short
value;
/* assign option */
option = PROC_EVENT_TYPE;
/* assign value */
value = ALL_EVENTS_ON;
return_code = SBSETUSRXOPTION (option, &value);
Considerations

Only available in the Other Servers environment

Must be executed within USRXINIT to be effective.

Must specify option from the set of HPE Shadowbase USRX options .

value must be in specified range corresponding to option
SBWARNINGSON Function
The SBWARNINGSON user exit API was added in HPE Shadowbase
release 3.964 in February, 2005 to determine if the CONS WARNINGS
parameters is set to ON.
It returns TRUE (1) if ON. Otherwise, it returns FALSE (0).
Product
HPE NonStop
Server
Other Servers
Availability
Yes
All
No
Calling Module Usage
N/A
Syntax for COBOL Programmers
ENTER C " SBWARNINGSON " IN USRXLIB
GIVING WARNINGS-FLAG
Syntax for C Programmers
short SBWARNINGSON (void)
COBOL Usage Example:
HPE Shadowbase Programming Manual—785431-007
202
User Exits
Step #2: Coding the Program
.
WORKING-STORAGE SECTION
01 WS-ITEMS.
05 WARNINGS-FLAG
PIC S9(4) COMP.
05 WARNINGS-FLAG
PIC S9(4) COMP.
88 WARNINGS-OFF
VALUE 0.
88 WARNINGS-ON
VALUE 1.
.
.
.
PROCEDURE DIVSION.
.
.
ENTER C "SBWARNINGSON" IN USRXLIB
GIVING WARNINGS-FLAG.
..
IF ( WARNINGS-ON )
…
END-IF.
..
C Usage Example:
.
.
#include "usrxlib.h"
..
If (SBWARNINGSON()) {
..
}
.
Considerations

SBWARNINGSON is only available in the NonStop environment.
SBTRANSACTION Functions
The SBTRANSACTION functions allow a Consumer user exit to start and
end an autonomous TMF transaction. Any I/O performed from that user
exit will be performed under this autonomous transaction once it is started;
otherwise, any I/O performed within that user exit is performed under the
default replay transaction that the Consumer starts for each transaction it
replays.
Note that the user exit must end the transaction before returning from the
user exit. Otherwise, the Consumer will abend. The SB TRANSACTION
functions are detailed below.
Note: Special care must be taken when a user wants to perform its
own transaction work and I/O inside a user exit. The reason is that
the user exit may not know if the source transaction ultimately
commits or aborts when it has to terminate the autonomous
transaction. So, a user exit that performs its own autonomous
transactions needs to have its own internal logic to deal with the
cases where it calls SBCOMMITTRANSACTION (and the source
HPE Shadowbase Programming Manual—785431-007
203
User Exits
Step #2: Coding the Program
transaction actually aborted), or SBABORTTRANSACTION (and the
source transaction actually committed).
Note: By default, HPE Shadowbase will not return UNDO (backout)
events for an aborted source transaction. In other words, HPE
Shadowbase will read and return the DO events for the transaction
(DO events are those that precede the abort point), and then call
ABORT when the “Network Abort” event is encountered in audit.
HPE Shadowbase will then, by default, ignore/discard all of the
UNDO (backout) events for the transaction, and also ignore/discard
the Forgotten Abort event. If you are performing your own
autonomous transaction in a HPE Shadowbase user exit, and
COMMIT these DO events as you process them, you will
subsequently (probably) need to receive and process the UNDO
events in your user exit. To enable the receipt of these UNDO
events (in all cases), you should thus enable the AUDMON
SBCOLLNONETENDS parameter. Contact HPE Shadowbase
Support for more information about this parameter if you are
performing your own autonomous transactions in a HPE
Shadowbase user exit and will need to process UNDO events (note
that you use the SBISUNDO API call to determine if a received event
is a DO event or an UNDO event).
SBABORTTRANSACTION
SBABORTTRANSACTION is used to roll back the user exit’s TMF
transaction. 0 is returned if the transaction was aborted successfully. -1
is returned if a user exit transaction is not active. Otherwise, the return
value is a Guardian file error number as to why the transaction could not
be committed.
Product
HPE NonStop
Server
Other Servers
Availability
Calling Module Usage
Yes
USRXPROCESS
USRXEXCEPTION
No
N/A
Syntax for COBOL Programmers
ENTER C " SBABORTTRANSACTION " IN USRXLIB
GIVING WS-RETURN-CODE
Syntax for C Programmers
HPE Shadowbase Programming Manual—785431-007
204
User Exits
Step #2: Coding the Program
short
SBABORTTRANSACTION (void)
COBOL Usage Example:
.
WORKING-STORAGE.
01 WS-ITEMS.
05 WS-RETURN-CODE
PIC S9(4) COMP.
PROCEDURE DIVISION.
.
.
.
ENTER C "SBABORTTRANSACTION" IN USRXLIB
GIVING WS-RETURN-CODE.
C Usage Example:
.
.
#include "usrxlib.h"
short return_code;
.
.
.
return_code=SBABORTTRANSACTION();
Considerations

SBABORTTRANSACTION is only available in the NonStop
environment.

When committing or aborting a transaction in a user exit, care should
be taken to understand if the original source transaction committed or
aborted, and to properly process all of the DO and UNDO events for
that transaction. Refer to HPE Shadowbase Support for more
information and additional documentation on the
SBCOLLNONETENDS parameter.
SBBEGINTRANSACTION
SBBEGINTRANSACTION is used to start the user exit’s TMF transaction.
0 is returned if a transaction is started successfully. -1 is returned if a user
exit transaction is already active. Otherwise, the return value is a
Guardian file error number as to why the transaction could not be started.
Product
HPE NonStop
Server
Other Servers
Availability
Calling Module Usage
Yes
USRXPROCESS
USRXEXCEPTION
No
N/A
Syntax for COBOL Programmers
HPE Shadowbase Programming Manual—785431-007
205
User Exits
Step #2: Coding the Program
ENTER C " SBBEGINTRANSACTION " IN USRXLIB
GIVING WS-RETURN-CODE
Syntax for C Programmers
short
SBBEGINTRANSACTOIN (void)
COBOL Usage Example:
.
WORKING-STORAGE.
01 WS-ITEMS.
05 WS-RETURN-CODE
PIC S9(4) COMP.
PROCEDURE DIVISION.
.
.
.
ENTER C "SBBEGINTRANSACTION" IN USRXLIB
GIVING WS-RETURN-CODE.
C Usage Example:
.
#include "usrxlib.h"
short return_code;
.
.
.
return_code=SBBEGINTRANSACTOIN();
Considerations

SBBEGINTRANSACTION is only available in the NonStop
environment.

When starting, committing, or aborting a transaction in a user exit, care
should be taken to understand if the original source transaction
committed or aborted, and to properly process all of the DO and UNDO
events for that transaction. Refer to HPE Shadowbase Support for
more information and additional documentation on the
SBCOLLNONETENDS parameter.
SBCOMMITTRANSACTION
SBCOMMITTRANSACTION is used to commit the user exit’s TMF
transaction. 0 is returned if the transaction was committed successfully. 1 is returned if a user exit transaction is not active. Otherwise, the return
value is a Guardian file error number as to why the transaction could not
be committed.
HPE Shadowbase Programming Manual—785431-007
206
User Exits
Step #2: Coding the Program
Product
HPE NonStop
Server
Other Servers
Availability
Calling Module Usage
Yes
USRXPROCESS
USRXEXCEPTION
No
N/A
Syntax for COBOL Programmers
ENTER C "SBCOMMITTRANSACTION " IN USRXLIB
GIVING WS-RETURN-CODE
Syntax for C Programmers
short
SBCOMMITTRANSACTION (void)
COBOL Usage Example:
.
WORKING-STORAGE.
01 WS-ITEMS.
05 WS-RETURN-CODE
PIC S9(4) COMP.
PROCEDURE DIVISION.
.
.
.
ENTER C "SBCOMMITTRANSACTION" IN USRXLIB
GIVING WS-RETURN-CODE.
C Usage Example:
.
.
#include "usrxlib.h"
short return_code;
.
.
.
return_code=SBCOMMITTRANSACTION();
Considerations

SBCOMMITTRANSACTION is only available in the NonStop
environment.

When committing a transaction in a user exit, care should be taken to
understand if the original source transaction committed, and if not, to
process all of the back out (UNDO) events properly. Refer to HPE
Shadowbase Support for more information and additional
documentation on the SBCOLLNONETENDS parameter.
SBRESUMETRANSACTION
HPE Shadowbase Programming Manual—785431-007
207
User Exits
Step #2: Coding the Program
The SBRESUMETRANSACTION user exit API function allows a user exit
to resume any current transaction the CONS has suspended.
SBRESUMETRANSACTION is called at some point thereafter to return
the CONS TMF transaction state to the current transaction prior to the call
to SBSUSPENDTRANSACTION.
0 (zero) is returned for success. -1 is returned if there is no transaction tag saved
available when RESUMETRANSACTION is called. A Guardian file error number
is returned for any other result.
Product
HPE NonStop
Server
Other Servers
Availability
Calling Module Usage
Yes
USRXPROCESS
USRXEXCEPTION
No
N/A
Syntax for COBOL Programmers
ENTER C "SBRESUMETRANSACTION" IN USRXLIB
GIVING WS-RETURN-CODE
Syntax for C Programmers
short SBRESUMETRANSACTION (void)
COBOL Usage Example:
WORKING-STORAGE
01 WS-ITEMS.
05 WS-RTRN-CD
PIC S9(4) COMP.
PROCEDURE DIVISION.
.
ENTER C "SBRESUMETRANSACTION" IN USRXLIB
GIVING WS-RTRN-CODE.
C Usage Example:
#include "usrxlib.h"
short rtrn_cd;
.
rtrn_cd = SBRESUMETRANSACTION();
SBSUSPENDTRANSACTION
The SBSUSPENDTRANSACTION user exit API function allows a user
exit to suspend any current transaction the CONS has active.
SBSUSPENDTRANSACTION is called to cause the CONS to put its
current TMF transaction to the nil state. This might be used so that a TMF
HPE Shadowbase Programming Manual—785431-007
208
User Exits
Step #3: Compiling and Binding/Linking User Exits
transaction is not propagated to a server process that a user exit is
interacting with.
0 (zero) is returned for success. -1 is returned if no transaction is active when
SUSPENDTRANSACTION is called. A Guardian file error number is returned for
any other result.
Product
HPE NonStop
Server
Other Servers
Availability
Calling Module Usage
Yes
USRXPROCESS
USRXEXCEPTION
No
N/A
Syntax for COBOL Programmers
ENTER C "SBSUSPENDTRANSACTION" IN USRXLIB
GIVING WS-RETURN-CODE
Syntax for C Programmers
short SBSUSPENDTRANSACTION (void)
COBOL Usage Example:
WORKING-STORAGE
01 WS-ITEMS.
05 WS-RTRN-CD
PIC S9(4) COMP.
PROCEDURE DIVISION.
.
ENTER C "SBSUSPENDTRANSACTION" IN USRXLIB
GIVING WS-RTRN-CODE.
C Usage Example:
#include "usrxlib.h"
short rtrn_cd;
.
rtrn_cd = SBSUSPENDTRANSACTION();
Step #3: Compiling and Binding/Linking
User Exits
The sections below describe compiling and binding NonStop user exits to
the NonStop Consumer and compiling and linking Other Servers user
exits to the HPE Shadowbase Other Servers process.
HPE Shadowbase Programming Manual—785431-007
209
User Exits
Step #3: Compiling and Binding/Linking User Exits
Compiling and Binding User Exits in the NonStop
Environment
The methods you use to compile and bind your user exits into the
Consumer depend upon whether you are planning to run HPE
Shadowbase with the native mode Consumer or not. The procedures for
each mode are outlined below.
Non-native Mode
In order to prepare your user exit routine for use in non-native mode, first
you must compile the source code into an object file called USRXO. The
following example shows how to do this for a COBOL program called
USRXCOB.
RUN COBOL85/IN USRXCOB/USRXO
NOTE: You must use a version of the USRXLIBO HPE Shadowbase
library that is compatible with the version of the Consumer into
which you will be binding the user exits. For example, if you are
running v2.900 Consumer, you must use the USRXLIBO that
came with that release.
The following example shows how to do this for a C program called
USRXC,
c /in usrxc, out $s.#usr,cpu 0/ usrxo;suppress,fieldalign shared2,refaligned 2
After successfully compiling the user exit source code, you need to bind it
into the Consumer and then SQL compile the Consumer, if appropriate.
HPE Shadowbase comes with a TACL macro, BINDUSRX, that binds in
USRXO, accelerates and SQL compiles the Consumer, if appropriate. To
use this macro, enter:
BINDUSRX
[ CATALOG <catalog> ]
<catalog>
Is the $volume.subvolume location of the SQL catalog into which the
Consumer is to be SQL compiled. If you do not enter a catalog, the
catalog identified in the =_defaults define is used.
HPE Shadowbase Programming Manual—785431-007
210
User Exits
Step #3: Compiling and Binding/Linking User Exits
NOTE: You must be certain to use the OAUDCONS file as the base
Consumer when binding in your user exit code on a D42 or later
HPE NonStop system. BINDUSRX does this automatically.
Native Mode
NOTE: Native mode is only available for HPE NonStop Versions D45+.
To prepare your user exit for use in native mode, first compile the native
source code into an object file called USRXN. The example below shows
how to do this for a COBOL program called USRXCOB.
RUN NMCOBOL/IN USRXCOB/USRXN
The following example shows how to do this for a C program called
USRXC,
nmc /in usrxc,out $s.#usr,cpu 1/ usrxn;EXTENSIONS,ENV COMMON,suppress,highpin,heap
0 pages,saveabend,inspect,symbols, &
fieldalign shared2,optimize 0,REFALIGNED 2
NOTE: You must use a version of the USRXLIBN native mode HPE
Shadowbase library that is compatible with the version of the
Consumer into which you will be linking the user exits. For
example, if you are running a 3.980 version Consumer, you must
use the USRXLIBN that came with that release.
For user exit development on the Integrity, the RUNCCOMP file has been
included as an example of a C compilation for a native program.
RUNCCOMP contains the following CCOMP compile command. Note the
use of the TANDEM_FLOAT directive.
ccomp /in nusrx2c/ usrxn;suppress,symbols,inspect,TANDEM_FLOAT,
optimize 0,fieldalign shared2
RUNECOMP has also been included as a COBOL compilation example
for a native user exit program. RUNECOMP contains the following
ECOMP compile command.
ECOBOL /in nusrxcob/ usrxn;suppress;inspect;symbols;saveabend;optimize 0
HPE Shadowbase Programming Manual—785431-007
211
User Exits
Step #3: Compiling and Binding/Linking User Exits
For any user exit that has embedded SQL/MX in its code, it will need to be
MX precompiled first before being able to be C compiled. In order to do
this, rename your code file to USRXEC and put it into your HPE
Shadowbase subvolume. You now need to SQL/MX compile your
USRXEC file into a straight C USRXC file which can then be compiled
with CCOMP. Generally the SQL/MX compile command is done from
OSS, but the following set of commands can be run from a TACL prompt
in order to do this:
param home /G/<Shadowbase vol>/<Shadowbase subvol>
osh -c "/usr/tandem/sqlmx/bin/mxsqlc usrxec -c usrxc -m usrxm ~|tee
usrxlg"
<Shadowbase vol>
Is the volume on NonStop where HPE Shadowbase is installed (do not
include $ sign)
<Shadowbase subvol>
Is the subvolume on NonStop where HPE Shadowbase is installed.
This will compile your USRXEC file into a USRXC file which you can now
compile into a linkable object with CCOMP as explained above.
After successfully compiling, link the user exits into the Consumer and
then SQL compile, if appropriate. HPE Shadowbase comes with a TACL
macro, LINKUSRX, that links in USRXN and SQL compiles the Consumer,
if appropriate
NOTE: As of the release for Version 3.980B the LINKUSRX TACL macro
delivered for D46 and the G0x series has a line to include
$system.system.crtlmain. You will have to update any custom
user exit build scripts you have to include this line.
To use this macro, enter:
LINKUSRX
[ CATALOG <catalog> ]
<catalog>
Is the $volume.subvolume location of the SQL catalog into which the
Consumer is to be SQL compiled. If you do not enter a catalog, the
catalog identified in the =_defaults define is used.
HPE Shadowbase Programming Manual—785431-007
212
User Exits
Step #3: Compiling and Binding/Linking User Exits
LINKUSRX will then issue a series of prompts asking you for information
about your user exit. These are shown below. Enter the appropriate
value (y or n) for each prompt.
ROUTINE FOR LINKING NATIVE USEREXIT ROUTINES
Does your user exit object include USRXINIT (y/n)?:y
Does your user exit object include USRXSTART (y/n)?:y
Does your user exit object include USRXEXCEPTIONINIT (y/n)?:y
Does your user exit object include USRXEXCEPTION (y/n)?:y
Does your user exit object include USRXPROCESS (y/n)?:y
Does your user exit object include USRXROLL (y/n)?:y
Does your user exit object include USRXADDDBS (y/n)?:y
Is the user exit program COBOL (y/n)?:y
For user exits to be used with an environment sending SQL/MX events
through an AUDCONXN program, there is a LINXUSMX TACL macro to
link USRXN into the consumer program and perform the SQL compile. To
use this macro, enter:
LINKUSMX MXCOMP
LINKUSMX will issue the same series of prompts as LINKUSRX as
described above. There is more information about the LINKUSMX TACL
macro described in the HPE NonStop Shadowbase SQLMX Manual.
The HPE Shadowbase product now supports the HPE NonStop Integrity
platform (Itanium). All basic HPE Shadowbase processes are now being
delivered as native programs for the G (S series) and newer operating
system releases, as well as all H (Integrity NonStop Itanium) operating
system releases.
Note that the Integrity versions of the bind TACL macros BINDUSRX and
BINDXYPR use OCA (the object code accelerator) instead of AXCEL.
The LINKUSRX TACL macro uses ELD instead of NLD.
Compiling and Linking User Exits in the Other Servers
Environment
There has been a fundamental change in the User Exit Processing feature. Prior
to HPE Shadowbase Other Servers v4052F, User Exit Processing was achieved
by user-defined and compiled object code that was then linked to one or more
HPE Shadowbase replication executables. e.g., TRS, TFS, Direct Writer, etc.
This method is now obsolete and has been replaced by a dynamic library
method.
The dynamic library method employs a separate DLL (Windows) or shared library
(UNIX) containing the user-defined code logic. Using a dynamic library approach
HPE Shadowbase Programming Manual—785431-007
213
User Exits
Step #3: Compiling and Binding/Linking User Exits
no longer requires static linking of the user-defined code logic into HPE
Shadowbase executables. With dynamic libraries, HPE Shadowbase replication
objects acquire the user-defined code logic at run-time.
In prior versions of HPE Shadowbase Other Servers, each executable supporting
user-exit capability could implement its own unique User Exit functionality. With
the new dynamic library approach, each configured replication object supporting
user exit capability has the ability to implement its own unique User Exit
functionality.
For example, prior to v4052x and newer, unique user-exit code would be
generated and linked to a particular executable; sbsywrtc (Cached SQL Statement
TRS for Sybase) for example. Any configured TRS using this executable
(sbsywrtc) would then implement this user-exit functionality when user-exit
processing was enabled (SHAD_USRX_PROCESSING=1).
However, for HPE Shadowbase Other Servers v4052x and newer, multiple
Cached SQL Statement Sybase TRS’s may now be configured whereby each
instance can have its own unique User Exit functionality. This capability is
achieved via dynamic libraries where the unique User Exit functionality is defined
in and implemented by a particular dynamic library module. In this way, multiple
unique dynamic libraries can be produced for simultaneous use.
The particularly configured replication objects choose their select dynamic library
at run-time via the shadparm.ini parameter SHAD_USRX_LIBARY_NAME, which is
described in the following section.
For Windows releases, a Visual Studio 2005 Solution is provided to aid in the
building of the DLL. In the event Visual Studio 2005 is not available, an NMAKE
makefile is also provided to aid in the building of the DLL.
For UNIX releases, an eclipse project is provided to aid in the building of the
shared library. In the event eclipse is not available, an GMAKE makefile is also
provided to aid in the building of the shared library.
User Exit Build Architecture for Windows
The following table expresses the contents of the UserExitBuild directory
installed with HPE Shadowbase Other Servers v4052F. This directory and its
contents are specifically designed for use in developing user-defined User Exit
functionality for use with HPE Shadowbase Other Servers v4052F.
Location
UserExitBuild
UserExitBuild\USRXDLL
Contents
USRXDLL (directory)
include (directory)
lib (directory)
source (directory)
USRXDLL.sln (VS 2005 Solution)
USRXDLL.vcproj (VS 2005
project)
HPE Shadowbase Programming Manual—785431-007
214
User Exits
Step #3: Compiling and Binding/Linking User Exits
UserExitBuild\USRXDLL\include
UserExitBuild\USRXDLL\lib
UserExitBuild\USRXDLL\lib\Debug
UserExitBuild\USRXDLL\lib\Release
UserExitBuild\USRXDLL\source
usrxlib.h (C source header file)
usrxopen.h (C source header file)
Debug (directory)
Release (directory)
USRXDLLINIT.obj (Debug
version)
USRXDLLINIT.obj (Release
version)
usrxopen.c (C skeleton source
file)
User Exit Build Architecture for Linux/Unix
Location
UserExitBuild
UserExitBuild\USRXDLL
UserExitBuild\USRXDLL\include
UserExitBuild\USRXDLL\lib
UserExitBuild\USRXDLL\lib\Debug
UserExitBuild\USRXDLL\lib\Release
UserExitBuild\USRXDLL\source
Contents
USRXDLL (directory)
include (directory)
lib (directory)
source (directory)
.cproject (eclipse c/c++ project
meta file)
.project (eclipse USRXDLL project
meta file)
usrxlib.h (C source header file)
usrxopen.h (C source header file)
Debug (directory)
Release (directory)
USRXDLLINIT.o (Debug version)
USRXDLLINIT.o (Release
version)
usrxopen.c (C skeleton source
file)
HPE Shadowbase Programming Manual—785431-007
215
User Exits
Step #3: Compiling and Binding/Linking User Exits
Visual Studio 2005 Solution
The USRXDLL.sln file produces the following project structure.
The USRXDLL project provided is configured to generate a single Dynamic
Library (.dll) using the skeleton code module, usrxopen.c, provided. By default
and without modifying any of the Solution or Project properties, this configuration
generates a Dynamic Library named CustomUE.dll.
Both the USRXDLL.sln solution and or USRXDLL.vcproj project may be used
directly or as templates for user-defined Dynamic Library generation. When
unique user exit processing logic is required between two or more HPE
Shadowbase Other Servers replication objects, a unique Dynamic Library
containing the instance-specific user exit processing logic must be created.
The Visual Studio 2005 Solution/Project provided by HPE Shadowbase offers
users choices and options in the methods and techniques of HPE Shadowbase
Other Servers User Exit development.
For examples:
A user has requirement for only a single User Exit. The logic incorporated in
the user exit processing is to be performed by all target replication objects.
e.g., Transaction Replay Servers.
User can use the VS 2005 Solution directly.
A user has requirement for multiple, dissimilar, user exit processing. The
logic incorporated in one user exit must be performed by a specific replication
object instance and not by all.
In this case, users can create multiple VS projects within the provided
solution where each is a copy of the USRXDLL.vcproj project (uniquely
named).
HPE Shadowbase Programming Manual—785431-007
216
User Exits
Step #3: Compiling and Binding/Linking User Exits
Alternatively, users can create multiple VS solutions, one for each of the
unique user exit processing requirements, using the USRXDLL.sln Solution
as a template.
The USRXDLL.vcproj project has the following General Configuration Properties:
Note: The Project Defaults→Configuration Type is set to Dynamic Library (.dll).
This setting must be maintained for all user exit project(s). As a rule, when
creating new projects for generating user exit dynamic libraries, configure them
with the same property settings as the base USRXDLL.vcproj project provided.
By default, the USRXDLL.vcproj project generates a dynamic library named
CustomUE.dll. The name of dynamic library is NOT required to be
CustomUE.dll. Users may specify another more appropriate name if they desire.
However, the name given to any specific user-defined user exit processing
dynamic library must not conflict with any of the names on the following list.
DB2CacheDLL.dll
DB2CLIInterface.dll
MsSqlEIDLL.dll
MSSQLSourceCollector.dll
ODBCCacheDLL.dll
Oracle10gr2Cache.dll
Oracle10gr2EI.dll
Oracle9ir2Cache.dll
Oracle9ir2EI.dll
SBEvents.dll
SybaseCache125DLL.dll
SybaseCache150DLL.dll
SybaseEI125DLL.dll
SybaseEI150DLL.dll
USRXAPIDLL.dll
USRXDLL.dll
HPE Shadowbase Programming Manual—785431-007
217
User Exits
Step #3: Compiling and Binding/Linking User Exits
To specify the name of the dynamic library to produce, use the
Configuration Properties→Linker→General property page as shown below.
The Output File property specifies the name of the output object resulting from
the project build. The Output File property is a text based property and allows
the use of project property macros. When specifying an output file name, proper
file naming conventions must be used. The screen-shot above shows the output
file name used by default and uses the project property macro
$(ConfigurationName) to specify the path. The $(ConfigurationName) macro
resolves to the active Configuration: selection in force. Visual Studio 2005
provides Debug and Release configurations by default.
HPE Shadowbase Programming Manual—785431-007
218
User Exits
Step #3: Compiling and Binding/Linking User Exits
CustomUE-MakeFile.mak
An NMAKE description file is provided to aid user-exit development in
environments where Visual Studio 2005 is not available. Under this condition,
however, a version of the Microsoft Platform SDK, Microsoft Windows SDK, or
.NET Framework SDK must be available for use. NMAKE.EXE is a 32-bit tool
that builds projects based on commands contained in a description file. The
NMAKE description file provided is designed to produce both a Debug and
Release version DLL using the skeleton source file, usrxopen.c. If additional
source files are required, the NMAKE description file will need to be modified
accordingly. The following is the usage syntax for NMAKE and the CustomUEMakeFile.mak description file.
NMAKE syntax:
NMAKE [options] [/f makefile] [/x stderrfile] [macrodefs] [targets]
Usage Syntax:
NMAKE /f CustomUE-MakeFile.mak [targets]
targets: Debug, Release, all, clean, cleand, cleanall (case sensitive)
Debug
Release
all
clean
target
cleand
target
cleanall
Build CustomUEd.dll
Build CustomUE.dll
Build both CustomUEd.dll and CustomUE.dll
.PHONY target used to force a full re-build of the Release
.PHONY target used to force a full re-build of the Debug
.PHONY target used to force a full re-build of both Debug
and Release targets
Special note: targets are constructed in the order in which they are specified on
the command-line.
HPE Shadowbase Programming Manual—785431-007
219
User Exits
Step #3: Compiling and Binding/Linking User Exits
Examples:
The following is an example run of CustomUE-MakeFile.mak using the all target
argument.
C:\Shadowbase\v4052F\UserExitBuild\USRXDLL\source>nmake /f CustomUE-MakeFile.mak
all
Microsoft (R) Program Maintenance Utility Version 8.00.50727.762
Copyright (C) Microsoft Corporation. All rights reserved.
----- DEBUG Build in-progress ----Building target: CustomUEd.dll
Invoking: Linker (Debug)
Creating library CustomUEd.lib and object CustomUEd.exp
Linker target: CustomUEd.dll - complete
Moving target: CustomUEd.dll to Directory: C:\Shadowbase\v4052F\bin
Building file: usrxopen.obj
Invoking: C Compiler
usrxopen.c
Compilation of: usrxopen.obj - complete
----- RELEASE Build in-progress ----Building target: CustomUE.dll
Invoking: Linker (Release)
Creating library CustomUE.lib and object CustomUE.exp
Linker target: CustomUE.dll - complete
Moving target: CustomUE.dll to Directory: C:\Shadowbase\v4052F\bin
C:\Shadowbase\v4052F\UserExitBuild\USRXDLL\source>
The following is an example run CustomUE-MakeFile.mak using the cleanall
target argument followed by the all target argument.
C:\Shadowbase\v4052F\UserExitBuild\USRXDLL\source>nmake /f CustomUE-MakeFile.mak
cleanall all
Microsoft (R) Program Maintenance Utility Version 8.00.50727.762
Copyright (C) Microsoft Corporation. All rights reserved.
Removing target Debug and dependant objects
Removing target Release and dependant objects
Building file: usrxopen.dbg.obj
Invoking: C Compiler
usrxopen.dbg.c
Compilation of: usrxopen.dbg.obj - complete
----- DEBUG Build in-progress ----Building target: CustomUEd.dll
Invoking: Linker (Debug)
LINK : CustomUEd.dll not found or not built by the last incremental link;
performing full link
Creating library CustomUEd.lib and object CustomUEd.exp
Linker target: CustomUEd.dll - complete
Moving target: CustomUEd.dll to Directory: C:\Shadowbase\v4052F\bin
Building file: usrxopen.obj
Invoking: C Compiler
HPE Shadowbase Programming Manual—785431-007
220
User Exits
Step #3: Compiling and Binding/Linking User Exits
usrxopen.c
Compilation of: usrxopen.obj - complete
----- RELEASE Build in-progress ----Building target: CustomUE.dll
Invoking: Linker (Release)
Creating library CustomUE.lib and object CustomUE.exp
Linker target: CustomUE.dll - complete
Moving target: CustomUE.dll to Directory: C:\Shadowbase\v4052F\bin
C:\Shadowbase\v4052F\UserExitBuild\USRXDLL\source>
Special notes:
 NNAKE is run from the command prompt window.
 It may be necessary to condition your command prompt session for
application development by executing one of Microsoft’s vcvars batch
files. See your SDK documentation.
Eclipse Project
Eclipse is a popular multi-language software development environment
comprising an IDE and an extensible plug-in system. HPE Shadowbase Other
Servers v4052F provides an eclipse CDT project to aid user-exit development
and therefore requires the Eclipse CDT for C/C++ plug-in. Eclipse supports, but
does not provide, numerous software development tool chains. Users must
ensure that an appropriate C/C++ software development tool chain is installed on
their development system.
Workspace Selection
Eclipse uses the workspace concept to organize projects for a given workbench
instance. An eclipse workbench refers to the running instance of the IDE. An
eclipse workspace is the top-level directory where all source code and other files
and settings are stored for a given workbench environment. When you first start
eclipse, the Workspace Launcher dialog window will appear prompting you to
select a workspace to use.
Select the UserExitBuild folder from your install, or your corresponding folder if
you are creating multiple user-exit shared libraries and you are using a different
location than the installation location.
HPE Shadowbase Programming Manual—785431-007
221
User Exits
Step #3: Compiling and Binding/Linking User Exits
If when launching eclipse you are not prompted to select a workspace, but rather
go directly to an existing workbench, you will need to modify the ‘startup and
shutdown’ properties and ensure the ‘Prompt for workspace on startup’ option is
checked.
HPE Shadowbase Programming Manual—785431-007
222
User Exits
Step #3: Compiling and Binding/Linking User Exits
The eclipse IDE should now present the ‘Welcome’ perspective.
Click the X on the Welcome tab to continue to a default workbench.
Ensure your workbench supports and is running the C/C++ perspective. If not,
select the C/C++ perspective by clicking on the Window menu and choosing
Open Perspective-> Other, and select the C/C++ option
HPE Shadowbase Programming Manual—785431-007
223
User Exits
Step #3: Compiling and Binding/Linking User Exits
You should now be presented with a default (empty) workbench similar to the
following.
HPE Shadowbase Programming Manual—785431-007
224
User Exits
Step #3: Compiling and Binding/Linking User Exits
Select Window->Preferences->General->Workspace and ensure the ‘Build
automatically’ option should is un-checked.
HPE Shadowbase Programming Manual—785431-007
225
User Exits
Step #3: Compiling and Binding/Linking User Exits
Importing Project into workbench
From the File menu of the eclipse workbench, select Import
Expand the General folder and select “Existing Projects into Workspace”, then
click Next
HPE Shadowbase Programming Manual—785431-007
226
User Exits
Step #3: Compiling and Binding/Linking User Exits
Select the radio button for “Select root directory” and then browse to the
UserExitBuild folder. You should see USRXDLL listed in the ‘Projects:’ box.
Click Finish.
HPE Shadowbase Programming Manual—785431-007
227
User Exits
Step #3: Compiling and Binding/Linking User Exits
The USRXDLL project should now have been added to the workbench as shown
above.
From the ‘Project’ menu select Build Configuration->Set Active and choose the
desired build configuration setting (Debug or Release) by checking the check-box
next to your selection.
Note: For Shadowbase on HPE NonStop OSS, there is no Release option
support, only Debug is available for this platform.
To execute a build, choose ‘Clean’ from the ‘Project’ menu.
HPE Shadowbase Programming Manual—785431-007
228
User Exits
Step #3: Compiling and Binding/Linking User Exits
In the ‘Clean’ dialog, ensure that the following are true.
 ‘Clean all projects’ radio button is select
 ‘Start a build immediately’ check-box is checked.
 ‘Build the entire workspace’ radio button is selected
Click ‘OK’ to start the build process.
HPE Shadowbase Programming Manual—785431-007
229
User Exits
Step #3: Compiling and Binding/Linking User Exits
CustomUEMakeFile
A GNU make makefile is provided to aid user-exit development in UNIX
environments where eclipse is not available. Under this condition, however, a
version of the GNU GCC/G++ tool chain must be available for use. GNU make
(aka gmake) is a tool that builds executables and other non-source files from
program source files based on commands contained in a makefile file. The
CustomUEMakeFile makefile is based on the GNU make makefile syntax and is
not directly compatible with other make utilities. The CustomUEMakefile
makefile was designed and tested using GNU make version 3.81
The CustomUEMakeFile makefile provided is designed to produce both a Debug
and Release version shared library using the skeleton source file, usrxopen.c. If
additional source files are required, the CustomUEMakeFile makefile will need to
be modified accordingly. The following is the usage syntax for gmake and the
CustomUEMakeFile makefile.
GNU make syntax:
make [options] [targets] …
Usage Syntax:
make -f CustomUEMakeFile [targets]
targets: Debug, Release, all, clean, cleand, cleanall (case sensitive)
Debug
Release
all
clean
target
cleand
target
cleanall
Build libCustomUEd.so
Build libCustomUE.so
Build both libCustomUEd.so and libCustomUE.so
.PHONY target used to force a full re-build of the Release
.PHONY target used to force a full re-build of the Debug
.PHONY target used to force a full re-build of both Debug
and Release targets
Special notes: targets are constructed in the order in which they are specified on
the command-line.
For Shadowbase on HPE NonStop OSS, there is no Release
option available for the “targets” option, only Debug is available for
this platform.
HPE Shadowbase Programming Manual—785431-007
230
User Exits
Step #3: Compiling and Binding/Linking User Exits
Examples:
The following is an example run of the CustomUEMakeFile makefile using the all
target argument.
>$ make -f CustomUEMakeFile all
* * * * * * * * * * * * * * * * * * * * * * * * * * * *
*
Shadowbase Open Server
*
v4052F (22NOV10)
*
Custom User Exit Makefile
*
* Copyright 1995-2010 Gravic, Inc.
* All Rights Reserved.
* [email protected]
WWW.GRAVIC.COM
* * * * * * * * * * * * * * * * * * * * * * * * * * * *
*
*
*
*
*
*
*
*
*
***** DEBUG Build in-progress *****
Building file: usrxopen.dbg.c
Invoking: GCC C Compiler
Compilation of: usrxopen.dbg.c - complete
---- **** ---Building target: libCustomUEd.so
Invoking: GCC C Linker
Linker
target: libCustomUEd.so - complete
Moving
target: libCustomUEd.so to Directory:
/home/Shadowbase/v4052F/lib
***** RELEASE Build in-progress *****
Building file: usrxopen.c
Invoking: GCC C Compiler
Compilation of: usrxopen.c - complete
---- **** ---Building target: libCustomUE.so
Linker
target: libCustomUE.so - complete
Moving
target: libCustomUE.so to Directory:
/home/Shadowbase/v4052F/lib
>$
The following is an example run of the CustomUEMakeFile makefile using the
cleanall target argument followed by the all target argument.
>$ make -f CustomUEMakeFile cleanall all
Removing target and dependant objects
libCustomUEd.so
libCustomUE.so
*** complete ***
* * * * * * * * * * * * * * * * * * * * * * * * * * * *
*
Shadowbase Open Server
*
v4052F (22NOV10)
*
Custom User Exit Makefile
*
* Copyright 1995-2010 Gravic, Inc.
* All Rights Reserved.
* [email protected]
WWW.GRAVIC.COM
* * * * * * * * * * * * * * * * * * * * * * * * * * * *
***** DEBUG Build in-progress *****
HPE Shadowbase Programming Manual—785431-007
231
*
*
*
*
*
*
*
*
*
User Exits
Step #4: Configuring HPE Shadowbase Use of the User Exit
Building file: usrxopen.dbg.c
Invoking: GCC C Compiler
Compilation of: usrxopen.dbg.c - complete
---- **** ---Building target: libCustomUEd.so
Invoking: GCC C Linker
Linker
target: libCustomUEd.so - complete
Moving
target: libCustomUEd.so to Directory:
/home/Shadowbase/v4052F/lib
***** RELEASE Build in-progress *****
Building file: usrxopen.c
Invoking: GCC C Compiler
Compilation of: usrxopen.c - complete
---- **** ---Building target: libCustomUE.so
Linker
target: libCustomUE.so - complete
Moving
target: libCustomUE.so to Directory:
/home/Shadowbase/v4052F/lib
>$
.
Step #4: Configuring HPE Shadowbase Use
of the User Exit
Once you have planned, coded, and compiled in the previous steps, you
must configure HPE Shadowbase to use the user exits. The sections
below detail configuring HPE Shadowbase to use user exits in the
NonStop and Other Servers environments.
Configuring HPE Shadowbase Use of User Exits in the
NonStop Environment
In general, configuring to use a user exit is not very different than
configuring for standard, direct replication. In the NonStop environment,
first OPEN AUDMON and enter your LICENSE file. Then issue any SET
AUD parameter commands you need in your environment and START
AUD. Be sure that the MAXDBSSPEC AUD parameter will be large
enough to accommodate all the DBSs for all the Consumers in your
environment.
Next, configure and add the Collector(s) and Consumer(s). Again, be sure
that the MAXDBSSPEC CONS parameter is set high enough to
accommodate the number of DBSs you need.
When you configure HPE Shadowbase to use a user exit process, you
need to associate the appropriate section of USRXPROCESS with a DBS.
HPE Shadowbase Programming Manual—785431-007
232
User Exits
Step #4: Configuring HPE Shadowbase Use of the User Exit
To do this, issue a SET DBS USEREXITID <n> where <n> is the number
of the user exit code to be executed in the USRXPROCESS program.
Depending upon the APIs you are using, you may also need to declare
other DBS non-required parameters. These parameters include:
SOURCEDICT, SOURCEREC, and BEFOREVALUES. See the
Considerations sections of the various APIs you are using for more
information.
Configuring HPE Shadowbase Use of User Exits in the
Other Servers Environment
User Exit processing is enabled for HPE Shadowbase Other Servers
replication objects via the setting of the shadparm.ini parameter
SHAD_USRX_PROCESSING.
If you have not configured the desired replication objects you should do so
now.
Use the SBMON ADD or EDIT commands to create or modify,
respectively, your desired replication objects.
Set the SHAD_USRX_PROCESSING parameter in the shadparm.ini file
to a value of 1 using your text file editor of choice.
[TRS]
SHAD_USRX_PROCESSING=1
Optionally, the shadparm.ini parameter SHAD_USRX_DIAGNOSTICS can
be set to 1 to turn on diagnostic logging. By setting this parameter to a
value of 1 in the shadparm.ini file turns on diagnostics that can help you
debug your user exits. When it is turned on, diagnostic data is sent to the
select HPE Shadowbase objects error log file. The default for this
parameter is 0 (off). Be sure this parameter is set to off when you are
not/do not need user exit processing as the verbose logging of the
diagnostic data will affect overall replication performance unnecessarily.
This parameter is not available in the HPE NonStop environment. See the
HPE Shadowbase Other Servers Operations Manual for details on the
SHAD_USRX_ DIAGNOSTICS parameter.
For installations running 4.052x and newer, the following parameter is required as well.
SHAD_USRX_LIBRARY_NAME
The SHAD_USRX_LIBRARY_NAME parameter specifies the dynamic link or
shared library module containing the user-defined User Exit functionality to be
implemented. The parameter is to be specified in the shadparm.ini file under the
specific group-name of replication object for which the User Exit logic is
HPE Shadowbase Programming Manual—785431-007
233
User Exits
Step #5: Testing and Debugging the User Exit
designed. Users are cautioned to take care in assigning this parameter.
Incorrect assignment can lead to database corruption.
This parameter takes an ASCII character string assignment representing the
name of an existing dynamic link or shared library module. No surrounding quote
characters are required and should be omitted. When the library module resides
in the bin directory (Windows) or lib directory (UNIX) of the HPE Shadowbase
installation, a fully qualified name is not required. If the library module resides in
a directory other than the bin directory (Windows) or lib directory (UNIX) of the
HPE Shadowbase installation, a fully qualified file name is required.
SHAD_USRX_LIBRARY_NAME=<dynamic link or shared library
name.extension>
Step #5: Testing and Debugging the User
Exit
Once you have compiled and bound the user exit, you are ready to begin
testing and debugging. Remember, the main goal of any user exit is to
produce accurate target data customized appropriately. You must
carefully and thoroughly test and debug your user exit. Be sure to test all
paths through the user exit code with all event types (insert, update, and
delete). Also, try to test with data that is truly representative of the data
that will be processed on the production system. No API call should ever
receive a return code value less than zero. The user exit should be coded
to take appropriate action if a return code value of less than zero is
detected.
The general steps for testing your user exit are:
1. Configure and start HPE Shadowbase. Configuration for user exits is
discussed in the section that follows.
2. In the NonStop environment it is highly recommended that you start
an EMS distributor to monitor HPE Shadowbase during the testing.
In the Open environment view the error log file periodically to review
any error or informational messages that will be produced. When
using the SHAD_USRX_DIAGNOSTICS parameter a significant
amount of informational messages are be produced.
3. Generate data into audited source files/tables.
4. Verify that source and target data match your expected results.
If you encounter problems during testing, it is recommended that you run
the user exit enabled process in debug mode.
HPE Shadowbase Programming Manual—785431-007
234
User Exits
Preparing User Exit Code for sbdocrd
In the NonStop environment use the NonStop INSPECT facility. To
enter Debug when the Consumer process starts, set the parameter SET
CONS DEBUG to the value ONSTART for the related Consumer. When
the INSPECT prompt comes up, set a break point at #USRXPROCESS
and/or other processes (#USRXINIT, #USRXSTART,
#USRXEXCEPTIONINIT, #USRXEXCEPTION) you wish to debug.
Also in the HPE NonStop environment, the user exit tracing facility and
the SQL tracing facility may aid in testing and debugging your user exit.
See the HPE NonStop Shadowbase Operations Manual for details on
these tools.
In the Other Servers environment use a debugging tool such as
Microsoft Visual Studio, gdb, dbx to debug the user exit enabled Other
Servers process.
While performing a debug session, keep the following items in mind.
 Verify that you are getting the correct data from your SBGET calls.
 Be sure that data is in the proper format before any SBPUT calls.
 Verify that no calls are receiving return codes less than zero.
 Check for SQL errors (EMS on NonStop, error log file on Open).
 Verify passed function argument value(s) make sense according to
their prototype.
Preparing User Exit Code for sbdocrd
The sections that follow describe the preparation of user exit code for the
customizable DOC reader (sbdocrd). Before beginning to code your user
exit routine, you should review this section and review the comments in
the shell program file located in the HPE Shadowbase source
subdirectory. If you plan to use a Transaction Replay server, it is not
necessary to modify sbdocrd. However, you should go through the DOC
Processing Considerations section, below, to gain a more thorough
understanding of DOCs.
HPE Shadowbase provides a shell program, sbdocrd, which enables the
reading of the DOC. It has API function calls that permit you to access the
data it reads from the DOC. You can then process the data as you wish.
Before you prepare your user exit code for sbdocrd, you need to review
the DOC Processing Considerations section, below. You also need to
look at the functions and structures used in sbdocrd. These topics are
covered in the subsections that follow.
DOC Processing Considerations
HPE Shadowbase Programming Manual—785431-007
235
User Exits
Preparing User Exit Code for sbdocrd
Please consider the following before preparing your sbdocrd user exit
code:

Other Servers and their DOCs are logically linked to the Collector
processes running in the NonStop HPE Shadowbase system in a oneto-one per target system relationship. This is because the Collector is
the first process to detect a replicable change and a DOC is an
organized repository of changes received from the Collector. There is
normally only one DOC per NonStop Collector process per target
system.

HPE Shadowbase supports three different formats of DOC: SQL
statement DOC, Cached SQL statement DOC, or column name/value
DOC (comma delimited). The SQL statement DOC and Cached SQL
statement DOC store the messages as event (insert, update, and
delete) statements. The SQL statements can be in Oracle, Sybase,
SQL Server (MSSQL), DB2, MySQL or NonStop NSSQL formats. If
you are going to use a Transaction Replay server to process your
DOC, you must not use the column name/value DOC. The column
name/value DOC stores the messages as a file of column names and
their new values separated by commas. The format of the DOC you
choose will depend upon how you plan to use the data. Column
name/value DOCs are often read and formatted into audit-type change
reports. SQL statement DOCs and Cached SQL statement DOCs can
be used when you wish to analyze not only the substance of the
changes, but also the types of events occurring on your source
database.

Within each format of DOC, you can specify whether the DOC is to be
created so that events that occurred on the source database are: 1)
grouped by their original TM/MP transactions (transaction order) or 2)
written in the order in which they occurred on the source system
without regard to TM/MP transactions (time order). When an insert,
update or delete event occurs on any audited file/table in the source
system, TM/MP records the event in the audit trail when it happens.
Because multiple TM/MP transactions can be active at any given time,
events for different transactions are often intermixed in the audit trail.
The Collector process reads the audit trail sequentially (time order). If
it is important that all events within a TM/MP transaction are organized
as a group, you need to configure your DOC Collector to
accommodate this need.

When you configure an Other Servers, the data directory for the DOC
is created underneath the SHAD_BASE directory. The DOC sequence
number for the Other Servers is set to 1. The initial event DOC
HPE Shadowbase Programming Manual—785431-007
236
User Exits
Preparing User Exit Code for sbdocrd
(sequence number 1) is created. Each DOC is in its own directory
named SHAD_BASE/data/<collectorname>. Where <collectorname>
is the same as the name assigned to the Collector process on the HPE
NonStop system via the SET COLL PROCESS parameter. All of the
DOC files related to that Collector reside in this directory.

A DOC that is being written to by the Collector cannot be processed by
sbdocrd until it is closed. To enable you to close a DOC for processing
by sbdocrd and not have to shut down the flow of changes coming
from the NonStop system, HPE Shadowbase closes the current DOC
and opens a new one. This is known as a DOC roll. DOCs being read
by a Transaction Replay server do not have to be closed before
processing. However, DOC rolls are still performed to maintain file
size limits.

Each time you close a DOC for processing by sbdocrd, a new set of
DOC files is created so that the Other Servers(s) can continue
recording events. When a roll is initiated from the HPE NonStop
system via a NEXTDOC or NEXTDOCTIME/NEXTDOCTRIGGER
commands (see the HPE NonStop Shadowbase Command
Reference Guide for information on these commands), the sequence
number of the new DOC files is one greater than the sequence number
of the DOC that was just closed. When DOC 999 is rolled, the
sequence number goes back to 1.

When a DOC roll occurs and you opt to store events so that they can
be processed within TM/MP transaction, the Collector will close the
current DOC, open a new one, and then roll any “in-flight” transactions
into the new DOC. An “in-flight” transaction is one for which an end
transaction has not yet been received from the Collector. By keeping
all events related to a transaction in the same DOC, sbdocrd has clean
starting and ending points (boundaries). If the Collector was
configured to write events in the order they occurred (time order),
some events for a TM/MP transaction can end up in the current DOC
and the remaining events may be in the next DOC.

Sbdocrd can read the DOC in event or committed transaction order
depending upon how it was created. Event order means the DOC is
read in the order in which the events occurred (time order). Committed
transaction order means the events are read in the order in which they
occurred within a NonStop TM/MP transaction (event-withintransaction order). In order to read the DOC in event-withintransaction order, it must have been created to facilitate this.
Transaction Replay servers read DOCs in committed transaction order.
Modifying sbdocrd
HPE Shadowbase Programming Manual—785431-007
237
User Exits
Preparing User Exit Code for sbdocrd
. To customize the DOC reader program, sbdocrd, modify the sbdocrd.c
code to suit your needs. Some information about the APIs available for
this program appears below. You should also review the sbdocrd.c shell
program file for details.
DOC Record Structures
. The sbdocrd.c shell program supplied with HPE Shadowbase reads
column name/value pairs and SQL statement DOCs and prints them to the
screen. Two structures are provided at the top of the sbdocrd.c module
and appear below:
Record structure for Column name/value pair database:
char SBInternal1[8];
char trans_id[8];
char SBInternal2[10];
unsigned short cons_id;
char table_name[8];
char op_type;
unsigned short num_keys;
unsigned short num_values;
char av_pair_list[64000];
typedef struct CommaDelimStruct CDRecord, *CDPointer;
Record structure for SQL Statement database:
char SBInternal1[8];
char trans_id[8];
char SBInternal2[10];
unsigned short cons_id;
char table_name[8];
char op_type;
unsigned short stmt_len;
char sql_stmt[65000];
Where:
trans_id
Is the source system transaction ID.
cons_id
Is the TCP/IP port assigned to the Consumer.
table_name
HPE Shadowbase Programming Manual—785431-007
238
User Exits
Preparing User Exit Code for sbdocrd
Is the TARGETFILE or PATHNAME assigned on the HPE NonStop
system.
op_type
Is the operation type (abort, begin, commit, delete, update, insert).
num_keys
Is the number of key column name/value pairs in the av_pair_list
which are used in the where clause (for deletes and updates).
Keys are listed before change values.
num_values
Is the total number of column name/value pairs (where clause
values plus change values) which are used in the body of the SQL
statement (change values follow the where key values).
stmt_len
Is the length of the sql_stmt.
sql_stmt
Is the actual SQL statement formatted for the correct database:
ORACLE, SYBASE, or MSSQL.
av_pair_list
Is primarily column name/value pairs separated by commas.
Sbdocrd Functions and User Structures
. There are two “read by” functions in sbdocrd that you can interact with:
ReadByTransaction and ReadByEvent. Each reads the DOC and calls
your user exit code for each record read. In your user exit, you take
whatever steps are needed to process the DOC data into their final form.
Each of the “read by” functions is described below.
ReadByTransaction
ReadByTransaction processes a DOC by event-within-transaction order.
This is only available if the DOC was created to facilitate this. A user exit
function can be passed to provide processing control for each transaction
in sequence. This function works in conjunction with the following static
variables and the function ReadTransHook.
Inputs:
CollectorName
Is the name of the Collector whose DOC is to be read.
HPE Shadowbase Programming Manual—785431-007
239
User Exits
Preparing User Exit Code for sbdocrd
SequenceNumber
Is the sequence number of the files to be read.
UserSuppliedPtr
Is a pointer to the buffer that will be filled with the event data.
UserSuppliedLength
Is a pointer to a variable that will be set to the length of the variable
length statement portion of the event record.
ReadTransHook
Is a function to be called for every event processed.
Returns:
If ReadTransHook is specified and they were passed initially,
UserSuppliedPtr and UserSuppliedLength will be filled with
appropriate values.
ReadByEvent
ReadByEvent reads a DOC in time order (order in which the events
occurred regardless of transaction). It can be called with a user exit to
process each event in sequence.
Inputs:
CollectorName
The name of the Collector whose DOC is to be read.
SequenceNumber
The Sequence number of the event DOC to be read.
UserSuppliedPtr
A pointer to the buffer to be filled with the event data. (Only
applicable if a user exit is supplied).
UserSuppliedLength
A pointer to the variable that returns the length of the current
variable length statement to the user.
ReadEventHook
A pointer to the user exit function to be called for each event in the
event DOC.
Returns:
UserSuppliedPtr and UserSuppliedLength will be filled with
appropriate values if passed in when ReadEventHook is specified.
HPE Shadowbase Programming Manual—785431-007
240
User Exits
Preparing User Exit Code for sbdocrd
Compiling sbdocrd
. After you have modified sbdocrd appropriately, you need to compile it.
To compile on a UNIX system, enter
make –f makefile.sbdocrd
To compile a Windows system, enter
nmake –f makefile.sbdocrd
HPE Shadowbase Programming Manual—785431-007
241
Data Mapping
Overview
Data Mapping
Overview
The HPE Shadowbase Data Transformation Facility extends the user exit
capabilities by externalizing some of the more common operations. Note
that there are some limitations. The Data Transformation Facility can be
used with both the HPE Shadowbase Other Servers and the NonStop
Server.
Implementing the Data Mapping Facility
There are four main steps when implementing the data mapping facility.
1. Plan data mapping processing and design the shaddbs.ini file.
2. Script the shaddbs.ini file.
3. Configure HPE Shadowbase for use of the shaddbs.ini file.
4. Test and debug the shaddbs.ini file.
The result of the plan processing/design program phase will be a layout of
all the processing your user exit will do. This may be in the form of a
flowchart, pseudo-code or whatever presentation usually works for you.
You may also want to include how you will test the user exit in these
plans. Next, you will code your user exit routine. This is followed by
compiling it and binding it into the Consumer. When the new Consumer is
prepared, configure, and start HPE Shadowbase. Finally, begin testing
and debugging the program.
Step #1: Planning for Data Mapping and
Designing the shaddbs File
The data mapping facility is controlled by a configuration file called
shaddbs (shaddbs.ini on Open). In this file, you specify mapping
instructions on a table by table basis. This makes the set of instructions
similar to a DBS specification on the HPE NonStop system.
Data mapping commands are added to the shaddbs file to map data from
the source to the target. In general, the format of the shaddbs file is as
follows:
HPE Shadowbase Programming Manual—785431-007
242
Data Mapping
Step #2: Scripting the shaddbs File
[DBS+]<operation>:<target_table1>
[<dbs_command1>]<dbs_command1_options>
[<dbs_command2>]<dbs_command2_options>
…
[<dbs_commandn>]<dbs_commandn_options>
[DBS+]<operation>:<target_table2>
[<dbs_command1>]<dbs_command1_options>
[<dbs_command2>]<dbs_command2_options>
…
[<dbs_commandn>]<dbs_commandn_options>
…
[DBS+]<operation>:<target_tablem>
[<dbs_command1>]<dbs_command1_options>
[<dbs_command2>]<dbs_command2_options>
…
[<dbs_commandn>]<dbs_commandn_options>
The shaddbs file contains a set of commands for each table for which you
want to map data, target_table1, target_table2, …, target_tablem, above.
For each table a series of commands is used to map the data
dbs_command1, dbs_command2, …, dbs_commandn, above. Details on
each of the shaddbs commands are provided in the sections to follow.
Step #2: Scripting the shaddbs File
Each of the mapping commands is described below. Sample shaddbs
configuration files appear at the end of this document.
Shaddbs File Syntax







No spaces are allowed between the <target_col_name> and = or the =
and the <new_value>.
# is the comment character for the shaddbs file.
The order of the commands matters. For example, the [DBS+]
command must appear in the file first. If you issue a [FLD++]
command and then issue a [WHERECLAUSE-] command, the added
columns will be dropped from the statement.
Use a double %% to escape a % needed in an expression.
Commands and comments can be preceded by spaces.
Commands can be up to 32,000 characters long.
The text of valid commands can include functions supported by the
target database system such as the Oracle TO_DATE function except
when using a Cached SQL statement Transaction Replay Server or
Cached SQL statement Direct Writer. All Cached SQL statement
Transaction Replay Servers and Direct Writers use the target DBMS’s
dynamic SQL capabilities. Dynamic SQL does not support SQL
functions within SQL statements.
HPE Shadowbase Programming Manual—785431-007
243
Data Mapping
Step #2: Scripting the shaddbs File

To define multiple [DBS+] definitions, include multiple [DBS+]
command lines. Each [DBS+] command line begins a new [DBS+]
definition.
[DBS+] Command
The first command you include in the shaddbs file is the [DBS+]
command.
In the Other Servers environment enter the following:
[DBS+]<I|U|D>:<target_name>
In the NonStop environment (pre v5.001) enter the following:
[DBS+]<userexit_id>:<I|U|D>:<target_name>
The <userexit_id> must match the user exit id defined for your DBS
(NonStop only). The shaddbs will only be executed for the event type
defined (I for insert, U for update, or D for delete). The <target_name>
must match the name coming from the HPE NonStop side of the
replication. It tells the server to which target table the proceeding
commands pertain.
NOTE: If you want to invoke the shaddbs file for all operations (inserts,
updates, and deletes), omit the <I|U|D>: For example, in the
Other Servers environment enter the following:
[DBS+]<target_name>
or in the NonStop environment (pre v5.001) enter the following:
[DBS+]:<userexit_id>:<target_name>
Note: [DBS+] constructs can be used in combination to achieve the
desired result for example:
[DBS+]I:TABLE <do nothing for inserts>
[DBS+]TABLE <all other DML ops>
HPE Shadowbase Programming Manual—785431-007
244
Data Mapping
Step #2: Scripting the shaddbs File
Will permit Update, and Delete events.
Any of the remaining commands listed below can be included in the
shaddbs file after the [DBS+] command:
[DBS+] Command for NonStop (v5.001 and newer)
Shaddbs mapping file command to add a dbs for mapping:
[DBS+][{I|U|D|*}+:]<dbs_name>
The shaddbs processing will only be executed for the event type(s)
defined (I for insert, U for update, or D for delete). In the NonStop
environment, the <dbs_name> must match the logical DBS name for the
desired DBS configured in HPE Shadowbase. If the specified DBS uses
wildcarding for the files it is replicating, all of the files must have identical
schemas.
The optional string of one or more ‘I’, ‘U’, ‘D’, and ‘*’ characters followed
by a colon (‘:’) character allow for the specification of event types any
following commands will apply to. The ‘I’, ‘U’, and ‘D’ characters, if
specified, cause any following commands to be applied to Insert, Update,
and Delete events, respectively. The presence of the ‘*’ character, or the
exclusion of the entire optional {I|U|D|*}+: clause, cause any following
commands to be applied by default for all insert, update, and delete
events for the DBS for which no more specific DBS+ command (i.e.
[DBS+]I: for inserts, [DBS+]U: for updates, or [DBS+]D: for deletes) is
found.
At most one DBS+ command may be entered for each of the 4
classifications (inserts, updates, deletes, and default).
The following are all examples of valid [DBS+] commands entered in the
NonStop environment for a DBS called DBS1:
#DBS+ command, signifying the following
# In other words, they apply for:
# inserts if no DBS+ command specifying
# updates if no DBS+ command specifying
# deletes if no DBS+ command specifying
[DBS+]*:DBS1
rules apply by default
an I:DBS1 exists
a U:DBS1 exists
a D:DBS1 exists
HPE Shadowbase Programming Manual—785431-007
245
Data Mapping
Step #2: Scripting the shaddbs File
#DBS+ command, signifying the following
#Identical to a [DBS+]*: command
# In other words, they apply for:
# inserts if no DBS+ command specifying
# updates if no DBS+ command specifying
# deletes if no DBS+ command specifying
[DBS+]DBS1
rules apply by default
an I:DBS1 exists
a U:DBS1 exists
a D:DBS1 exists
#DBS+ command, signifying the following rules apply only for insert
operations
[DBS+]I:DBS1
#DBS+ command, signifying the following rules apply only for update
operations
[DBS+]U:DBS1
#DBS+ command, signifying the following rules apply only for delete
operations
[DBS+]D:DBS1
#DBS+ command, signifying the following rules apply only for
# insert and update operations
[DBS+]IU:DBS1
If a DBS Mapping file contains both specific and default [DBS+]
commands, the default definition will be applied for only those event types
without specific event types. This could even mean that the default
definition is never applied. For example, given the following example, the
default definition would never be used:
#Default definition DBS+ command
[DBS+]*:DBS1
#commands here would never be executed, since all event types have a
#specific DBS+ definition
#DBS+ command, signifying the following rules apply for
# insert, update, and delete operations
[DBS+]IUD:DBS1
#commands here would be executed for all event types
The follow examples would be considered invalid, as they contain multiple
definitions for the same type of event. These files would cause the
process using them to log a message and abend:
HPE Shadowbase Programming Manual—785431-007
246
Data Mapping
Step #2: Scripting the shaddbs File
#DBS+ command, specifying insert, and update events
[DBS+]IU:DBS1
#DBS+ command, specifying update and delete events
#causing a duplicate definition for update events
[DBS+]UD:DBS1
#DBS+ command, signifying the default rules
[DBS+] DBS1
#DBS+ command, signifying the default rules
#causing a duplicate definition for events by default
[DBS+]*:DBS1
[NAME+] Command
In both the Other Servers and NonStop environments enter the following:
[NAME+]<new_target_name>
You can use this command to map the data to a new target table name.
The new table must exist before attempting to apply data to it.
<new_target_name> must be in a format appropriate for your target
database.
The following exceptions apply in the HPE NonStop environment when the
[NAME+] command is used to override the target table:

All puts and gets must be restated. The [FLD+] and [FLD-] commands
described below must be used to put and get each column.

The datetime type may not be used.

The interval type may not be used.

The varchar type may not be used.
[OP-] Command
In the Other Servers and NonStop environment enter the following:
[OP-]<I|U|D|*>
This will drop the associated event type (Insert, Update, or Delete) from
the replication for this table. For example, [OP-]D will discard all deletes.
Using the *, indicates that all events are to be dropped.
HPE Shadowbase Programming Manual—785431-007
247
Data Mapping
Step #2: Scripting the shaddbs File
NOTE: Care should be taken before deciding that any type of statement is
to be dropped. Even if your application does not produce the
specified type of events, they may be used as part of database
maintenance operations, or any number of other things
Dropping DELETE statements requires some careful consideration to
avoid unintended database inconsistencies:

Dropping DELETE statements only drops DO type statements, not
UNDO type statements. So HPE Shadowbase will suppress the
original delete statement, but not any back out DELETE statements
if the transaction is aborted. (An INSERT event that is aborted and
backed out produces a DELETE "UNDO" event in the audit trail).
This allows one to keep the target synched properly with the source
when an INSERT event aborts. This matters for Direct Writer
targets, but does not matter for DOC/TRS targets as the TRS will
never replay an aborted transaction.

On a NonStop system, when a source Enscribe file or source SQL
table has a unique alternate key file or unique index defined on it, a
DELETE may be added to the audit trail by the file system under
certain conditions. For example, if a source application issues an
INSERT into the file or table, and the I/O operation gets a
DUPLICATE KEY ERROR on the unique alternate key file or
unique index, the file system has actually, internally, added the
INSERT into the audit trail followed by a DELETE into the audit
trail. This DELETE is called a “REVERSING DELETE”, and is
automatic. When HPE Shadowbase reads this INSERT and
DELETE from the audit trail, there is nothing identifying the
DELETE as a REVERSING DELETE - it looks to HPE Shadowbase
like the application simply inserted a record and then deleted it.
More specifically, the following sequence could occur for an
application: The application does an INSERT and it gets a duplicate
key error on a unique index. The application then does some other
processing and calls COMMIT. The audit trail will contain the
following sequence: the first INSERT followed by the REVERSING
DELETE. HPE Shadowbase will replicate the first INSERT to the
target and apply it. If successful, the target now has a record in it
that the source does not have. If the REVERSING DELETE is
suppressed (because DELETES are being dropped), the source
and target database will no longer match.
Suppressing UPDATES can also cause similar issues, with relation to
“REVERSING UPDATEs”.
[OP+] Command
HPE Shadowbase Programming Manual—785431-007
248
Data Mapping
Step #2: Scripting the shaddbs File
In the Other Servers and NonStop environment enter the following:
[OP+]<I|U|D|*>=<I|U|D>
This command changes one event type (insert, update, or delete) to
another type. For example, [OP+]U=I will convert Updates to Inserts using
all columns present in the Update statement. A fully qualified Insert
statement may not result from this command. This will happen when the
Update statement was generated from compressed audit and not all
columns of the underlying table where touched.
Note: For Other Servers environments, the following set of [OP+]
commands are not supported due to the absence of primary key
information.
[OP+]I=U
[OP+]I=D
[WHERECLAUSE-] Command
In both the Other Servers and NonStop environments enter the following:
[WHERECLAUSE-]
This command will drop the where clause built by the NonStop Consumer
for the statement. It is akin to doing a SBNOTIFYUSRXKEYS from user
exit code. Use the [FLD++] command described below, to build a new
where clause.
Note: Do not use this command if you plan to reconstruct the where
clause using any of the source column(s) data or assign any of the
key column(s) data to another column without first making a copy of
all key columns and their data. The order of command specification
within the shaddbs file is critical in this regard.
[FLD-] Command
In both the Other Servers and NonStop environments enter the following:
[FLD-]<target_col_name>
HPE Shadowbase Programming Manual—785431-007
249
Data Mapping
Step #2: Scripting the shaddbs File
This command will drop the column specified by <target_col_name> from
the statement, including the WHERECLAUSE. This command will
remove <target_col_name> from WHERECLAUSE if and only if the
column is not used in a ‘SET’ clause for the given event.
[FLD+] Command
In both the Other Servers and NonStop environments enter the following:
[FLD+]<target_col_name>=<new_value>
This command will add or replace the specified non-key column with the
specified new value. It permits you to do the following:

Override the value in an existing column.

Change a column name in the target table applying a value from the
source.

Add a new column name with a value to the target table.
To override the value of an existing column, enter the <target_col_name>
as it appears in the executed (source) statement. The assigned column
name must match a column name from the target table. Put the override
value into the <new_value>. <new_value> can be anything allowed by the
SQL target database. If <new_value> is in quotes (single quotes for open,
double quotes for NSK), it is treated as a string. If it is a numeric or a
special value, no quotes will be added.
[FLD+]<target_col_name>=<new_value> where <new_value> is the correct format for
the target column
To change column names, set the <new_value> to the name of a column
that exists in the executed (source) statement. Then put the target column
name in the <target_col_name>. The <new_value> must conform to the
following format:
%<SOURCE_COLUMN_NAME>%
[FLD+]<target_col_name>=%<new_value>% where <new_value> is the column name from
the source table
When the HPE Shadowbase server sees this format, it will look up the
column value associated with the executed (source) statement and use it
HPE Shadowbase Programming Manual—785431-007
250
Data Mapping
Step #2: Scripting the shaddbs File
as the value for the target column in the statement it applies to the target
database.
It should be noted in the previous example, the operation does not drop
the column name assigned to <new_value> from the statement. In order
to do so, an appropriate [FLD-] command is needed to complete the
replacement.
To add a new column to a table, enter the appropriate <new_col_name>
and <new_value>. The <new_col_name> must exist in the target
database and the <new_value> must be of the appropriate type for the
column. If <new_value> is in quotes, it is treated as a string. If it is a
numeric or a special value, no quotes are required.
[FLD+]<new_col_name>=<new_value>
NOTE: The following exceptions apply in the HPE NonStop environment
when using the [FLD+] command to put a new value into an existing
column or add a new column:

If the source column and the target column are of type char, [FLD+]
can only be used if the target column size is greater than or equal to
the source column size. Then, the [FLD+] command line must be
padded with spaces:
[FLD+]<target_col_name>=”%<source_col_name>%

<padded with spaces>
"
If the source column is of type char and the target column is of type
varchar, [FLD+] can only be used if the target column size is greater
than or equal to the source column size. Here, though the [FLD+]
command line need not be padded with spaces:
[FLD+]<target_col_name>=”%<source_col_name>%<without padded spaces>”

If the source column is of type varchar and the new_column is of type
char the [FLD+] command cannot be used.

The [FLD+] command cannot be used to increment a numeric value:
HPE Shadowbase Programming Manual—785431-007
251
Data Mapping
Step #2: Scripting the shaddbs File
[FLD+]<target_col_name>=%<source_col_name>%+10

The [FLD+] command cannot be used to change a column’s non-string
value:
[FLD+]<target_col_name>=10
[FLD++] Command
In both the Other Servers and NonStop environments enter the following:
[FLD++]<target_col_name>=<new_value>
This command is similar to [FLD+], but is used to specify changes to key
columns that are included in the where clause of update and delete
statements or new columns for inserts. Please note that altering the value
of an existing key column is not permitted by most SQL systems. This
command is most useful for building a where clause when the structure of
the key in the open SQL database is different from the key structure on
the NonStop platform. Please refer to the [FLD+] syntax for more details.
[FLD+]/[FLD++] using Transform Specification syntax
The [FLD+] and [FLD++] commands support an additional transformation
capability. This transformation capability provides character level
manipulation of data values and the ability to specify text string constants.
This transformation capability can be especially useful for formatting date,
time, and timestamp representations.
The transform specification has the following syntax.
Note: The [FLD+] command is used to describe the syntax below,
however, the syntax applies equally to the [FLD++] command
Syntax: [FLD+]<column name>=<transformation specification>
<column name> =Name of column to be acted upon and
or included.
<transformation specification> = Free form text supporting new SB
transformation specification syntax.
Transformation Specification Syntax:
HPE Shadowbase Programming Manual—785431-007
252
Data Mapping
Step #2: Scripting the shaddbs File
%<column name>:<offset>:<length>[:<default substitution value> | +/<template>]%
Attributes:
%
Leading % required; indicates start of transform
sequence.
<column name> Column name specifying the source data to use in
transformation.
:
First colon; delimiter indicating that the following
byte(s) represent starting offset of the source
data.
<offset>
Numeric digit(s) specifying starting offset position
of
source data (1 relative).
:
Second colon; delimiter indicating following
byte(s)
represent length of source data to be used.
<length>
Numeric digit(s) or asterisk (*) , specifying length of
source data (1 relative) to be used. See note below.
(optional)
The following are optional. The <default> and
<template> specifications are mutually exclusive
(one or the other, not both)
:
Third colon; delimiter indicating following byte(s)
represent a default substitution value or a
template.
<default>
value is
Value string to be used when <column name>
NULL or DNE.
Or
+/-<template>
A formatting template. To be used to format
<column name> data.
The leading +/- specify the justification to apply to
a
template specification and is a required template
attribute.
+ = Right justification within <template>
- = Left justification within <template>
%
Trailing % required; indicates end of transform
instruction.
Note: An asterisk (*) may be used as a <length> argument. When used,
signifies "all remaining source data bytes" relative to <offset> specified.
HPE Shadowbase Programming Manual—785431-007
253
Data Mapping
Step #2: Scripting the shaddbs File
Example Transformation Specification Usage
Numeric Digit String to DATE:
The following example shows the use of the transformation specification to
format a character string of digits representing a Date into a Date
representation form supported by the target database.
In this example, the COL1 column is a six digit numeric data column used
to represent a calendar date, in the form of YYMMDD. This data is to be
replicated to a target database which requires ‘dates’ to be of the form
YYYY-MM-DD. Two [FLD+] commands are used to achieve a proper
transformation.
First, a [FLD+] command is used with the optional +/-<template> to ensure
that the source data will contain a leading zero (0) character as numeric
source data may not provide the leading zero where YY is less than ten.
The <offset> is specified as 1 (beginning) and the <length> is specified as
6. The leading + in the template specification instructs right justification
within the temple string. The template is a string of six 0 character digits.
Second, a [FLD+] command is used to transform the contents of COL1
into the required character representation supported by the target
database (yyyy-mm-dd). Observe that the transformation specification is
used three times by this [FLD+] command, once for each specific portion
of col1 to act upon. The transformation specification can be used any
number of times within a given [FLD+] command, however, the DBS
Mapping Facility limits a command to a maximum of 255 bytes.
Input (original) COL1 data:
Output (target image) COL1 data:
80808
2008-08-08
Commands:
[FLD+]COL1=%COL1:1:6:+000000%
[FLD+]COL1=20%COL1:1:2%-%COL1:3:2%-%COL1:5:2%
Multiple Column Concatenation:
The following example shows how multiple columns can be concatenated
and used to populate a third column.
Note: If COL3 in the example below where to not exist in the source
statement being manipulated, it will be created.
[FLD+]COL3=%COL1%%COL2%
Positional Substring Manipulation:
HPE Shadowbase Programming Manual—785431-007
254
Data Mapping
Step #2: Scripting the shaddbs File
The following example shows a use of the positional substring aspect. A
new column is populated with the first character of the source column
data. The <default> attribute is used in this example to populate the new
column when the source data is NULL.
Input (original) COL1:
Output (target image) COLN:
'Texas'
‘T’
Command: [FLD+]COLN=%COL1:1:1:0%
Note: If COL1 is set to NULL, COLN will be set to ‘0’
[FLD+]/[FLD++] Command Limitations
The [FLD+] and [FLD++] commands have the following usage limitations
when used with Cached Transaction Replay Servers and or Direct Writers.
No target database SQL Function support with the exception of Oracle’s
TO_DATE()
No computation support
No conditional or comparison support
The [FLD+] and [FLD++] commands have the following usage limitations
when used with Non-Cached Transaction Replay Servers and or Direct
Writers.
Target database SQL Functions supported to the extent provided by the
target database with a maximum command string length of 255 bytes.
No computation support
No conditional or comparison support
The [FLD+] and [FLD++] commands (simple and complex) operate
according to the existence or absence of the specified column(s) within
the SQL DML statement being processed. Additionally for the complex
transformation form, the existence or absence of a <default> specification
can affect the result of the command. The following tables express the
action taken according to the condition(s) encountered.
Simple Transform:
[FLD+]/[FLD++]<TargetColumn>=%<SourceColumn>%
Target
Column
Found
Found
DNE
DNE
Source
Column
Found
DNE
Found
DNE
Action
Replace Target Column using Source Column
Remove Target Column
Add Target Column using Source Column
no-op
umn>=%<SourceColumn>:offset:length[<default|<+/-template>]%
Target
Column
Source
Column
Default
Specification
Action
HPE Shadowbase Programming Manual—785431-007
255
Complex
Transfor
m:
[FLD+]/[
FLD++]<T
argetCol
Data Mapping
Step #2: Scripting the shaddbs File
Found
Found
Found
DNE
DNE
DNE
Found
DNE
DNE
Found
DNE
DNE
n/a
Y
N
n/a
Y
N
Replace Target Column using Source Column
Replace Target Column using Default Specification
Remove Target Column
Add Target Column using Source Column
Add Target Column using Default Specification
no-op
[SYSTEM+] Command
In both the Other Servers and NonStop environments enter the following:
[SYSTEM+]<program name>
This command will execute the specified <program name>. This can be
useful if you want to launch a program when a specific table is updated.
The full program name must appear after the command unless it exists in
the path. To exit the HPE Shadowbase process if <program name> fails,
set SHAD_DBS_SYSTEM_STOP to 1. To start <program name> with a
column’s value as a parameter, set SHAD_SYSTEM_PARM_COL to the
column name.
[SYSTEM++] Command
[SYSTEM++]<program name>
This command functions in the same manner as the [SYSTEM+] command,
however, it
is not executed until ALL other DBS map command tasks have been performed
(the
SYSTEM+ command is executed before all other DBS map command tasks have
been
performed). It can be thought of as a 'post' transformation version of [SYSTEM+].
This command will execute the specified <program name>. This can be useful if
you
want to launch a program when a specific table is updated. The full program
name must
appear after the command unless it exists in the path. To exit the HPE
Shadowbase process if
<program name> fails, set SHAD_DBS_SYSTEM_STOP to 1. To start the
<program
name> with a column’s value as a parameter, set SHAD_SYSTEM_PARM_COL
to the
HPE Shadowbase Programming Manual—785431-007
256
Data Mapping
Step #3: Configuring HPE Shadowbase for Use of the shaddbs.ini File
column name.
Either the SYSTEM+ or the SYSTEM++ command will be executed, but not both.
Step #3: Configuring HPE Shadowbase for
Use of the shaddbs.ini File
Once you have scripted your shaddbs data mapping file, you need to
configure HPE Shadowbase to use the shaddbs file.
Invoking the shaddbs File
In the Other Servers environment, you need to set the following
parameter in the shadparm.ini file:
SHAD_USRX_PROCESSING=1
By setting this parameter value to 1 it turns on the mapping processing. If
it is set to 0, the mapping processing is turned off. The default is off. So,
be sure you have this parameter set correctly in your shadparm.ini file.
See the HPE Shadowbase Other Servers Operations Manual for details
on the SHAD_USRX_PROCESSING parameter.
WARNING: Only set the SHAD_USRX_PROCESSING parameter for the
HPE Shadowbase Other Servers objects for which you want to
invoke the shaddbs.ini file (or are using user exits). Do this by
putting the SHAD_USRX_PROCESSING parameter into the
specific section(s) for the object that you want to use the
shaddbs.ini file. Adding this parameter to the [GENERAL]
section would cause the data mapping to be invoked for every
HPE Shadowbase Other Servers object that you have
configured, producing a lot of overhead.
For example if you want to invoke data mapping or user exits for 2 Other
Servers objects, MYCL1 and MYCL2, then add the following lines to the
shadparm.ini file:
[MYCL1]
SHAD_USRX_PROCESSING=1
[MYCL2]
SHAD_USRX_PROCESSING=1
HPE Shadowbase Programming Manual—785431-007
257
Data Mapping
Step #3: Configuring HPE Shadowbase for Use of the shaddbs.ini File
In the NonStop environment you need to define your DBS with a
USEREXITID set greater than zero. Not setting a USEREXITID or setting
the USEREXITID to 0 will turn the mapping processing off.
Setting the Location of the shaddbs File
In the Other Servers environment, by default, the shaddbs file is located
in the Other Servers data directory or the SHAD_LOCAL_CONTEXT
directory, if specified. The SHAD_DBSINI_NAME parameter enables
processes on one node to have more than one DBS mapping file. Set this
parameter to the name of the DBS mapping file that you want to use
(instead of shaddbs.ini). Fully qualify the file name below the HPE
Shadowbase data directory.
For example, if your HPE Shadowbase data directory is
C:\Shadowbase\v3940\data and the DBS mapping file that you want to
use is “mydbs.ini” located in the CONS data directory
(C:\Shadowbase\v3940\data\CONS\mydbs.ini), then set this parameter to
CONS\mydbs.ini.
See the HPE Shadowbase Other Servers Operations Manual for details
on the SHAD_DBSINI_NAME parameter. To set this parameter add the
following line to the appropriate section ([GENERAL] or [<object name>])
of the shadparm.ini file.
SHAD_DBSINI_NAME=<filename below Shadowbase data directory>
In the NonStop environment, the shaddbs file is created by the user and
its location is specified by a DEFINE. Add the DEFINE before starting
Shadowbase by entering the following from TACL:
ADD DEFINE =SBUSRXINI-<consumer_name>, CLASS MAP, FILE <shaddbs_file_name>
where <consumer_name> is the name of your Consumer and
<shaddbs_file_name> is the full path name of your shaddbs file.
Configuring for the [SYSTEM+] Command
The parameters listed below can be used in conjunction with the
[SYSTEM+] command to further customize your shaddbs script.
SHAD_DBS_SYSTEM_STOP
HPE Shadowbase Programming Manual—785431-007
258
Data Mapping
Step #3: Configuring HPE Shadowbase for Use of the shaddbs.ini File
With the [SYSTEM+] command, a program can be defined to be executed
after each operation. By default, if the program fails, the HPE
Shadowbase process will log an error message and continue. Set the
SHAD_DBS_SYSTEM_STOP parameter to 1 to have the HPE
Shadowbase process will log an error message and exit. The default is 0.
In the Other Servers environment set the SHAD_ DBS_SYSTEM_STOP
parameter to 1 to enable this feature. See the HPE Shadowbase Other
Servers Parameter Reference Guide for details on the SHAD_
DBS_SYSTEM_STOP parameter.
SHAD_SYSTEM_PARM_COL
The [SYSTEM+] command can be customized to execute the program
specified with a parameter as defined by this parameter. Set the
SHAD_SYSTEM_PARM_COL parameter to a column name from the
source table. The program defined by the [SYSTEM+] command is
executed with the current value of <col name> as a parameter. If this
parameter is set to 0 or is unset, the defined program will execute without
a parameter. The default is 0.
In the Other Servers environment set the SHAD_SYSTEM_PARM_COL
parameter. See the HPE Shadowbase Other Servers Parameter
Reference Guide for details on the SHAD_SYSTEM_PARM_COL
parameter.
Enabling User Exit Diagnostics
User exit diagnostics can be turned on to help you debug your shaddbs
configuration file. When they are turned on, a lot of diagnostic data is sent
to the error log file. The default is 0 (off). Be sure this feature is set to off
when you do not need it because the logging of the diagnostic data will
slow down replication.
In the Other Servers environment set the SHAD_USRX_DIAGNOSTICS
parameter to 1 to turn on diagnostics. See the HPE Shadowbase Other
Servers Parameter Reference Guide for details on the
SHAD_USRX_DIAGNOSTICS parameter.
HPE Shadowbase Programming Manual—785431-007
259
Data Mapping
Step #4: Testing and Debugging the shaddbs.ini File
Step #4: Testing and Debugging the
shaddbs.ini File
Once you have scripted the shaddbs file and have configured HPE
Shadowbase for use with the shaddbs file, the shaddbs script must be
thoroughly tested. The tools and techniques described for testing and
debugging user exits in the Step #4: Configuring HPE Shadowbase Use
of the User Exit section of this manual can be applied to the testing and
debugging of the shaddbs script. See the Step #5: Testing and
Debugging the User Exit section for more details.
HPE Shadowbase Programming Manual—785431-007
260
Appendix A – User Exit Supporting Files
Step #4: Testing and Debugging the shaddbs.ini File
Appendix A – User Exit Supporting
Files
The following files are included with HPE NonStop Shadowbase to aid you
in preparing your user exit routines in the HPE NonStop environment.
BINDUSRX
TACL macro for binding non-native user exits into
Consumer.
LINKUSRX
TACL macro for binding native user exits into Consumer.
REJECTH
Contains definitions related to the reject file record
structure.
Note: That a COBOL version of REJECTH is not available at this
time.
USRXC
This is the C language shell for the four entry points and
default processing code for exception handling.
USRXCOB
COBOL language shell for the four entry points and
default processing code for exception handling.
USRXO
Non-native compiled objects for USRXC or USRXCOB.
You must compile to this object filename if you are using
the BINDUSRX macro.
USRXN
Native compiled objects for USRXC or USRXCOB. You
must compile to this object filename if you are using the
LINKUSRX macro.
USRXCOPY COBOL language source copybook file for certain record
descriptions (structures) used by the API functions.
USRXLIBH
C language include source file containing the API function
prototypes and structure definitions used by the API
functions.
USRXLIBO
API function object file. This is necessary for the COBOL
environment.
The following files are included with the HPE Shadowbase Other Servers
to aid you in preparing your user exit routines in the Other Servers
environment.
HPE Shadowbase Programming Manual—785431-007
261
Appendix A – User Exit Supporting Files
Step #4: Testing and Debugging the shaddbs.ini File
USRXOPEN.C This is the C language shell for the four entry points and
default processing code for exception handling.
USRXLIB.H C language include source file containing the API function
prototypes and structure definitions used by the API
functions.
Enhanced User Exit Processing
There has been a fundamental change in the User Exit Processing feature in
HPE Shadowbase Other Servers releases generated after v4040x. Prior to HPE
Shadowbase Other Servers v4050, User Exit Processing was achieved by userdefined and compiled object code that was then linked to one or more HPE
Shadowbase replication executable files, e.g., TRS, TFS, Direct Writer, etc. This
method is now obsolete and has been replaced by a dynamic link library method
(DLL). The dynamic link library method employs a separate DLL (Windows) or
shared library (UNIX/OSS) containing the user-defined code logic. Using a
dynamic library approach no longer requires static linking of the user-defined
code logic into HPE Shadowbase executable files. With dynamic libraries, HPE
Shadowbase replication objects acquire the user-defined code logic at run-time.
In prior versions of HPE Shadowbase Other Servers, each executable supporting
user-exit capability could implement its own unique User Exit functionality. With
the new dynamic library approach, each configured replication object supporting
user exit capability also has the ability to implement its own unique User Exit
functionality, with even more process granularity supported.
For example, prior to v4050, unique user-exit code would be generated and
linked to a particular executable; sbsywrtc (Cached SQL Statement TRS for Sybase)
for example. Any configured TRS using this executable (sbsywrtc) would then
implement this user-exit functionality when user-exit processing was enabled
(SHAD_USRX_PROCESSING=1). However, for HPE Shadowbase Other Servers
v4050, multiple Cached SQL Statement Sybase TRS’s may now be configured
whereby each instance can have its own unique User Exit functionality. This
capability is achieved via dynamic libraries where the unique User Exit
functionality is defined in and implemented by a particular dynamic library
module. In this way, multiple unique dynamic libraries can be produced for
simultaneous use.
The particularly configured replication objects choose their select dynamic library
at run-time via the shadparm.ini parameter SHAD_USRX_LIBARY_NAME.
SHAD_USRX_LIBRARY_NAME
The SHAD_USRX_LIBRARY_NAME parameter specifies the dynamic link or
shared library module containing the user-defined User Exit functionality to be
implemented. The parameter is specified in the shadparm.ini file under the
specific group-name of replication object for which the User Exit logic is
HPE Shadowbase Programming Manual—785431-007
262
Appendix A – User Exit Supporting Files
Step #4: Testing and Debugging the shaddbs.ini File
designed. Users are cautioned to take care in assigning this parameter.
Incorrect assignment can lead to database corruption.
This parameter takes an ASCII character string assignment representing the
name of an existing dynamic link or shared library module. No surrounding quote
characters are required and should be omitted. When the library module resides
in the bin directory (Windows) or lib directory (UNIX/OSS) of the HPE
Shadowbase installation, a fully qualified name is not required. If the library
module resides in a directory other than the bin directory (Windows) or lib
directory (UNIX/OSS) of the HPE Shadowbase installation, a fully qualified file
name is required.
SHAD_USRX_LIBRARY_NAME=<dynamic link or shared library name.extension>
Windows User Exit Development
For Windows releases, a Visual Studio 2005 Solution is included to aid in the
building of the DLL. In the event Visual Studio 2005 is not available, an NMAKE
makefile is also included to aid in the building of the DLL.
Linux/UNIX User Exit Development
For UNIX releases, an Eclipse project is included to aid in the building of the
shared library. In the event eclipse is not available, a GMAKE makefile is also
included to aid in the building of the shared library.
HPE NonStop Integrity OSS User Exit Development
For HPE NonStop Integrity OSS releases, an Eclipse-based NSDEE project is
included to aid in the building of the shared library. In the event Eclipse/NSDEE
is not available, a makefile, compatible with the make utility present in OSS, is
also included to aid in the building of the shared library.
HPE Shadowbase Programming Manual—785431-007
263
Appendix B – User Exit Samples
Overview
Appendix B – User Exit Samples
Overview
The SBUSRX collection of code contains COBOL and C sample source
code for various user exits. The collection also contains configurations
and file information for running these samples. The following list briefly
describes the available samples. The AAREADME, ABREADME,
TESTINFO and SAMPLE files in the collection contain additional pertinent
information. If you would like access to these user exit samples please
contact HPE Shadowbase Support.
COBOL Samples
There are eleven sets of COBOL sample source code and corresponding
HPE Shadowbase configuration files. Binder commands, DDL source,
and other user libraries are also included in the SBUSRX collection.
Samples for the following functions are available:
USRXCOB1
USRXCOB2
USRXCOB3
USRXCOB4
USRXCOB5
USRXCOB6
USRXCOB7
USRXCOB8
USRXCOB9
This user exit converts Enscribe dates to SQL
datetime format.
This user exit converts a fixed-length Enscribe
field to an SQL varchar type.
This user exit takes multiple occurrences of a
column in a row and writes them out as
multiple rows.
This user exit converts a relative record
number from Enscribe to a named column in
SQL.
This user exit examines an event record, and
based on the value of a field, ignores the event
(does not write to the target) or executes
(writes to the target).
This user exit converts an Enscribe pic
99v9999 comp to an SQL pic 9v99999
(decimal format).
This user exit examines a record image, and
based on the value of one field, either writes
the record to the designated target or notifies
HPE Shadowbase to write to a different target.
This user exit uses a USRXEXCEPTION
routine to correct an Enscribe to SQL data
incompatibility.
This user exit converts Enscribe to SQL Year
2000.
HPE Shadowbase Programming Manual—785431-007
264
Appendix B – User Exit Samples
C Samples
URXCOB10
URXCOB11
USRXUNDO
This user exit accesses an additional table for
column values to be "put" into the target.
This user exit replicates from SQL to Enscribe.
This user exit reverses events to their before
images allowing you to undo file damage. See
UNDODOC for more information.
C Samples
The C sample file, SAMUSRXC, located in the SBUSRX collection, can be
compiled, bound, and executed. What it does depends upon the
USEREXITID it is sent. See the SAMPLE file for more information.
USEREXITID
1
2
3
4
5, 10, 11, 12
6, 7, 8, 9
14, 15, 16
17
20
21
25
30
31
User Exit Functionality
Simple display of data (E2E)
Simple display of data (S2S)
Relative Enscribe file to key-sequenced
SQL table
Get Enscribe record and change one
field.
Records are sent to the appropriate
target based on the value of the
char_code field.
Normalize an Enscribe table with a field
that occurs 4 times. USEREXITID 8
also reads a value from another file
and "puts” that value into the column.
Normalize an SQL table with three
occurs. Userexit 14 writes the first
occur row, 15 the second and 16 writes
the third.
Using a target override and
SBPUTRECORD
Every supported data type is retrieved
and printed. Maximum and minimum
values are inserted and updated.
Every supported SQL data type is
retrieved and printed to a text file.
Maximum and minimum values are
inserted and updated. Date-times are
converted from internal SQL format to
external format for the text file.
Changing the relative address of a row
Sending only certain records
(char_code "MN") to an Other Servers.
Enscribe to Other Servers SQL target
with a target override
HPE Shadowbase Programming Manual—785431-007
265
Appendix B – User Exit Samples
C Samples
USEREXCEPTION
Look for certain error codes. Change
the data if it is the wrong type.
Remove the column if it is the wrong
type.
HPE Shadowbase Programming Manual—785431-007
266
Appendix B – User Exit Samples
C Samples
In addition to the C sample file, SAMUSRXC, the following C user exit
examples are also present in the SBUSRX collection:
USRXC1
A user exit that converts Enscribe dates to SQL datetime
format. This is similar to the COBOL USRXCOB1 described
above.
USRXC2
A user exit that converts a fixed-length Enscribe field to an
SQL varchar type. This is similar to the USRXCOB2
described above.
USRXC5
A user exit that examines an event record and, based on the
value of a field, either ignores (does not write to the target)
or executes (writes to the target) the event. This is similar to
USRXCOB5.
USRXCAA
A user exit that queries a third table for a value that is then
"put" into the target table (a column that does not exist in the
source table).
USRXCBB
This user exit demonstrates how data values can be
replicated when the target column name is NOT the same as
the source column name. In this particular example, the
column is a key column and requires a few more API calls
than a non-key column.
CONSUMEC This user exit demonstrates the consumptive capability of
the Consumer by simply executing SBSETIGNORE, thereby
ignoring every event that gets processed by the user exit.
HPE Shadowbase Programming Manual—785431-007
267
Appendix C – Data Mapping Examples
Other Servers Mapping Command File (shaddbs.ini) Example
Appendix C – Data Mapping
Examples
Other Servers Mapping Command File
(shaddbs.ini) Example
The following sample shaddbs file demonstrates a number of mapping
functions.
HPE Shadowbase Programming Manual—785431-007
268
Appendix C – Data Mapping Examples
NonStop Mapping Command File (shaddbs) Example
#Gravic, Inc. Shadowbase 5/1/2000
#This is a sample shaddbs.ini file. It should be located in
#the SHAD_BASE\data directory or the SHAD_LOCAL_CONTEXT
#directory if it is defined.
#The following mapping commands apply to all events for
#KEYTABL
[DBS+]KEYTABL
#For test purposes, the events need to go into KEYTABL1234
#instead of the production KEYTABL
[NAME+]KEYTABL1234
#this command executes the CALC program
[SYSTEM+]calc.exe
#Drop all events so they’re not written to the database.
#This is for debugging.
#Comment out once code is debugged.
[OP-]*
#Drop all deletes so they’re not applied to the database.
#Care should be taken when dropping statements as it can cause database
#inconsistency.
[OP-]D
#convert all updates to inserts for this table.
#used to load the table initially.
#[OP+]U=I
This can be
# example of a nullable field that can be dropped
[FLD-]C8NMAX
#the next one is indented. This command adds the C1CHNEW
#column and sets its value to ‘aabb’
[FLD+]C1CHNEW='aabb'
#add a new column that is 9000 higher than an existing
#column:
[FLD+]C0IKNEW=%C0IK%+9000
#this would drop a single column.
#[FLD-]C0IK
#However, the C01K column is in the where clause so we drop
#the where clause
[WHERECLAUSE-]
#add a new where clause
[FLD++]C0IKNEW
#Reset an existing column to a value of 999
[FLD+]C6SI=999
NonStop Mapping Command File (shaddbs)
Example
The following sample shaddbs file can be created in the HPE NonStop
environment.
HPE Shadowbase Programming Manual—785431-007
269
Appendix C – Data Mapping Examples
Converting DELETES to Logical DELETES
#The following mapping commands apply to all events for
#KEYTABL associated with the DBS with USEREXITID 1.
[DBS+]1:*:KEYTABL
#For test purposes, the events need to go into KEYTABL1234
#instead of the production KEYTABL
[NAME+]KEYTABL1234
#this command executes the CALC program
[SYSTEM+]calc.exe
#Drop all events so they’re not written to the database.
#This is for debugging. Comment out once code is debugged.
[OP-]*
#Drop all deletes so they’re not applied to the database. Care should be taken
#when dropping statements as it can cause database inconsistency.
[OP-]D
#convert all updates to inserts for this table.
#table initially.
#[OP+]U=I
This can be used to load the
# example of a nullable field that can be dropped
[FLD-]C8NMAX
#the next one is indented. This command adds the C1CHNEW column and sets its
#value to “aabb” it pads the new value with spaces, so that the new value
#equals the new column’s size
[FLD+]C1CHNEW=”aabb
“
#add a new column that is equal to an existing column:
[FLD+]C0IKNEW=%C0IK%
#this would drop a single column.
#[FLD-]C0IK
#However, the C01K column is in the where clause so we drop the where clause
[WHERECLAUSE-]
#add a new where clause
[FLD++]C0IKNEW
#Create a new datetime column for the old one (example)
#[FLD+]C32DTNEW=”%C32DT%”
[FLD+]C32DT=”12-13-99 06:05:04”
[FLD+]C32DTNEW=”12-13-99 06:05:04”
#Construct an involved column
[FLD+]C5VCNEW=”data%C5VC%moredata, percent sign : %% the end”
#need to put and get all columns that weren’t changed because
#the target table was overridden with the [NAME+] command
[FLD+]C6SI=%C6SI%
[FLD-]C6SI
[FLD+]C11I=%C11I%
[FLD-]C11I
[FLD+]C12I=%C12I%
[FLD-]C12I
Converting DELETES to Logical DELETES
If you want to take DELETES from the source and instead of deleting the
row in your target, you wish to set a flag to show that the record was
HPE Shadowbase Programming Manual—785431-007
270
Appendix C – Data Mapping Examples
Preventing a Table from Being Replicated
deleted. To do this, turn the DELETES into UPDATES and then change
the flag. The steps below detail how to achieve this:
1. Add a column called DELETED, that was not present on the source
table, to the target table.
2. Configure the HPE Shadowbase object to use the shaddbs file. In the
NonStop environment set the DBS USEREXITID parameter to some
value greater than 1. In the Other Servers environment set the
SHAD_USRX_PROCESSING parameter to 1 in the shadparm.ini file
under the section/group heading corresponding to the Transaction
Replay Server or Direct Writer performing the target side data
application.
3. Configure the shaddbs file, by adding the commands below to the file.
In the Other Servers environment the syntax is:
[DBS+]D:MYTABLE
[OP+]D=U
[FLD+]DELETED='yes'
In the HPE NonStop environment the syntax is:
[DBS+]1:D:MYTABLE
[OP+]D=U
[FLD+]DELETED='yes'
Now, when a row is deleted from the source table, the row on the target
table will NOT be deleted. Instead, for the affected row, the target table’s
DELETED column will be changed from ‘no’ to ‘yes’.




The [DBS+]D:MYTABLE line indicates that this shaddbs script will be
used for all DELETE operations (D) on the table, MYTABLE.
The [DBS+]1:D:MYTABLE line indicates that this shaddbs script will
be used for the DBS specification with USEREXITID 1 for all DELETE
operations (D) on the table, MYTABLE.
The [OP+]D=U line indicates that all DELETE operations (D) will be
converted to UPDATES (U).
The [FLD+]DELETED=’yes’ line indicates that the DELETED column
will be added with a value of ‘yes’.
Preventing a Table from Being Replicated
If you want to prevent a specific table from being replicated from your
source environment to your target environment, configure the following
shaddbs file commands. In the Other Servers environment the syntax is:
HPE Shadowbase Programming Manual—785431-007
271
Appendix C – Data Mapping Examples
Converting Date Based on CASE
[DBS+]MYTABLE
[OP-]*
In the NonStop environment the syntax is:
[DBS+]1:MYTABLE
[OP-]*



The [DBS+]MYTABLE line indicates that this shaddbs script will be
used for all operations on the table, MYTABLE.
The [DBS+]1:MYTABLE line indicates that this shaddbs script will be
used for the DBS specification with USEREXITID 1 for all operations
on the table, MYTABLE.
The [OP-]* line indicates that all operations (*) will be dropped from
replication.
Converting Date Based on CASE
The following example converts the value of a column, DATE, based on
the original value of the column. If the original value of the DATE column
is ‘NULL’, then the value is converted to NULL. If the original value of the
DATE column is not ‘NULL’, then the value is converted to the first 10
characters of the original DATE column. The [FLD+] command can be
used in conjunction with any valid SQL expression to convert the value of
a column. Here, the SQL CASE and SUBSTRING functions are used to
convert the DATE column to a new value. The example below is valid for
Other Servers environment. Any SQL function used with the [FLD+]
command must be supported by the target DBMS.
Note: SQL functions (all) are not supported in dynamic SQL
statements by all RDBMS supported by HPE Shadowbase. This
aspect then prohibits the use of SQL function(s) in HPE
Shadowbase Data Mapping Facility commands when using the
Cached SQL statement form of DOC/TRS and or Direct Writer.
To convert the DATE column based on the original value enter the
shaddbs script below:
[DBS+]MYTABLE
[FLD+]DATE=CASE'%DATE%' WHEN 'NULL' THEN NULL ELSE SUBSTRING('%DATE%',1,10) END

The [DBS+]MYTABLE line indicates that this shaddbs script will be
used for all operations on the table, MYTABLE.
HPE Shadowbase Programming Manual—785431-007
272
Appendix C – Data Mapping Examples
Converting Date Based on CASE

The [FLD+]DATE=CASE'%DATE%' WHEN 'NULL' THEN NULL
ELSE SUBSTRING('%DATE%',1,10) END line indicates that the
DATE column will be converted from its original value to a new value
based on its original value via the CASE expression. If the original
value (%DATE%) was ‘NULL’, then it will be converted to NULL. If
the original value (%DATE%) was not ‘NULL’, then it will be converted
to the first 10 characters of the original value (%DATE%) via the
SUBSTRING expression.
HPE Shadowbase Programming Manual—785431-007
273
Appendix D – Eliminating Need to Recompile COBOL User Exits
Description of Procedure
Appendix D – Eliminating Need to
Recompile COBOL User Exits
Prior to the 4.090 release, clients using the sample COBOL user exit libraries shipped
with each release as a basis for their user exits had to recompile the library with each
new release. The samples, as shipped, bind the module that interfaces the user exit
code to core HPE Shadowbase (USRXLIBO or USRXLIBN) into the library during
compilation. This module changes from release to release; hence, the library must be
recompiled for each HPE Shadowbase release.
However, by modifying the COBOL library, clients can change the compilation process
so that the USRXLIBO or USRXLIBN module is not bound into the library, eliminating
the need to recompile for each release. Instead, the compiled library will just have to be
rebound with a new Consumer, much like the C based user exits. This can be
accomplished by using a ?CONSULT directive instead of the FILE USRXLIBx IS
USRXLIB statement. The ?CONSULT directive allows functions from the specified file
to be used without binding in the file; the FILE statement causes the file to bind.
A further discussion is appropriate to explain the difference between CONSULT and
SEARCH.
When a client compiles a COBOL program (a user exit) that uses external functions, the
COBOL compiler needs to understand the calling sequence for the external function.
There are two methods, CONSULT and SEARCH, both of which reference an object
code module (for the external functions). CONSULT just extracts the calling sequence
from the object file, SEARCH extracts the calling sequence and copies the function to
user exit object file.
For example, suppose the client is running HPE Shadowbase at v4090 and has
compiled their user exit code with the SEARCH directive. The generated object file for
the user exit contains the object for the v4090 functions that the user exit invokes. When
the user exit object file is then bound with the v4090 consumer, the user exit and the
consumer both contain the same version of the functions. Once the client upgrades to
v4092, the user exit object file contains code that is incompatible: the v4090 library.
Therefore, they must recompile against v4092 to include the correct HPE Shadowbase
object code.
If the client compiled the user exit using CONSULT, the SB functions are flagged as
external and are not included in the object. When the library is bound with the v4090
consumer, the external references are resolved using the code already bound into the
consumer. As long as the calling sequences for the SB functions remain backwards
compatible, the same happens when you bind the user exit object file into the V4092
consumer - the external references are resolved with the correct version (v4092) of the
library. No recompilation is necessary.
Description of Procedure
HPE Shadowbase Programming Manual—785431-007
274
Appendix D – Eliminating Need to Recompile COBOL User Exits
Description of Procedure
There are three steps to modifying the COBOL user exit library to eliminate the need for
recompilation:
Add a CONSULT directive, specifying the USRXLIBO (non-native) or USRXLIBN
(native) file to be used. The CONSULT directive can either be specified in the beginning
of the Cobol source file, or on the compile line (for example, COBOL85 /in
mylibsrc/mylibobj;CONSULT USRXLIBO).
Delete all instances of the
FILE “USRXLIBO” IS USRXLIB. (non-native)
or
FILE “USRXLIBN” IS USRXLIB. (native)
statements in the source code. These statements cause the USRXLIBx file to bind into
the compiled object file.
Change all instances of the calls (typically invoked by ENTER C … ) to the HPE
Shadowbase user exit functions, removing the IN USRXLIB clause. This will cause the
COBOL compiler to search the file specified by CONSULT directive. For example, the
statement:
ENTER C “SBSETEXCEPTIONCODES” IN USRXLIB
USING MAX-TRIES, NUM-ERR, USR-ERR-LIST.
becomes
ENTER C “SBSETEXCEPTIONCODES”
USING MAX-TRIES, NUM-ERR, USR-ERR-LIST.
After these changes are made, the user exit library should be recompiled one last time.
The steps for binding the user exit library to the Consumer remain the same.
Below is the USRXCO.cob sample file, modified to use the ?CONSULT directive:
************* Shadowbase-User Exits API Functions in COBOL **************
*-----------------------------------------------------------------------*
*
PROGRAM DESCRIPTION
*
*-----------------------------------------------------------------------*
*
*
* This source file contains skeleton code for the user exit functions *
* written in COBOL. The programs are: USRXSTART, USRXPROCESS,
*
* USRXEXCEPTION, USRXEXCEPTIONINIT, USRXINIT, and USRXROLL.
*
*
*
*-----------------------------------------------------------------------*
*
SPECIAL CONSIDERATIONS
*
*-----------------------------------------------------------------------*
* Use great care not to overwrite any of the parameter values. This
*
* could cause unpredictable results in the base Consumer.
*
*-----------------------------------------------------------------------*
*-----------------------------------------------------------------------*
*
REVISION HISTORY
*
HPE Shadowbase Programming Manual—785431-007
275
Appendix D – Eliminating Need to Recompile COBOL User Exits
Description of Procedure
*-----------------------------------------------------------------------*
* 2.000 | ITI
| 02/20/96 | Initial release
*
*-----------------------------------------------------------------------*
* 2.200 | ITI
| 09/12/96 | Added USRXINIT function. This is
*
*
|
|
| called by Shadowbase for user exits.
*
*
|
|
| It can be used to perform some sort of *
*
|
|
| initialization.
*
*
|
|
|
*
*
|
|
| Added USRXROLL function. It is called *
*
|
|
| by Shadowbase if a NEXTODOC command is *
*
|
|
| entered or when using the automatic
*
*
|
|
| cut over feature by configuring the
*
*
|
|
| NEXTODOCTRIGGER and NEXTODOCTIME
*
*
|
|
| parameters. Note that it is only
*
*
|
|
| called for Consumers configured with
*
*
|
|
| a CONNECTIONTYPE set to DIRECTDOC.
*
*-----------------------------------------------------------------------*
?symbols; inspect; saveabend; env common
?highpin; highrequesters
*
* Note: use ?consult usrxlibn for native mode compilation, use
*
?consult usrxlibo for non-native compilation.
*
*?consult usrxlibn
?consult usrxlibo
*
* ?sql
*
***** ADD THIS BACK IN IF YOU NEED SQL
IDENTIFICATION DIVISION.
PROGRAM-ID. USRXINIT.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. TANDEM.
OBJECT-COMPUTER. TANDEM.
SPECIAL-NAMES.
* DELETED: FILE “USRXLIBO” IS USRXLIB.
DATA DIVISION.
WORKING-STORAGE SECTION.
LINKAGE SECTION.
PROCEDURE DIVISION.
0000-EXCEPTION.
EXIT PROGRAM.
END PROGRAM USRXINIT.
*************************************************************************
IDENTIFICATION DIVISION.
PROGRAM-ID. USRXEXCEPTIONINIT.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. TANDEM.
OBJECT-COMPUTER. TANDEM.
SPECIAL-NAMES.
* DELETED: FILE “USRXLIBO” IS USRXLIB.
DATA DIVISION.
HPE Shadowbase Programming Manual—785431-007
276
Appendix D – Eliminating Need to Recompile COBOL User Exits
Description of Procedure
WORKING-STORAGE SECTION.
01 MAX-TRIES
01 NUM-ERR
01 USR-ERR-LIST.
05 ERR-1.
10 LOW-RANGE-VAL
10 HIGH-RANGE-VAL
05 ERR-2.
10 LOW-RANGE-VAL
10 HIGH-RANGE-VAL
05 ERR-3.
10 LOW-RANGE-VAL
10 HIGH-RANGE-VAL
05 ERR-4.
10 LOW-RANGE-VAL
10 HIGH-RANGE-VAL
05 ERR-5.
10 LOW-RANGE-VAL
10 HIGH-RANGE-VAL
PIC S9(4) COMP VALUE 10.
PIC S9(4) COMP VALUE 5.
PIC S9(4) COMP VALUE 8401.
PIC S9(4) COMP VALUE 8401.
PIC S9(4) COMP VALUE 8405.
PIC S9(4) COMP VALUE 8406.
PIC S9(4) COMP VALUE 8410.
PIC S9(4) COMP VALUE 8412.
PIC S9(4) COMP VALUE 8417.
PIC S9(4) COMP VALUE 8418.
PIC S9(4) COMP VALUE 8423.
PIC S9(4) COMP VALUE 8428.
LINKAGE SECTION.
PROCEDURE DIVISION.
0000-START.
********* CALL SBSETEXCEPTIONCODES HERE IF YOU HAVE SQL DATA EXCEPTIONS *******
* THE FOLLOWING CODE ESTABLISHES THE SQLCODE(S) THAT WILL CAUSE SHADOWBASE
* TO CALL USRXEXCEPTION IF ONE OF THESE ERRORS OCCURS. THIS SAMPLE ESTABLISHES
* ERROR SETTINGS FOR THOSE SQL ERRORS THAT CAUSE DATA EXCEPTION TYPE ERRORS.
* ADDITIONALLY, THE MAXIMUM NUMBER OF SQL ERRORS ON RETRIES FOR THIS TYPE OF
* PROBLEM IS SET HERE. THE DEFAULT IS 10.
* NOTE: THE SUPPLIED CODES SHOULD BE POSITIVE VALUES FOR THE SQL ERROR CODES.
ENTER C "SBSETEXCEPTIONCODES"
USING MAX-TRIES, NUM-ERR, USR-ERR-LIST.
EXIT PROGRAM.
END PROGRAM USRXEXCEPTIONINIT.
*************************************************************************
IDENTIFICATION DIVISION.
PROGRAM-ID. USRXSTART.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. TANDEM.
OBJECT-COMPUTER. TANDEM.
SPECIAL-NAMES.
* DELETED: FILE “USRXLIBO” IS USRXLIB.
DATA DIVISION.
WORKING-STORAGE SECTION.
LINKAGE SECTION.
PROCEDURE DIVISION.
0000-START.
EXIT PROGRAM.
END PROGRAM USRXSTART.
*************************************************************************
HPE Shadowbase Programming Manual—785431-007
277
Appendix D – Eliminating Need to Recompile COBOL User Exits
Description of Procedure
IDENTIFICATION DIVISION.
PROGRAM-ID. USRXPROCESS.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. TANDEM.
OBJECT-COMPUTER. TANDEM.
SPECIAL-NAMES.
* DELETED: FILE “USRXLIBO” IS USRXLIB.
DATA DIVISION.
WORKING-STORAGE SECTION.
LINKAGE SECTION.
PROCEDURE DIVISION.
0000-PROCESS.
9999-EXIT-PROGRAM.
EXIT PROGRAM.
END PROGRAM USRXPROCESS.
*************************************************************************
IDENTIFICATION DIVISION.
PROGRAM-ID. USRXEXCEPTION.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. TANDEM.
OBJECT-COMPUTER. TANDEM.
SPECIAL-NAMES.
* DELETED: FILE “USRXLIBO” IS USRXLIB.
DATA DIVISION.
WORKING-STORAGE SECTION.
LINKAGE SECTION.
PROCEDURE DIVISION.
0000-EXCEPTION.
EXIT PROGRAM.
END PROGRAM USRXEXCEPTION.
*************************************************************************
IDENTIFICATION DIVISION.
PROGRAM-ID. USRXROLL.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. TANDEM.
OBJECT-COMPUTER. TANDEM.
SPECIAL-NAMES.
* DELETED: FILE “USRXLIBO” IS USRXLIB.
DATA DIVISION.
WORKING-STORAGE SECTION.
LINKAGE SECTION.
PROCEDURE DIVISION.
0000-EXCEPTION.
EXIT PROGRAM.
HPE Shadowbase Programming Manual—785431-007
278
Appendix D – Eliminating Need to Recompile COBOL User Exits
Description of Procedure
END PROGRAM USRXROLL
HPE Shadowbase Programming Manual—785431-007
279
Appendix E – Enscribe QUEUE file Processing
Enscribe QUEUE File Background
Appendix E – Enscribe QUEUE file
Processing
Enscribe QUEUE File Background
Enscribe QUEUE files are a special type of key-sequenced Enscribe file. There
is considerable information available in the HPE NonStop Enscribe
Programmer’s Guide regarding QUEUE files. Also review the HPE NonStop File
Utility Program (FUP) documentation. The reader should review this information
for specific details.
Enscribe QUEUE files do not support alternate keys, and do not support
secondary partitions. Hence, there is only a base file primary partition allowed
for this file type. This is important, as it means there is one DP2 process
controlling all inserts, updates, and deletes into this special file type.
The primary feature of the QUEUE file is to provide a first-in-first-out (FIFO)
enqueing and dequeing mechanism. However, QUEUE files support other
features that allow them to be used to implement other queueing algorithms,
such as last-in-first-out (LIFO), priority-driven queueing, as well as custom
algorithms based on what a user needs. These features will be reviewed below.
The primary key in a QUEUE file defaults to an 8-byte Julian timestamp (called
JTS below) that is guaranteed to be unique on insert. This is part of the reason
why only one DP2 process is allowed to manage a single QUEUE file. The JTS
is also guaranteed to be increasing on insert. Because the key is increasing (by
default), this means that new entries are added to the end of the queue, and the
lowest key value is the ‘oldest’ (first) entry inserted into the queue.
The user can alter the default ordering by placing additional key fields in front of
the QUEUE file JTS. These key fields are filled in by the application before
insert. The JTS is always filled in by the DP2 disk process and requires 8 bytes
for it at the end of the other key fields. Hence, the application can add, for
example, a PRIORITY field, setting it appropriately (0 for critical on up to LARGE
INTEGER for minor). This approach then creates a priority driven queue
structure when viewing the queue from the lowest key value on up.
An application can either read destructively (called a dequeue operation) or read
in inquiry mode (a ‘read-only’ read). Dequeue operations perform a delete of the
record being dequeued. Read-only inquiry reads simply return a copy of the
record at that position without affecting the queue.
The DP2 disk process managing the QUEUE file also supports some special file
processing features, very useful when there are many queue reading operations
going on at the same time. For instance, a queue reader process can request
the first “unlocked” entry on the queue, and the DP2 process will scan the key
path (from the starting position, typically set by a setposition call), looking for a
record that is not currently locked/being processed by another queue reader
HPE Shadowbase Programming Manual—785431-007
280
Appendix E – Enscribe QUEUE file Processing
Enscribe QUEUE File Background
application. If a record is found, the DP2 disk process will lock it and return it to
the queue reader. If no such record exists, DP2 can defer this request waiting for
a new queue entry to be inserted, and then satisfy the queue read with that entry.
This enables rather efficient publish/subscribe application architectures to be
built. Refer to the HPE documentation for more details on these features.
A few more comments are helpful – to implement a FIFO queue, use the default
key value (JTS) and issue your read/dequeue operations at the beginning of the
QUEUE file , i.e. the lowest key value. To implement a LIFO queue always
read/dequeue at the end of the QUEUE file, i.e. the highest key value (via a read
reverse operation on the primary key. Other custom algorithms are available by
reading along the primary key to arbitrary positions.
Extending this thought, if the user prepends fields to the key, they can implement
custom queuing algorithms by setting these fields in insert (enqueue operations),
and positioning then dequeuing (reading/deleting) using this key fields later on.
This supports, for example, both priority queues (as described above) and
queues that can support multiple topics.
HPE Shadowbase Programming Manual—785431-007
281
Appendix E – Enscribe QUEUE file Processing
Shadowbase Support for Enscribe QUEUE Files
Shadowbase Support for Enscribe QUEUE
Files
Effective with release NSB6220, support for Enscribe QUEUE files is now
performed with the AUDCONSQ target consumer object. Please refer to the
following section in this manual Appendix F – Enscribe QUEUE File Support
Using a Keyed Or Queue File Target (AUDCONSQ) for specifics on how to utilize
this functionality.
HPE Shadowbase Programming Manual—785431-007
282
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
Introduction
Appendix F – Enscribe QUEUE File
Support Using a Keyed Or Queue File
Target (AUDCONSQ)
Introduction
Enscribe queue files (“queue files”) are special key-sequenced files used by
processes to enqueue and dequeue records. One feature of queue files that sets
them apart from standard key-sequenced files is that the primary key has a
system generated 8-byte Julian timestamp appended onto the end of the primary
key definition. The Julian timestamp can be the only field in the key, or appended
onto a key definition the user specifies.
Another feature of queue files is that records can only be inserted, read for
delete, or read for browse (non-delete read). There is no mechanism to update a
record in a queue file.
Enscribe queue files consist of a single base file “primary” partition, and they do
not support alternate keys. This makes it possible for one disk process to
manage all queue file access, an important feature for making sure that the
assigned Julian timestamp is unique and an always increasing/ascending value
during inserts (enqueue operations).
Generally, queue files pose replication a problem because user processes
cannot assign a value for the Julian timestamp in the primary key during an
insert. This prevents HP Shadowbase replication from replicating inserted queue
file records exactly to a real queue file target, as the source timestamp in the key
field cannot be set to the same value on the target, rather the disk process on the
target will assign the target record’s Julian timestamp. This means that the keys
on the target cannot be made to match the keys from the source.
That being said, with one method of queue file replication using the provided
AUDCONSQ Consumer, the target file will be a normal key-sequenced file (the
queue file attribute is not set). This allows the Consumer core engine to maintain
the exact key value between the source and target files when processing inserts
and deletes. In the event of a fail-over situation to the backup node, these keysequenced files will need to be turned into queue files before use by application
programs. This is accomplished by running the Shadowbase SBQFILE utility.
See the “Queue File Replication with SBQFILE” section of the HPE NonStop
Shadowbase Installation and Planning Manual for more specific operating
information about SBQFILE.
With another method of queue file replication using the provided AUDCONSQ,
the target file will be a real queue file. In this method, a mapping file is utilized to
provide a link between the source key and the target key for purposes of
HPE Shadowbase Programming Manual—785431-007
283
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
AUDCONSQ User Exit Processing
processing deletes. It is not necessary to run the SBQFILE utility during a failover to the backup node.
As with prior implementations of queue file replication (i.e. as documented in
Appendix E previously), a user exit is provided in the AUDCONSQ object to
generate a mapping file, as this may be necessary for application environments
that already make use of such a file as part of access logic to a queue file. When
the target file is a key-sequenced file, the source and target key values recorded
in a mapping file record will be the same value. When the target file is a real
queue file, the mapping file will contain the primary key value for the source
queue file record and the primary key value for the related target queue file
record.
Note that the scope of this queue file replication and mapping file generation is
for audited uni-directional replication only. Expand is required. Contact
Shadowbase Support if bi-directional support is required for queue files.
Special Note: Hard-resetting the NonStop system clock backwards in time
can be problematic for many NonStop subsystems, including TMF, the disk
processes, the file system, and Shadowbase’s replication to a queue file
target. In almost all cases, the system clock should only be “drifted”
forwards or backwards and not “hard reset” to a particular time unless the
application and replication are quiesced. The algorithm used by
Shadowbase’s AUDCONSQ relies on an ascending system-assigned
(SYSKEY) key value in a queue file target. The basis for this key value,
assigned by the operating system disk process, is the system clock in the
corresponding cpu where the disk process for that file is located. The file
system does not appear to provide a means via a system function call to
directly obtain the last inserted record key value. Thus, after inserting a
record, the AUDCONSQ will read the target queue file in reverse via the
primary key path to find the last inserted record in order to capture the
value in the related mapping file record (to cross reference the source and
target keys). Should you hard-reset the clock backwards in time, it is
advisable to shut down Shadowbase replication (and most likely your
applications) prior to the adjustment and then wait to restart Shadowbase
until the clock is subsequently beyond the time when the clock was reset.
Otherwise, it is advisable to reload the target before continuing replication
processing. This can be accomplished by shutting down Shadowbase,
doing a FUP purge of the target queue file and mapping file for those that
are still active in replication, and then restart Shadowbase. Or, for those
that are no longer active in replication, do a FUP PURGE and DUP from the
source queue file to the target queue file.
AUDCONSQ User Exit Processing
AUDCONSQ contains a user exit for the base queue file processing (DBS
USEREXITID 1 or 11) and another user exit for the mapping file processing (DBS
USEREXITID 2 or 22). Two DBS objects will be used: one to define the source
HPE Shadowbase Programming Manual—785431-007
284
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
AUDCONSQ User Exit Processing
queue file to target file definition, the other to define the source queue file to
mapping file definition. USEREXITID’s 1 and 2 are used when you want the
target base file to be a key-sequenced file. USEREXITID’s 11 and 22 are used
when you want the target base file to be a real queue file. The following
commands are used to define the user exit for the DBS objects:
SET DBS USEREXITID 1 [for the base file DBS object]
SET DBS USEREXITID 2 [for the mapping file DBS object]
or
SET DBS USEREXITID 11 [for the base file DBS object]
SET DBS USEREXITID 22 [for the mapping file DBS object]
Following startup when the first DDL or DML event is received, the user exit code
will correlate the queue file with the mapping file as necessary for creation and
verification/(re)load of the target key-sequenced file and the mapping file.
Following startup, during replication, the user exit code will process DDL and
DML for the queue file, resulting in these operations being applied to the target
key-sequenced file or target queue file and the mapping file. Create events are
disregarded, as the base target file and mapping file are created during the
startup sequence as needed.
For Shadowbase to process queue file events, the following DBS parameter
must be defined for both the base file and mapping file DBS objects:
SET DBS ALLOWQUEUEFILE ON
As with a typical Shadowbase environment, DDL processing is optional and is
enabled via DBS parameters. With the exception of the target and mapping file
create’s (which are automatic as discussed above), this is also the case with the
AUDCONSQ environment. The following are used to enable DDL processing:
SET DBS ALTERS ON
SET DBS CREATES ON [for documentation purposes only here
SET DBS PURGES ON
SET DBS PURGEDATAS ON
When the target file is created, it is created using the same attributes as the
source file. However, the queuefile attribute is not enabled for a target keysequenced file, but is enabled for a real target queue file. The mapping file is
created with similar key structure as the source file and using the source file
extents and block size definition, unless overridden by setting the extent size or
block size in the USEREXITPARAM as discussed below. For alter events, as is
the case with a typical Shadowbase environment, the following attribute changes
are replicated: maxextents, audit on/off, buffered/write-thru-cache, and
auditcompress on/off.
Wild-carded source queue file names (e.g. “$VOL.SUBVOL.QFILE*”) are
supported by the Shadowbase DBS configuration. Wild-carded target file names
are supported as well (e.g. $vol.subvol.*, * meaning use the source file name in
this place). This applies to the target file as well as the mapping file. The startup
sequence (when the first event is received) will verify that the TARGETFILE
setting uses a similar construct for both DBS objects. That is, if a fully-qualified
file name is configured for the mapping file TARGETFILE, a wild-carded
HPE Shadowbase Programming Manual—785431-007
285
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
AUDCONSQ User Exit Processing
TARGETFILE is not permitted for the key-sequenced target file for the other DBS
object and vice versa. Fully-qualified file names are supported as well.
The DBS USEREXITPARAM parameter is used to optionally define the mapping
file extents and block size. It is also used to provide a keywords that define the
startup correlation logic to be used. The value for USEREXITPARAM must be
defined in parenthesis “( )”. It contains the “QMAP=” keyword followed by the
override definitions separated by “/”. Note that white space (blank characters) is
not allowed. For example: (QMAP=<100,100,50>/4096/NEVER/EXTCHECKS).
The following are the optional parameters (any of the parameters can be used
and in any order):
 Extents String – This parameter specifies the file extents for the target
mapping file. If not suppled, the source queue file’s extent sizes are used.
The format is: <primary-extent-size,secondary-extent-size,maximumextents>.
 Block Size – This parameter specifies the file block size for the target
mapping file. It is entered as a number. If not suppled, the source queue
file’s block size is used.
 Extending Checking – The EXTCHECKS keyword will cause the
Consumer to examine the maximum extents, primary extent size,
secondary extent size, file format, and block size attributes as a part of
the integrity checking between the source and target files. By default, it
will verify the consistency of the file type, key length, record length, file
code, buffered, and audit file attributes.
 Reload Option Keyword – This defines the startup sequence logic
rule to be used. Valid options are the following:
ALWAYS - This setting causes the target file and mapping file to
be reloaded at startup (data verification steps are not performed).
NEVER - This setting uses the existing target file and mapping file
contents (bypasses the data verification step and possible reload).
Note: If the target file or mapping do not exist, Shadowbase will
log a message and stop.
VERIFY_STOP_ON_ERR - This is the default setting. It causes
the target Consumer to validate that the target file and mapping
file that exist are properly configured and contain consistent
information (validation tasks defined below). If the verification
does not pass, Shadowbase will log a message and stop.
VERIFY_FIX_FROM_SRC - This setting causes the target
Consumer to validate that the target file and mapping file that exist
are properly configured and contain consistent information
(validation tasks defined below). If the target file and mapping file
are properly configured but not consistent, Shadowbase will log a
message and continue after fixing the target file and mapping file
to make them consistent based from the source queue file data
content.
VERIFY_FIX_FROM_SRC_ALWAYS – During startup, the target
Consumer checks attributes associated with the target file and
HPE Shadowbase Programming Manual—785431-007
286
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
AUDCONSQ User Exit Processing
mapping to make sure they are consistent. With the
VERIFY_FIX_FROM_SRC, VERIFY_FIX_FROM_SRC_ON_
NOMAP_KEYDIFF, or VERIFY_FIX_FROM_SRC_2 options, the
Consumer will log an error message and stop. VERIFY_FIX_
FROM_SRC_ALWAYS causes the Consumer to log a warning
and then reload the related target file and mapping file.
VERIFY_FIX_FROM_SRC_ON_NOMAP_KEYDIFF – During
startup, the target Consumer checks to see if the mapping file
exists when the target file exists. It also checks that the target file
key length is consistent with the source file. When this option is
set and the mapping file does not exist or the key length of the
target file is different than the source, the Consumer will log a
warning and reload the related target file and mapping
file.
VERIFY_FIX_FROM_SRC_2 – This option is similar to
VERIFY_FIX_FROM_SRC, but differs in that the Consumer will
reload the target file and mapping file if the target file exists, but
the mapping file does not exist. Additionally, if both the target file
and mapping file do not exist, the Consumer will log a message
and stop.
VERIFY_FIX_FROM_TGT - This setting causes the target
Consumer to validate that the target key-sequenced file and
mapping file that exist are properly configured and contain
consistent information (validation tasks defined below). If the
target key-sequenced file and mapping file are properly configured
but not consistent, Shadowbase will log a message and continue
after fixing the target mapping file to make it consistent based
from the target key-sequenced file data content. Note that this
option is not permitted for a queue file target.
Note that when a reload of the target file and mapping file occurs, the
Consumer will purge and recreate the files if any file attributes were found
to be different from the source file during the verification. Otherwise, it will
use a purgedata on the target file and mapping file when necessary prior
to reloading.
Special Note: The purpose of the Consumer checking the attributes
of the target file against the source file for consistency is to attempt
to prevent the Consumer from purging/rebuilding the wrong target
and mapping file if a user mistake is made in the Shadowbase
configuration (i.e. the wrong value is set for the DBS object
TARGETFILE parameter). Typically, it is not advisable to set the
VERIFY_FIX_FROM_SRC_ALWAYS option. Use extra care when
setting this option as the Consumer will disregard the results of the
consistency checks. The Consumer will log a warning message to
HPE Shadowbase Programming Manual—785431-007
287
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
AUDCONSQ User Exit Processing
EMS for inconsistiencies found and will continue running and
rebuild and reload the target file and mapping file.
Note that if the target file is empty during startup but there is data in the
source queue file, the target and mapping file will be reloaded from the
source queue file.
The following is a description of the Reload Option settings from another
different perspective.
Step #1: Always verify that the target and mapping file attributes (not
data) are consistent and that they both exist together. If not, then the
Consumer will log an appropriate message and stop, regardless if
VERIFY_STOP_ON_ERR is set or not. The next step will not be
necessary.
However, if VERIFY_FIX_FROM_SRC_ALWAYS is set, the Consumer
will not stop, but will log a warning message, and then reload the target
file and mapping file. The attributes checked for correctness or
consistency between the source file and target file are: file type, key
length, maximum extents, audit flag, buffered, file format, record length,
block size, primary extent size, secondary extent size, and file code. The
attributes checked for correctness or consistency between the target file
and the mapping file are: file type, key length, record length, file format,
and audit flag. Note that the target file and mapping file are purged and
recreated prior to reloading if there is an attribute inconsistency. The
maximum extents, primary extent size, secondary extent size, file format,
and block size are only checked if the EXTCHECKS (extended checks)
keyword is specified in the USEREXITPARAM DBS parameter.
When VERIFY_FIX_FROM_SRC_ON_NOMAP_KEYDIFF is set, the
Consumer will also log an error message and stop if there are attribute
inconsistencies found as described previously. However, it will log a
warning and then reload the target and mapping files if the mapping file is
missing. If the key length of the target is different than the source file, the
Consumer will rebuild the target file and mapping files and then reload
them.
Step #2 : This is in regards to the verification of the data in the target and
mapping files. Note that the data in a target file will never be compared to
the data in the source queue file.
 ALWAYS – Always reload the target and mapping files from the
source after re-creating the target files first.
 NEVER – Do nothing. The target and mapping files will not be
compared against each other for consistency.
HPE Shadowbase Programming Manual—785431-007
288
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
Sample DBS Object Definitions
 VERIFY_STOP_ON_ERR – If the data is inconsistent between
the target file and the mapping file, the user exit will log a
message and cause Shadowbase to stop.
 VERIFY_FIX_FROM_SRC - If the data is inconsistent between
the target file and mapping file, the user exit will reload them from
the source queue file. An appropriate message will be logged.
 VERIFY_FIX_FROM_SRC_ALWAYS - If the data is inconsistent
between the target file and mapping file, the user exit will reload
them from the source queue file. An appropriate message will be
logged.
 VERIFY_FIX_FROM_SRC_2 - If the data is inconsistent between
the target file and mapping file, the user exit will reload them from
the source queue file. An appropriate message will be logged. In
the case that the target file exists, but the mapping file does not
exist, the user exit will create the mapping file and then reload
them from the source queue file. An appropriate message will be
logged. If neither file exists or the mapping file only exists, the
user exit will log a message and stop.
 VERIFY_FIX_FROM_SRC_ON_NOMAP_KEYDIFF - If the data is
inconsistent between the target file and mapping file, the user exit
will reload them from the source queue file. An appropriate
message will be logged.
 VERIFY_FIX_FROM_TGT - If the data is inconsistent between the
target key-sequenced file and mapping file, the user exit will
reload the mapping file from the target key-sequenced file. An
appropriate message will be logged. Note that this is not available
for a target queue file.
Note that if there is a failure of any (re)load (e.g. in the case that the
Consumer fails or is shut down), the base target and mapping files will be
reloaded from the source queue file during the next restart after the
Consumer receives the first event for processing.
Sample DBS Object Definitions
The following are sample DBS object definitions for the AUDCONSQ method of
queue file replication. Note the bolded items which are specifically associated
with queue file processing.
Wild-carded selection sample:
[DBS OBJECT FOR THE BASE TARGET]
ASSUME DBS
RESET DBS
HPE Shadowbase Programming Manual—785431-007
289
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
Sample DBS Object Definitions
SET
SET
SET
SET
SET
SET
SET
SET
SET
CONSNAME
CONS01
ALLOWQUEUEFILE ON
ALTERS
ON
CREATES
ON
PURGES
ON
PURGEDATAS
ON
SOURCEFILE
\PRIM.$VDV*.QAQFILS.QFIL*
TARGETFILE
\BKUP.$*.QAQFILT.*
USEREXITID
1 [BASE WHEN TARGET IS KEYED]
or
SET USEREXITID
11 [BASE WHEN TARGET IS A QUEUE FILE]
ADD DBS DBS-QFIL-BASE
[DBS OBJECT FOR THE BASE TARGET]
ASSUME DBS
RESET DBS
SET CONSNAME
CONS01
SET ALLOWQUEUEFILE ON
SET ALTERS
ON
SET CREATES
ON
SET PURGES
ON
SET PURGEDATAS
ON
SET SOURCEFILE
\PRIM.$VDV*.QAQFILS.QFIL*
SET TARGETILE
\BKUP.$*.QAQFILM.*
SET USEREXITID
2 [MAP WHEN TARGET IS KEYED]
or
SET USEREXITID
22 [MAP WHEN TARGET IS A QUEUE FILE]
SET USEREXITPARAM (QMAP=<75,75,200/4096/VERIFY_STOP_ON_ERR)
ADD DBS DBS-QFIL-MAP
Fully-qualified selection sample:
[DBS OBJECT FOR THE BASE TARGET]
ASSUME DBS
RESET DBS
SET CONSNAME
CONS01
SET ALLOWQUEUEFILE ON
SET ALTERS
ON
SET CREATES
ON
SET PURGES
ON
SET PURGEDATAS
ON
SET SOURCEFILE
\PRIM.$VDV001.QAQFILS.QFIL0001
SET TARGETFILE
\BKUP.$VDV001.QAQFILT.QFIL0001
SET USEREXITID
1 [BASE WHEN TARGET IS KEYED]
or
SET USEREXITID
11 [BASE WHEN TARGET IS A QUEUE FILE]
ADD DBS DBS-QFIL0001-BASE
[DBS OBJECT FOR THE BASE TARGET]
ASSUME DBS
HPE Shadowbase Programming Manual—785431-007
290
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
Mapping File Definition
RESET DBS
SET CONSNAME
CONS01
SET ALLOWQUEUEFILE ON
SET ALTERS
ON
SET CREATES
ON
SET PURGES
ON
SET PURGEDATAS
ON
SET SOURCEFILE
\PRIM.$VDV001.QAQFILS.QFIL0001
SET TARGETILE
\BKUP.$VDV001.QAQFILM.QFIL0001
SET USEREXITID
2 [MAP WHEN TARGET IS KEYED]
or
SET USEREXITID
22 [MAP WHEN TARGET IS A QUEUE FILE]
SET USEREXITPARAM (QMAP=<75,75,200/4096/VERIFY_STOP_ON_ERR)
ADD DBS DBS-QFIL0001-MAP
Mapping File Definition
The following is the record layout for the mapping file data:
Source Primary Key:
Optional User Part Key – Length is user-defined.
System Assigned Source Key Value – 8 bytes.
Target Primary Key – Target key (same as source for keyed).
Audit Trail Event Timestamp – 8 byte binary Julian timestamp.
Target I/O Timestamp – 8 byte binary Julian timestamp.
EMS Messages
The following informative EMS messages are reported for EMS event number
2043 (USRX_LOG_EVENT):
TARGET FILE <file name> AND MAPFILE <file name> WILL BE
RELOADED FROM SOURCE <file name> DUE TO DETECTED
INCONSISTENCY
Cause:
The user exit detected a difference between the
source file and target file or between the
target file and mapping file. A prior message
identifies the inconsistency. Both the target
file and mapping file will be reloaded from the
source file.
Effect:
The files are reloaded and the Consumer continues
to run.
Recovery:
None
HPE Shadowbase Programming Manual—785431-007
291
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
EMS Messages
TARGET FILE <file name> AND MAPFILE <file name> WILL BE
INITIALLY LOADED FROM SOURCE <file name> DUE TO EMPTY
TARGET
Cause:
The target file is empty, so the target file and
mapping file will be reloaded from the source
as needed.
Effect:
The files are reloaded and the Consumer continues
to run.
Recovery:
None
TARGET FILE <file name> AND MAPFILE <file name> WILL BE
(RE)LOADED AGAIN FROM SOURCE <file name> DUE TO PRIOR
(RE)LOAD FAILURE
Cause:
A (re)load during a previous startup was not
completed, either due to a failure or Shadowbase
was shut down.
Effect:
The target file and mapping file are reloaded as
needed and the Consumer continues to run.
Recovery:
None.
TARGET FILE <file name> AND MAPFILE <file name> WILL BE
RELOADED FROM SOURCE <file name> DUE TO 'ALWAYS RELOAD'
SETTING
Cause:
The 'ALWAYS" USEREXITPARAM option is
configured, so the target file and mapping file
are reloaded as needed.
Effect:
The target file and mapping file are reloaded as
needed and the Consumer continues to run.
Recovery:
None.
TARGET FILE <file name> AND MAPFILE <file name> WILL BE
RELOADED FROM SOURCE <file name> DUE TO DETECTED DATA
INCONSISENCY (VERIFY_FIX_FROM_SRC)
Cause:
Key data differences were found between the target
file and mapping file during startup and
VERIFY_FIX_FROM_SRC is set. They are
reloaded.
Effect:
The target file and mapping file are reloaded as
needed and the Consumer continues to run.
HPE Shadowbase Programming Manual—785431-007
292
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
EMS Messages
Recovery:
None.
MAPFILE <file name> WILL BE RELOADED FROM TARGET <file
name> DUE TO DETECTED DATA INCONSISENCY
(VERIFY_FIX_FROM_TGT)
Cause:
Key data differences were found between the target
file and mapping file during startup and
VERIFY_FIX_FROM_TGT is set. The mapping file
is reloaded.
Effect:
The mapping file is reloaded as needed and the
Consumer continues to run.
Recovery:
None.
TARGET FILE <file name> AND MAPFILE <file name> (RE)LOADED
SUCCESSFULLY FROM SOURCE <file name>, <count> RECORDS
INSERTED
Cause:
The target file and mapping file were reloaded
successfully.
Effect:
The files are reloaded and the Consumer continues
to run.
Recovery:
None
MAPFILE <file name> (RE)LOADED SUCCESSFULLY FROM TARGET
<file name>, <count> RECORDS INSERTED
Cause:
The mapping file was reloaded successfully.
Effect:
The file is reloaded and the Consumer continues to
run.
Recovery:
None
The following critical EMS messages are reported for EMS event number 2043
(USRX_LOG_EVENT):
ERROR: INVALID USEREXITPARAM VALUE FOR DBS <DBS object
name>, SPACES NOT ALLOWED
ERROR: INVALID USEREXITPARAM VALUE FOR DBS <DBS object
name>, UNKNOWN KEY WORD
ERROR: INVALID USEREXITPARAM VALUE FOR DBS <DBS object
name>, TOO MANY PARARMETER VALUES
HPE Shadowbase Programming Manual—785431-007
293
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
EMS Messages
ERROR: INVALID USEREXITPARAM VALUE FOR DBS <DBS object
name>, TOO MANY PARARMETER VALUES
ERROR: INVALID USEREXITPARAM SYNTAX OR INVALID
USEREXITPARAM PARAMETER VALUE FOR DBS <DBS object name>
ERROR: INVALID USEREXITPARAM SYNTAX OR INVALID
USEREXITPARAM PARAMETER VALUE FOR DBS <DBS object name>
ERROR: INVALID USEREXITPARAM SYNTAX OR INVALID
USEREXITPARAM PARAMETER VALUE FOR DBS <DBS object name>
Cause:
The text associated with the DBS
USEREXITPARAM for the identified DBS object is
invalid.
Effect:
The Consumer abends.
Recovery:
Correct the USEREXIPARAM value and restart
Shadowbase.
ERROR: TARGETFILE PARAMETER MISSING FOR DBS <DBS object
name>
Cause:
The DBS TARGETFILE parameter was not
specified for the identified DBS object.
Effect:
The Consumer abends.
Recovery:
Set the TARGETFILE parameter and restart
Shadowbase.
ERROR: POSSIBLE MISSING DBS RELATED TO SOURCE <file name>
Cause:
USEREXITID is set to 1 or 2 and caused an event
to be routed to USRXPROCESS. However, the
mapfile DBS object or target file object is missing.
Effect:
The Consumer abends.
Recovery:
Add the missing DBS object and restart
Shadowbase.
ERROR: TARGET FILE DBS MISSING FOR SOURCE FILE <file name>
Cause:
The target file DBS object is missing for the
identified source file.
Effect:
The Consumer abends.
Recovery:
Add the missing DBS object and restart
HPE Shadowbase Programming Manual—785431-007
294
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
EMS Messages
Shadowbase.
ERROR: MAPFILE DBS MISSING FOR SOURCE FILE <file name>
Cause:
The mapping file DBS object is missing for the
identified source file.
Effect:
The Consumer abends.
Recovery:
Add the missing DBS object and restart
Shadowbase.
ERROR: SOURCE AND TARGET FILE CAN'T BE THE SAME FILE (<file
name>)
Cause:
The target file is the same as the source file.
Effect:
The Consumer abends.
Recovery:
Review your DBS object TARGETFILE settings,
correct as needed, and restart Shadowbase.
ERROR: SOURCE AND MAP FILE CAN'T BE THE SAME FILE (<file
name>)
Cause:
The mapping file is the same as the source file.
Effect:
The Consumer abends.
Recovery:
Review your DBS object TARGETFILE settings,
correct as needed, and restart Shadowbase.
ERROR: TARGET FILE AND MAP FILE CAN'T BE THE SAME FILE
(<file name>)
Cause:
The target file is the same as the mapping file.
Effect:
The Consumer abends.
Recovery:
Review your DBS object TARGETFILE settings,
correct as needed, and restart Shadowbase.
ERROR: INVALID TARGETFILE FORMAT FOR DBS <DBS object
name>
Cause:
The TARGETFILE parameter for the identified DBS
object has invalid content. It is not a supported
file name format, consisting of a node name,
volume name, subvolume name, and file name. '*'
and "?' wild-carding characters are supported using
NonStop file name conventions.
HPE Shadowbase Programming Manual—785431-007
295
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
EMS Messages
Effect:
The Consumer abends.
Recovery:
Correct the TARGETFILE parameter and restart
Shadowbase.
ERROR: FOR DBS OBJECTS <DBS object name> AND <DBS object
name>, TARGETFILE USAGE (WILD CARD OR NOT) FOR MAP FILE
AND TARGET MUST BE SIMILAR
Cause:
The TARGETFILE values for the identified DBS
objects do not have a similar format.
Effect:
The Consumer abends.
Recovery:
Correct the TARGETFILE parameter and restart
Shadowbase.
ERROR: CAN'T CREATE <TGT or MAP> FILE <file name> DUE TO
FILE ERROR <error number>
Cause:
The target or mapping file could not be created due
to the reported file error number.
Effect:
The Consumer abends.
Recovery:
Correct the condition resulting in the file error and
restart Shadowbase.
ERROR: CAN'T PURGE <TGT or MAP> FILE <file name> DUE TO FILE
ERROR <error number>
Cause:
The target or mapping file could not be purged due
to the reported file error number.
Effect:
The Consumer abends.
Recovery:
Correct the condition resulting in the file error and
restart Shadowbase.
ERROR: COULD NOT OPEN <TGT or MAP> FILE <file name>,
FILE_OPEN_ RETURNED FILE ERROR <error number>
Cause:
The target or mapping file could not be opened due
to the reported file error number.
Effect:
The Consumer abends.
Recovery:
Correct the condition resulting in the file error and
restart Shadowbase.
HPE Shadowbase Programming Manual—785431-007
296
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
EMS Messages
ERROR: COULD NOT PURGEDATA ON <TGT or MAP> FILE <file
name>, CONTROL RETURNED FILE ERROR <error number>
Cause:
A purgedata could not be performed against the
target or mapping due to the reported file error
number.
Effect:
The Consumer abends.
Recovery:
Correct the condition resulting in the file error and
restart Shadowbase.
ERROR: TARGET FILE <file name> EXISTS BUT MAPFILE <file name>
DOES NOT
Cause:
The target file was found but the mapping file was
not found.
Effect:
The Consumer abends.
Recovery:
Review why the mapping file might not exist.
Purge the target file so that both are
(re)loaded during a restart. Then, restart
Shadowbase.
WARNING: TARGET FILE <file name> EXISTS BUT MAPFILE <file
name> DOES NOT
Cause:
The target file was found but the mapping file was
not found.
Effect:
The Consumer continues because one of the nonabend options is configured. The target and
mapping file will be (re)loaded.
Recovery:
None.
ERROR: MAPFILE FILE <file name> EXISTS BUT TARGET FILE <file
name> DOES NOT
Cause:
The mapping file was found but the target file was
not found.
Effect:
The Consumer abends.
Recovery:
Review why the target file might not exist. Purge
the mapping file also so that both are (re)loaded
during a restart. Then, restart Shadowbase.
WARNING: MAPFILE FILE <file name> EXISTS BUT TARGET FILE <file
name> DOES NOT
HPE Shadowbase Programming Manual—785431-007
297
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
EMS Messages
Cause:
The mapping file was found but the target file was
not found.
Effect:
The Consumer continues because one of the nonabend options is configured. The target and
mapping file will be (re)loaded.
Recovery:
None.
ERROR: TARGET FILE <file name> AND MAPFILE <file name> DO
NOT EXIST, CONS STOPPING (VERIFY_FIX_FROM_SRC_2)
Cause:
The target file and mapping file do not exist and the
VERIFY_FIX_FROM_SRC_2 option is configured
to stop in this situation.
Effect:
The Consumer abends.
Recovery:
Review why the files might not exist.Create them
manually or configure a different option.Then,
restart Shadowbase.
ERROR: SOURCE <file name> IS NOT A QUEUE FILE
Cause:
The identified source file is not a queue file.
Effect:
The Consumer abends.
Recovery:
Review your DBS object definitions, correct as
needed, and restart Shadowbase.
ERROR: TARGET <file name> IS NOT A QUEUE FILE
Cause:
The identified target file is not a queue file.
Effect:
The Consumer abends.
Recovery:
Review your DBS object definitions, correct as
needed, and restart Shadowbase.
WARNING: TARGET <file name> IS NOT A QUEUE FILE
Cause:
The identified target file is not a queue file. This is a
warning because VERIFY_FIX_FROM_SRC_
ALWAYS is set.
Effect:
The target and mapping file will be rebuilt and
reloaded.
HPE Shadowbase Programming Manual—785431-007
298
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
EMS Messages
Recovery:
None.
ERROR: TARGET <file name> IS NOT A NORMAL KEY-SEQUENCED
FILE
ERROR: MAPFILE <file name> IS NOT A NORMAL KEY-SEQUENCED
FILE
Cause:
The identified target file or mapping file is not a
normal key-sequenced file.
Effect:
The Consumer abends.
Recovery:
Review your DBS object definitions, correct as
needed, and restart Shadowbase.
WARNING: TARGET <file name> IS NOT A NORMAL KEYSEQUENCED FILE
WARNING: MAPFILE <file name> IS NOT A NORMAL KEYSEQUENCED FILE
Cause:
The identified target file or mapping file is not a
normal key-sequenced file. This is a warning
because VERIFY_FIX_FROM_SRC_ALWAYS is
set.
Effect:
The target and mapping file will be rebuilt and
reloaded.
Recovery:
None.
ERROR: SOURCE <file name> MUST BE AUDITED
ERROR: TARGET <file name> MUST BE AUDITED
ERROR: MAPFILE <file name> MUST BE AUDITED
Cause:
The identified source file, target file, or mapping file
is not audited and this is a requirement.
Effect:
The Consumer abends.
Recovery:
Turn on audit for the related file and restart
Shadowbase.
WARNING: TARGET <file name> MUST BE AUDITED
WARNING: MAPFILE <file name> MUST BE AUDITED
Cause:
The identified target file or mapping file is not
HPE Shadowbase Programming Manual—785431-007
299
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
EMS Messages
audited and this is a requirement. This is a
warning because VERIFY_FIX_FROM_SRC_
ALWAYS is set.
Effect:
The target and mapping file will be rebuilt and
reloaded.
Recovery:
None.
ERROR: SOURCE <file name> AND TARGET <file name> KEY
LENGTHS DO NOT MATCH, SOURCE: <number>, TARGET: <number>
ERROR: SOURCE <file name> AND TARGET <file name> MAX
EXTENTS DO NOT MATCH, SOURCE: <number>, TARGET: <number>
ERROR: SOURCE <file name> AND TARGET <file name> MUST HAVE
MATCHING BUFFERED FLAGS
ERROR: SOURCE <file name> AND TARGET <file name> FORMAT DO
NOT MATCH, SOURCE: <number>, TARGET: <number>
ERROR: SOURCE <file name> AND TARGET <file name> TARGET
RECORD LENGTHS DO NOT MATCH, SOURCE: <number>, TARGET:
<number>
ERROR: SOURCE <file name> AND TARGET <file name> BLOCK
SIZES DO NOT MATCH, SOURCE: <number>, TARGET: <number>
ERROR: SOURCE <file name> AND TARGET <file name> PRIMARY
EXTENTS DO NOT MATCH, SOURCE: <number>, TARGET: <number>
ERROR: SOURCE <file name> AND TARGET <file name>
SECONDARY EXTENTS DO NOT MATCH, SOURCE: <number>,
TARGET: <number>
ERROR: SOURCE <file name> FILECODE AND TARGET <file name>
FILECODE DO NOT MATCH, SOURCE: <number>, TARGET: <number>
Cause:
The target file has an attribute that is not consistent
with the source file.
Effect:
The Consumer abends.
Recovery:
Check your configuration to ascertain the reason
for this, correct the configuration, and restart
Shadowbase.
WARNING: SOURCE <file name> AND TARGET <file name> KEY
LENGTHS DO NOT MATCH, SOURCE: <number>, TARGET: <number>
HPE Shadowbase Programming Manual—785431-007
300
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
EMS Messages
WARNING: SOURCE <file name> AND TARGET <file name> MAX
EXTENTS DO NOT MATCH, SOURCE: <number>, TARGET: <number>
WARNING: SOURCE <file name> AND TARGET <file name> MUST
HAVE MATCHING BUFFERED FLAGS
WARNING: SOURCE <file name> AND TARGET <file name> FORMAT
DO NOT MATCH, SOURCE: <number>, TARGET: <number>
WARNING: SOURCE <file name> AND TARGET <file name> TARGET
RECORD LENGTHS DO NOT MATCH, SOURCE: <number>, TARGET:
<number>
WARNING: SOURCE <file name> AND TARGET <file name> BLOCK
SIZES DO NOT MATCH, SOURCE: <number>, TARGET: <number>
WARNING: SOURCE <file name> AND TARGET <file name> PRIMARY
EXTENTS DO NOT MATCH, SOURCE: <number>, TARGET: <number>
WARNING: SOURCE <file name> AND TARGET <file name>
SECONDARY EXTENTS DO NOT MATCH, SOURCE: <number>,
TARGET: <number>
WARNING: SOURCE <file name> FILECODE AND TARGET <file name>
FILECODE DO NOT MATCH, SOURCE: <number>, TARGET: <number>
Cause:
The target file has an attribute that is not consistent
with the source file. This is a warning because
either VERIFY_FIX_FROM_SRC_ALWAYS or
VERIFY_FIX_FROM_SRC_ON_NOMAP_
KEYDIFF is set. Note that the key length difference
message is only applicable to VERIFY_FIX_
FROM_SRC_ON_NOMAP_KEYDIFF.
Effect:
The target and mapping file will be rebuilt and
reloaded.
Recovery:
None.
ERROR: TARGET <file name> AND MAPFILE <file name> KEY
LENGTHS DO NOT MATCH, TARGET: <number>, MAPFILE: <number>
ERROR: MAPFILE <file name> RECORD LENGTH OF <number> IS
NOT THE EXPECTED RECORD LENGTH OF <number>
ERROR: TARGET <file name> AND MAPFILE <file name> FORMAT DO
NOT MATCH, TARGET: <number>, MAPFILE: <number>
Cause:
The mapping file has an attribute that is not
consistent with the target file.
HPE Shadowbase Programming Manual—785431-007
301
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
EMS Messages
Effect:
The Consumer abends.
Recovery:
Check your configuration to ascertain the reason
for this, correct the configuration, and restart
Shadowbase.
WARNING: TARGET <file name> AND MAPFILE <file name> KEY
LENGTHS DO NOT MATCH, TARGET: <number>, MAPFILE: <number>
WARNING: MAPFILE <file name> RECORD LENGTH OF <number> IS
NOT THE EXPECTED RECORD LENGTH OF <number>
WARNING: TARGET <file name> AND MAPFILE <file name> FORMAT
DO NOT MATCH, TARGET: <number>, MAPFILE: <number>
Cause:
The mapping file has an attribute that is not
consistent with the target file. This is a warning
because VERIFY_FIX_FROM_SRC_ALWAYS is
set.
Effect:
The target and mapping file will be rebuilt and
reloaded.
Recovery:
None.
ERROR: COULD NOT BEGIN TRANSACTION FOR (RE)LOAD, USER
EXIT API SBBEGINTRANSACTION RETURNED <error number>
ERROR: COULD NOT BEGIN TRANSACTION IN
QF_USRX_set_load_state, USER EXIT API SBBEGINTRANSACTION
RETURNED <error number>
ERROR: COULD NOT BEGIN TRANSACTION FOR TARGET
(RE)LOAD, USER EXIT API SBBEGINTRANSACTION RETURNED
<error number>
ERROR: COULD NOT END TRANSACTION FOR (RE)LOAD, USER
EXIT API SBCOMMITTRANSACTION RETURNED <error number>
ERROR: COULD NOT END TRANSACTION FOR TARGET/MAPPING
FILE (RE)LOAD, USER EXIT API SBCOMMITTRANSACTION
RETURNED <error number>
ERROR: COULD NOT END TRANSACTION FOR MAPPING FILE
(RE)LOAD, USER EXIT API SBCOMMITTRANSACTION RETURNED
<error number>
Cause:
A TMF transaction could not be started or
committed due to the reported file error number.
Effect:
The Consumer abends.
HPE Shadowbase Programming Manual—785431-007
302
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
EMS Messages
Recovery:
Correct the condition resulting in the file error and
restart Shadowbase.
ERROR: FILE_SETKEY_ ERROR <error number> ON MAP FILE <file
name>, COULD NOT READ FROM FILE
Cause:
The user exit was unable to position into the
mapping file due to the reported file error number.
Effect:
The Consumer abends.
Recovery:
Correct the condition resulting in the file error and
restart Shadowbase.
ERROR: FILE_SETKEY_ ERROR <error number> ON TGT FILE <file
name> IN QF_USRX_read_by_key_del
Cause:
The user exit was unable to position into the
target file due to the reported file error number.
Effect:
The Consumer abends.
Recovery:
Correct the condition resulting in the file error and
restart Shadowbase.
ERROR: READX FAILED ON TARGET FILE <file name>, COULD NOT
READ FROM FILE
ERROR: READX FAILED ON MAPPING FILE <file name>, COULD NOT
READ FROM FILE
ERROR: READX FAILED ON <SRC or TGT or MAP> FILE <file name>,
COULD NOT READ RECORD
ERROR: READX FAILED ON <SRC or TGT or MAP> FILE <file name>,
COULD NOT READ FROM FILE
ERROR: READUPDATELOCKX FAILED ON MAP FILE <file name>,
COULD NOT READ FROM FILE
ERROR: WRITEX FAILED ON <TGT or MAP> FILE <file name>
ERROR: WRITEUPDATEUNLOCKX FAILED ON MAP FILE <file name>,
COULD NOT WRITEUPDATE RECORD
Cause:
The user exit was unable to perform an I/O
operation for the reported file name.
Effect:
The Consumer abends.
HPE Shadowbase Programming Manual—785431-007
303
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
EMS Messages
Recovery:
Look for additional EMS messages that contain the
related file error number.
READX FILE ERROR <number> ON <TGT or MAP> FILE <file name> IN
QF_USRX_read_by_key_del
READUPDATELOCKX FILE ERROR <TGT or MAP> FILE <file name>
IN QF_USRX_read_by_key_del
Cause:
The user exit was unable to perform an I/O
operation for the reported file name.
Effect:
The Consumer abends.
Recovery:
Correct the condition resulting in the file error and
restart Shadowbase.
ERROR: RECORD NOT FOUND IN TGT FILE <file name> AFTER
<number> FILE_SETKEY_ ATTEMPTS, KEY=<key value>
Cause:
The user exit was unable to locate the related
target record, based upon the key previously
recorded in a mapping file record. This is highly
unusual. Note that have seen an unusual timing
anamoly resulting in an error 11 being returned by
the file system when it appears that the record does
exist. The user exit will automatically retry this a
number of times and abend if the record can’t be
found.
Effect:
The Consumer abends.
Recovery:
Autorestarting or a manual restart may correct this
condition. Contact Shadowbase Support if it
persists.
ERROR: READ COMMAND TIMED OUT AFTER <number> ATTEMPTS
FOR <number> SECONDS EACH, ERROR 40 ON <SRC or TGT or
MAP> FILE <file name>
Cause:
The user exit's read timed out for the identified file
after a number of retries.
Effect:
The Consumer abends.
Recovery:
Correct the condition resulting in the file error and
restart Shadowbase. It may be that other processes
have records locked.
ERROR: COULD NOT RETRIEVE TARGET FILE ERROR NUMBER,
FILE_GETINFO_ RETURNED <error number>
HPE Shadowbase Programming Manual—785431-007
304
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
EMS Messages
ERROR: COULD NOT RETRIEVE MAPPING FILE ERROR NUMBER,
FILE_GETINFO_ RETURNED <error number>
ERROR: COULD NOT RETRIEVE FILE ERROR NUMBER FOR <SRC
or TGT or MAP> <file name>, FILE_GETINFO_ RETURNED <error
number>
ERROR: COULD NOT RETRIEVE <SRC or TGT or MAP> FILE ERROR
NUMBER, FILE_GETINFO_ RETURNED <error number>
ERROR: COULD NOT RETRIEVE <SRC or TGT or MAP> FILE <file
name> ERROR NUMBER, FILE_GETINFO_ RETURNED <error
number>
ERROR: COULD NOT RETRIEVE MAP FILE ERROR NUMBER,
FILE_GETINFO_ RETURNED <error number>
Cause:
The user exit was unable to determine the file error
number for a prior I/O operation due to the
identified error.
Effect:
The Consumer abends.
Recovery:
Correct the condition resulting in the file error and
restart Shadowbase.
FILE ERROR <error number> ON MAPPING FILE <file name>
FILE ERROR <error number> ON TARGET FILE <file name>
FILE ERROR <error number> ON <SRC or TGT or MAP> FILE <file
name>
FILE ERROR <error number> ON MAP FILE <file name>
<SRC or TGT or MAP> FILE ERROR <error number>
ERROR: FILE ERROR NUMBER <error number> ON <SRC or TGT or
MAP> FILE <file name> (FILE NUMBER <number>) IN FUNCTION
QF_USRX_REPLICATE_RECS
ERROR: <SRC or TGT or MAP> FILE <file name> RETURNED FILE
ERROR <error number> IN FUNCTION QF_USRX_just_zero_rec
ERROR: TARGET FILE <file name> RETURNED FILE ERROR <error
number> IN FUNCTION QF_USRX_COMPARE_TRG_AND_MAP
HPE Shadowbase Programming Manual—785431-007
305
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
EMS Messages
ERROR: MAPPING FILE <file name> RETURNED FILE ERROR <error
number> IN FUNCTION QF_USRX_COMPARE_TRG_AND_MAP
ERROR: MAP FILE <file name> RETURNED FILE ERROR <error
number> IN FUNCTION QF_USRX_set_load_state
Cause:
The user exit was unable to perform an I/O
operation for the reported file name due to the
reported error number.
Effect:
The Consumer abends.
Recovery:
Correct the condition resulting in the file error and
restart Shadowbase.
FILE ERROR <error number> ON TGT FILE <file name> IN
QF_USRX_get_last_key
Cause:
The user exit was unable to perform an I/O
operation for the reported target file name due to
the reported error number.
Effect:
The Consumer abends.
Recovery:
Correct the condition resulting in the file error and
restart Shadowbase.
ERROR: AWAITIOX FAILED ON TARGET FILE <file name>, COULD
NOT READ FROM FILE
ERROR: AWAITIOX FAILED ON MAPPING FILE <file name>, COULD
NOT READ FROM FILE
ERROR: AWAITIOX FAILED ON <TGT or MAP> FILE <file name>,
COULD NOT WRITE
ERROR: AWAITIOX FAILED ON <SRC or TGT or MAP> FILE <file
name>, COULD NOT WRITEUPDATE RECORD
ERROR: AWAITIOX FAILED ON <SRC or TGT or MAP> FILE <file
name>, COULD NOT READ RECORD
ERROR: AWAITIOX FAILED ON <SRC or TGT or MAP> FILE <file
name>, COULD NOT READ FROM FILE
ERROR: AWAITIOX FAILED ON MAP FILE <file name>, COULD NOT
READ FROM FILE
Cause:
The user exit was unable to complete a prior I/O for
the identified file name.
HPE Shadowbase Programming Manual—785431-007
306
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
EMS Messages
Effect:
The Consumer abends.
Recovery:
This generally should not occur. Correct the
condition resulting in the error and restart
Shadowbase.
ERROR: AWAITIOX FAILED WITH ERROR NUMBER <error number>
ON <SRC or TGT or MAP> FILE <file name>, COULD NOT READ
FROM FILE
Cause:
The user exit was unable to complete a prior I/O for
the identified file name.
Effect:
The Consumer abends.
Recovery:
This generally should not occur. Correct the
condition resulting in the error and restart
Shadowbase.
ERROR: COULD NOT RETRIEVE FILE ERROR NUMBER FOR <SRC
or TGT or MAP> FILE <file name>, FILE_GETINFO_ RETURNED
<number>
Cause:
The user exit was unable to complete a prior I/O for
the identified file name.
Effect:
The Consumer abends.
Recovery:
This generally should not occur. Correct the
condition resulting in the error and restart
Shadowbase.
ERROR: COULD NOT GET INFO FOR SOURCE FILE <file name>,
FILE_GETINFOLISTBYNAME_ RETURNED <error number>
ERROR: COULD NOT GET INFO FOR TARGET FILE <file name>,
FILE_GETINFOLISTBYNAME_ RETURNED <error number>
ERROR: COULD NOT GET INFO FOR MAPPING FILE <file name>,
FILE_GETINFOLISTBYNAME_ RETURNED <error number>
Cause:
The user exit could not get information about a
source, target, or mapping file due to the reported
error number.
Effect:
The Consumer abends.
Recovery:
Correct the condition resulting in the error and
restart Shadowbase.
HPE Shadowbase Programming Manual—785431-007
307
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
EMS Messages
ERROR: COULD NOT DO TARGET (<file name>) AND MAPPING FILE
(<file name> VERIFICATION, USER EXIT FUNCTION
COMPARE_TGT_AND_MAP RETURNED -1
ERROR: COULD NOT INSERT RECORD INTO TARGET FILE <file
name>, USER EXIT FUNCTION QF_USRX_DO_INSERT RETURNED -1
ERROR: COULD NOT INSERT NEW RECORD INTO MAPPING FILE
<file name>, USER EXIT FUNCTION QF_USRX_DO_INSERT
RETURNED -1
ERROR: COULD NOT COPY SOURCE RECORDS TO
TARGET/MAPPING FILES, USER EXIT FUNCTION
QF_USRX_REPLICATE_RECS RETURNED -1
ERROR: COULD NOT COPY TARGET KEYS TO MAPPING FILE, USER
EXIT FUNCTION QF_USRX_REPLICATE_RECS RETURNED -1
ERROR: COULD NOT INSERT 'LOAD ACTIVE' RECORD INTO
MAPPING FILE <file name>, USER EXIT FUNCTION
QF_USRX_DO_INSERT RETURNED -1
ERROR: COULD NOT DELETE 'LOAD ACTIVE' RECORD FROM MAP
FILE <file name>, USER EXIT FUNCTION QF_USRX_do_update
RETURNED -1
Cause:
The user exit could not complete a logic sequence,
as reported.
Effect:
The Consumer abends.
Recovery:
Look for other EMS messages that may contain
specific error information. Correct the condition
resulting in the error and restart Shadowbase.
ERROR: CONS STOPPING DUE TO PRIOR OUTAGE DURING A
(RE)LOAD, SOURCE <file name>, TARGET <file name>, MAPFILE <file
name> (VERIFY_STOP_ON_ERR)
Cause:
A previous (re)load failed during startup and
VERIFY_STOP_ON_ERR is set.
Effect:
The Consumer abends.
Recovery:
Check your EMS messages as to what happened
causing the previous (re)load to fail. Purge the
target file and mapping file and restart
Shadowbase. Or, set another option besides
VERIFY_STOP_ON_ERR.
HPE Shadowbase Programming Manual—785431-007
308
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
EMS Messages
ERROR: CONS STOPPING DUE TO MAPFILE <file name> DATA
INCONSITENCY WITH TARGET FILE <file name>
(VERIFY_STOP_ON_ERR)
Cause:
The keys in the mapping file do not match the
target file and VERIFY_STOP_ON_ERR is set.
Effect:
The Consumer abends.
Recovery:
Purge the target file and mapping file and restart
Shadowbase so that the files are (re)loaded. Or, set
another option besides VERIFY_STOP_ON_ERR
so that the files are (re)loaded as your option
dictates.
ERROR: 0 LENGTH RETURNED BY SBGETDBSNAME USER EXIT API
RELATED TO SOURCE FILE <file name>
ERROR: <return code> RETURNED BY SBGETDBSPARAM USER EXIT
API FOR USEREXITPARAM RELATED TO DBS <DBS object name>
ERROR: SBGETAFTERRECORD OR SBGETBEFORERECORD USER
EXIT API RETURNED ERROR CODE <return code>
ERROR: SBGETSRCFILEINFO USER EXIT API RETURNED ERROR
CODE <return code>
ERROR: SBPUTRECORD USER EXIT API RETURNED ERROR CODE
<return code>
Cause:
A user exit API reported an error condition.
Effect:
The Consumer abends.
Recovery:
See the documentation for the related user exit API
function, correct the condition causing the error,
and restart Shadowbase.
ERROR: VERIFY_FIX_FROM_TGT USEREXITPARAM SETTING FOR
DBS <DBS object name> IS NOT VALID FOR A TARGET QUEUE FILE
Cause:
VERIFY_FIX_FROM_TGT is set for the
USEREXITPARAM parameter. This is not
supported for a target queue file.
Effect:
The Consumer abends.
Recovery:
Set the USEREXITPARAM value to another option
and restart Shadowbase.
HPE Shadowbase Programming Manual—785431-007
309
Appendix F – Enscribe QUEUE File Support Using a Keyed Or Queue File Target
(AUDCONSQ)
Preparing AUDCONSQ For Use
ERROR: USEREXITID'S FOR TARGET MAP FILE DBS<DBS object
name> AND ASSOCIATED TARGET BASE FILE DBS MUST BE 1 AND
2 OR 11 AND 22
Cause:
The USEREXITID’s are not set to the correct
value(s).
Effect:
The Consumer abends.
Recovery:
Set the USEREXITID to the appropriate value(s)
and restart Shadowbase.
Preparing AUDCONSQ For Use
At this time, the AUDCONSQ object file is not shipped as part of the base
Shadowbase product. If you receive this object, you will be provided instructions
about installing it on your NonStop system. Once it is on your NonStop system,
you should run FUP and SECURE it and GIVE it to the appropriate user as is
needed. To use this objet file you need to set the CONS PROGRAM parameter
in your Shadowbase configure like as follows:
SET CONS PROGRAM <$vol>.<subvol>.AUDCONSQ
Replication Fail-Over
When it is determined that a fail-over to a backup node is warranted, the
SBQFILE utility must be run to turn target key-sequenced files into queue files
before any application doing dequeue reads makes use of a file. See the “Queue
File Replication with SBQFILE” section of the HPE NonStop Shadowbase
Installation and Planning Manual for more information about running SBQFILE.
SBQFILE does not have to be run for real target queue files (those replicated
under USEREXITID’s 11 and 22).
After a fail-over and related to key-sequenced target files, before re-starting
replication in the reverse direction, the user could run SBQFILE to turn the
original, still active, queue files into key-sequenced files or purge them and have
them reloaded using the applicable “Reload Option” as documented above.
Additionally, prior to starting up the reverse direction, the user may want
procedures in place to preserve (and process) the original source queue file’s
contents that had not been replicated as of the failure point. Note that processing
this data is outside of the scope of the current Shadowbase implementation for
queue file processing.
[***** End of document *****]
HPE Shadowbase Programming Manual—785431-007
310