nealef / libascii Goto Github PK

  *********************************************************************
  *                                                                   *
  * libascii - ascii-ebcidic interface layer - README file            *
  *                                                                   *
  * Version 1.1.9                                                     *
  *                                                                   *
  * To report problems or ask questions send e-mail to:               *
  *                                                                   *
  *             [email protected]                                 *
  *                                                                   *
  * Copyright:   Licensed Materials - Property of IBM.                *
  *              (C) Copyright IBM Corp. 1997, 1998.                  *
  *              All rights reserved.                                 *
  *                                                                   *
  * License information:                                              *
  *                                                                   *
  *   The libascii source code is provided free of charge and         *
  *   may be distributed freely.  No fee may be charged if you        *
  *   distribute the libascii source code (except for such things     *
  *   as the price of a disk or tape, postage ).  The libascii        *
  *   makefile will compile and produce a libascii.a archive file.    *
  *   The libascii.a archive may be link edited  with any software    *
  *   vendor  product.  Any software vendor product that is link      *
  *   edit with libascii.a archive is free to distribute and charge   *
  *   for that product.                                               *
  *                                                                   *
  *   THIS PROGRAM IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY       *
  *   KIND, EXPRESS  OR IMPLIED, INCLUDING THE IMPLIED  WARRANTIES    *
  *   OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.        *
  *   IBM does not warrant uninterrupted or error free operation of   *
  *   the  Program, or that the Program is free from claims by a      *
  *   third party of copyright, patent, trademark, trade secret,      *
  *   or any other intellectual property infringement. IBM  has       *
  *   no obligation to provide service, defect correction, or any     *
  *   maintenance for the Program. IBM  has  no  obligation to        *
  *   supply any Program updates or enhancements to you even if       *
  *   such are or later become available.                             *
  *                                                                   *
  *    Under no circumstances is IBM liable for any of the            *
  *    following:                                                     *
  *                                                                   *
  *      1.  third-party claims against you for losses or damages;    *
  *      2.  loss of, or damage to, your records or data; or          *
  *      3.  direct  damages,  lost  profits, lost savings,           *
  *          incidental, special, or indirect damages or other        *
  *          consequential damages,  even if IBM or its authorized    *
  *          supplier, has been advised of the possibility of         *
  *          such damages.                                            *
  *                                                                   *
  *    Some jurisdictions do not allow these limitations or           *
  *    exclusions, so they may not apply to you.                      *
  *                                                                   *
  *                                                                   *
  *********************************************************************

  OVERVIEW

       The libascii package helps you port ASCII-based C applications 
       to the EBCDIC-based OS/390 OpenEdition environment. 

       If you are porting an application which has a lot of ASCII
       dependencies, then you may find there are a large number of
       changes required to port the application to EBCDIC-based OS/390.

       The C/C++ Run-Time Library functions support EBCDIC characters.
       The libascii package provides an ascii interface layer for some of
       the more commonly used C/C++ Run-Time Library functions.
       libascii supports ascii input and output characters by
       performing the necessary iconv() translations before and after
       invoking the C/C++ Run-Time Library functions. Note that not all 
       C functions are supported (see Limitations for additional 
       information). 

       The OS/390 1.3.0 C/C++ compiler predefined macro
       __STRING_CODE_SET__="ISO8859-1", will generate ASCII characters
       rather than the default EBCDIC characters.  Using this with
       libascii will provide an ASCII like environment.

       The libascii package is as thread safe as the Run-Time 
       library except where stated under limitations below.

       Note that not all C functions are supported (see LIMITATIONS
       section for additional information).

       In order to use the libascii functions you need to:

       o   Install the libascii code.

       o   Build the libascii.a archive file.

       o   Make minor modifications to your C source code and
           recompile, using the __STRING_CODE_SET__="ISO8859-1" flag

       o   Link edit your application with the libascii.a archive file.

       The libascii archive also contains four functions to convert 
       between IEEE floating point and S390 hex floating point.


  INSTALLING THE LIBASCII CODE

       The libascii TAR file contains all the parts required to create 
       the libascii archive. To install: 

            1.Create a directory where you want libascii installed. 

            2.Copy the TAR file to that directory. 

            3.Unwind the file using this command: 

                 tar -xvfz libascii.tar.Z

       The libascii source files, makefile, and readme file should 
       now be installed. 

  BUILDING THE LIBASCII ARCHIVE FILE (libascii.a)

       You can use the makefile file provided to build libascii.a 
       from the libascii source files. 

       To build libascii.a, cd into the directory with the libascii 
       source files and issue the make command. 

  BUILDING and RUNNING SAMPLES

       After you have made the libascii.a archive file, cd into the 
       samples directory and issue the make command. This builds the 
       samples. 

       To run the sample programs issue the following from the samples
       directory:

            sample1
            sample2

  USING LIBASCII

       After you have installed libascii and built the archive file, 
       to use the libascii functions you need to: 

       o   Make minor modifications to your C source code and 
           recompile, using the __STRING_CODE_SET__="ISO8859-1"
           predefined macro. 

       o   Link edit your application with the libascii.a archive file. 

       First it must determined which parts in your application will be
       compiled with -D__STRING_CODE_SET__="ISO8859-1" specified to 
	   generate ASCII strings.  It is possible that part of the application
       will be compiled to generate ASCII strings and the other part will 
       be compiled to generate EBCDIC strings.

       For all parts compiled with the -D__STRING_CODE_SET__="ISO8859-1" 
       libascii should be used.  The following steps describes how
       to use libascii:

       o   Find all the C/C++ Run Time Library functions which require
           EBCDIC input (for example, fopen()) or produce EBCDIC output
           (for example, readdir()). Both the "nm" shell command and
           the following grep command will help perform this task.
           The following grep command will display the file names that 
           contain a libascii function followed by the character '(' .

                grep -l -f /the-libascii-directory/libascii.lst *.c

       o   Determine which C/C++ Run Time Library functions obtained
           above are not supported by libascii.  (See LIMITATIONS
           section for additional information.)  For any unsupported
           functions you will need to either add functions to libascii
           or change the application  to add iconv() ASCII/EBCDIC 
           conversions around the run time library calls.

       o   Make sure all the required header files are included as
           specified in the OS/390 C/C++ Run-Time Library Reference.
           For example strncasecmp() requires <strings.h> to be 
           included.

       o   Add the following statement:

                  #include "_Ascii_a.h"

            to your source file, after all the existing #include
            statements.

       o   Recompile using the -D__STRING_CODE_SET__="ISO8859-1"
           option to cause the compiler to generate all strings
           defined in your program in ASCII rather than EBCDIC
           format.

       o   Link-edit your application with the libascii.a archive file. 

  FLOATING POINT CONVERSION 

           The libascii archive also contains four functions to convert 
           between IEEE floating point and S/390 native hex floating 
           point. The OS/390 1.3.0 C/C++ compiler does not support
           IEEE floating point. Math operators such as + (add) and 
           / (divide) and run-time library functions such as printf() 
           and sin() using IEEE floating point numbers will produce 
           undefined results. The main difference between the two 
           floating point formats is IEEE supports a larger range of 
           numbers, up to 10 to the 308 power. S/390 supports better
           precision but a smaller range, up to 10 to the 75 power. 

       The four floating point conversion routines included in libascii
       are as follows:

           void ConvertFloatToIEEE(void *source, void *destination);
           void ConvertDoubleToIEEE(void *source, void *destination);
           void ConvertIEEEToFloat(void *source, void *destination);
           void ConvertIEEEToDouble(void *source, void *destination);

  LIMITATIONS

       The libascii interface code is code that we found useful and is
       offered as is for your use.  It's intended to be used as an
       assistance in getting your applications running as quickly as
       possible.

       The following are some of the known restrictions:

       o   Not all the C functions are supported.

           The file libascii.lst contains a list of supported ascii run 
           time library routines.

       o   For some of the supported functions there are known
           restrictions, as follows:

           -   GETOPT function

               --  The libascii getopt() function is not thread-safe.
                   The second argument is changed for a short period of 
                   time from EBCDIC to ASCII and then back to EBCDIC. 

           -   PRINTF family functions

               --  The "%$n" specification is not supported in the
                   format string.
               --  These functions are limited to 2048 bytes of output.
                   To increase the size of the strings and output supported
                   change #define MAXSTRING_a in global_a.h

           -   SCANF family functions

               --  The "%$n" specification is not supported in the
                   format string.
               --  The maximum number of arguments supported is 20.
               --  These functions are limited to 2048 bytes of input.
                   To increase the size of the strings and output supported
                   change #define MAXSTRING_a in global_a.h

       o   The interface layer is not NLS-enabled; it only supports
           ISO8859-1 <-> IBM1040-1 character set conversions.

  FAQs

       The following are frequently asked questions:

         1. I compiled my code using -D__STRING_CODE_SET__="ISO8859-1" and
            included the _Ascii_a.h.  The printf output to stdout is 
            unreadable.

            Response: Not all the header files were included.  For example
                      libascii requires <stdio.h> to be included to use the
                      libascii version of printf().  If your application 
                      uses ctime() and you wish to use the libascii ctime
                      then <time.h> must be included.

                      Another possible error is _Ascii_a.h must be 
                      included after all the other header files.

         2. I compiled my code using -D__STRING_CODE_SET__="ISO8859-1" and
            included the _Ascii_a.h. The link edit of my application fails.

            Response: The application's "make" file needs to be modified
                      to specify libasii.a on the link edit.
  
  CHANGE HISTORY
       06/08/97 - Added gcvt() fuction
       06/08/97 - Fixed ctime already defined error message when time.h
                  is included.
       06/12/97 - Added undef for putc and putchar if already defined.
       06/18/97 - Removed K&R CTYPE macros isxxx() from _Ascii_a.h.  
                  Too many problems with callers passing parms
                  like c++ which incremented c more than once.
       06/23/97 - Improved all printf() to support strings larger than
                  1000 bytes.  MAXSTRING_a in global_a.h can be set to
                  the maximum printf() string the application requires.
       07/22/97 - Fixed gcvt and fcvt to return the same buffer passed 
                  on input. Fixed bug to printf() and sprintf() to print     
                  more than 199 characters. 
       10/16/97 - Fixed printf family of functions to handle %c when the
                  argument was '\0'.  (Example: frpintf(fp,"1 %c 2",'\0'); )
       10/30/97 - Fixed localconv() program check and inet_addr() from looping
       01/29/98 - Added +1 to length of malloc() in scanf_a.c and print_a.c.
                  A CEE dump occurred when the string did not take into   
                  account the null character at the end of the string.

                  Change    : Added support for gethostbyaddr
                  Parts     : _Ascii_a.h, netdb_a.c

                  Change    : Added support for inet_ntoa
                  Parts     : _Ascii_a.h, inet_a.c

                  Change    : Added support for OE Sockets versions of
                              functions gethostbyname, gethostbyaddr,
                              and getservbyname
                  Parts     : _Ascii_a.h, netdb2_a.c, makefile

                  Change    : Translated character string in structure
                              returned by gethostbyname, gethostbyaddr,
                              and getservbyname to ASCII
                  Parts     : netdb_a.c

                  Change    : Add support for tmpnam function.
                  Parts     : _Ascii_a.h, stdio_a.c
       02/10/98 - Fixed strtol and strtoul for case with NULL pointer
                  passed in 2 parameter.
       09/25/98 - Added macros for ctype.h isxxxxx() functions.
                  The macros are faster than function calls such as
                  __isascii_a(). The use of macros may be turned off by 
                  commenting out the following line in _Ascii_a.h
                      #define __CTYPE_MACROS__
                - Added catopen() and catgets() support
                - Fixed storage leak on thread termination by adding 
                       free(athdptr->epathname);
                - Fixed prelinker problem for duplicate setenv define
                  when export _CXX_STEPS=-1 is set.