Creating a New eComStation NLV in CVS

An NLV (National Language Version) build is normally referred to by its assigned locale name, which takes the form 'xx_yy'.




Existing NLV locales names include:


There is also a two-letter abbreviation used in some cases to refer to the language alone. This is the same as the 'xx' portion of the locale name, with the exception of the two Chinese languages: Simplified Chinese is CN and Traditional Chinese is TW.

In addition, the numerical three-digit country code is used in some contexts. This is referred to in this document as 'ZZZ'.



Each NLV must have the following directories or directory trees in CVS, following the naming convention described above:

• ecsInst1_2\xx_yy
• ecsInst1_2\SOURCE\xx_yy
• ecsInst1_2\SOURCE\COMMON\GPS\xx
• ecsInst1_2\SOURCE\LIST\xx_yy
• ecsInst1_2\COMMON\ECS\BOOT\DESKTOP\ZZZ
• ecsInst1_2\COMMON\ECS\INSTALL\NLS\xx
• ecsInst1_2\PROGRAM\MEMDISK\BIN\xx

(Note that some software packages also have language- or country-specific subdirectories and/or files; however, these are generally only required to support user interaction in the given language, and are not needed for a functioning install.)

Creating the NLV tree

1. Create the NLV-specific directories (in your CVS sandbox) listed above.

2. Populate the ecsInst1_2\SOURCE\xx_yy directory tree by copying the contents from an existing NLV. (Note: SBCS and DBCS versions are slightly different, so copy files from the appropriate one. You should generally use EN_US as the source for a new SBCS NLV, and JA_JP for a new DBCS NLV.)

IMPORTANT: Make sure you remove all 'CVS' subdirectories from the new directory tree. New 'CVS' subdirectories will be created (with the proper information) when you run 'cvs add' later on.

• Now go through each directory and replace all relevant files with the correct versions (if they exist) from the new NLV language. Language-specific files which lack versions in the new language should be left in their English versions until they can be translated.

• Make sure that (only) the correct language directory (xx) exists under ecsInst1_2\SOURCE\xx_yy\SGUIDE\ECS\SYSTEM\SGUIDE\NLS.

• Also add the files ecsInst1_2\SOURCE\COMMON\GPS\xx\*.GPS by copying them from an existing NLV.

3. Adjust the contents of the ecsInst1_2\SOURCE\xx_yy\ECSDISK* directories as necessary for the NLV. You should replace the following files with versions specific to the new NLV (which you can normally get from the OS/2 MCP2 CD for that language, if one exists):



(You should also take the opportunity to verify that the kernel boot files (OS2KRNL, OS2BOOT, OS2DUMP, OS2LDR and OS2LOGO) are the same as the ones in the ecsInst1_2\SOURCE\COMMON\KERNEL directory.)

The actual set of files is generally the same for all SBCS versions. However, in addition to the above, all DBCS NLVs require their own specific files in the ECSDISK3 directory (in particular the system font files *.MAP and *.FNT). Examine a MCP/WSeB boot system for the NLV in question to determine the specific files needed. Be sure to edit the ECSDISK*.LST packfiles to reflect any changes you make to the directory contents.

Especially, note the following for DBCS versions:

• $SYSINDX.FNT points to the font files used for DBCS text (used in both text and PM sessions). Make sure that it points to the correct path - this will be relative to the memory disk, so the font files should generally be located on the memory disk in order to be found correctly (generally the root directory).
• The file _SYSINDX.FNT is an alternate name for $SYSINDX.FNT apparently designed for FAT compatibility. It should not be included in the boot images.
• Similarly, there are three .FNT files whose names begin with _. These are stripped-down versions of the corresponding full versions (beginning with $) for use in floppy/text only systems. These files must not be included in the boot images - if they exist at all, they will be loaded in preference to the full versions, whether or not they are listed in $SYSINDX.FNT!
• Alternating versions of KBDBASE.SYS (for each selectable keyboard layout) are required in ECSDISK1. These must be obtained from the corresponding packfiles on the DBCS MCP2 CD, usually titled "KBD??" where ?? is the name of the keyboard layout (e.g. 'US', 'AX').

