This document describes how to use the cnls utility (cnls.exe), detailing how to set up customized language translation, test it, and apply it to your application.
NLS TRANSLATION
To set up a customized NLS translation, follow these steps:
  1. Start up the NLS utility by double clicking the cnls.exe, located in the CacheSys\Bin directory.
  2. Choose the server connection window, use the default LOCALTCP or select another server from the pull-down list. (Defined in the "Preferred Server" section).
  3. Under the Locale tab. Create the Locale with "New" in the lower right. Insert a description.
    The OK button in the lower right corner should then no longer be greyed out. Hit OK. Choose "Options" located at the top left of the screen and "Install the Locale". You can use the NLS "Import" or "Export" option, located in the far right corner, to import or export a locale from another Cache system. You can also import and export tables with this utility.
    Note: If selecting another standard locale as your current locale, you must use the NLS utility "Import Locale Option" to copy the locale definition from the Cache installation CD into the Cachesys\Bin directory. Standard locales are located in the \nt\install\eightbit or \nt\install\unicode directories. Locale definitions are the goq files. Locales are identified by a four-character locale name. Always import the_src.goq (source code) version of the locale. For example “English, United States Latin1” is “enu8_src.goq”. The install locale option also prompts you for these files from disk and you simply point it to the Cachesys\Bin directory or NLS Subdirectory.
  4. Go to the Translation Tab and set up the Translation Table choosing "New" in the lower right corner “Copy From,” is left blank. i.e. For printing use an "Output Only" table where "Translate From" would be "Latin 1" and "Translate To" is the new translation table which should always start with "y". If the translation is for terminal input, it would be an "Input Only" table and "Translate From", would be the new translation table and "Translate To" would be "Latin 1". "Mapping Type" is primarily "Single to Single" unless you have multiple characters you want to translate into one, or multiple to multiple which would then be a "Multiple to Single" or "Multiple to Multiple" table. The characters are translated in the table on on the far right. By default they are displayed in decimal, which are the ascii values. The table can also be displayed in hex or character mode. This is adjusted in the top left corner under the "Help" option. To set up your translation, you simply change the values in either row or add new values at the bottom next to the *.
  5. Once the translation table is set up go back to the "Locale Tab" to update it with the new translation table. In the "Translation Name Grid (the middle grid), go to the * to add your translation. Here you can call it anything you want. i.e. "sueprint" Then move over to the "Output" tab, or "Input" tab, whichever you are using, the drop down list should contain your new translation table, which you then choose. Depending on what you are translating "input" vs "output", you should always have a default table as a placeholder in either the "input" or "output" column. The Translation Name name is critical, as this is the name used by Cache to specify I/O translation. Each translation name is associated with an Output and an Input character set.
  6. Go to the "Translation Type" grid (the bottom grid), and change the "Programmer Window" to your new "Translation Name" i.e. "sueprint" (the name you assigned in the second grid) so that you can test the translation. The "Translation Name" is the name used by Cache to specify I/O translation. Each translation name is associated with an Output an Input character set.
  7. Install or Validate the locale again with the new translation. Validate compiles the sources for the tables and loads the objects into shared memory. Install validates the locale and makes it the current one.
  8. Open up a new terminal window:
    w $zm
    should list the translation name that you updated your locale with.
    >w $zm
    >RY\Latin1\K\SUEPRINT
    Note: i.e. Translation Name is "sueprint"
Additional Notes
To set translation for a printer, you set the translation when the device is opened.
u x s zzz=$$SetIO^%NLS("sueprint") 
Use the following syntax to test it:
>s x="|PRN|"

>o x
 
>u x s zzz=$$SetIO^%NLS("sueprint") w $C(146),!,$C(147),!
 
>c x
The $ZCVT function allows you to test your translation with the following syntax where "ySue" is the output translation table.
>f I=0:1:255 s x=$ZCVT($C(i),"o","ySue") if x'=$c(i) w I," ",$a(x),!
>177 49
 178 50
 180 52
 183 55
 184 56
 231 103
