===========================================
IBM Global Name Management, Version 6.0.0.0

GNM iFix #4 (GNM_6.0.0.0.iFix004)

June 2018

This readme includes the following sections:
I. System requirements
II. Required files
III. Issues addressed and performance improvements
IV. Implementation
V. Technical details

I. System requirements:

This interim fix is cumulative of IBM Global Name Management fixes and was built all supported platforms.
You must have one of the listed InfoSphere Global Name Management versions installed prior to applying this fix.

Platform	Product Version
ALL	Version 6.0.0.0
	Version 6.0.0.0_iFix001
	Version 6.0.0.0_iFix002
	Version 6.0.0.0_iFix003

II. Required files:

GNM installation

This list represents the updated files for a basic GNM installation for each of the currently supported platforms:

Platform	Directory	Files
AIX	`/bin`	`commgr`
		`npp`
		`searcher`
---------------	-----------------------------	----------------------------
	`/data`	`gnv.ibm`
		`snv.ibm`
		`onv.ibm`
		`taq.ibm`
		`koreanOnTransRule.ibm`
		`swasianRegRule.ibm`
---------------	-----------------------------	----------------------------
	`/lib`	`libanalytics.so`
		`libscoring.so`
		`libNameDataObject.so`
		`NameWorksAnalytics.jar`
		`NameWorksScoring.jar`
---------------	-----------------------------	----------------------------
	`/sdk/include`	`gnrndo.h`
		`nwcommon.h`
		`nwexcept.h`
		`scoring.h`
		`NameParser.h`
---------------	-----------------------------	----------------------------
	`/sdk/samples/java`	`analysis.config`
		`search.config`
---------------	-----------------------------	----------------------------
	`/support/bin`	`coaclu`
		`nc_coaclu`
		`npclu`
		`nvgclu`
		`search`
		`testnc`
		`testng`
		`why`
---------------	-----------------------------	----------------------------
Linux	`/bin`	`commgr`
		`searcher`
---------------	-----------------------------	----------------------------
	`/data`	`gnv.ibm`
		`snv.ibm`
		`onv.ibm`
		`taq.ibm`
		`koreanOnTransRule.ibm`
		`swasianRegRule.ibm`
---------------	-----------------------------	----------------------------
	`/lib`	`libanalytics.so`
		`libscoring.so`
		`libNameDataObject.so`
		`NameWorksAnalytics.jar`
		`NameWorksScoring.jar`
---------------	-----------------------------	----------------------------
	`/sdk/include`	`gnrndo.h`
		`nwcommon.h`
		`nwexcept.h`
		`scoring.h`
		`NameParser.h`
---------------	-----------------------------	----------------------------
	`/sdk/samples/java`	`analysis.config`
		`search.config`
---------------	-----------------------------	----------------------------
	`/support/bin`	`coaclu`
		`nc_coaclu`
		`npclu`
		`nvgclu`
		`search`
		`testnc`
		`testng`
		`why`
---------------	-----------------------------	----------------------------
Windows	`\bin`	`analytics.dll`
		`scoring.dll`
		`commgr.exe`
		`searcher.exe`
		`NameDataObject.dll`
---------------	-----------------------------	----------------------------
	`\data`	`gnv.ibm`
		`snv.ibm`
		`onv.ibm`
		`taq.ibm`
		`koreanOnTransRule.ibm`
		`swasianRegRule.ibm`
---------------	-----------------------------	----------------------------
	`\lib`	`analytics.lib`
		`scoring.lib`
		`NameWorksAnalytics.jar`
		`NameWorksScoring.jar`
---------------	-----------------------------	----------------------------
	`\sdk\include`	`gnrndo.h`
		`nwcommon.h`
		`nwexcept.h`
		`scoring.h`
		`NameParser.h`
---------------	-----------------------------	----------------------------
	`\sdk\samples\java`	`analysis.config`
		`search.config`
---------------	-----------------------------	----------------------------
	`\support\bin`	`coaclu.exe`
		`nc_coaclu.exe`
		`npclu.exe`
		`nvgclu.exe`
		`search.exe`
		`testnc.exe`
		`testng.exe`
		`why.exe`

ENS installation

This list represents the updated files for an ENS installation for each of the currently supported platforms:

Platform	Directory	Files
AIX	`/data`	`gnv.ibm`
		`snv.ibm`
		`onv.ibm`
		`taq.ibm`
		`koreanOnTransRule.ibm`
		`swasianRegRule.ibm`
---------------	-----------------------------	----------------------------
	`/lib`	`libanalytics.so`
		`libscoring.so`
		`libNameDataObject.so`
		`NameWorksAnalytics.jar`
		`NameWorksScoring.jar`
		`NameLoader.jar`