4. Edit the preboot options file ecsInst1_2\SOURCE\xx_yy\OS2CSM\MENU.BRN:

• Set '<ECS_DBCS>' as appropriate.

• Country spinbutton: change '<MISC_LOC_COUNTRY_DEFAULT>' and '<MISC_LOC_CCVALUE_DEFAULT>' to the correct locale values (from the list).

• Keyboard spinbutton: make sure the correct keyboard values are present in the list. (Do NOT increase the number of items in the list.) Then set '<MISC_LOC_COUNTRY_DEFAULT>' and '<MISC_LOC_CCVALUE_DEFAULT>' to those values (they must be identical to the list entries).

• Codepage spinbutton: change '<MISC_LOC_CODEPAGE_DEFAULT>' to the correct locale values (from the list).

• Set '<MISC_LOC_LOCALE>' and '<MISC_LOC_TIMEZONE>' as appropriate per the file comments.

• Set '<MISC_LOC_CHARSET>' to either 'SBCS' or 'DBCS' as appropriate.

• Set '<MISC_LOC_TCPMSG>' and '<MISC_START_INST_LANG>' as appropriate per the file comments.

5. Populate the ecsInst1_2\xx_yy directory tree. (All references to the MCP2 CD are assumed to be that of the NLV in question, if one exists):

• Create the subdirectory BOOTIMGS. Copy the file README.TXT from another NLV to this directory.

• Copy the following directories and all their contents (including subdirectories) from the MCP2 CD-ROM (or from another NLV if there is no MCPx CD available, but in this case you must omit the 'CVS' subdirectories):
  • CID\DLL
  • CID\EXE (except for SEINST.EXE)
  • CID\LOCINSTU
  • CID\SERVER (except for the JAVA131 subdirectory)
  • CID\SRVIFS
  • CID\WINDOWS
  • OS2IMAGE

• Create the subdirectory DISKIMGS and copy IMAGE.EXE and LOADDSKF.EXE from the same directory on the MCP2 CD-ROM. Copy SELECT.COM and SELECT.EXE from another NLV.

• Examine CID\EXE\OS2\SAMPLE.RSP on the MCP2 CD-ROM to see if there are any response file options specific to this NLV.

• Copy the ECS directory tree from another NLV. Replace any files that have versions available in the new NLV. Remember to delete all 'CVS' subdirectories.

• Adjust the INI file templates in ECS\INSTALL\DESKTOP with any specific entries required by the new NLV. Pay particular attention to the 'PM_National' entries in INI.RC, as well as to those referring to DBCS-specific fonts and other items (which should be copied from the INI.RC file from an MCP2 system of that DBCS language).

• Edit the file ecsInst1_2\SOURCE\xx_yy\OS2CSM\CONFIG.BRN and set the value for <DESKTOP_BUILD_SUBDIR> to ZZZ (the NLV country code).

6. Apply the necessary modifications for the eCS build environment (and required patches) to the IBM product images:

• The MPTS files under CID\SERVER\MPTS need updating.
  • Under the the IBMGSK* directories (there are three), rename the COPYRI~1.TXT files to COPYRT.TXT.
  • Delete the files MPTN\PROTOCOL\MPROT2.ZIP and IBMCOM\MACS\MACS.ZIP (as these are taken from the COMMON tree).
  • Modify the file MPTN\BIN\BIN.ZIP by adding the LLAECS.EXE program. Make sure the modified ZIP file is compatible with the old version of PKUNZIP2 used by the MPTS installer. (The old zip program can be found under \program\bin\infozip1.exe in the CVS root)

