Detailed Design Specification
© 2006, 2009 Ingres Corporation
Project Name
Check Digit SQL Functions
Author Marty Bowes
Last Saved Date
March 6, 2016
Revision 1.0
Template Revision 1.7
533574468
Responsibility List
Assigned To
Marty Bowes
Steve Ball
Chris Rogers
David Reed
Pam Fowler
Bill Maimone
Elaine Grieco
Christine
Normile
Action
Owner
Peer Review
Peer Review
Test Review
Peer Review
Sustainability
Review
Peer Review
Peer Review
Peer Review
Peer Review
Responsibility
Engineer/Architect
Development Manager
QA Manager
QA Engineer
Sustaining Engineering
Manager
Sustaining Engineering
Engineer
Level 1 Support Manager
Chief Architect
Technical Writer
Product Manager
Peer Review
Peer Review
Services
Services
Signature
Note: The Responsibility List reflects those required to review and provide
feedback for the document. Signoff by those listed is required prior to the
beginning of the development phase.
Additional reviewers
Assigned To
Steve Ball
Teresa King
Teresa King
Joe Kronk
Roger Whitcomb
Emma
McGrattan
Action
Information
Information
Information
Information
Information
Information
Responsibility
DBMS
Gateways
Connectivity
OpenROAD
Tools
Usability
Signature
533574468
Page 2 of 32
Note: The additional reviewers list reflects other people that should be copied
on the document and invited to review meetings, but feedback from them is
not required for the document to be approved. Managers of other engineering
groups are copied for comment on how it affects their product or product area.
The manager for your own engineering area is included in first table and can
be removed from here.
SQL Language Review
Assigned To
Steve Ball
Teresa King
Teresa King
Joe Kronk
David Reed
Action
Language
Review
Language
Review
Language
Review
Language
Review
Language
Review
Responsibility
DBMS
Signature
Gateways
Connectivity
OpenROAD
Supportability and
Backward
Compatability
Note: The SQL language review table lists people that should be sent an initial
draft copy of this document if you answered “yes” to any questions in section
2.2. If you did not answer yes to any of those questions you may delete this
table.
533574468
Page 3 of 32
Change History:
Revision
Date
Last Revision By
Description of Change
30-Nov-2007
Steve Ball
Template: Fixed up instructions to be more Ingres
product range specific and added sections specific
to Ingres/OpenROAD
3-Dec-2007
Steve Ball
Template: Add tech writing changes and examples
section
4-Dec-2007
Steve Ball
Template: changes based on feedback
1-May-08
Christine Normile
Template: changes based on working meeting
Punta Cana, DR, Development Summit 2008
22-May-08
Christine Normile
Template: removed confidential markings
21-Aug-2008
Steve Ball
Template: Add language review elements
4-Apr-2009
Steve Ball
Template: Added section on catalog changes
28-May-2009
Mary Bowes
V 1.0: Initial draft for review
533574468
Page 4 of 32
TABLE OF CONTENTS
1
INTRODUCTION ...................................................................................................... 8
1.1
1.2
1.3
1.4
2
SCOPE AND SUMMARY ............................................................................................ 8
DEFINITIONS, ACRONYMS AND ABBREVIATIONS .................................................... 8
REFERENCES ......................................................................................................... 10
NOTEWORTHY ISSUES ........................................................................................... 10
ARCHITECTURE OVERVIEW ........................................................................... 12
2.1 HIGH LEVEL DESCRIPTION ..................................................................................... 12
2.2 SQL LANGUAGE CHANGES ................................................................................... 12
2.3 IMPLICATIONS FOR GCA ....................................................................................... 13
2.4 CONNECTION PARAMETERS .................................................................................. 13
2.5 LANGUAGE, UNICODE AND INTERNATIONALIZATION ISSUES ................................. 13
2.6 IMPLICATIONS FOR INGRES/STAR .......................................................................... 13
2.7 IMPLICATIONS FOR DBA TOOLS ............................................................................. 13
2.8 NEW IMA/MIB OBJECTS .......................................................................................... 13
2.9 NEW TRACE POINTS ............................................................................................... 13
2.10
CATALOG ALTERATIONS.................................................................................... 14
2.11
IMPLICATION FOR GATEWAYS ........................................................................... 14
2.12
IMPLICATIONS FOR DATABASE DRIVERS............................................................. 14
2.13
IMPLICATIONS FOR OPENROAD .......................................................................... 14
2.14
DESIGN LIMITATIONS AND ASSUMPTIONS ......................................................... 14
2.15
PLATFORM SPECIFIC ISSUES .............................................................................. 16
2.16
PRODUCT INTERACTION..................................................................................... 16
2.17
PATENT INFORMATION ...................................................................................... 16
3
EXTERNAL SPECIFICATION ............................................................................. 17
3.1
3.2
3.3
3.4
4
USER PERSPECTIVE ............................................................................................... 17
INSTALLATION AND ADMINISTRATION PERSPECTIVE ............................................ 21
MIGRATION ISSUES ............................................................................................... 21
SECURITY IMPACT ................................................................................................ 21
INTERNAL SPECIFICATION .............................................................................. 22
4.1
4.2
4.3
4.4
4.5
4.6
4.7
4.8
ESTIMATED TASKS AND EFFORT ........................................................................... 22
PROGRAMMING ..................................................................................................... 23
COMPATIBILITY LIBRARY INTERFACE CHANGES ................................................... 24
INTERFACE............................................................................................................ 24
BUILD IMPLICATIONS ............................................................................................ 24
UI RESOURCE/PROPERTIES FILES ......................................................................... 25
BITMAP RESOURCES ............................................................................................. 25
ICON FILES ........................................................................................................... 25
533574468
Page 5 of 32
4.9
5
IMPACT AND DOCUMENTATION SUMMARY .............................................. 27
5.1
5.2
6
PICCOLO CHANGE NUMBERS.................................................................................. 26
PRODUCT/COMPONENT IMPACTS .......................................................................... 27
DOCUMENTATION ................................................................................................. 27
QUALITY ISSUES .................................................................................................. 28
6.1
6.2
6.3
6.4
UNIT TESTING SUMMARY ..................................................................................... 28
HANDOFFQA IMPACT ............................................................................................. 29
TESTING RECOMMENDATIONS .............................................................................. 30
REGRESSION RISK ASSESSMENT ........................................................................... 30
7
PACKAGING AND INSTALLATION IMPACT ................................................ 31
8
SUPPORT IMPACT ................................................................................................ 32
8.1
EXAMPLES AND TESTS ........................................................................................... 32
533574468
Page 6 of 32
PREFACE
This document describes external functional specifications as well as design
specifications for one feature of a release project. There will be many Detailed
Design Specifications (DDS) for each project, one for each major feature
described in the Software Requirements Specification (SRS) or project wiki page.
The SRS or the wiki page is the master document for the entire project.
This is intended to be a living document. The product development cycle is a
dynamic process in which our understanding of the project and its criteria for
success are refined over time. It is therefore expected that the completed
Detailed Design Specification will undergo many revisions during the course of a
project as requirements; resources and constraints evolve. The engineer would
not be expected to complete all sections in the initial draft; some sections are
designed so that they can only be completed one the project is coded. *note that
you are expected to continue updating this document until the release
project is handed over to SE*
The Development Manager is responsible for the contents of this document.
Deliverables that must be completed prior to releasing this document are at least
one of:
 Software Requirements Specification
 Wiki page on the engineering web describing the components of the
