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.7x
 
Copyright (c) 1997-2004 Objective Systems, Inc. All Rights Reserved.
 

 
Usage: asn1c <filename> <options>
 

 
    <filename>          ASN.1 source file name(s).  Multiple filenames
 
                          may be specified.  * and ? wildcards are allowed.
 

 
  language options:
 
    -c                  generate C code
 
    -c++                generate C++ code
 
    -c#                 generate C# code
 
    -java               generate Java code
 
    -xsd [<filename>]   generate XML schema definitions
 

 
  encoding rule options:
 
    -ber                generate BER encode/decode functions
 
    -cer                generate CER encode/decode functions
 
    -der                generate DER encode/decode functions
 
    -per                generate PER encode/decode functions
 
    -xer                generate XER encode/decode functions
 
    -xml                generate XML encode/decode functions
 

 
  basic 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)
 
    -print [<filename>] generate print functions
 
    -config <file>      specify configuration file
 
    -shortnames         reduce the length of compiler generated names
 
    -notypes            do not generate type definitions
 
    -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
 
    -lax                do not generate constraint checks in code
 
    -compact            generate compact code
 
    -pdu <type>         designate <type> to be a Protocol Data Unit (PDU)
 
                        (<type> may be * to select all type definitions)
 
    -warnings           output compiler warning messages
 
    -o <directory>      set output file directory
 
    -I <directory>      set import file directory
 
    -trace              add trace diag msgs to generated code
 
    -list               generate listing
 
    -1990               parse 1990-compatible ASN.1 specification
 
                          (provides support for ROSE macro specs)
 
    -compat <version>   generate code compatible with previous
 
                        compiler version. <version> format is 
 
                        x.x (for example, 5.3)
 

 
  C/C++ options:
 
    -genBitMacros       generate named bit set, clear, test macros
 
    -genFree            generate memory free functions for all types
 
    -genMake            generate makefile to build generated code
 
    -maxlines [<num>]   set limit of number of lines per source file
 
                        (default value is 50000)
 
    -oh <directory>     set output directory for header files
 
    -static             generate static elements (not pointers)
 
    -w32                generate code for Windows O/S (default=GNU)
 

 
  Java options:
 
    -pkgpfx <text>     Java package prefix
 
    -pkgname <text>    Java package name
 
    -dirs              output Java code to module name dirs
 
    -genjsources       generate <modulename>.mk for list of java files
 

 
  C# options:
 
    -nspfx <text>      C# namespace prefix
 
    -namespace <text>  C# namespace name
 
    -dirs              output C# code to module name dirs
 
    -gencssources      generate <modulename>.mk for list of C# files
 

 
  pro options:
 
    -events            generate code to invoke SAX-like event handlers
 
    -stream            generate stream-based encode/decode functions
 
    -tables            generate table constraint functions
 
    -strict            do strict checking of table constraint conformance
 
    -prtToStr [<filename>]
 
                       generate print-to-string functions (C/C++)
 
    -prtToStrm [<filename>]
 
                       generate print-to-stream functions (C/C++)
 
    -genTest  [<filename>]
 
                       generate sample test functions (C/C++)
 
    -reader            generate sample reader program(C/C++, BER/DER/PER)
 
    -writer            generate sample writer program(C/C++, BER/DER/PER)
 
    -compare [<filename>]
 
                       generate comparison functions (C/C++)
 
    -copy [<filename>] generate copy functions (C/C++)
 
    -maxcfiles         generate separate file for each function (C/C++)
 

 
  XSD options:
 
    -tags              add ASN.1 tag info as appInfo in XSD spec
 
    -targetNS          specify XSD target namespace
 
    -noappinfo         do not include appInfo in generated XSD spec
 

 

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 -1990 command-line option 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. The options are shown in alphabetical order. Note that the Java and C# options are not shown here. They are shown in their respective documents.