• Some patches are required for the IBM installer:
  • Rename OS2IMAGE\DISK_6\LVM.DLL to IVM.DLL using the DLLRNAME utility: "dllrname lvm.dll LVM=IVM". (It may be necessary to force the MZ header on LVM.DLL first using LXLITE: "lxlite lvm.dll /c:minstub".)
  • Copy LVM.DLL from another NLV to OS2IMAGE\DISK_6, and to OS2IMAGE\FI\LVMGUI. This is a special wrapper DLL which calls the "real" LVM.DLL (as IVM.DLL).
  • Update OS2IMAGE\DISK_5\BUNDLE (or whichever packfile contains LVM.DLL) to replace LVM.DLL with the wrapper, and add the renamed IVM.DLL.
  • For DBCS versions, full-screen prompts do not work when booted from CD. Therefore, RSPINST.EXE must be marked as VIO-compatible using MARKEXE in order to prevent it from hanging: "markexe rspinst.exe windowcompat".
  • Rename DISK_3\CHKINST.EXE to CHKINST2.EXE, and copy CHKINST.INI and CHKINST.EXE to this directory from another NLV.

• Convert all directory names to uppercase. You can use "case -dur" if you have case.exe installed.

• Delete the following files from the OS2IMAGE directory tree (as they already exist under the COMMON tree):
  • OS2IMAGE\FI\SYSMGT\OS2\INSTALL\*
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\kernel.sdf
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\kerneld.sdf
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\PMDF.EXE
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\WARP45\df_ret.exe
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\WARP45\kernel.sdf
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\WARP45\kerneld.sdf
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\WARP45\os2krnlb.sym
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\WARP45\os2krnlr.sym
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\WARP45_S\df_ret.s1
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\WARP45_S\df_ret.s2
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\WARP45_S\kernel.s1
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\WARP45_S\kernel.s2
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\WARP45_S\kerneld.s1
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\WARP45_S\kerneld.s2
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\WARP45_S\os2krnlb.s1
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\WARP45_S\os2krnlb.s2
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\WARP45_S\os2krnlr.s1
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\WARP45_S\os2krnlr.s2
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\WARP45_U\df_ret.u1
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\WARP45_U\df_ret.u2
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\WARP45_U\kernel.u1
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\WARP45_U\kernel.u2
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\WARP45_U\kerneld.u1
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\WARP45_U\kerneld.u2
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\WARP45_U\os2krnlb.u1
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\WARP45_U\os2krnlb.u2
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\WARP45_U\os2krnlr.u1
  • OS2IMAGE\FI\SYSMGT\OS2\PDPSI\PMDF\WARP45_U\os2krnlr.u2
  • OS2IMAGE\FI\SYSMGT\OS2\SYSTEM\TRACE\*
  • OS2IMAGE\FI\SYSMGT\SMP\*
  • OS2IMAGE\DEBUG\SMP\*
  • OS2IMAGE\DEBUG\UNI\*
  • OS2IMAGE\DISK_0\OS2KRNLI
  • OS2IMAGE\DISK_0\OS2LDR
  • OS2IMAGE\DISK_0\OS2DUMP

7. Update ecsInst1_2\SOURCE\LIST\xx_yy\Makefile.OS2 and DIRLIST.LST:

• You need to determine exactly what files required for the bootable CD system must reside on the CD itself, and where. (These are generally the same for all SBCS versions, but each DBCS version may have a number of differences.) The list of targets at the top of Makefile.OS2 must include all these files.

• You also need to determine exactly where in the OS2IMAGE tree (i.e. DISK_* subdirectory and packfile name) each file can be found. Then update the make instructions to extract/copy each file to the necessary location in the CD structure.

• For DBCS versions, make sure the directory OS2\SYSDATA is specified in DIRLIST.LST (the list of work tree directories to create). This is required in order for many vital DBCS files to be copied.

8. Populate the ecsInst1_2\PROGRAM\MEMDISK\BIN\xx directory by copying the files from another NLV.