These are the translated characters.
The Do Dump^%NLSMISC command lists the %NLS settings. An example of the sections of this appears below.
I/O Table Name      Offset:Type       Source Global
--------------      -------------     -------------
UnicodeLittleIn     4A0030:Struct8
           Out      4A0038:Struct8
UnicodeBig In       4A0020:Struct8
           Out      4A0028:Struct8
SAME       In       4A0000:Struct8
           Out      4A0008:Struct8
UTF8       In       4A0AAC:Struct8    %nls("Src","XLT","UTF8","Latin1")
           Out      4A0AB8:Struct8    %nls("Src","XLT","Latin1","UTF8")
BIN        In       4A0000:Struct8
           Out      4A0008:Struct8
RAW        In       4A0000:Struct8
           Out      4A0008:Struct8
Ricky      Out      4A0098:Struct8    %nls("Src","XLT","Latin1","yAquis")
$X/$Y Table Name    Offset:Type       Source Global
----------------    -------------     -------------
Latin1              4A0074:Struct8
Collation Table     Offset:Type       Source Global
---------------     -------------     -------------
 0         Enc      Old ANSI
           Dec
 1         Enc      New ANSI
           Dec
 2         Enc
           Dec
 3         Enc
           Dec
 4         Enc
           Dec
 5         Enc      Unicode
           Dec
128        Enc      Old string
           Dec
129        Enc      New string
           Dec
133        Enc      Unicode string
           Dec
Default             Offset:Type       Source Global
-------             -------------     -------------
Pattern             4A0040:Struct8
Ident               4A004C:Struct8
UpperCase           4A0080:Struct8
LowerCase           4A008C:Struct8
TitleCase           4A0080:Struct8
I/O Default         Offset:Type       Name
-----------         -------------     ----
Process             490233:ByteStr    Ricky
Direct Term         490233:ByteStr    Ricky
Telnet/LAT          490002:ByteStr    RAW
File                490002:ByteStr    RAW
Magtape             490002:ByteStr    RAW
Network             490002:ByteStr    RAW
DSM-DDP             490002:ByteStr    RAW
DTM-DCP             490002:ByteStr    RAW
SysCalls            490002:ByteStr    RAW
$X/$Y Default       Offset:Type       Name
-------------       -------------     ----
Process             49002D:ByteStr    Latin1
 
I/O Slots           All Empty
 
$X/$Y Slots         All Empty
Process             Offset:Type       Source Global
-------             -------------     -------------
Pattern             4A0040:Struct8
Ident               4A004C:Struct8
UpperCase           4A0080:Struct8
LowerCase           4A008C:Struct8
TitleCase           4A0080:Struct8
Process I/O         Offset:Type       Name
-----------         -------------     ----
Process             490233:ByteStr    Ricky
Direct Term         490233:ByteStr    Ricky
Telnet/LAT          490002:ByteStr    RAW
File                490002:ByteStr    RAW
Magtape             490002:ByteStr    RAW
Network             490002:ByteStr    RAW
DSM-DDP             490002:ByteStr    RAW
DTM-DCP             490002:ByteStr    RAW
SysCalls            490002:ByteStr    RAW
Process $X/$Y       Offset:Type       Name
-------------       -------------     ----
Process             49002D:ByteStr    Latin1
To check the locale setting do the following:
>d ^%G
>Global ^%SYS("LOCALE","CURRENT") -- NOTE: translation in effect
>^%SYS("LOCALE","CURRENT")=yaq8
Entry Points for General Functionality
The following is a list of the entry points in ^%NLS. Each entry point is in the form EntryPoint(Arg), where the full name of the call is $$EntryPoint^%NLS(Arg).
Entry Points for Modal Transactions
The following operations are for modal translations only:
Entry Points for Managing Replacement Attributes for I/O Translations
These functions set or get replacement attributes for I/O translations. These functions return a replacement status, where:
Some of the functions accept arguments, which are either:
The functions are:
The “Set” functions typically return the prior setting, when this value is meaningful.