ASN.1 / XML Software Tools from Objective Systems

Thank you for downloading this release of the ASN1C software. ASN1C is a powerful ASN.1 compiler capable of parsing and generating C, C++, C#, or Java source code for the most advanced ASN.1 syntax.

This package contains the ASN1C compiler executables and run-time libraries. Documentation is available online at http://www.obj-sys.com/manuals.shtml#asn15.7

Release Notes

This release of ASN1C adds the following new capabilities:

Generation of C# code: Support has been added to generate C# code for the Microsoft .NET framework. This code is similar in structure to the code produced by the Java version of the compiler. The run-time library supports the 2002 and 2003 versions of .NET. All encoding rules are supported as well as table constraint code generation. A library that supports the compact edition of C# is available as well.
New C/C++ space optimization options: Options have been added to change how code is written to C/C++ output files. The -maxcfiles option causes a separate .c or .cpp file to be created for every generated function. This can have a huge impact in reducing the size of statically linked executable files or DLL's. For example, in our security framework, we found in some cases that we were able to achieve a 34x reduction in the size of a sample program executable file.
Makefile and test code generation: Automatic generation of makefiles and unit test code to make it easier to quickly build application programs. This is especially true with the -maxcfiles option described above which requires a large makefile to build all of the generated code.
Enhanced SAX-like event handlers: Enhanced SAX-like event handlers can be generated without backing types to hold the data. This means a smaller code footprint for applications that need to parse ASN.1 messages to operate on specific data items within the message.
Print-to-stream functionality: Abstraction of print output in the run-time and in generated code using the -prtToStrm allows diagnostic and other output to be redirected to output streams via callback functions. This makes it possible to print directly to a window display or a log file.
Improved C++ exception handling: Exception handling within the C++ run-time has been deprecated to allow maximum portability to environments that have no exception handling mechanisms. All errors are now handled via status codes as is done in the C environment.
Enhanced C++ run-time base classes: New methods have been added to the C++ run-time OBJECT IDENTIFER (ASN1TObjId) and OCTET STRING (ASN1TDynOctStr) base classes. Also, run-time base classes have been added for UTC and Generalized Time (ASN1TUTCTime and ASN1TGeneralizedTime). These make construction and manipulation of values of these types easier.

Compatibility

In an ongoing effort to improve the product, changes have been made in how code is generated in some cases. Users of previous versions of the compiler can achieve backward compatility with their existing code bases by using the compiler '-compat' switch (for example, '-compat 5.6' will generate code compatible with the 5.6 version of the compiler).

The following is a summary of changes that were made in code generation for this release:

The default name format and number of .c or .cpp files generated for a given ASN.1 specification have been changed. Encode and decode functions are now written to separate files with 'Enc' and 'Dec' suffixes respectively. New files are also created if a maximum number of lines threshold is reached (by default, this is 50,000, but this can be changed with the -maxlines option).
Generated C++ code was changed to always return status values instead of throwing exceptions. Therefore, code that was written to only use try/catch blocks to catch C++ errors will not work correctly. The status value of the method should be checked instead (note: it was always true that the status of C++ methods should be checked, so this change should not affect most existing applications). Note that for XER decoders, C++ exceptions are still used because these are built into the underlying SAX parser framework.

Documentation

Documentation for this release is available online at the following web-link:

http://www.obj-sys.com/manuals.shtml#asn15.7

Windows Installation

The steps to install ASN1C on a Windows system are as follows:

Download the ASN1C package that is of interest to you. Packages are available online for C/C++, C#, and Java. The C/C++ package contains run-time libraries built with the Microsoft Visual C++ v6.0 and v7.0 (.NET) compilers, the Borland v5.5 C++ compiler, and the GNU Cygwin 3.3.1 compiler.
ASN1C for Windows is packaged in a self-extracting executable file format. To install, all that should be necessary is to double-click this file after downloading and then following the setup wizard instructions from that point.
After installation is complete, the license file must be installed to allow the product to operate. This was sent in the osyslic.txt file that was attached to the E-mail message that was sent at the time the product was downloaded. If you did not receive a license file, please contact us.
The osyslic.txt file must be copied to a location where the compiler can find it. This can be done in one of the following ways:

a. The file can be copied into any of the directories specified within your PATH environment variable (copying to the c:\windows directory works on most systems), or

b. The file can be copied to a different directory and an environment variable named 'OSLICDIR' created to point at this directory location, or

c. The file can be copied to the same directory that the ASN1C compiler executable file is located in. This is in the bin subdirectory located under the top-level install directory.

Note that licenses from previous versions of ASN1C are not compatible with this release of the product.

The compiler should now be operational. The following command can be executed:

<rootdir>\bin\asn1c

to verify operation.

Contents of the Release

