From da5378bd85de442a8e48b706618d5d921b9cc729 Mon Sep 17 00:00:00 2001 From: George Rhoten Date: Thu, 2 Aug 2001 01:55:34 +0000 Subject: [PATCH] ICU-1080 general readme.html updates X-SVN-Rev: 5420 --- icu4c/readme.html | 1122 +++++++++++++++++++++++++-------------------- 1 file changed, 625 insertions(+), 497 deletions(-) diff --git a/icu4c/readme.html b/icu4c/readme.html index f91c5bbfad2..9b2508c2ac9 100644 --- a/icu4c/readme.html +++ b/icu4c/readme.html @@ -8,19 +8,21 @@ + "The introduction to the International Components for Unicode with instructions on building, installation, usage and other information about ICU."> ReadMe for ICU @@ -28,81 +30,68 @@

International Components for Unicode
ReadMe

-

Version: 2001-Jun-13
+

Version: 2001-Aug-01
Copyright © 1995-2001 International Business Machines Corporation and others. All Rights Reserved.

-


-
-

+

Table of Contents

-

Contents

+ - -

OS/390 Batch (PDS) - support

- -

By default, ICU builds its libraries into the HFS. However, there is a - 390-specific switch to build some libraries into PDS files. The switch is - the environmental variable OS390BATCH, and if set, the following - libraries are built into PDS files: libicuucXX.dll, - libicudtXXe.dll, libicudtXXe_390.dll, and libtestdata.dll. - Turning on OS390BATCH does not turn off the normal HFS build, thus the - HFS dlls will always be created.

- -

The names of the PDS files are determined by the value of the - environmental variables LOADMOD and LOADEXP. These variables must contain - the target PDS names whenever the OS390BATCH variable is set. LOADMOD is - the library (.dll) target dataset and LOADEXP is the side deck (.x) - target dataset.

- -

The PDS member names are as follows:

-
-IXMICUUC --> libicuucXX.dll
-IXMICUDA --> libicudtXXe.dll
-IXMICUD1 --> libicudtXXe_390.dll
-IXMICUTE --> libtestdata.dll
-
-

Example PDS attributes are as follows:

-
-Data Set Name . . . : USER.ICU.LOAD
-General Data
-Management class. . : **None**
-Storage class . . . : BASE
-Volume serial . . . : TSO007
-Device type . . . . : 3390
-Data class. . . . . : LOAD
-Organization  . . . : PO
-Record format . . . : U
-Record length . . . : 0
-Block size  . . . . : 32760
-1st extent cylinders: 40
-Secondary cylinders : 59
-Data set name type  : PDS
-
-Data Set Name . . . : USER.ICU.EXP
-General Data
-Management class. . : **None**
-Storage class . . . : BASE
-Volume serial . . . : TSO007
-Device type . . . . : 3390
-Data class. . . . . : **None**
-Organization  . . . : PO
-Record format . . . : FB
-Record length . . . : 80
-Block size  . . . . : 3200
-1st extent cylinders: 3
-Secondary cylinders : 3
-Data set name type  : PDS
-
- -

OS/400 Platform

- -

ICU Reference Release 1.8.1 contains partial support for the 400 - platform, but additional work by the user is currently needed to get it - to build properly. A future release of ICU should work - out-of-the-box under OS/400.

- - - -

How To Build And Install ICU

- -

How To Build And Install On +

How To Build And Install On Windows

Building International Components for Unicode requires:

@@ -914,9 +723,9 @@ Data set name type : PDS indicates where the locale data files and conversion mapping tables are located. -
  • Be sure that the ICU binary directory, $Root\bin\, - is included in the PATH environment variable. The - tests may not work without the DLL files in the path.
    • +
  • Be sure that the ICU binary directory, $Root\bin\, is included in + the PATH environment variable. The tests may not work + without the DLL files in the path.
  • Set the TZ environment variable to PST8PDT. The tests will not work in any other @@ -996,7 +805,7 @@ Data set name type : PDS
  • intltest and cintltst, if you want to run the test suite.
    • -

    How To Build And Install On Unix

    +

    How To Build And Install On Unix

    There is a set of Makefiles for Unix that supports Linux w/gcc, Solaris w/gcc and Workshop CC, AIX w/xlc and OS/390 with C++.

    @@ -1004,10 +813,9 @@ Data set name type : PDS

    Building International Components for Unicode on Unix requires:

    A UNIX C++ compiler, (gcc, cc, xlc_r, etc...) installed on the target - machine. A recent version of GNU make (3.7+). OS/390 gnu utilities for - both make (gmake) and zip (gzip/gunzip) can be found at the MKS web site - at http://www.mks.com. Please do a - search on "os/390".

    + machine. A recent version of GNU make (3.7+). For a list of OS/390 tools + please view the OS/390 build section of + this document for further details.

    The steps are:

    @@ -1082,6 +890,321 @@ Data set name type : PDS
  • intltest and cintltst, if you want to run the test suite.
    • +

    OS/390 (zSeries) Platform

    + +

    If you are building on the OS/390 UNIX System Services platform, it is + important that you understand a few details:

    + + + +

    OS/390 Batch (PDS) support

    + +

    By default, ICU builds its libraries into the HFS. However, there is a + 390-specific switch to build some libraries into PDS files. The switch is + the environmental variable OS390BATCH, and if set, the following + libraries are built into PDS files: libicuucXX.dll, + libicudtXXe.dll, libicudtXXe_390.dll, and libtestdata.dll. + Turning on OS390BATCH does not turn off the normal HFS build, thus the + HFS dlls will always be created.

    + +

    The names of the PDS files are determined by the value of the + environmental variables LOADMOD and LOADEXP. These variables must contain + the target PDS names whenever the OS390BATCH variable is set. LOADMOD is + the library (.dll) target dataset and LOADEXP is the side deck (.x) + target dataset.

    + +

    The PDS member names are as follows:

    +
    +IXMICUUC --> libicuucXX.dll
+IXMICUDA --> libicudtXXe.dll
+IXMICUD1 --> libicudtXXe_390.dll
+IXMICUTE --> libtestdata.dll
+
    + +

    Example PDS attributes are as follows:

    +
    +Data Set Name . . . : USER.ICU.LOAD
+General Data
+Management class. . : **None**
+Storage class . . . : BASE
+Volume serial . . . : TSO007
+Device type . . . . : 3390
+Data class. . . . . : LOAD
+Organization  . . . : PO
+Record format . . . : U
+Record length . . . : 0
+Block size  . . . . : 32760
+1st extent cylinders: 40
+Secondary cylinders : 59
+Data set name type  : PDS
+
+Data Set Name . . . : USER.ICU.EXP
+General Data
+Management class. . : **None**
+Storage class . . . : BASE
+Volume serial . . . : TSO007
+Device type . . . . : 3390
+Data class. . . . . : **None**
+Organization  . . . : PO
+Record format . . . : FB
+Record length . . . : 80
+Block size  . . . . : 3200
+1st extent cylinders: 3
+Secondary cylinders : 3
+Data set name type  : PDS
+
    + +

    OS/400 (iSeries) Platform

    + +

    ICU Reference Release 1.8.1 contains partial support for the 400 + platform, but additional work by the user is currently needed to get it + to build properly. A future release of ICU should work out-of-the-box + under OS/400.

    + + + +

    Important Notes About Using ICU

    + +

    Windows Platform

    + +

    If you are building on the Win32 platform, it is important that you + understand a few build details:

    + +

    DLL directories and the PATH setting: As delivered, the + International Components for Unicode build as several DLLs. These DLLs + are placed in the "icu\bin" directory. You must add this directory to the + PATH environment variable in your system, or any executables you build + will not be able to access International Components for Unicode + libraries. Alternatively, you can copy the DLL files into a directory + already in your PATH, but we do not recommend this. You can wind up with + multiple copies of the DLL and wind up using the wrong one.

    + +

    To change your PATH:

    + + + +

    Link with Runtime libraries: All the DLLs link with the C + runtime library "Debug Multithreaded DLL" or "Multithreaded DLL." (This + is changed through the Project Settings dialog, on the C/C++ tab, under + Code Generation.) It is important that any executable or other DLL you + build which uses the International Components for Unicode DLLs links with + these runtime libraries as well. If you do not do this, you will + seemingly get memory errors when you run the executable.
    +

    +

    Using Shared Data Libraries

    HP/UX has a documented characteristic where the shl_unload() function @@ -1093,59 +1216,64 @@ Data set name type : PDS libicudata.sl) by a process, it cannot be unloaded and replaced without stopping and restarting the process.

    +

    Getting More Information About ICU

    -

    Important Change Of Error Codes From - Streaming Conversion Functions (change for ICU 1.6)

    + + -

    We have decided to make a semantic change to the conversion API which - affects applications using ICU that are migrated to use ICU versions 1.6 - or later compared to earlier ICU versions before 1.6:
    - The error code that is set from streaming conversion like

    -
    -ucnv_fromUnicode() - ucnv_toUnicode()