---------------	-----------------------------	----------------------------
	`/wlp/apps`	`ibm-infosphere-ens.ear`
---------------	-----------------------------	----------------------------
Linux	`/data`	`gnv.ibm`
		`snv.ibm`
		`onv.ibm`
		`taq.ibm`
		`koreanOnTransRule.ibm`
		`swasianRegRule.ibm`
---------------	-----------------------------	----------------------------
	`/lib`	`libanalytics.so`
		`libscoring.so`
		`libNameDataObject.so`
		`NameWorksAnalytics.jar`
		`NameWorksScoring.jar`
		`NameLoader.jar`
---------------	-----------------------------	----------------------------
	`/wlp/apps`	`ibm-infosphere-ens.ear`
---------------	-----------------------------	----------------------------
Windows	`\bin`	`analytics.dll`
		`scoring.dll`
		`NameDataObject.dll`
---------------	-----------------------------	----------------------------
	`\data`	`gnv.ibm`
		`snv.ibm`
		`onv.ibm`
		`taq.ibm`
		`koreanOnTransRule.ibm`
		`swasianRegRule.ibm`
---------------	-----------------------------	----------------------------
	`\lib`	`analytics.lib`
		`scoring.lib`
		`NameWorksAnalytics.jar`
		`NameWorksScoring.jar`
		`NameLoader.jar`
---------------	-----------------------------	----------------------------
	`\wlp\apps`	`ibm-infosphere-ens.ear`

III. Issues addressed and performance improvements:

New reference data file additions to the sample configuration files.
Chinese name search performance improvements.
Distributed Search performance improvements.
Short Name scoring efficiency and memory improvements.
Turkish given name variant additions.
Elimination of redundant parses of names provided in Chinese script.
Improved parsing of Southwest Asian names.
Score logging enhancement in PreprocessedName comparison.
Parsing of Southwest Asian names containing initials has been corrected.
Improved handling of Symbolic names (NFN/FNU/NLN/LNU) appearing in Southwest Asian names.
Embedded Search datalists in NameWorks no longer risk thread conflicts when loading Native Script data.
Southwest Asian regularization rules now prevent over-generation.
Record data for add/update names in Distributed Search servers is reported correctly when running in unique name mode.
Additions to Korean organization name reference data.
Addition of the ability to override name data statistics in reference data (Name Data Object overrides).
An authorization error occurring when interim updates are performed on ENS servers has been corrected.
Handling of internal database credentials was modified in ENS to improve security of an installation.
AIX shared libraries now export all low-level component API methods.
Accuracy improved in short-name scoring of Southwest Asian personal names.
New custom parsing token types added to support Titles and Prefixes that may be given names.
A new ‘createName()’ method added to NameWorks Scoring to support specifying culture and native script.
Genderization accuracy of multi-token name phrases improved for the ‘analyze()’ method of NameWorks Analytics.
Corrections applied to Southwest Asian regularization rules.
General performance improvements to name searching.
Sort order of alternate parses corrected for the low-level NameParser API.
An issue related to stale internal credentials used in internal HTTP requests among ENS components has been resolved. GNM iFix003 contained some ENS changes for this issue, but further changes were required and are delivered in this fix.

IV. Implementation:

Before you begin:

<GNM_ROOT> is the directory where you installed InfoSphere Global Name Management.
<ENS_ROOT> is the directory where you installed InfoSphere Global Name Management Enterprise Name Search.
<FIX_ROOT> is the root directory of the fix.
<PLATFORM> is the platform / operating system of the installation.
<ARCHIVE> is the archive file type (tar or zip).

Procedure (for GNM only):

Extract the gnm_6.0.0.0.ifix004_. file into a separate directory on your hard drive.

As a precaution only, back up the following directories based on the platform on which you are installing the fix:

Platform	Files and Directories to Backup
AIX, Linux	`<GNM_ROOT>/bin`
	`<GNM_ROOT>/data`
	`<GNM_ROOT>/lib`
------------	---------------------------------
Windows	`<GNM_ROOT>\bin`
	`<GNM_ROOT>\data`
	`<GNM_ROOT>\lib`

If the GNM web service is in use, run <GNM_ROOT>/bin/stopGNMServer.sh, or on Windows run <GNM_ROOT>\bin\stopGNMServer.bat.
On all platforms, copy the files from <FIX_ROOT>/data to the <GNM_ROOT>/data directory.
On all platforms, copy the files from <FIX_ROOT>/sdk/<PLATFORM>/bin to the <GNM_ROOT>/bin directory.
On all platforms, copy the files from <FIX_ROOT>/sdk/<PLATFORM>/lib to the <GNM_ROOT>/lib directory.
On all platforms, copy the files from <FIX_ROOT>/jar to the <GNM_ROOT>/lib directory.
Copy the file <FIX_ROOT>/gnm_6.0.0.0.ifix004_version.txt to the <GNM_ROOT>/version directory. If the <GNM_ROOT>/version directory does not exist, create it.
To restart the GNM web service, run <GNM_ROOT>/startGNR.sh or on Windows run <GNM_ROOT>/startGNR.bat.