9. Create the Guided Procedure scripts:

• Populate the ecsInst1_2\COMMON\ECS\INSTALL\NLS\xx directory by copying the contents of one of the other language subdirectories.

• Make the following changes to these files:
  • In EISTART.GPS, make sure that the lone uncommented language listed under the Data = LANGUAGE section is the appropriate one for this NLV (add it if necessary).
  • In EINSTLOC.GPS, make sure that the necessary country and keyboard codes are included in their respective lists. (For SBCS, it should not be necessary to make any changes to this file. For DBCS, countries and keyboards other than those specific to the current NLV should be removed. NOTE: DBCS versions may allow a choice of multiple keyboards, which are often not supported by the ecsInst1_2\COMMON\ECS\INSTALL\KBDMAP.CMD script. If this is the case, you can identify these keyboards using arbitrary names, but you must modify ecsInst1_2\COMMON\ECS\INSTALL\DEFAULT\DEFRSP.CMD to process these names correctly.)
  • In EIENDPH1.GPS and EIENDPH2.GPS, change the two-letter language code passed to PATHSED.CMD to the correct (xx) value.
  • In RIENDPH0.GPS, RIENDPH1.GPS, and RIENDPH2.GPS, change the two letter language code passed to NETPATH.CMD and MKSTART.CMD to the correct (xx) value.

10. Edit the script ecsInst1_2\CONFIGURE.CMD, and make sure that xx is included in the 'short_languages' string, and xx_yy in the 'long_languages' string.

Building

You should now be ready to try building the NLV installation CD. Run 'configure' to select the new language, and then 'make iso'.

Some common errors you may encounter:

• Boot hangs when loading CDFS.IFS. Edit the CONFIG.SYS template for OS2CSM and try removing the /Q switch from CDFS.IFS (this problem generally affects DBCS versions).
• TRAP in PMDD right before Presentation Manager starts. Make sure that the build process is successfully copying all the SNAP files (it may fail if SNAP uses a different two-letter language code for the NLV-specific files).
• Hang immediately after PM starts on DBCS versions. This generally indicates that KBDBASE.SYS is out of synch with the CODEPAGE and/or DEVINFO values. Make sure that the correct KBDBASE.SYS is on the memory disk for the codepage and keyboard in question. (Remember that DBCS versions must use the correct keyboard value for the DEVINFO=KBD statement.)

Other Tasks

1. Apply the latest FixPaks and other updates to the OS2IMAGE and CID\SERVER trees. This is done using UpdCD. (Instructions not included here.)
IMPORTANT: After applying FixPaks, the updates for Step 6 under Creating the NLV Tree must be (re-)applied (as must the steps listed below, if already done).

2. Install the updated JFS drivers required to support Bootable JFS

3. Patch LVM.DLL for the 1024-cylinder and Boot Manager fixes.

4. Update the Peer install files with the SMP fix from IBM.

5. (Optional) Delete all files named PACK?? from under OS2IMAGE\DISK_* except for the one which contains MMPMDIG.FON (these files are no longer needed as the multimedia files are installed separately). This frees up several megabytes of disk space on the final CD.

6. Create the Selective Installer patch for this NLV. This requires replacing PATCH_SI.ZIP (located in the xx_yy\CID\SERVER\ECSPKG directory) with one that contains properly-updated versions of BLISTLAY.OUT and INSTRES.DLL.

• Copy INSTRES.DLL from wherever it is packed inside the OS2IMAGE tree, and patch the resources to set controls #5905, 5906 (SBCS only), 5604, 5605 (SBCS only), 6200 and 6300 (SBCS only) in dialog #136 to set the "NOT WS_VISIBLE" flag. (This disables the Primary and Secondary Display controls.)
• BLISTLAY.OUT should be copied from xx_yy\OS2IMAGE\DISK_3 and then modified so that all PACK* lines are removed.