-ucnv_fromUChars()  - ucnv_toUChars()
-scsu_compress()    - scsu_decompress()
-
    - when the target buffer is full but the source not empty is changed from - U_INDEX_OUTOFBOUNDS_ERROR to - U_BUFFER_OVERFLOW_ERROR. This change makes the error codes - more consistent with their names and with their use in other icu - APIs.
    -
    + + + + -

    You need to test for this new error code if your code uses ICU for - conversion and used the old error code. ucnv.h and scsu.h are updated - with this information. Please search in your source code for - U_INDEX_OUTOFBOUNDS_ERROR. If it is used with the above - functions (not with ucnv_getNextUChar()), then you - need to change it to U_BUFFER_OVERFLOW_ERROR in order to get - your code to work with icu 1.6 or later.

    + + -

    See the updated sample code in icu/source/samples. All - samples are updated. See - jitterbug 516 for details. This was discussed in July 2000 on the icu - mailing list. Please see the list archive for the discussion.

    + + -

    Where To Find More Information

    + + -

    http://oss.software.ibm.com/icu/ - is the homepage of the International Components for Unicode.

    + + -

    The API Documentation is available online or for download. The (draft - of) the User Guide is available for browsing and as a PDF - file.

    + + -

    http://www.ibm.com/developer/unicode/ - is a pointer to information on how to make applications global.

    + + + + + + + + + + + + + + + + + + + +
    + Here are some useful links regarding ICU and internationalization in + general. +
    http://oss.software.ibm.com/icu/International Components for Unicode homepage
    http://oss.software.ibm.com/icu/userguide/icufaq.htmlFrequently asked questions about ICU
    http://oss.software.ibm.com/icu/downloadDownload the latest version of ICU and + documentation
    http://oss.software.ibm.com/icu/apiref/API Documentation in HTML form
    http://oss.software.ibm.com/icu/userguide/Draft User's Guide Documentation in HTML form
    http://oss.software.ibm.com/icu/userguide/icu.pdfDraft User's Guide Documentation in PDF form
    http://www.ibm.com/developer/unicode/Information on how to make applications global.

    Submitting Comments, Requesting Features and Reporting Bugs

    @@ -1157,7 +1285,6 @@ scsu_compress() - scsu_decompress() submitted and/or fixed yet, then please submit a jitterbug.

    -

    Copyright © 1997-2001 International Business Machines Corporation @@ -1167,3 +1294,4 @@ scsu_compress() - scsu_decompress() All rights reserved.

    +