In addition to command line options, a configuration file can be used to specify compiler options. These options can be applied not only globally but also to specific modules and productions.
A simple form of the Extended Markup Language (XML) is used to format items in the file. This language was chosen because it is fairly well known and provides a natural interface for representing hierarchical data such as the structure of ASN.1 modules and productions. The use of an external configuration file was chosen over embedding directives within the ASN.1 source itself due to the fact that ASN.1 source versions tend to change frequently. An external configuration file can be reused with a new version of an ASN.1 module, but internal directives would have to be reapplied to the new version of the ASN.1 code.
At the outer level of the markup is the <asn1config> </asn1config> tag pair. Within this tag pair, the specification of global items and modules can be made. Global items are applied to all items in all modules. An example would be the <storage> qualifier. A storage class such as dynamic can be specified and applied to all productions in all modules. This will cause dynamic storage (pointers) to be used to any embedded structures within all of the generated code to reduce memory consumption demands.
The specification of a module is done using the <module></module> tag pair. This tag pair can only be nested within the top-level <asn1config> section. The module is identified by using the required <name></name> tag pair or by specifying the name as an attribute (for example, <module name="MyModule">). Other attributes specified within the <module> section apply only to that module and not to other modules specified within the specification. A complete list of all module attributes is provided in the table at the end of this section.
The specification of an individual production is done using the <production></production> tag pair. This tag pair can only be nested within a <module> section. The production is identified by using the required <name></name> tag pair or by specifying the name as an attribute (for example, <production name="MyProd">). Other attributes within the production section apply only to the referenced production and nothing else. A complete list of attributes that can be applied to individual productions is provided in the table at the end of this section.
When an attribute is specified in more than one section, the most specific application is always used. For example, assume a <typePrefix> qualifier is used within a module specification to specify a prefix for all generated types in the module and another one is used to specify a prefix for a single production. The production with the type prefix will be generated with the type prefix assigned to it and all other generated types will contain the type prefix assigned at the module level.
Values in the different sections can be specified in one of the following ways:
Using the <name>value</name> form. This assigns the given value to the given name. For example, the following would be used to specify the name of the "H323-MESSAGES" module in a module section:
<name>H323-MESSAGES</name>
Flag variables that turn some attribute on or off would be specified using a single <name/> entry. For example, to specify a given production is a PDU, the following would be specified in a production section:
<isPDU/>
An attribute list can be associated with some items. This is normally used as a shorthand form for specifying lists of names. For example, to specify a list of type names to be included in the generated code for a particular module, the following would be used:
<include types="TypeName1,TypeName2,TypeName3"/>
The following are some examples of configuration specifications
<asn1config><storage>dynamic</storage></asn1config>
This specification indicates dynamic storage should be used in all places where its use would result in significant memory usage savings within all modules in the specified source file.
<asn1config>
<module>
<name>H323-MESSAGES</name>
<sourceFile>h225.asn</sourceFile>
<typePrefix>H225</typePrefix>
</module>
...
</asn1config>
This specification applies to module 'H323-MESSAGES' in the source file being processed. For IMPORT statements involving this module, it indicates that the source file 'h225.asn' should be searched for specifications. It also indicates that when C or C++ types are generated, they should be prefixed with the 'H225'. This can help prevent name clashes if one or more modules are involved and they contain productions with common names.
The following tables specify the list of attributes that can be applied at all of the different levels: global, module, and individual production:
Global Level
There are no attributes that are specific to Java that can be specified at the global level.
Module Level
These attributes can be applied at the module level by including them within a <module> section:
| Name | Values | Description |
|---|---|---|
|
<name> |
module name | This attribute identifies the module to which this section applies. It is required. |
| <include types="names" values="names"/> | ASN.1 type or values names are specified as an attribute list |
This item allows a list of ASN.1 types and/or values to be included in the generated code. By default, the compiler generates code for all types and values within a specification. This allows the user to reduce the size of the generated code base by selecting only a subset of the types/values in a specification for compilation. Note that if a type or value is included that has dependent types or values (for example, the element types in a SEQUENCE, SET, or CHOICE), all of the dependent types will be automatically included as well. However, if an element is marked <notUsed/> or <notUsedSkip/>, the referenced type is not automatically included; if an element is marked <notUsedDecode/> or <notUsedDecodeSkip>, the referenced type is included for encoding only; if an element is marked <notUsedEncode/>, the referenced type is included for decoding only. |
| <include importsFrom="name" /> | ASN.1 module name(s) specified as an attribute list. | This form of the include directive tells the compiler to only include types and/or values in the generated code that are imported by the given module(s). |
| <exclude types="names" values="names"/> | ASN.1 type or values names are specified as an attribute list | This item allows a list of ASN.1 types and/or values to be excluded in the generated code. By default, the compiler generates code for all types and values within a specification. This is generally not as useful as in include directive because most types in a specification are referenced by other types. If an attempt is made to exclude a type or value referenced by another item, the directive will be ignored. |
|
<sourceFile> |
source file name | Indicates the given module is contained within the given ASN.1 source file. This is used on IMPORTs to instruct the compiler where to look for imported definitions. This replaces the module.txt file used in previous versions of the compiler to accomplish this function. |
| <pkgName> | Java package name | Name of the Java package associated with this module. This will cause a Java import statement to be generated for the module if this name is not the same as that of the package being compiled. |
Production Level
These attributes can be applied at the production level by including them within a <production> section:
| Name | Values | Description |
|---|---|---|
|
<name> </name> |
production name | This attribute identifies the production (type) to which this section applies. It is required. |
| <aligned/> | n/a | This item is used to specify that byte alignment is to be done after encoding or decoding an instance of the targeted type. This item is only supported for 3GPP layer 3 code generation. |
| <cDecFuncName> </cDecFuncName> | <Java source file name | This item is used (despite the name) to substitute the Java source code contained within the given file for what would have been generated for the Java decode function for the given type. The current include path is searched for the given filename. This item is only supported for 3GPP layer 3 code generation. |
| <cEncFuncName> </cEncFuncName> | <Java source file name | This item is used (despite the name) to substitute the Java source code contained within the given file for what would have been generated for the Java encode function for the given type. The current include path is searched for the given filename. This item is only supported for 3GPP layer 3 code generation. |
| <displayFormat> </displayFormat> | bits, hex | This is used to specify an alternate stringified representation for binary data. The bits and hex entries are used with BIT STRING types. The bits qualifier causes bit strings to be displayed in binary form (all 1's and 0's). The hex qualifier causes bit strings to be displayed as hexadecimal digits, regardless of whether the BIT STRING has named bits. |
| <is3GExtList pre-eol="0|1" post-eol="0|1"/> | n/a | This item specifies that this production will be modelled as a 3G extended list. This can only be applied to SEQUENCE OF productions. It is used in 3G layer 3 messages when the extension of a repeating type is controlled by an extension bit that occurs either before or after the record. If the pre-eol attribute (short for "preceding end-of-list") is specified, it indicate a bit before the record signals whether another record follows. The value (0 or 1) indicates which bit value signal end-of-list. The post-eol attribute is the same except that it indicates the control bit follows after the record. This item is only supported for 3GPP layer 3 code generation. |
| <is3GMessage/> | n/a | This item specifies that this production represents a 3G layer 3 message type as opposed to a 3G layer 3 information element (IE). This item is only supported for 3GPP layer 3 code generation. |
| <isBigInteger/> | n/a |
This is a flag variable (an 'empty element' in XML terminology) that specifies that this production will be used to store an integer larger than the Java long type (64 bits). A Java BigInteger class will be used to hold the value. This qualifier can be applied to either an integer or constructed type. If constructed, all integer elements within the constructed type are flagged as big integers. |
| <isPLMNidentity/> | n/a |
This flag identifies the production as a PLMNidentity. Any production so identified will be treated as an OCTET STRING, regardless of how the production might be defined in the ASN.1. |
| <isTBCDString/> | n/a | This item is used to indicate that values of this production are to be interpreted as telephony binary coded strings (TBCD). TBCD strings are not part of the ASN.1 standards but are a widely used encoding format in telephony applications. |
|
<listclass> |
Java List Class | This instructs the compiler to use a different class than the default
LinkedList; it would be possible, for
example, to use java.util.ArrayList. |
Element Level
These attributes can be applied at the element level by including them within a <element> section:
| Name | Values | Description |
|---|---|---|
| <aligned/> | n/a | This item is used to specify that byte alignment is to be done after encoding or decoding this element. This item is only supported for 3GPP layer 3 code generation. |
| <asn1typename/></asn1typename> | ASN.1 type name | This allows you to specify the ASN.1 name to use for an anonymous type. The anonymous type will be treated as if it were a named type having the given name. |
| <cDecSrcName> </cDecSrcName> | Java source file name | This item is used (despite the name) to substitute the Java source code contained within the given file for what would have been generated for decoding the element. The code in this case is not a complete function but rather a snippet to be inserted within a larger function. The current include path is searched for the given filename. This item is only supported for 3GPP layer 3 code generation. |
| <cEncSrcName> </cEncSrcName> | Java source file name | This item is used to substitute the Java source code contained within the given file for what would have been generated for encoding the element. The code in this case is not a complete function but rather a snippet to be inserted within a larger function. The current include path is searched for the given filename. This item is only supported for 3GPP layer 3 code generation. |
| <end3GExtElem name="element name"/> | <Element name> attribute | This item is used to delimit a group of optional elements that start with an 'ext' boolean element. A common pattern in the specification of 3GPP IE's is to include an extension bit to signal the presence or absence of group of elements (these normally comprise a single octet). This is essentially an alternative way to specify an optional element group in ASN.1. This item is only supported for 3GPP layer 3 code generation. |
| <iei format="t|tv|tlv" length="length"/> | IEI hex value | This item is used to indicate an element is part of the non-imperative part 3GPP layer 3 message. These are optional elements with single byte tags. The tag is the IEI hex value specified at the value of the item. The format attribute specifies if the item is a tag (t), tag/value (tv), or tag/length/value (tlv). The length attribute is only required if format if tv to specify the length of the value. This item is only supported for 3GPP layer 3 code generation. |
| <inline/> | n/a | This item is used to indicate that code generated for a nested item within a constructed type should be expanded inline rather than pulled out to create a separate new type. |
| <is3GExtList pre-eol="0|1" post-eol="0|1"/> | n/a | This item specifies that this element will be modelled as a 3G extended list. This can only be applied to elements of type SEQUENCE OF. It is used in 3G layer 3 messages when the extension of a repeating type is controlled by an extension bit that occurs either before or after the record. If the pre-eol attribute (short for "preceding end-of-list") is specified, it indicate a bit before the record signals whether another record follows. The value (0 or 1) indicates which bit value signal end-of-list. The post-eol attribute is the same except that it indicates the control bit follows after the record. This item is only supported for 3GPP layer 3 code generation. |
| <is3GLength bitFieldSize="nbits" units="bits|bytes"/> | n/a | This item is used to mark an element as a 3GPP length field element. Normally this an element with the name 'length' of type INTEGER that is the first element in a SEQUENCE. This indicates special processing should be done on the element. On encode, any value populated in this field will be ignored and the actual length of the encoded data will be calculated and populated in this field after encoding is complete. On decode, this element is used to determine when end of message occurs. The 'bitFieldLength' attribute is used to specify the field size if it not an even octet (8 bits). The 'units' attribute specifies the units stored in the length field (bits or bytes). This item is only supported for 3GPP layer 3 code generation. |
| <is3GVarLenList lengthElem="name"/> | n/a | This item specifies that this element will be modelled as a 3G variable length list. This can only be applied to elements of type SEQUENCE OF. It is used in 3G layer 3 messages when a length element is used to determine the number of items in the list. The 'lengthElem' attribute specifies the element within the structure that contains this count. This item is only supported for 3GPP layer 3 code generation. |
| <length fixed-size="number" expr="@-notation-expr" unusedBits="@-notation-expr"/> | n/a |
This item is used to configure a length field for an OCTET STRING, SEQUENCE OF, TBCD or GSM string type, for 3GPP layer 3 messages. This item is only supported for 3GPP layer 3 code generation. The fixed-size attribute is used to specify the size of a length field that immediately precedes the related type. By default, length fields are assumed to be a single byte, but other sizes are possible. The value 0 indicates there is no length field (the value ends when the enclosing IE ends). Another common value is 2, for a two-byte length field. The expr attribute identifies another field that provides the length. This uses the @-notation used for table constraints and can be a simple expression using + or - operators. The unusedBits attribute identifies a field that provides the number of unused bits for a GSM string. It uses the same format as the expr attribute. |
| <isBigInteger/> | n/a |
This is a flag variable (an 'empty element' in XML terminology) that specifies that this production will be used to store an integer larger than the Java long type (64 bits). A Java BigInteger class will be used to hold the value. This qualifier can be applied to either an integer or constructed type. If constructed, all integer elements within the constructed type are flagged as big integers. |
|
<isOpenType/> |
n/a | This flag variable specifies that this element will be decoded as an open type (i.e. skipped). Refer to the section on deferred decoding and partial decoding for further information. Note that this variable can only be used with BER, CER, or DER encoding rules. |
| <notUsed/> | n/a | This flag variable specifies that this element will not be used at all in the generated code. It can only be applied to optional elements within a SEQUENCE or SET, or to elements within a CHOICE. Its purpose is for production of more compact code by allowing users to configure out items that are of no interest to them. |
| <notUsedSkip/> | n/a | This is the same as <notUsed/> except that it tells the compiler to generate skip functions when necessary. Skip functions are used for skipping over values of a type during decoding, rather than reporting an error if that type should happen to be encountered in the encoding. |
| <notUsedDecode/> | n/a | Similar to the notUsed flag, except that rather than indicating the element is not used at all, it indicates the element is not used for decoding (i.e. it is still used for encoding). This can be useful for reducing the amount of generated code, when used in conjuction with a production level <include/> (which see). It signals that the element's type does not require a decode function for the sake of this element. |
| <notUsedDecodeSkip/> | n/a | This is the same as <notUsedDecode/> except that it tells the compiler to generate skip functions when necessary. Skip functions are used for skipping over values of a type during decoding, rather than reporting an error if that type should happen to be encountered in the encoding. |
| <notUsedEncode/> | n/a | The encoding complement to <notUsedDecode/> |
| <selector element="name" value="value"/> | n/a | This item is used to configure an element within a CHOICE in a 3GPP layer 3 message. It specifies the value of another element within the container type which selects this element. The 'element' field specifies the name of the element within the container type and 'value' specifies the value. This item is only supported for 3GPP layer 3 code generation. |
|
<skip/> |
n/a | Deprecated. This is now equivalent to <notUsedDecode/> |