Running ASN1C from the Command-line

---

The ASN1C compiler distribution contains command-line compiler executables as well as a graphical user interface (GUI) wizard (Windows version only) that can aid in the specification of compiler options. This section describes how to run the command-line version; the next section describes the GUI.

To test if the compiler was successfully installed, enter asn1c with no parameters as follows (note: if you have not updated your PATH variable, you will need to enter the full pathname):

asn1c

You should observe the following display (or something similar):

ASN1C Compiler, Version 5.5x
 
Copyright (c) 1997-2003 Objective Systems, Inc. All Rights Reserved.
 

 
Usage: asn1c <filename> options
 

 
    <filename>         ASN.1 source file name
 

 
  options:
 
    -hfile <filename>  C or C++ header (.h) filename
 
                          (default is <ASN.1 Module Name>.h)
 
    -cfile <filename>  C or C++ source (.c or .cpp) filename
 
                          (default is <ASN.1 Module Name>.c)
 
    -ber               generate BER encode/decode functions
 
    -der               generate DER encode/decode functions
 
    -per               generate PER encode/decode functions
 
    -xer               generate XER encode/decode functions
 
    -c                 generate C code
 
    -c++               generate C++ code
 
    -java              generate Java code
 
    -xsd               generate XML schema definitions
 
    -events            generate code to invoke event handlers
 
    -stream            generate stream-based encode/decode functions
 
    -config <file>     specify configuration file
 
    -nodecode          do not generate decode functions
 
    -noencode          do not generate encode functions
 
    -noIndefLen        do not generate indefinite length tests
 
    -noOpenExt         do not generate open extension elements
 
    -genBitMacros      generate named bit set, clear, test macros
 
    -static            generate static elements (not pointers)
 
    -compact           generate compact code
 
    -warnings          Output compiler warning messages
 
    -o <directory>     Output file directory
 
    -I <directory>     Import file directory
 
    -pkgpfx <text>     Java package prefix
 
    -pkgname <text>    Java package name
 
    -trace             add trace diag msgs to generated code
 
    -list              generate listing
 
    -compat <version>  generate code compatible with previous
 
                       compiler version. <version> format is 
 
                       x.x (for example, 5.3)
 

 
  additional code generation options*:
 
    -genPrint [<filename>]    or
 
    -print [<filename>]       Generate print functions
 
    -genPrtToStr [<filename>] or
 
    -prtToStr [<filename>]    Generate print-to-string functions (C/C++)
 
    -genCompare [<filename>]  or
 
    -compare [<filename>]     Generate comparison functions (C/C++)
 
    -genCopy [<filename>]     or
 
    -copy [<filename>]        Generate copy functions (C/C++)
 
    -genTables [<filename>]   or
 
    -tables [<filename>]      Generate table constraint functions
 

* These options take an optional output C or C++ filename argument.

If not supplied, a default name will be constructed. For java,

output is written to the generated .java file for each class.

Note that this usage summary shows all options for the pro version of ASN1C. Some of these options are not available in the basic version.

To use the compiler, at a minimum, an ASN.1 source file must be provided along with at least one set of encoding rules and a target output language. The source file specification can be a full pathname or only what is necessary to qualify the file. If directory information is not provided, the user's current default directory is assumed. If a file extension is not provided, the default extension ".asn" is appended to the name. Multiple source filenames may be specified on the command line to compile a set of files. The wildcard characters `*' and `%' are also allowed in source filenames (for example, the command `asn1c *.asn' will compile all ASN.1 files in the current working directory).

The source file(s) must contain ASN.1 productions that define ASN.1 types and/or value specifications. This file must strictly adhere to the syntax specified in ASN.1 standard ITU X.680.. The asn1c90 executable should be used to parse files based on the 1990 ASN.1 standard (x.208) or that contain references to ROSE macro specifications..

The following table lists all of the command line options and what they are used for:

Option	Argument	Description
-hfile	<filename>	This option allows the specification of a header (.h) file to which all of the generated typedefs and function prototypes will be written. If not specified, the default is <modulename>.h where <modulename> is the name of the module from the ASN.1 source file.
-cfile	<filename>	This option allows the specification of a C or C++ source (.c or .cpp) file to which all of the generated encode/decode functions will be written. If not specified, the default is <modulename>.c where <modulename> is the name of the module from the ASN.1 source file.
-ber	None	This option instructs the compiler to generate functions that implement the Basic Encoding Rules (BER) as specified in the ASN.1 standards.
-der	None	This option instructs the compiler to generate functions that implement the Distinguished Encoding Rules (DER) as specified in the ASN.1 standards.
-per	None	This option instructs the compiler to generate functions that implement the Packed Encoding Rules (PER) as specified in the ASN.1 standards.
-xer	None	This option instructs the compiler to generate functions that implement the XML Encoding Rules (XER) as specified in the ASN.1 standards.
-xsd	<filename>	This option instructs the compiler to generate XML Schema Definitions (XSD) for each of the ASN.1 productions in the ASN.1 source file. The definitions are written to the given filename or to <modulename>.xsd if the filename argument is not provided.
-trace	None	This option is used to tell the compiler to add trace diagnostic messages to the generated code. These messages cause printf statements to be added to the generated code to print entry and exit information into the generated functions. This is a debugging option that allows encode/decode problems to be isolated to a given production processing function. Once the code is debugged, this option should not be used as it adversely affects performance.
-java	None	Generate Java source code.
-c	None	Generate C source code.
-c++	None	Generate C++ source code.
-events	None	Generate extra code to invoke user defined event and error handler callback methods (see the Event Handlers section).
-config	<filename>	This option is used to specify the name of a file containing configuration information for the source file being parsed. A full discussion of the contents of a configuration file is provided in the Compiler Configuration File section.
-noencode	None	This option suppresses the generation of encode functions. .
-nodecode	None	This option suppresses the generation of decode functions.
-noIndefLen	None	This option instructs the compiler to omit indefinite length tests in generated decode functions. These tests result in the generation of a large amount of code. If you know that your application only uses definite length encoding, this option can result in a much smaller code base size.
-noOpenExt	None	This option instructs the compiler to not add an open extension element (extElem1) in constructs that contain extensibility markers. The purpose of the element is to collect any unknown items in a message. If an application does not care about these unknown items, it can use this option to reduce the size of the generated code.
-static	None	This has the same effect as specifying the global <storage> static </storage> configuration item. The compiler will insert static elements instead of pointer variables in generated structures.
-stream	None	This option instructs the compiler to generate stream-based encoders/decoders instead of memory buffer based. This makes it possible to encode directly to or decode directly from a source or sink such as a file or socket. In the case of BER, it will also cause forward encoders to be generated, which will use indefinite lengths for all constructed elements in a message.
-bitMacros	None	This option instructs the compiler to generate additional macros to set, clear, and test named bits in BIT STRING constructs. By default, only bit number constants are generated. Bit macros provide slightly better performance because mask values required to do the operations are computed at compile time rather than run-time.
-lax	None	This option instructs the compiler to not generate code to check constraints. When used in conjunction with the -compact option (described next), it produces the smallest code base for a given ASN.1 specification.
-compact	None	This option instructs the compiler to generate more compact code at the expense of some constraint and error checking. This is an optimization option that should be used after an application is thoroughly tested.
-warnings	None	Output information on compiler generated warnings.
-o	<directory>	This option is used to specify the name of a directory to which all of the generated files will be written.
-I	<directory>	This option is used to specify a directory that the compiler will search for ASN.1 source files for IMPORT items. Multiple -I qualifiers can be used to specify multiple directories to search.
-pkgpfx	<prefixName>	This is a Java option for adding a prefix in front of the assigned Java package name . By default, the Java package name is set to the module name. If the package is embedded within a hierarchy, this option can be used to set the other directory names that must be added to allow Java to find the .class files.
-pkgname	<packageName>	This is a Java option that allows the entire Java package name to be changed. Instead of the module name, the full name specified using this option will be used. This option cannot be used in conjunction with -pkgpfx option.
-dirs	None	This is a Java option that causes a subdirectory to be created to hold each of the generated Java source files for each module in an ASN.1 source file.
-list	None	Generate listing. This will dump the source code to the standard output device as it is parsed. This can be useful for finding parse errors.
-compat	<versionNumber>	Generate code compatible with an older version of the compiler . The compiler will attempt to generate code more closely aligned with the given previous release of the compiler. <versionNumber> is specified as x.x (for example, -compat 5.2)
-genPrint -print	<filename>	This option allows the specification of a C or C++ source (.c or .cpp) file to which generated print functions will be written. Print functions are debug functions that allow the contents of generated type variables to be written to stdout. They are optional: if -print is not specified, no print functions will be generated. The <filename> argument to this option is also optional. If not specified, the print functions will be written to <modulename>Print.c where <modulename> is the name of the module from the ASN.1 source file.
-genCompare -compare	<filename>	This option allows the specification of a C or C++ source (.c or .cpp) file to which generated compare functions will be written. Compare functions allow two variables of a given ASN.1 type to be compared for equality. They are optional: if -genCompare is not specified, no comparison functions will be generated. The <filename> argument to this option is also optional. If not specified, the functions will be written to <modulename>Compare.c where <modulename> is the name of the module from the ASN.1 source file.
-genCopy -copy	<filename>	This option allows the specification of a C or C++ source (.c or .cpp) file to which generated copy functions will be written. Copy functions allow a copy to be made of an ASN1C generated variable. For C++, they cause copy constructors and assignment operators to be added to generated classes. They are optional: if -genCopy is not specified, no copy functions will be generated. The <filename> argument to this option is also optional. If not specified, the functions will be written to <modulename>Copy.c where <modulename> is the name of the module from the ASN.1 source file.
-genPrtToStr -prtToStr	<filename>	This option allows the specification of a C or C++ source (.c or .cpp) file to which generated "print-to-string" functions will be written. "Print-to-string" functions are similar to print functions except that the output is written to a user-provided text buffer instead of stdout. This makes it possible for the use to display the results on different output devices (for example, in a text window). They are optional: if -genPrtToStr is not specified, no functions will be generated. The <filename> argument to this option is also optional. If not specified, the functions will be written to <modulename>Print.c where <modulename> is the name of the module from the ASN.1 source file.
-genTables -tables	<filename>	This option is used to generate additional code for the handling of table constraints as defined in the X.682 standard. See <section> for additional details on the type of code generated to support table constraints.