Procedure (for ENS only):

Extract the gnm_6.0.0.0.ifix004_. file into a separate directory on your hard drive.

As a precaution only, back up the following directories based on the platform on which you are installing the fix:

Platform	Files and Directories to Backup
Linux	`<ENS_ROOT>/bin`
	`<ENS_ROOT>/data`
	`<ENS_ROOT>/lib`
	`<ENS_ROOT>/ibm-home/wlp/apps`
------------	---------------------------------
Windows	`<ENS_ROOT>\bin’
	`<ENS_ROOT>\data`
	`<ENS_ROOT>\lib`
	`<ENS_ROOT>\ibm-home\wlp\apps`

Stop all ENS profiles. For example, if your ENS profiles are named p1 and p2:
On Windows, run <ENS_ROOT>\bin\stop-p1.bat and <ENS_ROOT>\bin\stop-p2.bat.
On Linux, run <ENS_ROOT>/bin/stop-p1.sh and <ENS_ROOT>/bin/stop-p2.sh.
If you have a distributed installation, repeat this stop step on all hosts.
Note that in a distributed ENS installation, <ENS_ROOT> is on the shared network drive used by all hosts, so the following copy steps only need to happen once.
On all platforms, copy the files from <FIX_ROOT>/data to the <ENS_ROOT>/data directory.
On Windows, copy the three *.dll files from <FIX_ROOT>/sdk//bin to the <ENS_ROOT>/bin directory.
On Linux, copy the three *.so files from <FIX_ROOT>/sdk//lib to <ENS_ROOT>/lib.
On all platforms, copy the *.jar files from <FIX_ROOT>/jar to <ENS_ROOT>/lib.
On all platforms, copy the ibm-infosphere-ens.ear file from <FIX_ROOT>/wlp/apps to the <ENS_ROOT>/ibm-home/wlp/apps directory.
Restart the ENS profiles. For example, if your ENS profiles are named p1 and p2:
On Windows, run <ENS_ROOT>\bin\start-p1.bat and <ENS_ROOT>\bin\start-p2.bat.
On Linux, run <ENS_ROOT>/bin/start-p1.sh and <ENS_ROOT>/bin/start-p2.sh. If you have a distributed installation, repeat this on all hosts.

V. Technical details:

Southwest Asian name handling

Cultural considerations are expanded in the parsing of Southwest Asian names, beyond the standard analysis of name frequency information.
This change improves the matching of Southwest Asian names where previous versions placed too many name phrases into the given name field.

Score logging in preprocessed name comparison

Preprocessed name comparison has limited and very specific usefulness, and is not recommended for most clients.

NDO overrides

Name Data Object overrides allow site-specific adjustments to the main internal database of name frequency data used by many aspects of Global Name Management name analysis and scoring operations.
Low-level component access is provided in a new gnrndo.h header file, and NameWorks access is provided through a new General configuration entry (NDOOverrides=filename).
Details of low-level access appear in the gnrndo.h header file. The NDOOverrides= configuration entry indicates the name of a file containing records that override NDO data.
A new NameWorks Configuration object method addNdoOverrideFile() has also been added.

NDO override data is supplied for individual countries associated with specific name phrases.
For each associated country relative frequency data is provided for surname and given name frequencies, with given name data split into female, male, and unknown values.

NDO override files use a configuration format similar to other GNM configuration data,
where a section name provides the name phrase being overridden and individual entries within a section provide per-country statistics for the related name phrase.
A special ‘Extends=true/false’ entry indicates whether the override data should replace any existing NDO data (Extends=false) or appear in addition to any existing data (Extends=true).
The ‘Extends=…’ entry is not required; the default value is ‘false’ (replace existing data).

Frequency data is expressed as a percentile ranking which provides a value relative to the overall collection of known name data.
Thus a single country data entry for the name LEONARD in Australia might contain a surname frequency of the 13th percentile, a female given name frequency of the 2nd percentile,
a male given name frequency of the 19th percentile, and an unknown given name frequency of the 5th percentile.
Given the NDO statistics at the time of this writing, the sum of given name frequencies would be of the 19th percentile.

All percentile ranking values must be in the range 0…100, otherwise an exception will be thrown when an attempt is made to add override data.

Each entry within a section contains an ISO-3166 two-letter country code (the same codes used in other areas of NameWorks) followed by a list of frequency percentiles for that specific country:
Code=surname_percentile,female_percentile,male_percentile,unknown_percentile

Thus an entry for LEONARD with two country overrides could appear as:
[LEONARD]
AU=13,2,19,5
GB=15,1,22,3

NDO override data affects parsing, culture classification, country association, genderization, and special scoring of short names.
NDO override data does not affect variant generation.

New custom parsing token types

To provide finer control over certain types of Title and Prefix tokens, two new custom parsing token types have been added.
These new token types represent name tokens that could appear as either a Title or a Given Name (TITLE_OR_GN, TitleOrGivenName) or as either a Prefix or a Given Name (PREFIX_OR_GN, PrefixOrGivenName).
These new token types can be set through the NameParser API (if low-level components are used), through NameWorks configuration files, or through NameWorks Configuration objects.
An example for a custom parsing token in a NameWorks configuration file:
[Custom Tokens]
SANTA=PrefixOrGivenName

Modifying internal user credentials in ENS

ENS 6.0 uses an internal set of credentials for communication among ENS components.
We recommend you modify the password and username for these credentials, as described below.
These credentials are not for the ENS admin user that you define at installation time; they are for a separate user internal initially named “ens-app-user”.

Changing the password:

If ENS is running, use the ENS console to stop the cell, and then stop all ENS profiles by running <ENS_ROOT>/bin/stop-<profileName> for each profile on each host.
With the profiles stopped, edit <ENS_ROOT>/ibm-home/wlp/users.xml
a. Find the line that begins <user name=“ens-app-user” and change it to:

(You will keep this temporary password only until step 5 below.)
In your first profile, edit the <ENS_ROOT>/wlp/usr/servers/<profileName>/jvm.options file:
a. Find the line that begins with -Dcom.ibm.ea.internal.app.user.password= and change it to:
-Dcom.ibm.ea.internal.app.user.password=changeMeNow
Start just your first profile with <ENS_ROOT>/bin/start-<profileName>. You don’t need to start the cell or browse to the ENS console.
Close and re-open your browser, and browse (assuming your first profile uses https port 14511) to https://<host>:14511/changePassword.jsp .
a. Log in with user name “ens-app-user” and password “changeMeNow”.
b. In the “Change Password” form, type the desired new password.
c. You should then see the message “Your password has been changed.” This
means that users.xml has been updated with the new password, now
aes-encoded.
d. Close your browser.
Stop the profile with <ENS_ROOT>/bin/stop-<profileName> command.
View the <ENS_ROOT>/ibm-home/wlp/users.xml file.
a. Find the line that begins <user name="ens-app-user", and copy the quoted string after password= . Don’t include the beginning or ending quotes.
In your first profile, edit the <ENS_ROOT>/wlp/usr/servers/<profileName>/jvm.options file:
a. Find the line that begins -Dcom.ibm.ea.internal.app.user.password= and replace the part after the equals sign with the string that you copied in step 7a.
b. Save the file.
Repeat step 8 for each of your other profiles, if any.
Edit the <ENS_ROOT>/installer/ensServerTemplate/jvm.options file: a. As above, find the line that begins with-Dcom.ibm.ea.internal.app.user.password=` and make the same change as in step 8.
b. Save the file. This file affects any profiles you create in the future using the enscu utility.
You can verify that the changes were successful by starting your profiles, starting the cell, and searching for a name.