project
All template instructions can be identified by their gray italic type. This
information may be removed after completing the necessary project
information.
Ant information detailed in this document should not be repeated in the wiki
page for this feature unless there is a compelling reason to do otherwise
one of the copies of the information may become out-of-date. If you need
to, refer to the DDS on the wiki page.
533574468
Page 7 of 32
1 INTRODUCTION
1.1
SCOPE AND SUMMARY
Add the ability to generate or validate a check digit on a string using a
specific check digit encoding scheme.
The functions added are:
 generate_digit('scheme', 'string')
which returns the check digit as a character.
 validate_digit('scheme', 'string')
which returns 1 for valid, 0 for invalid.
In both cases the scheme may be one of:
 LUHN, LUHN_A
 VERHOEFF, VERHOEFFNR
 ISBN
 ISBN_13
 ISSN
 UPC (aka: UPC_A, EAN_12)
 UPC_E.
 EAN (aka: EAN_13, GTIN_13, JAN)
 EAN_8 (aka: GTIN_8)
The scheme names are case insensitive.
Note that the luhn and verhoeff schemes can function on a character
string of any length and no restriction is made by the function. That is, if
you wish to generate a luhn digit for a string of 1024 characters then you
may...whether or not that's a useful exercise is upto you.
The other schemes are 'fixed length' schemes and can only be applied to
a string of the correct length. An error will be generated if a string of
incorrect length string is supplied.
1.2
DEFINITIONS, ACRONYMS AND ABBREVIATIONS
Detailed Design Specification: (DDS) A representation of a software
system or component of a system created to facilitate analysis,
533574468
Page 8 of 32
planning, implementation and decision-making. The DDS is used as
the primary medium for communicating software design
information.
LUHN:
The luhn algorithm was invented by Hans Peter Luhn. It is used in
most credit cards and many other applications.
LUHN_A:
This version of the luhn algorithm allows for alphabetical characters
by assigning numbers 10 == ‘A’, 11 == ‘B’ and so on.
VERHOEFF:
The verhoeff algorithm was invented by the Dutch Mathematician
Jacobus Verhoeff. This algorithm detects all transposition errors as
well as other types of error that would not be detected by the Luhn
Algorithm.
This implementation is the one as described in wikipedia.
VERHOEFFNR:
The verhoeff algorithm as found in 'Numerical Recipes in C'.
ISBN: International Standard Book Number.
The standard ISBN is a 10 character numeric identifier for printed
material. Since 1st January, 2007, the ISBN have been 13 digits.
Note that these are compatible with EAN_13.
ISBN_13: International Standard Book Number - 13 character version.
ISSN: International Standard Serial Number.
UPC: Universal Product Code
Also known as UPC_A or EAN_12. These are 12 character product
identification numbers.
UPC_E: Universal Product Code.
This is an eight character UPC used on smaller packages where a
12 character number would be too cumbersome to print.
EAN: European Article Number
Also known as: EAN_13, GTIN_13, JAN
The European Article Number is another product identification code
under the umbrella of the Global Trade Identification Number
(GTIN). In japan it also referred to as a Japanese Article Number
(JAN).
EAN_8: European Article number
Also known as GTIN_8.
These are eight character numbers designed for use on smaller
packages.
533574468
Page 9 of 32
1.3
REFERENCES
The Luhn and Luhn_A algorithms are described in:
http://en.wikipedia.org/wiki/Luhn_algorithm
The Verhoeff Algorithm is described by:
http://en.wikipedia.org/wiki/Verhoeff_Algorithm.
The verhoeff algorithm may be corroborated against:
http://www.augustana.ab.ca/~mohrj/algorithms/checkdigit.html
ISBN and ISBN_13 are described in: http://en.wikipedia.org/wiki/ISBN
ISSN International Standard Serial Number is described in:
http://en.wikipedia.org/wiki/ISSN
UPC and UPC_E are described in:
http://en.wikipedia.org/wiki/Universal_Product_Code
EAN is described in:
http://en.wikipedia.org/wiki/EAN-13
1.4
NOTEWORTHY ISSUES
Since the DDS is an evolving representation of the design (a "living
document"), this section is used to keep track of issues that arise during
the project life cycle and items that need special attention. If you add a
FIX_ME or comment similar to “need to do something about blah here” to
the code, you should note the issue here.
Verhoeff Algorithm:
There seems to be two opinions on the Verhoeff Algorithm. The version in
wikipedia (http://en.wikipedia.org/wiki/Verhoeff_Algorithm) and the version
as published in "Numerical Recipes in C". These do give different
answers.
The wikipedia version is also supported by:
http://www.augustana.ab.ca/~mohrj/algorithms/checkdigit.html
533574468
Page 10 of 32
I have coded both versions as I could not decide which would be
considered the ‘correct’ version.
Scope of validation.
The algorithms apply only what is required to mathematically validate the
check digit. Some schemes have further rules that give embedded
meaning to sets of characters within the string. No attempt has been made
to enforce such rules. For example the GTIN have reserved 2 or 3
characters at the start of the string as a country code.
Length of Check Digit.
The check digit is generated as a char(1) item. From a scan of Wikipedia it
appears that single character check digits are by far the norm. However
there are some two character check digit schemes. (eg. the Australian
Business Number).
All schemes can generate check digits.
Users are allowed to generate check digits on schemes for which they
would have no ‘right’ to do so. For example a user can generate an EAN
number, but that seems an act of dubious worth. Realistically only the
validation of an EAN number would be a reasonable user act.
533574468
Page 11 of 32
2 ARCHITECTURE OVERVIEW
2.1
HIGH LEVEL DESCRIPTION
Describe the overall architecture. Architectural design may be represented
in many forms, including text, graphical description, pseudo-code
representation or combination.
Simple addition of extra SQL functions generate_digit() and check_digit()
2.2
SQL LANGUAGE CHANGES
The functions added are:
 generate_digit('scheme', 'string')
which returns the check digit as a character.
 validate_digit('scheme', 'string')
which returns 1 for valid, 0 for invalid.
2.2.1 Language changes to Ingres/Star’
It will be available as per other functions.
2.2.2 Language Changes to ABF
It will be available as per other functions.
2.2.3 Language Changes to Database Procedures
It will be available as per other functions.
2.2.4 Language Changes to Embedded SQL pre-compilers
It will be available as per other functions.
2.2.5 Effects on dynamic SQL
It will be available as per other functions.
533574468
Page 12 of 32
2.3
IMPLICATIONS FOR GCA
None
2.4
CONNECTION PARAMETERS
None
2.5
LANGUAGE, UNICODE AND INTERNATIONALIZATION ISSUES
Is there anything about this feature that causes it to have unique
characteristics or testing requirements when implemented for the
international market and support for international or multi-byte character
sets including Unicode (UTF16 or UTF8)?
No
2.6
IMPLICATIONS FOR INGRES/STAR
Does this feature have any implication for Ingres/Star? If so what are
they?
None
2.7
IMPLICATIONS FOR DBA TOOLS
Does the feature have any implications for the DBA tools such as copydb,
auditdb, rollforwarddb, verifydb? Would a new verifydb option be useful?
No.
2.8
NEW IMA/MIB OBJECTS
Did you add any IMA objects as part of this feature? Are there any that
would be useful that perhaps you didn’t add because of lack of time?
None.
2.9
NEW TRACE POINTS
Trace points should be avoided in favor of IMA objects. If you added any
trace points detail them here with an explanation of why it was not
siuitable for an IMA object.
None.
533574468
Page 13 of 32
2.10 CATALOG ALTERATIONS
Does the feature add or alter the Ingres catalogs, either DBMS catalogs,
front-end catalogs, or iidbdb catalogs? If so, fill in the details here and be
sure to update the document containing the catalog spec, which can be
found here: http://community.ingres.com/wiki/Ingres_Catalogs
None.
2.11 IMPLICATION FOR GATEWAYS
Does this feature have any implications for the Ingres gateways? Do any
SQL language changes need to be considered for implementation in
gateway products?
None.
2.12 IMPLICATIONS FOR DATABASE DRIVERS
Does this feature have any implications for any of the database drivers
such as ODBC, JDBC, Python, PHP, Ruby, etc? Do any SQL language
changes need to be considered for implementation in these drivers?
None.
2.13 IMPLICATIONS FOR OPENROAD
Does this feature have any implications for OpenROAD? De sure to
mention any changes to ADF that are necessary to implement this feature,
they often impact OpenROAD. Do any SQL language changes need to be
considered for implementation in OpenROAD
None.
2.14 DESIGN LIMITATIONS AND ASSUMPTIONS
This section should list current limitations and assumptions made in the
design.
2.14.1 Generation on all schemes.
The generate_digit() function will work on all schemes the validate_digit()
function supports. This includes those schemes controlled by various
533574468
Page 14 of 32
International bodies such as ISBN, EAN. This might be excessive, who
would want to generate ISBNs?
Although it is useful from a testing perspective to have the generate_digit()
function act on all schemes, perhaps it should only be allowed on the
‘generic’ schemes, namely: luhn, luhn_a, verhoeff and verhoeffnr.
Alternatively a configuration variable could be set to restrict/permit the
function to offer all schemes.
If the generate_digit() Is called with an 'inappropriate' scheme the code
would have to be altered to generate an error 'Invalid scheme for
generate' message.
2.14.2 Scope of validation.
The algorithms apply only what is required to mathematically validate the
check digit. Some schemes have further rules that give embedded
meaning to sets of characters within the string. No attempt has been made
to enforce such rules.
For example an EAN is split into a GS1 Prefix, The Company Number, an
Item reference and the check digit. The GS1 Prefix is two or three
characters, essentially being a country code. The code will not attempt to
validate the GS1 prefix.
2.14.3 Length of Check Digit.
The check digit is generated as a char(1) item. From a scan of Wikipedia it
appears that single character check digits are by far the norm. However the
Australian Business Number has a two character check digit. There may
be others.
A code change to allow for varchar(2) check digits would be possible and
would not adversely affect anything which had been built on the single
character version.
533574468
Page 15 of 32
2.14.4 Dependencies
Does this feature depend on any external functionality (such as an XML
parser, or some other similar piece of code that does not belong to
Ingres)? Does this feature depend on another feature that will be, or has
been coded in this release of the product? Describe the dependency.
No.
2.15 PLATFORM SPECIFIC ISSUES
Is there anything about this feature that causes it to have unique
characteristics or testing requirements when implemented on a specific
platform? Are there any platform limitations to this feature, or is it
intended to run only on one platform? Will the feature need to re-coded
for other platforms (e.g. CL additions or re-architecture)
No.
2.16 PRODUCT INTERACTION
Does this feature cause any changes in the way that Ingres products
interact with each-other other than already detailed in the above sections?
Are there certain products that will/will no work with this feature (this is
more relevant to tools such as VDBA and new middle-ware servers)?
No.
2.17 PATENT INFORMATION
If there is any technology being developed for this feature that could be
considered for a patent, note the information here.
No.
533574468
Page 16 of 32
3 EXTERNAL SPECIFICATION
3.1
USER PERSPECTIVE
In this section, the focus is on the tasks that a user will perform with this
feature. Describe what the feature does and how it works form a user
perspective. Focus on how it is used to perform the function described in
the high level description.

Provide screen shots if appropriate
3.1.1 generate_digit()
(char(1) )C = generate_digit((varchar )scheme, (varchar )string);
This function generates the check digit ‘C’ for the string using the nominated
encoding scheme. The check digit is a single character computed from the other
characters in the string and is typically appended to the string for validation. Note
that this function does not append the check digit to the string.
The check digit may be employed as a means to help determine if a string has
been entered correctly. There are several error types that a check digit may be
able to detect.
Specifically:
- mistyped characters: eg '0123' not '0124'
- omissions or additions of characters.
- adjacent transposition errors: eg '01234' not '01243'
- twin errors: eg '11' becomes '22'
- jump transpositions: 123 becomes 321
- jump twin errors: 121 becomes 323
- phonetic errors: ie. the mixing of similar sounding numbers
- eg. sixty '60' not sixteen '16'
There are many check digit schemes of varying complexity, purpose and abilities.
For example the Luhn algorithm is widely used in credit card numbers and is
programmatically simple to implement. But the Verhoeff algorithm is considered
superior in detection of certain error types such as jump transpositions. However
it is a more complicated algorithm.
533574468
Page 17 of 32
Note that a check digit is not an infallible error detector; it simply improves the
chance of detecting errors in keying. Furthermore a check digit does not provide
error correction capability.
For a description on supported schemes please refer to validate_digit.
3.1.2 validate_digit()
(int1 )r = validate_digit((varchar )scheme, (varchar )string);
This function validates the check digit in the string is mathematically correct for
the nominated scheme. The function returns 1 for valid and 0 for invalid.
This function has the same caveats on scheme name and strings as noted for
generate_digit().
A brief description of each supported check digit scheme follows.
NOTE:
- The scheme name may be in mixed case.
- Although many schemes use whitespace, dashes etc to separate their
strings into 'blocks', this implementation demands that such separators are
removed from the strings as in many cases the separation is not clearly
defined.
- Some schemes have internal formatting rules. For example an EAN is split
into a GS1 Prefix, The Company Number, an Item reference and the
check digit. This function will only calculate the check digit. It will not
attempt to enforce any other formatting rules.
Scheme
EAN
Description
European Article Number
Synonyms: EAN_13, GTIN, GTIN_13, JAN
The EAN is a barcoding standard defined by the standards
organisation GS1. It is used worldwide for marking retail goods.
It was developed as a superset of the original 12 digit Universal
Product Code (UPC) system. It is also called a Japanese
Article Number (JAN) in Japan. UPC, EAN, and JAN numbers
are collectively called Global Trade Item Numbers (GTIN).
An EAN string is a 13 character string composed entirely of
digits. The check digit is the rightmost character in the string.
533574468
Page 18 of 32
Scheme
EAN_8
Description
European Article Number
Synonyms: GTIN_8, RCN_8
The EAN_8 are 8 character numbers derived from the longer
EAN_13 and are intended for usage on small packages where
the longer number would be awkward.
The EAN_8 may also be used internal to companies to identify
restricted or 'own-brand' products to be sold within their stores
only. These are often referred to with the synonym: RCN_8.
ISBN
An EAN_8 string is an eight character string composed entirely
of digits. The check digit is the rightmost character in the string.
International Standard Book Number
ISBN_13
The standard ISBN is a 10 character alphanumeric identifier for
printed material. The check digit is the right most character and
may be either a digit or the alpha 'X'. The other characters in
the string must be digits.
International Standard Book Number
ISSN
This is the 13 character version of the ISBN. The string is
composed entirely of digits. The check digit is the rightmost
character in the string.
International Standard Serial Number
LUHN
ISSNs are 8 character alphanumeric identifiers for electronic or
print periodicals. The check digit is the right most character and
may be either a digit or the alpha 'X'. The other characters in
the string must be digits.
The LUHN algorithm
Created by IBM scientist Hans Peter Luhn. Most credit cards
and many government identification numbers are based on this
simple algorithm. For example the Canadian Social Security
number is a nine digit number based on the Luhn algorithm.
The string may be of any permitted length, but must be
composed entirely of digits. The check digit is the right most
character in the string.
533574468
Page 19 of 32
Scheme
LUHN_A
Description
The LUHN algorithm (alphanumeric)
This is an extension of the Luhn Algorithm which allows for
alphabetic characters by assigning numbers 10 to 'A', 11 to 'B',
...35 to 'Z'. Note that it is case insensitive.
The Committee on Uniform Security Identification Procedures
(CUSIP) provides a 9-character alphanumeric string based on
this algorithm. Also the International Securities Identification
Number (ISIN) is a 12 character version of this algorithm.
UPC
The string may be of any permitted length, but must be
composed entirely of alphanumeric characters. The check digit
is the right most character in the string.
Universal Product Code
Synonyms: UPC_A, EAN_12
Used to mark retail goods as per the EAN (see above).
UPC_E
These are composed of 12 digits with the check digit being the
right most character.
Universal Product Code
VERHOEFF
A UPC_E is composed of six digits and were intended for
smaller packages where a full size UPC_A would be
cumbersome. Unlike the UPC_A the check digit is not
appended to the number. Rather, it is used to determine the
'odd/even' parity assigned to the numbers for when they are
encoded as bar-code lines.
The Verhoeff Algorithm as described in Wikipedia
Developed by Dutch Mathematician Jacobus Verhoeff. This
algorithm detects all transposition errors as well as other types
of error that would not be detected by the Luhn Algorithm.
The Verhoeff Algorithm, like the Luhn algorithm can also handle
strings of any permitted length. The strings must be composed
entirely of digits and the check digit will be the right most
character.
VERHOEFFNR Verhoeff Algorithm as described in ‘Numerical Recipes in C’.
533574468
Page 20 of 32
Scheme
Description
A variation on the Verhoeff algorithm published in ‘Numerical
recipes in C’ by Press, Teukolsky, Vetterling and Flannery.
3.2
INSTALLATION AND ADMINISTRATION PERSPECTIVE
Include any special installation and setup tasks, system parameters or
other preparations that are necessary prior to use. Describe the steps
needed to setup and get the component going and any ongoing
administration that will need to be performed if relevant. List all
configuration parameters that apply to this feature here.
None
3.3
MIGRATION ISSUES
Describe any special steps required to migrate from existing versions
Ingres/OpenROAD to this version that arise because of this feature. Does
this feature have any new catalogs or other implications for upgradedb?

Is the component going to be backward compatible?

Can this version co-exist with an older version?
There are no new catalogs.
These are new functions so they are not backwards compatible.
3.4
SECURITY IMPACT
Does anything about the function need securing? Could it do any
damage? Could it cause the display of sensitive information?
Does the implementation methodology do anything that produces a
potential security exposure, such as run as root or Ingres (if this is an
application)?
None.
533574468
Page 21 of 32
4 INTERNAL SPECIFICATION
4.1
ESTIMATED TASKS AND EFFORT
Estimate the engineering effort to code and test the component ready for
hand over to QA and Technical Writing. If it is a large function, break it up
into smaller “function points” and estimate each one. For large projects,
filling out the table below and should help but is not required. Estimates
should be effort to code complete; that is engineering effort assuming
100% of an engineer’s time is used, which will not normally be equal to
elapsed time for the project. Estimates should include time to:

Code the feature and all of the error checking required for the
feature (error checking may be up to 50% of the code in the DBMS)

Test your code and make corrections

Write and post an integration plan (or more than one for large
projects)

Run HandoffQA for each proposed submission and check the
results
As a guide, an experienced engineer who already knows the code will
normally write and sanity test about 100 lines of code per day; engineers
with less experience or those that are new to the code will write less.
Factor about 20% of the time it took to code for final testing and fixes.
Look at existing modules to help make an estimate of the number of lines
of code required. Tasks should normally be submitted as they are sane
and complete, so the formula might be something like:
Time for task = (no_of_lines / 100) + 2 days for IP and HandoffQA
Total time = Sum (time for all tasks) + 20% for overall testing and fixes
Click here to begin typing
Task
Effort
(persondays)
Assigned to
Done
(yes/no)
Tested
(yes/no)
Description of task
TOTAL
Total days
-
-
-
533574468
Page 22 of 32
4.2
PROGRAMMING
List programs and modules written, changed or deleted. Initially this will
be a first pass estimate of what needs to be changed, it will likely change
during the course if the project. The version of this document at code
complete will contain the modules or programs that actually changed.
4.2.1 $ING_SRC/common/adf/adg/adgoptab.roc
Add references to the new functions.
4.2.2 $ING_SRC/common/adf/adg/fi_defn.txt
Add the function instances for the new functions.
4.2.3 $ING_SRC/common/adf/adu/aduerror.c
Allow for the new error codes generated by the functions.
4.2.4 $ING_SRC/common/adf/adu/adustring.c
Create the function executor code for the new functions.
4.2.5 $ING_SRC/common/adf/hdr/adffiids.h
Allow for the new function instance id’s.
4.2.6 $ING_SRC/common/adf/hdr/aduint.h
Include the new function prototypes.
4.2.7 $ING_SRC/common/hdr/hdr/adf.h
Set up the error code numbers for the new functions errors.
4.2.8 $ING_SRC/common/hdr/hdr/adfops.h
Allow for the new functions in table of function identifiers.
4.2.9 $ING_SRC/common/hdr/hdr/eradf.msg
Add trhe formatted error message strings for the new functions.
533574468
Page 23 of 32
4.3
COMPATIBILITY LIBRARY INTERFACE CHANGES
Describe any changes made to the compatibility library interface. Any
changes described here should be copied to CL platform reviewers for
approval before changes are made, and the CL spec should be updated to
reflect the new interface. Current platform reviewers are:
Joe Abbate – VMS
Viktoriya Driker - Windows
Bob Bonchik, Hong Hwe – UNIX
Mike Touloumtzis - Linux
None
4.4
INTERFACE
How do other components that are external to the design interact with
this component? Describe methods and rules of interaction.

Communication protocols; is GCA affected? Other?

Changes of facility call interfaces in the DBMS (e.g. is dmf_call
changed?)

Changes to the interface of non static functions

New error codes or error conditions that will be logged or propagated
up the stack to other functions. Has the error handling for those
functions been updated?
New error codes:
4.5

E_AD2055_CHECK_DIGIT_SCHEME

E_AD2056_CHECK_DIGIT_STRING

E_AD2057_CHECK_DIGIT_EMPTY

E_AD2058_CHECK_DIGIT_STRING_LENGTH:
BUILD IMPLICATIONS
Does this feature require any special jam rules? Did it require any
changes in jam MANIFEST files? Any new build targets? Any other build
alterations?
533574468
Page 24 of 32
No.
4.6
UI RESOURCE/PROPERTIES FILES
This section is largely relevant to GUI applications like OpenROAD and
can be removed for DBMS features.
Provide the names of the files required by the UI and Messages
File Name
4.7
Byte Count
Word Count
Format
Comments
BITMAP RESOURCES
This section is largely relevant to GUI applications like OpenROAD and
can be removed for DBMS features.
Provide the bitmap resources.
File
4.8
Comments
ICON FILES
This section is largely relevant to GUI applications like OpenROAD and
can be removed for DBMS features.
Provide the icon files used..
File
Comments
533574468
Page 25 of 32
Release note
System
requirements
4.9
PICCOLO CHANGE NUMBERS
Provide piccolo change numbers for changes made for this feature. This
will be filled in after the fact and should include change numbers for
propagations of the same change to other branches if appropriate
Change Number
Submitted to (code-branch)
Submission date
main
533574468
Page 26 of 32
5 IMPACT AND DOCUMENTATION SUMMARY
The estimates in this section are approximate and are intended to give
other groups such as Technical Writing, Services, Support and QA an idea
of the impact this change will have.
5.1
PRODUCT/COMPONENT IMPACTS
5.1.1 Entities
List the tools, commands, reports and messages that are impacted by the
development of the module/function. Use the table below to summarize
these changes; you can refer to other sections for details.
Entity
New
Modified
Comments
Tool
Commands
Messages
Help Modules
5.2
DOCUMENTATION
List the existing end-user documentation that is affected by modules
changes, and how it is affected. Be as specific and thorough as possible.
MANUAL
CHANGES NEEDED
Installation Guide
Database Administrator Guide
System Administrator Guide
Connectivity Guide
SQL Reference Guide
Command Reference Guide
Migration Guide
No
No
No
No
Yes, chapter 4.
Refer to details in section
3.1
No
No
Estimated
# of Pages
4
533574468
Page 27 of 32
6 QUALITY ISSUES
Look at the component from the QA point of view. Suggest any special
tests that will stress the component. Think how to make the component
NOT work and what special tests should be performed on this
component. This is a guideline to the QA testing procedures.
6.1
UNIT TESTING SUMMARY
Testing individual functions or subroutines in isolation is called unit
testing. Unit testing in some cases requires the developer to use stubs
and drivers. Describe the unit testing you did in these sections. Attach all
unit tests to the wiki page for this feature so that they are available to QA.
6.1.1 Unit Testing Description
List and unit testing planned or done..
Several test scripts have been created. These should be executed as follows.
6.1.1.1 test_basics.sh
The program will first display all the error messages I've added. These should be
checked manually for correct formatting.
It will then perform other basic tests and generate a summary at the end. Ensure
this has no errors listed.
6.1.1.2 Required data files
Several data files have been provided. These contain known valid check digits
for a scheme. The files are:
-
ean_8s.dat
-
eans.dat
-
isbn_13s.dat
-
isbns.dat
-
issns.dat
-
upces.dat
-
upcs.dat
533574468
Page 28 of 32
6.1.1.3 Required symlinks
Several scheme names are synonyms; to test these ensure the following
symlinks are loaded:
ln -s ./test_upc.sh test_ean_12.sh
ln -s ./test_ean.sh test_ean_13.sh
ln -s ./test_ean.sh test_gtin_13.sh
ln -s ./test_ean_8.sh test_gtin_8.sh
ln -s ./test_ean.sh test_gtin.sh
ln -s ./test_ean.sh test_jan.sh
ln -s ./test_ean_8.sh test_rcn_8.sh
ln -s ./test_upc.sh test_upc_a.sh
6.1.1.4 test all schemes
Then execute each of the remaining test programs...Simply check the summary
at end to see if errors have been listed.
- test_ean_12.sh
- test_ean_13.sh
- test_ean_8.sh
- test_ean.sh
- test_gtin_13.sh
- test_gtin_8.sh
- test_gtin.sh
- test_isbn_13.sh
- test_isbn.sh
- test_issn.sh
- test_jan.sh
- test_luhn_a.sh
- test_luhn.sh
- test_rcn_8.sh
- test_upc_a.sh
- test_upc_e.sh
- test_upc.sh
- test_verhoeffnr.sh
- test_verhoeff.sh
6.2
HANDOFFQA IMPACT
In this section you should document expected or observed diffs in
HandofQA caused by the feature as well as other things that impact
533574468
Page 29 of 32
HandoffQA; should any new tests be added to HandoffQA for this feature
to prevent regression?
6.3
TESTING RECOMMENDATIONS
Suggest other additional function tests that are necessary. Special test
requirements, for example: the security levels, hardware or software
configurations, code page and multiple code pages, multi-system issues.
Note anything that cannot be tested in a lab and which might require field
tests. What can go wrong? How are these situations dealt with?
The tests mentioned in 6.1 are extensive ands should be sufficient in
themselves.
6.4
REGRESSION RISK ASSESSMENT
What would be the implications of failure in the component? Is the code
complex? What is the potential for destabilizing existing functions?
What other areas of the product/component interact with this module?
A failure in the code would result in generating bad check digits or
incorrectly validating check digits. Such a failure would be local to the
application and would not hurt existing functions.
The code is not complex and should a bug arise then it should be a
straightforward fix.
6.4.1 Backward Compatibility Issues
Is there anything that should be tested for backward compatibility? Does
this feature affect how a down-rev client connects the current version of
the DBMS? Did the GCA protocol level change? Is upgradedb required?
No
533574468
Page 30 of 32
7 PACKAGING AND INSTALLATION IMPACT
Indicate any special packaging or installation requirements. Detail what
the packaging and installation requirements, if any, will be. Detail any
new files that are required, remember they should be added to the
manifest, you are responsible for doing this as part of the project.
None
533574468
Page 31 of 32
8 SUPPORT IMPACT
Detail any diagnostics or trace facilities built in to the component
including new IMA objects, trace points, or other build time or run-time
diagnostics. Note anything that could be made into a good supportability
tool. Note components that are:

Difficult to diagnose (for example: no tracing facility, dependent on
specific timing)

Difficult to service
Include workarounds where appropriate.
None.
8.1
EXAMPLES AND TESTS
Detail any example or test code that you wrote during the development of
the feature that may be useful to help support, QA, or customers to
understand the feature or useful to QA for testing. Attach all example and
test code or details to the wiki page for this feature
See list in 6.1.1
533574468
Page 32 of 32