ASN.1 / XML Software Tools from Objective Systems

Creating a new project/Project configuration

This document provides tutorial information for the ASN1C Compiler Wizard, a graphical application that acts as a front end to Objective Systems' ASN1C command-line compiler. Documentation related to the ASN1C compiler and runtime library may be found on-line at http://www.obj-sys.com/docs/documents.shtml . This document is not intended to be a comprehensive reference for the command-line tool. Consult the documentation when questions arise about compiler use.

The Compiler Wizard is navigated by means of Next and Back buttons. Check boxes, text-entry forms, and radio buttons are used to select compiler options.

The Wizard contains several context-sensitive options, so some items may be inactive or invisible when others are active. For example, it is impossible to specify both BER and DER encoding rules simultaneously. When the target language is Java, function types that may be generated for C or C++ do not appear at all

New project

Using the new file wizard "ASN.1 Compiler Project Wizard" we may now create an ASN1C project. The wizard can be accessed either using the File -> New -> Project... menu

or using the rightmost toolbar action called "New ASN1C Compiler Project".

The first wizard page requires a name for the project that is just about to be created. Starting from the next page, the wizard will be identical with the wizard shown when configuring an existing ASN1C project.

Configure an existing project

ASN1C Project Configuration can be activated via the context sensitive menu of the project right-click -> ASN1C Compiler -> Configure and also using the previously presented toolbar actions.

Select files and directories

XSD and ASN.1 Files

To add ASN.1 or XSD specifications to be compiled, click the Select button next to the pane labeled ASN.1 / XSD Files and select files from the browse window that appears. This window shows only files from existing projects inside the workspace. In order to add a file from the file system use the Add File button. To remove a file, highlight it in the list and click Remove.

Note that all selected files from outside the workspace are copied to a folder named "asn1" inside the newly generated project.

Note ASN1C will compile both ASN.1 and XSD files, but it will not compile both at the same time. In order to add an XSD file, all ASN.1 files must be removed from the list, and vice versa.

Import Directories

To specify directories for the compiler to search for imported specifications (i.e., those provided by IMPORT declarations in ASN.1 files), click the Add button next to the Include / Import Directories pane to add a directory from inside the workspace and choose Add Folder in order to select one from the file system. To remove a directory, highlight it in the list and click Remove.

Configuration Files

Configuration files are added the same way. A configuration file contains directives that tell the compiler how to treat production rules it encounters in an ASN.1 specification. Configuration files have a .cfg or .xml extension. The compiler manual describes the format of these files in detail.

Output Directory

By default, the compiler generates code in the current working directory. Specifying an output directory will cause the compiler to write all of its files to a directory of the user's choosing. The output directory for newly created projects is by default src. This can be changed later by selecting another directory inside the project.

Generate Listing

By default, ASN1C does not display the contents of the specification it compiles. Checking Generate Listing will cause it to echo the specification to the screen.

Output Warning Messages

The same is true of compilation warnings. Checking Output Warning Messages will cause the compiler to produce warning messages if any are appropriate.

Code Generation Options

Input File Type

ASN1C can parse ASN.1 specifications based on both the X.680 standard (post-1997) and the X.208 standard (pre-1997, with ROSE or SNMP macros). When compiling a legacy specification, select the Legacy ASN.1 option.

Application Language Type

The target language may be C, C++, C#, or Java. In order to perform a simple syntax check without generating any source code, click None.

Additional Translations

Depending on which file type is selected in the Select Files and Directories window, options are also available to translate between ASN.1 specifications and XML Schema Definitions. If the input is an ASN.1 specification, the check box marked Generate equivalent XML schema (XSD) file will be active and the check box marked Generate ASN.1 file based on X.694 (XSD input only) will be inactive. The disposition of the check boxes is reversed when the input is an XSD file.

Dependencies

ASN1C can also attempt to compile all specifications that are imported by the given specification. If different compilation options are required, a configuration may be created that can fine-tune some of the controls.

Java Code Generation Options

The Java Project Settings page is the builtin Java Project configuration page indicating the build path settings for a new Java project. The build class path is a list of paths visible to the compiler when building the project. If you are new within the Eclipse Java Environment, you can reach the documentation of this page in the Java Development Users Guide ("New Java Project Wizard").

Select Encoding Rules

ASN1C can generate code compliant with several ASN.1 standards as well as the W3C XML standard:

BER
Encoding Rules, defined in ASN.1 standard X.690.
DER
Distinguished Encoding Rules, defined in ASN.1 Standard X.690.
CER
Canonical Encoding Rules, defined in ASN.1 Standard X.690.
PER
Packed Encoding Rules, defined in ASN.1 Standard X.691.
XER
XML Encoding Rules, defined in ASN.1 Standard X.693.
XML
XML Encoding rules, as specified by the World Wide Web Consortium.

Note that only one of BER, CER, and DER may be selected at a time. XML and XER are also mutually exclusive options.

Generated Function Types

