grey_rule.gif

  Overview

The libascii functions are integrated into the base of the Language Environment. They help you port ASCII-based C applications to the EBCDIC-based  z/OS UNIX environment.

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 XL C/C++ compiler predefined macro __STRING_CODE_SET__="ISO8859-1" generates ASCII characters rather than the default EBCDIC characters. Using this with the libascii code provides an ASCII-like environment.

The libascii package is as thread-safe as the run-time library except where stated under Limitations below.

You can download the package. The libascii source code is licensed by IBM; for more information, see the readme file in the package.

We have instructions on downloading through your browser and anonymous FTP.


  Floating point conversion

The libascii archive also contains four functions to convert between IEEE floating point and S/390 native hex floating point. The XL 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:

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

  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 -xvfoz 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 the 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 these commands from the samples subdirectory:

   sample1
   sample2

  Using libascii

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

  • Make minor modifications to your C source code and recompile, using the __STRING_CODE_SET__="ISO8859-1" predefined macro.
  • Link-edit your application with the libascii.a archive file.

First, you need to determine 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", use libascii. The following steps describe what to do with a program that will use the libascii functions:

  1. Find all the C/C++ functions that 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. This grep command displays the file names that contain a libascii function followed by the character ( :
    grep -l -f /the-libascii-directory/libascii.lst *.c
    
  2. Determine which C/C++ functions obtained above are not supported by libascii. (See Limitations for additional information.) For any unsupported functions, you will need to either add functions to libascii or change the code to add iconv() ASCII/EBCDIC conversions around the runtime library calls.
  3. Make sure all the required header files are included, as specified in the XL C/C++ Run-Time Library Reference, SC28-1663. For example strncasecmp() requires to be included.
  4. Add the following statement:
     #include "_Ascii_a.h"
    
    to your source file, after all the existing #include statements.
  5. 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.
  6. Link-edit your application with the libascii.a archive file.

 Limitations

The libascii interface package is code that we found useful in our IBM porting work, and it is offered as-is for your use. It's intended to assist in getting your applications running as quickly as possible.

These are some of the known restrictions:

  • Not all the C functions are supported. The file libascii.lst contains a list of supported ASCII run-time library routines.
  • 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 of 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 of 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
  • The interface layer is not NLS-enabled; it only supports conversions between the ISO8859-1 and IBM1040-1 character sets.

  FAQs

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

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

Another possible problem is _Ascii_a.h : it must be included after all the other header files.

Question 2: I compiled my code using -D__STRING_CODE_SET__="ISO8859-1" and included the _Ascii_a.h. Why does the link-edit of my application fail?

Response: The application's makefile needs to be modified to specify libascii.a on the link-edit.

Question 3: My link-edit shows libascii.a as not found, but I did install the libascii code. Why is this missing?

Response: Part of the installation of libascii includes compiling all the libascii code to create the libascii.a archive. Verify that the libascii.a archive has been created and and it is in a directory that the linkage editor can find.

 

 

Contact IBM

Browse z/OS