The following subdirectories contain the following files (note: <installdir> refers to the installation directory that was specified during the installation process):

Base Compiler Package

<installdir>\bin\asn1c.exe: The command-line compiler executable file. This is invoked on ASN.1 source files to generate C, C++, C#, or Java encode/decode classes and functions. It is recommended you modify your PATH environment variable to include <installdir>\bin to allow the compiler executable to be run from anywhere.

As of this release, the special ASN.1 '90 executable (asn1c90.exe) is no longer available. This functionality has been built into the main asn1c executable and is accessed via the -1990 command line switch. This option allows older specifications based on the ASN.1 1990 syntax to be compiled. It provides support for ROSE MACROs (OPERATION and ERROR) and SNMP MACROs (OBJECT-TYPE).

<installdir>\bin\asn1cGUI.exe: The compiler graphic user interface (GUI) wizard executable file. This is the Windows wizard that guides a user through the process of specifying ASN.1 source files and options. This is the program invoked from the start menu or desktop icon.
<installdir>\bin\berfdump.exe <installdir>\bin\ber2def.exe <installdir>\bin\ber2indef.exe: Utility programs for operating on BER-encoded files. The first program allows a file to be dumped in a human-readable format. The other two utilities convert files from the use of indefinite to definite length encoding and vice-versa.
<installdir>\doc: This directory contains documentation files. Note that the bulk of the documentation items must be downloaded as a separate package (see the Documentation section above).
<installdir>\utils: This directory contains the source code and build makefile for some of the utility programs included in the bin subdirectory.
<installdir>\xsd\lib\asn1.xsd: This directory contains the common XML schema definitions (XSD) library. This contains type mappings for built-in ASN.1 types that do not have an equivalent types defined in XSD.
<installdir>\xsd\sample: This directory contains sample programs related to the conversion of ASN.1 to XML Schema.

C/C++ run-time libraries and source files

<installdir>\c\lib\* (Visual C++ 6.0)
<installdir>\c_mscv7\lib\* (Visual C++ 7.0)
<installdir>\c_gnu\lib\*.a (GNU gcc 3.3.1): The ASN1C C run-time library files. These contain BER/DER, PER, and/or XER run-time functions. For each encoding rules type, there is a dynamic link library (.dll) and standard library file (.lib) for linking with the DLL. There is also a static library for direct linkage to the object modules (this is the library file with the '_a.lib' suffix). The static library included in the evaluation version is not thread-safe. The licensed version of the product also contains a thread-safe static library (compiled with -MT option) and a DLL-ready library (compiled with -MD option) for building your own value-added DLL's. Also note that the evaluation and development libraries are not fully optimized (they contain diagnostic tracing and are not compiled with compiler optimization turned on). The deployment libraries are fully optimized.
<installdir>\cpp\lib\*.lib (Visual C++ 6.0)
<installdir>\cpp_mscv7\lib\*.lib (Visual C++ 7.0)
<installdir>\cpp_borland\lib\*.lib (Borland C++)
<installdir>\cpp_gnu\lib\*.a (GNU g++ 3.3.1): The ASN1C C/C++ run-time library files. These are the same as the C run-time libraries above except that they contain run-time C++ classes as well as C run-time functions.
<installdir>\c*\lib_opt\*
<installdir>\cpp*\lib_opt\*: The optimized version of the ASN1C run-time libraries. This version version has all diagnostic messages, error stack trace and text, and non-essential status checks removed. (Note: these libraries are only available in the licensed deployment version of the product).
<installdir>\c\sample_*
<installdir>\cpp\sample_*: The sample directories contain sample programs demonstrating the use of the compiler. There are a set of sample programs that correspond to each encoding rule set supported by ASN1C. Most sample programs are broken down into a writer and a reader. The writer encodes a sample data record and writes it to a disk file. The reader reads the encoded message from the file, decodes it, and then prints the results of the decode operation.
<installdir>\rtsrc\*
<installdir>\rtbersrc\*
<installdir>\rtpersrc\*
<installdir>\rtxersrc\*: The installation run-time source directories contain the header files required to compile the compiler generated code. The C or C++ source files will also be located here if the run-time source code kit option was selected.
<installdir>\expatsrc\*: The XML parser run-time source directories contain the source files for the Expat C XML parser. (Note: these files are only present in the XER distribution).

Java run-time libraries