Several different functions may be generated for each ASN.1 or XML production. Generating these functions may result in a substantially larger code base, so care should be exercised when code size is a concern. By default, only Encode and Decode functions are selected. In cases where only one or the other is required, a smaller code base may be generated by unchecking the indicated boxes.

Get/Set
Get/Set to instruct the compiler to generate getter and setter methods for fields encapsulated in generated types.
Compare Functions
Check Compare to generate functions that will permit generated type variables to be compared to each other. These are debug functions.
Test Functions
Check Test to generate test functions that populate generated types with random data. Use the generated encode functions to encode test constructs. Test functions may also serve as a template for how to populate generated types.
Print Functions
When specified, the print option instructs the compiler to generate code that permits printing objects to standard output.
Stream Functions
Check Stream to generate stream-based encode/decode functions instead of the typical memory-buffer based. These permit users to encode directly to or decode directly from a source or sink such as a file or socket. Stream-based encode and decode routines cannot be combined with memory-buffer-based routines in any way.

Space Optimization Options

The compiler may optimize code for space in several ways. Note that some options are not available for all Encoding Rules.

Indefinite Length Processing Tests
Check Do not generate indefinite length processing code to instruct the compiler to omit indefinite length tests in generated decode functions. These tests result in the generation of a large amount of code. If the compiled application only uses definite length encoding, this option can result in a much smaller code base size.
Note Do not generate indefinite length processing code may only be selected in conjunction with Basic and Distinguished Encoding Rules.
Open Extension Elements
Check Do not generate code to save/restore unknown extensions to prevent the compiler from generating code to read and write elements with extensibility markers. If such generality is not required by the application, check this option to reduce the code size.
Type Constraints
If Do not generate code to check constraints is checked, ASN.1 types with constraints will be treated as types without constraints.
Compact Code
Checking Generate Compact Code instructs the compiler to create more compact code at the expense of some error and constraint checks. It is not recommended to select this option until after the application has been thoroughly tested.
Compatibility Options
To generate code compatible with older versions of the compiler, check the box and select the desired compiler version from the drop-down list.

Java Build Options

Build Script Options
To automate the build process, you may opt for the Apache ANT build script generation or check Generate build script to compile all generated .java files. This produces a UNIX-style shell script that may be easily converted into a Windows batch file if necessary.
Output File Options
To instruct the compiler to create a directory for each module, check Output generate code to separate directories based on module name. Hyphens (-) in a module name will be converted to underscores (_). To specify a package prefix, check Specify prefix to be prepended to each package name. This option cannot be used in conjunction with Specify fixed package name for all generated classes. The default namespace for Java classes is the module name. You may opt also for the Java 1.4 compatible code (e.g. without generics).

General settings

Generated Class Modifiers
Checking Generate short form of type names will cause the compiler to used only the production name and final element name in a type name. By default, the compiler will use intermediate names to generate final element names; in deeply nested types, this can result in very long type names. Collisions are resolved by appending a unique number to the end of the type name. To cause the compiler to treat all type names as Protocol Data Units (PDUs), check the corresponding box. Default behavior is to treat only unreferenced types within a module as PDUs.
Event Handler Options
Check Generate code to invoke event handler callback functions to provide support for user-defined event and error handlers.
Sample Program Generation Options
Check Generate writer sample program to instruct the compiler to produce a program that demonstrates how to populate and encode data structures. Check Generate reader sample program to instruct the compiler to produce a program that demonstrates how to decode and output data structures.
Table Constraint Options
Check Generate code to fully encode/decode items with table constraints to instruct the compiler to generate table constraint processing structures and functions. These add logic for handling types that use message tables for defining what is to be included in a give protocol interaction message. The added logic makes it possible to encode or decode these multi-part messages in a single step. Note This option is not available for XML Schema or XML Encoding Rules. Check Enable strict constraint checks on all table constraint items to instruct the compiler to generate code for strict validation of table constraints. Real world messages typically do not follow value field table constraint definitions, so this option should be used with care. It will increase code size and decrease performance.

ASN.1 to XML Schema Translation Options

Application Info
Generate appInfo for ASN.1 tags, enumerations, and/or extensions. By default all are enabled.
Attributes
Generate non-native attributes for ASN.1 tags, enumerations, and/or extensions. By default all are enabled.
Namespace
Specify target namespace URI, if not given no target namespace declaration is added.
XSD
Reference types in asn1.xsd schema.

Compilation

The compilation command is displayed in the top pane. To execute the compiler, check the Compile checkbox. Output from the compiler is displayed in the ASN1C Compiler Output Console. The current project settings are automatically saved on Ok. If additional changes are required, hit Back until the necessary window appears.

The java code will be generated into a folder named "src" also inside the project.

Additionally, all needed ASN.1 Editor and ASN1C settings are created for the new project. In case that Java Code Generation was selected, a library container including the asn1rt.jar (ASN1C Runtime Library) is added to the project. This will ensure that the ASN1C generated files would compile.

Copyright Notice

Copyright ©1997-2008 Objective Systems, Inc. All Rights Reserved This document may be distributed in any form, electronic or otherwise, provided that it is distributed in its entirety and that the copyright and this notice are included.