Option	Argument	Description
-1990	None	This option instructs the compiler to parse the older 1990 version of the ASN.1 syntax as specified in the now deprecated X.208 and X.209 standards. This syntax allowed the ANY construct as well as unnamed fields in SEQUENCE, SET, and CHOICE constructs. This option also allows for parsing and generation of code for ROSE OPERATION and ERROR macros and SNMP OBJECT-TYPE macros.
-ber	None	This option instructs the compiler to generate functions that implement the Basic Encoding Rules (BER) as specified in the X.690 ASN.1 standard.
-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.
-c	None	Generate C source code.
-c++ or -cpp	None	Generate C++ source code.
-c# or -csharp	None	Generate C# source code. See the ASN1C C# User's Guide for more information and options for generating C# code.
-cer	None	This option instructs the compiler to generate functions that implement the Canonical Encoding Rules (CER) as specified in the X.690 ASN.1 standard.
-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 to write to a series of .c or .cpp files based on the ASN.1 module name(s) of the documents being compiled.
-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.
-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)
-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.
-der	None	This option instructs the compiler to generate functions that implement the Distinguished Encoding Rules (DER) as specified in the X.690 ASN.1 standard.
-events	None	Generate extra code to invoke user defined event and error handler callback methods (see the Event Handlers section). When combined with the -notypes option, causes pure parser functions to be generated.
-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.   The <filename> argument to this option is 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.   The <filename> argument to this option is 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.
-genFree	None	This option instructs the compiler to generate a memory free function for each ASN.1 production. Normally, memory is freed within ASN1C by using the rtMemFree run-time function to free all memory at once that is held by a context. Generated free functions allow finer grained control over memory freeing by just allowing the memory held for specific objects to be freed.
-genMake	None	This option instructs the compiler to generate a portable makefile for compiling the generated C or C++ code.
-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.   The <filename> argument to this option is 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.
-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).   The <filename> argument to this option is 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.
-genPrtToStrm -prtToStrm	<filename>	This option allows the specification of a C or C++ source (.c or .cpp) file to which generated "print-to-stream" functions will be written. "Print-to-stream" functions are similar to print functions except that the output is written to a user-provided stream instead of stdout. The stream is in the form of an output callback function that can be set within the run-time context making it possible to redirect output to any type of device.   The <filename> argument to this option is 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.
-genTest	<filename>	This option allows the specification of a C or C++ source (.c or .cpp) file to which generated "test" functions will be written. "Test" functions are used to populate an instance of a generated PDU type variable with random test data. This instance can then be used in an encode function call to test the encoder. Another advantage of these functions is that they can act as templates for writing your own population functions.   The <filename> argument to this option is optional. If not specified, the functions will be written to <modulename>Test.c where <modulename> is the name of the module from the ASN.1 source file.
-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.
-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.
-java	None	Generate Java source code. See the ASN1C Java User's Guide for more information on Java code generation.
-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.
-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.
-maxcfiles	None	Maximize number of generated C files. This option instructs the compiler to generate a separate .c file for each generated C function. In the case of C++, a separate .cpp file is generated for each control class, type, and C function. This is a space optimization option - it can lead to smaller executable sizes by allowing the linker to only link in the required program module object files.
-maxlines	<number>	This option is used to specify the maximum number of lines per generated .c or .cpp file. If this number is exceeded, a new file is started with a "_n" suffix where "n" is a sequential number. The default value if this is not specified is 50,000 lines which will prevent the VC++ "Maximum line numbers exceeded" warning that is common when compiling large ASN.1 source files.   Note that this number is approximate - the next file will not be started until this number is exceeded and the compilation unit that is currently being generated is complete.
-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.
-notypes	None	This options suppresses the generation of type definitions. It is used in conjunction with the -events options to generate pure parser functions.
-o	<directory>	This option is used to specify the name of a directory to which all of the generated files will be written.
-oh	<directory>	This option is used to specify the name of a directory to which only the generated header files (*.H) will be written (C or C++ only).
-pdu	<typeName>	Designate given type name to be a PDU type. This will cause a C++ control class to be generated for the given type. By default, PDU types are determined to be types that are not referenced by any other types within a module. This option allows that behavior to be overridden.   The `*' wildcard character may be specified for <typeName> to indicate that all productions within an ASN.1 module should be treated as PDU types.
-per	None	This option instructs the compiler to generate functions that implement the Packed Encoding Rules (PER) as specified in the ASN.1 standards.
-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.
-strict	None	This option instructs the compiler to generate code for strict validation of table constraints. By default, generated code will not check for value field constraints. It should be noted that real world messages typically do not strictly follow value field table constraint definitions. Therefore, this option should be used with care.
-trace	None	This option is used to tell the compiler to add trace diagnostic messages to the generated code. These messages cause print 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.
-warnings	None	Output information on compiler generated warnings.
-xer	None	This option instructs the compiler to generate functions that implement the XML Encoding Rules (XER) as specified in the X.693 ASN.1 standard.
-xml	None	This option instructs the compiler to generate functions that encode/decode data in an XML format that is more closely aligned with World-Wide Web Consortium (W3C) XML schema. The -xsd option can be used in conjunction with this option to generate a schema describing the XML format.
-xsd	<filename>	This option instructs the compiler to generate an equivalent XML Schema Definition (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.