Changing the username

In addition to changing the password for the internal ens user, you can
optionally change its username as well, as follows.

If ENS is running, use the ENS console to stop the cell, and then stop all ENS profiles by typing <ENS_ROOT>/bin/stop-<profileName> for each profile on each host.
With ENS stopped, edit <ENS_ROOT>/ibm-home/wlp/users.xml and change two lines:
a. Find the line that begins <user name=“ens-app-user” and change the name from “ens-app-user” to some new internal user name.
b. Under , find the line that says

and change the name from “ens-app-user” to the new internal user name you chose.
In your first profile, edit the <ENS_ROOT>/wlp/usr/servers/<profileName>/jvm.options file:
a. Find the line that says
-Dcom.ibm.ea.internal.app.user=ens-app-user
and change the name from “ens-app-user” to your new internal user name.
Repeat step 3 for each of your other profiles, if any.
Edit the <ENS_ROOT>/installer/ensServerTemplate/jvm.options file:
a. Find the line that says
-Dcom.ibm.ea.internal.app.user=ens-app-user
and change the name from “ens-app-user” to your new internal user name. This affects any profiles you create in the future using the enscu utility.
As before, you can verify that the changes were successful by starting your profiles, starting the cell, and searching for a name.
======================================================
END OF FILE

=========================================== IBM Global Name Management, Version 6.0.0.0