<installdir>\java\asn1rt.jar <installdir>\java\asn1rt1.jar: The ASN.1 Java run-time libraries. These contain the low-level BER, PER, and/or XER encode/decode classes. The asn1rt.jar file contains classes compatible with the Java 2 JRE. The asn1rt1.jar file contains classes compatible with the older Java 1.1 standard.
<installdir>\java\sample_ber <installdir>\java\sample_der <installdir>\java\sample_per <installdir>\java\sample_xer: Sample programs illustrating the use of the Java version of ASN1C. As was the case for C/C++, most have a writer and a reader. Some contain support code used by other samples (for example, SimpleROSE contains the ROSE headers used by CSTA).
<installdir>/java/doc/*: The ASN.1 Java run-time libraries documentation files. These are html files generated with the javadoc documentation tool. To view the documentation, open the index.shtmll file with a web browser and follow the hyperlinks.

C# run-time libraries

<installdir>\csharp\asn1rt.dll: The ASN.1 C# run-time library DLL. This contains the low-level BER, PER, and/or XER encode/decode classes. It supports both the .Net 2002 and .Net 2003 versions.
<installdir>\csharp\sample_ber <installdir>\csharp\sample_der <installdir>\csharp\sample_per <installdir>\csharp\sample_xer: Sample programs demonstrating the use of the C# version of ASN1C. As was the case for C/C++, most have a writer and a reader. Some contain support code used by other samples (for example, SimpleROSE contains the ROSE headers used by CSTA).
<installdir>/csharp/doc/*: The ASN.1 C# run-time libraries documentation files. Documentation is contained within the ASN1CLibrary.chm file. This is in Microsoft help format.

Getting Started with C or C++

The compiler can be run using either the GUI wizard or from the command line. To run the GUI wizard, launch the application and follow the steps. To run a simple test from the command line, do the following:

Open an MS-DOS or other command shell window.
Change directory (cd) to one of the employee sample directories (for example, c/sample_ber/employee).
Execute the nmake utility program:

nmake

(note: nmake is a make utility program that comes with the Microsoft Visual C++ compiler. It may be necessary to execute the batch file vcvars32.bat that comes with Visual C++ in order to set up the environment variables to use this utility). If you are using Borland or another compiler, execute the make utility for that compiler.

This should cause the compiler to be invoked to compile the employee.asn sample file. It will then invoke the Visual C++ compiler to compile the generated C file and the test drivers. The result should be a writer.exe and reader.exe program file which, when invoked, will encode and decode a sample employee record.

Invoke writer from the command line:

writer

This will generate an encoded record and write it to a disk file. By default, the file generated is message.dat (in the case of XER, it is message.xml). The test program has a number of command line switches that control the encoding. To view the switches, enter writer ? and a usage display will be shown.

Invoke reader from the command line:

reader

This will read the disk file that was just created by the writer program and decode its contents. The resulting decoded data will be written to standard output. The test program has a number of command line switches that control the encoding. To view the switches, enter reader ? and a usage display will be shown.

Getting Started with Java

Open an MS-DOS or other command shell window.
Change directory (cd) to one of the employee sample directories (for example, java/sample_ber/Employee).
Execute the build batch file:

build

This will cause the ASN1C compiler to be invoked to compile the employee.asn sample file. It will then invoke the Java compiler (javac) to compile all generated java files and the reader and writer programs (Note: JDK 1.4 was used to build all the run-time library classes). It will also automatically execute the writer and reader programs. These programs will produce a writer.log and reader.log file respectively.

Note: a makefile is also available for use if you have a make utility program available. The makefile is compatible with the GNU make utility and with the Microsoft Visual C++ make utility (nmake).

View the writer and reader log files. The writer.log file will contain a dump of the encoded message contents. The reader.log file will contain a printout of the decoded data.

Getting Started with C#

Make sure Microsoft .NET 2002 or 2003 is installed on your system.
Open the Visual Studio .NET command prompt (This can be found using: Start->Programs->Microsoft Visual Studio .Net->Visual Studio .NET Tools)
Execute the nmake command to run the complete sample program. The makefile will invoke the ASN1C compiler to generate C# code for the ASN.1 definition and then compile the generated C# code.
Execute the writer.exe to encode the binary message.
Execute the reader.exe to decode the binary message.

Known Problems and Issues

There are a few known issues and limitations of the compiler in its current state. The compiler can parse all syntax as defined in the X.680 through X.683 standards (2002) and older X.208 standard. However, no backend code is generated to support the following items:

Value Sets
Unrestricted character string type (an Open Type is generated)

It is our desire to make a practical ASN.1 tool that can handle the syntax that people use, not something that can handle every possible syntax. So we are interested in hearing what you are using in practice that doesn't work. In other words, if you create overly complex syntax in order to try and break it, you probably will.

Reporting Problems

Report problems you encounter by sending E-mail to support@obj-sys.com. The preferred format of example programs is the same as the sample programs. Please provide a writer and reader and indicate where in the code the problem occurs.

If you have any further questions or comments on what you would like to see in the product or what is difficult to use or understand, please communicate them to us. Your feedback is important to us. Please let us know how it works out for you - either good or bad.