We stand with Ukraine ASN.1/C Compiler Options Reference
This section lists the compiler options alphabetically and provides a thorough description of their function.
-1990 | -2021
Specifies the version of the standard used in the input ASN.1 specification files.
The -1990 option indicates that the ASN.1 specification should contain only syntax that conforms to the 1990 standard. The compiler provides support for the 1990 version of ASN.1, including the following features:
- Macro notation
- ANY DEFINED BYs
- Named types that have no identifiers
The compiler flags any syntax that follows a standard newer than 1990.
The -2021 option indicates that the ASN.1 specification should contain only syntax that conforms to a more modern ASN.1 standard than 1990. The compiler provides support for the 2021 version of ASN.1, including the addition of WITH SUCCESSORS and WITH DESCENDANTS to the imports clause, and for the following features:
- Automatic tagging
- Information object class
- Component relation constraints
- Table constraints
- User-defined constraints
- Parameterization
- Version brackets
- Subtype notation
- TIME, OID-IRI and RELATIVE-OID-IRI types
Default Behavior
By default, before detecting a particular type of notation, the compiler uses neutral mode. After the compiler detects notation particular to ASN.1:1990 or ASN.1:2021, it switches out of neutral mode and enforces conformance to that standard. One disadvantage of using neutral mode is that often, when creating new ASN.1 specifications, the debugging cycle may take longer than usual to complete.
Remarks
You can use both versions of the ASN.1 standard for the same specification; however, this behavior is not allowed by the X.680 (2021) ISO/IEC 8824-1:2021 standard, and therefore the compiler will generate warnings.
When using ASN.1:2021 syntax, the compiler issues warnings or errors if:
- Components of a SET, SEQUENCE, or CHOICE do not have an identifier.
- Colons (":") are not included in open type values or CHOICE values.
- Value references appear before the DEFINITIONS keyword that signals the start of an ASN.1 module.
See Also
The -1993, -1994, -1997, -2002, -2008 and -2015 compiler options are equivalents of the -2021 option.
-allow argument
Enables the compiler to retain a previous behavior specified by an argument. Use this option sparingly, only when it is absolutely necessary for a specific task.
The option takes a single argument. If you use multiple compatibility options, it can be specified more than once.
Example:
asn1 foo.asn -allow BadValues -allow BadSerialFROM
Arguments
-allow BadComponentsOfWithAutoTagging
Instructs the ASN.1 compiler to expand the "COMPONENTS OF Type" notation and to apply automatic tagging to the outer type, regardless of whether automatic tagging transformation was applied to "Type" due to its location in the input ASN.1. When this flag is specified The ASN.1 compiler could produce different automatic tags when the definition of "Type" appears before or after the definition of the type that includes the "COMPONENTS OF Type" notation.
Example
A ::= SEQUENCE {
x INTEGER
}
B ::= SEQUENCE {
w [15] BOOLEAN,
COMPONENTS OF A,
COMPONENTS OF C
}
C ::= SEQUENCE {
y INTEGER
}
value B ::= {
w FALSE,
x 0,
y 0
}
Without -allow BadComponentsOfWithAutoTagging, the DER encoding of value is the following:
Tracing Information from the DER Encoder...
B SEQUENCE: tag = [UNIVERSAL 16] constructed; length = 9
w BOOLEAN: tag = [15] primitive; length = 1
FALSE
x INTEGER: tag = [0] primitive; length = 1
0
y INTEGER: tag = [0] primitive; length = 1
0
PDU successfully encoded, in 11 bytes:
30098F01 00800100 800100
With -allow BadComponentsOfWithAutoTagging:
Tracing Information from the DER Encoder...
B SEQUENCE: tag = [UNIVERSAL 16] constructed; length = 9
w BOOLEAN: tag = [15] primitive; length = 1
FALSE
x INTEGER: tag = [0] primitive; length = 1
0
y INTEGER: tag = [UNIVERSAL 2] primitive; length = 1
0
PDU successfully encoded, in 11 bytes:
30098F01 00800100 020100
-allow BadExplicitAutomaticTagging
Instructs the ASN.1/C compiler to use explicit automatic tagging not only for untagged but also for tagged CHOICE types, open types, and "DummyReference" types, based on the interpretation of clause 31.2.7 c of the X.680 2002 ASN.1 standard.
In the following example, if -allow BadExplicitAutomaticTagging is specified, the compiler uses explicit automatic tagging for the ch field that has the tagged CHOICE type. If -allow BadExplicitAutomaticTagging is not specified, the compiler uses implicit tagging for this field.
B4114 DEFINITIONS AUTOMATIC TAGS ::= BEGIN
Seq ::= [65] SEQUENCE { ch Cho }
Cho ::= [65] CHOICE { b BOOLEAN }
s Seq ::= { ch b : TRUE }
END
Version Information
The -allow BadExplicitAutomaticTagging compiler option is available in version 10.5 and later.
-allow BadExtensibilityImplied
This option instructs the ASN.1 compiler to ignore the EXTENSIBILITY IMPLIED option in the module definition for the following types defined in a module:
- All ENUMERATED types.
- SET, SEQUENCE, and CHOICE types whose type definitions match some other type definitions inside other modules that do not have the EXTENSIBILITY IMPLIED option.
Example
Mod DEFINITIONS AUTOMATIC TAGS ::= BEGIN
Set ::= SET {a INTEGER, b BOOLEAN}
Choice ::= CHOICE {a INTEGER, b BOOLEAN}
END
ModExt DEFINITIONS AUTOMATIC TAGS EXTENSIBILITY IMPLIED ::= BEGIN
SetExt ::= SET {a INTEGER, b BOOLEAN}
ChoiceExt ::= CHOICE {a INTEGER, b BOOLEAN}
EnumExt ::= ENUMERATED { a(1), b(2)}
END
When -allow BadExtensibilityImplied is specified, the SetExt, ChoiceExt, and EnumExt types are not marked as extensible in the generated code. As a result, their values could be incorrectly encoded using the Packed Encoding Rules.
-allow BadValues
This option is enabled by the default -relaxedMode option and it instructs the ASN.1 compiler to continue the current compilation if a content error occurs in the value notation of restricted character strings, OBJECT IDENTIFIER types, and extensible types.
Example
The following value notation will cause the ASN.1 compiler to exit with an error message:
myPhoneNumber NumericString ::= "(800) 555-1212 EXT-6"
myObjectID OBJECT IDENTIFIER ::= {0 26}
Remarks
According to the ASN.1 standard, the NumericString type allows numbers 0 through 9 and whitespace. However, the OBJECT IDENTIFIER type does not allow a value larger than 4 for its second node.
When the -allow BadValues option is specified, the compiler does not truncate the values of the following types:
- Restricted string, BIT STRING, and OCTET STRING types with extensible size constraints when the UNBOUNDED or NULLTERM representation is used.
- SEQUENCE OF and SET OF, unless the ARRAY representation is in use.
To instruct the ASN.1 compiler to treat the errors as warnings, use the -ignoreError compiler option.
This option also instructs the ASN.1 compiler to issue the warning message A1007W, instead of the error message A1006E in the case of a type-value mismatch in value assignments of ENUMERATED, SET, SEQUENCE or CHOICE types.
For ENUMERATED types, the option allows names from one ENUMERATED type to be used in the value of a different ENUMERATED type, as shown in the following example:
Enum1 ::= ENUMERATED {blue(0), red(1)}
Enum2 ::= ENUMERATED {green(3)}
var Enum1 ::= green
For SET, SEQUENCE, and CHOICE types, the option allows a difference in the tags of the fields and in the position of the extension marker.
-allow BadSerialFROM
Instructs the compiler to retain behavior prior to version 7.0, related to handling of a serial application of a permitted alphabet constraint applied to a type. When an effective permitted alphabet for a type is calculated, only the last constraint is considered.
Example
S ::= PrintableString (FROM("ABC")) (FROM("DEF"))
Remarks
Starting with version 7.0, the compiler issues an error in case the permitted alphabet is empty. However, if you specify the -allow BadSerialFROM, no error is issued and the alphabet "DEF" is used for S.
-allow Bad6.0Extensions
Instructs the ASN.1 compiler to ignore a tag conflict for an untagged extensible CHOICE inside an extensible SEQUENCE.
Example
S ::= SEQUENCE {
a INTEGER,
c C OPTIONAL,
...,
e BMPString,
...
}
C ::= CHOICE {
c1 [0] INTEGER,
c2 [1] IA5String,
...
}
Remarks
If you don't specify the -allow Bad6.0Extensions, the compiler issues the following error:
"test.asn", line 4 (M): A0554E: Extension marks conflict in type S: extension marker and element 'c' (line 4).
-allow incompatibleGovernorsForObjectValueSets
This option instructs the ASN.1 compiler to accept information object sets or value sets as actual parameters even when they have governors that are not compatible with the actual parameters of the paramdummy governors included in an instance of a parameterized type. As a result, the generated code might have issues.
For example, the time-optimized code generated by the ASN.1/C compiler could fail during C compilation, and the following errors could be reported:
error C2065: '_ref_ids0': undeclared identifier error C2099: initializer is not a constant
Example
B4468 DEFINITIONS ::= BEGIN
MACAlgorithms ALGORITHM ::= { ... }
MessageAuthenticationCodeAlgorithm ::= AlgorithmIdentifier
{MAC-ALGORITHM, {MACAlgorithms}}
AlgorithmIdentifier {ALGORITHM-TYPE, ALGORITHM-TYPE:AlgorithmSet} ::=
SEQUENCE {
algorithm ALGORITHM-TYPE.&id({AlgorithmSet}),
parameters ALGORITHM-TYPE.&Params({AlgorithmSet}{@algorithm})
}
ALGORITHM ::= CLASS {
&id OBJECT IDENTIFIER UNIQUE,
&Params
}
MAC-ALGORITHM ::= CLASS {
&id OBJECT IDENTIFIER UNIQUE,
&Params,
&Other OPTIONAL
}
END
The governor of the information object set, MACAlgorithms, used as the actual parameter in MessageAuthenticationCodeAlgorithm, is ALGORITHM, but it should be MAC-ALGORITHM according to the definition of the parameterized type AlgorithmIdentifier {} . When -allow incompatibleGovernorsForObjectValueSets is not in effect, the ASN.1 compiler reports the following errors when the -autoencdec option is specified:
"b4468.asn", line 4 (B4468): A0998E: The governor 'MAC-ALGORITHM' of the dummy parameter 'AlgorithmSet' and the governor of the valueset 'MACAlgorithms' used as the actual parameter in the instance 'MessageAuthenticationCodeAlgorithm' of the parameterized type 'AlgorithmIdentifier' are not compatible.
"b4468.asn", line 8 (B4468): A0875E: The ObjectClassFieldType uses the class 'MAC-ALGORITHM' while the information object set of class 'ALGORITHM' is used in the TableConstraint or ComponentRelationConstraint. The same class must be used for both.
"b4468.asn", line 9 (B4468): A0875E: The ObjectClassFieldType uses the class 'MAC-ALGORITHM' while the information object set of class 'ALGORITHM' is used in the TableConstraint or ComponentRelationConstraint. The same class must be used for both.
-allow MixedCaseForSomeBuiltInTypesNames
This option is enabled by the default -relaxedMode option and it instructs the compiler to accept mixed case names for some ASN.1 built-in types, if types with such names are not already defined in the ASN.1 input.
Example
Type ::= IA5STRING value Type ::= "abc"
Remarks
The compiler will assume that the IA5STRING is the built-in type IA5String.
-allow namedBitThatExceedsConstraint
When a named bit is larger than the size of a BIT STRING, the ASN.1 Compiler issues an error and stops. This flag causes the compiler to issue a warning instead.
-allow UnderscoresInAsn1Names
This option is enabled by the default -relaxedMode option and it instructs the ASN.1 compiler to accept ASN.1 names that contain the underscore character ("_") after the initial character.
Example
Some_Type ::= INTEGER
-allow universaltags
The option instructs the ASN.1 compiler to accept tags of the UNIVERSAL tag class.
You can use the UNIVERSAL tag class for:
- IMPLICIT tags whose number corresponds to a built-in type tag.
- CHARACTER STRING and OCTET STRING types with a specified tag number corresponding to one of the restricted character string types.
If you use the UNIVERSAL tag for the CHARACTER STRING and OCTET STRING types, the compiler will redefine the type to be a restricted character string type according to its tag number.
Example
M DEFINITIONS IMPLICIT TAGS ::= BEGIN
B-ignore ::= [UNIVERSAL 1] IMPLICIT BOOLEAN
CS-ignore ::= [UNIVERSAL 29] CHARACTER STRING
OS-ignore ::= [UNIVERSAL 4] OCTET STRING
GT-ignore ::= [UNIVERSAL 24] GeneralizedTime
UTCT-ignore ::= [UNIVERSAL 23] UTCTime
U8-ignore ::= [UNIVERSAL 12] UTF8String
BMP-ignore ::= [UNIVERSAL 30] BMPString
CS-U8 ::= [UNIVERSAL 12] CHARACTER STRING
OS-U8 ::= [UNIVERSAL 12] OCTET STRING
CS-BMP ::= [UNIVERSAL 30] CHARACTER STRING
OS-BMP ::= [UNIVERSAL 30] OCTET STRING
END
Remarks
In this example, type CS-U8 is treated as a UTF8String. The following warning message is issued:
A1163W: OSS has relaxed the standards to allow the definition of a type with the tag [UNIVERSAL 12] resulting in 'CHARACTER STRING' to be redefined to 'UTF8String'.
This option is enabled by default in trial versions of the ASN.1 compiler.
See Also
-assignments
Instructs the ASN.1 compiler to process type and value assignments found outside input modules.
Example
Module1 DEFINITIONS ::= BEGIN
MyInt ::= INTEGER
END
ExtraModularType ::= INTEGER
Module2 DEFINITIONS ::= BEGIN
MyBit ::= INTEGER
END
Remarks
If the -assignments option is not specified, the ASN.1 compiler issues an error because ExtraModularType is outside the bounds of the BEGIN and END keywords.
-autoEncDec
Allows open types to be automatically encoded/decoded even when runtime constraint checking is disabled, which results in a faster and more efficient use of system resources.
Remarks
Open types can be regarded as messages within messages. They are decoded by decoding the outer message in one pass, then decoding the inner message in a second pass. Encoding is the opposite, first encoding the inner message in one pass, then encoding the outer message in a second pass. The OSS runtime can be set to decode open types either manually, where you call ossDecode() for each pass, or automatically, where you call ossDecode() once and the runtime takes care of the additional passes on its own. Likewise for encoding.
Open types are usually defined as component relation constraints. Difficulty arises when constraint checking is disabled because component relation constraint checking is disabled as well, and so is automatic decoding and encoding.
For example, if you employ the -noConstraints option to save the processing time which constraint checking consumes, you don't expect it to also disable automatic encoding and decoding of open types. Similarly, if you use the TOED runtime, where -noConstraints is the default, you don't expect to disable automatic encoding and decoding of open types. The function of the -autoEncDec option is to counter these unexpected effects.
In a nutshell, -autoEncDec leaves component relation constraint checking enabled even if all other constraint checking is disabled.
See Also
-ber | -der | -cer |-per | -uper | -cper | -cuper | -xer | -cxer | -exer | -oer | -coer | -json | -avn | -csv
Specifies the encoding rules available at runtime:
- Basic Encoding Rules (-ber)
- Distinguished Encoding Rules (-der)
- Canonical Encoding Rules (-cer)
- Aligned Basic-Packed Encoding Rules (-per)
- Unaligned Basic-Packed Encoding Rules (-uper)
- Aligned Canonical-Packed Encoding Rules (-cper)
- Unaligned Canonical-Packed Encoding Rules (-cuper)
- XML Encoding Rules (-xer)
- Canonical XML Encoding Rules (-cxer)
- Extended XML Encoding Rules (-exer)
- Octet Encoding Rules (-oer)
- Canonical Octet Encoding Rules (-coer)
- JSON Encoding Rules (-json or -jer)
- ASN.1 Value Notation Encoding Rules (-avn)
- Comma-Separated Value Encoding Rules (-csv)
Remarks
- The Comma-Separated Value (CSV) encoding rules are currently supported only by the TOED runtime; this feature is not available in RTOED. The -csv compiler option is not compatible with the -soed or -rtoed option.
- ASN.1 Value Notation encoding rules (AVN) are currently supported by the TOED runtime only. The -avn compiler option is not compatible with the -soed option.
- Currently, only the Space-Optimized Encoder/Decoder (SOED) supports CER.
- When you specify the -xer, -cxer, or -exer option, -debug is also enabled. Also, the header file is identical to the one that is generated without these options.
- The options have the following precedence: (1) -ber, (2) -per, (3) -der, (4) -uper, (5) -xer, (6) -cxer, (7) -cer, (8) -exer, (9) -oer, (10) -coer, (11) -json, (12) -cper, (13) -cuper, (14) -avn, (15) -csv. For example, if you specify -der -per -xer, the PER encoding rules will be used by default, but you can switch to DER and XER at runtime.
The specific encoding rules available at runtime when one of these command-line options is specified vary according to the encoder/decoder library in use. This is summarized in the following table:
| -ber | -per | -der | -uper | -xer | -cxer | -cer | -exer | -oer | -coer | -json | -cper | -cuper | -avn | -csv | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| SOED | BER | PER UPER |
DER BER |
UPER PER |
XER | XER CXER |
CER BER |
E-XER | OER | COER OER |
JSON | CPER CUPER PER UPER |
CUPER CPER PER UPER |
N/A | N/A |
| TOED | BER | PER | DER BER |
UPER | XER | CXER | N/A | E-XER | OER | COER | JSON | CPER | CUPER | AVN | CSV |
| LED | BER | PER UPER |
DER BER |
UPER PER |
XER | XER CXER |
N/A | E-XER | OER | OER COER |
JSON | CPER CUPER PER UPER |
CUPER CPER PER UPER |
N/A | N/A |
To switch between encoding rules at runtime, specify all options. Then, use the ossSetEncodingRules() function to switch to one of these encoding rules before calling the encoder or decoder. For example:
ossSetEncodingRules(world, OSS_DER); /* switch to DER */
Version Information
The -json compiler option is available since version 10.3.
The -avn compiler option is available since version 11.1.
-C | -C++
Instructs the compiler to generate header files and control table or code file for a C or C++ application.
Remarks
The default setting (-c) of the ASN.1 compiler is to generate C code. Such C, although perfectly valid, is not always accepted by the more demanding rules of a C++ compiler. When you specify the -c++ option, you ask the ASN.1 compiler to generate C code which is also suitable for use with a C++ compiler. Note that -c++ does not generate C++ classes.
The generated C or C++ headers and .c or .cpp files are similar, but certain constructs that cannot be used in both languages are modified to avoid C or C++ compiler errors. For example, if you specify the -C++ option and use class as an identifier in the ASN.1 input, it is modified before it is written to the header file, because it is a C++ reserved word. However, if you specify the -C option, the identifier is not modified because it is not a C reserved word.
Reserved words for -C and -C++: auto, break, case, char, const, continue, default, do, double, else, enum, extern, float, for, goto, if, int, long, main, register, return, short, signed, sizeof, static, struct, switch, typedef, union, unsigned, void, volatile, while.
Reserved words for -C++: asm, auto, bool, catch, class, const_cast, delete, dynamic_cast, explicit, false, friend, inline, mutable, naked, namespace, new, operator, private, protected, public, reinterpret_cast, static_cast, template, this, thread, throw, true, try, typeid, typename, using, uuid, virtual, wchar_t, xalloc.
See Also
-charIntegers
Instructs the ASN.1 compiler to generate an unsigned char or a signed char for an INTEGER type when it is constrained to a range of values that fits into one byte.
Example
| ASN.1 | C |
|---|---|
A ::= INTEGER (0..7) B ::= INTEGER (0..255) C ::= INTEGER (0..256) D ::= INTEGER (-100..100) E ::= INTEGER (-1..127) F ::= INTEGER (-1..128) |
typedef unsigned char A; typedef unsigned char B; typedef unsigned short C; typedef signed char D; typedef signed char E; typedef short F; |
-commandFile filename
Instructs the ASN.1 compiler to take files and options from filename as if they were found on the command line. This option is useful when you have many input files or options on the command line.
Example
To compile input.asn using the command-line options included in the tenLinesOfOptions.opt text file, the following command is issued:
asn1 input.asn -commandFile tenLinesOfOptions.opt
Remarks
Command files may contain comments. The "--" characters specify the beginning of a comment. They can be placed anywhere on the line. The comment continues until a subsequent "--" is reached or until the line ends.
-codeFile [CFileName] | -noCodefile
-controlFile [CFileName] | -noControlFile
The -codeFile [CFileName] | -noCodefile compiler option has been renamed to -toedFile [toedCFileName] | -noToedFile.
The -controlFile [CFileName] | -noControlFile compiler option has been renamed to -soedFile [soedCFileName] | -noSoedFile.
-comments | -noComments
Informs the compiler whether it should transfer ASN.1 comments from the input ASN.1 file to the generated header file using valid C or C++ comment constructs.
See Also
-compactNoDecode
Instructs the compiler to generate a compact version of the Time-Optimized Decoder code for fields marked with the OSS.NODECODE directive. Note that when a field marked with the OSS.NODECODE directive is present in the input encoding, an error is reported if the compact version of the decoder is used (however, the error is not reported for open type fields and extension additions because the decoder easily skips these fields).
Default Behavior
The -compactNoDecode option is disabled.
Remarks
The -compactNoDecode option cannot be used with the -soedFile or -controlFile option and imposes the following restriction when using the OSS.NODECODE directive: the directive must be applied either to all fields of an extension group or to none of the fields of an extension group.
See Also
-compat VersionNumber | Option
Instructs the compiler to generate header and .c files compatible with previous versions of the OSS ASN.1 compiler.
Remarks
This option takes a single operand or flag, and can be specified more than once. For example:
asn1 foo.asn -compat v3.6 -compat noUInt
NOTE: OSS does not guarantee compatibility between different versions of the ASN.1 Tools released more than 10 years apart.
For more information about the arguments that can be specified with the -compat option, see Backward Compatibility.
-compress
Enables compression during runtime. This option is available for all encoding rules, but is especially useful for text-based encoding rules like XER or E-XER.
Default Behavior
By default, the OSS libraries use the common zlib/gzip algorithm for compression. However, you can also substitute your own compression routines with the ossSetCompressDecompressFunctions() | ossGetCompressDecompressFunctions() routines.
Remarks
During runtime, before calling the encoder/decoder for the types used for compression, you must specify the USE_COMPRESSION flag using the ossSetFlags() flag.
Currently, only the Space-Optimized Encoder/Decoder supports compression.
Handling of ASN.1 types marked with the OSS.NOCOPY or the ASN1.DeferDecoding directive is disabled in the decoder because these directives require uncompressed encoded data to be available immediately after decoding.
NOTE: Before you employ compression, make sure the default memory manager is enabled.
For more details about using compression, see OSS API/C Runtime.
-constraints | -noConstraints
The -constraints option instructs the compiler to generate information in the code for runtime constraint checking.
The -noConstraints option disables generation of information in the code for runtime constraint checking. The size of the generated code is smaller and can be executed faster. Also, user-defined constraint checking functions are not called.
Default Behavior
For SOED: -constraints.
For TOED and LED: -noConstraints.
Remarks
To disable runtime constraint checking when the -constraints option is present, specify the NOCONSTRAIN encoder/decoder flag.
When neither the -constraints nor the -noConstraints option is specified, the TOED checks the encoded size of a size constrained UNBOUNDED string to make sure it does not exceed the upper bound. If otherwise, the TOED will report an error. For example, when a length is encoded incorrectly, instead of full constraint checking which consumes a large amount of memory, the verification performed by the TOED is more efficient.
See Also
-CStyleComments
Instructs the ASN.1 compiler to transfer input ASN.1 comments to the generated header file using language comment tokens specific to C (/* comment text */, for example) instead of C++ (// comment, for example) for single line comments when the -C++ option is specified.
When CStyleComments is used with -C++, the compiler generates files compatible with C and C++ compilers.
Default Behavior
By default, when -C++ is enabled, single-line ASN.1 comments are transferred using C++ comments.
Remarks
To disable ASN.1 comments to be transferred to the header file, specify the -compat noASN.1Comments option.
See Also
-debug | -noDebug
Enables or suppresses generation of debugging information into a C file.
When -debug option is specified, the encoder/decoder can access and print the C file if it encounters an error, and then it generates descriptive messages that include the names of ASN.1 identifiers and DefinedTypes.
Default Behavior
Unless the -lean option is specified, the -debug option is used by default.
Remarks
When you use the TOED -codeFile option, specify the C compiler option -DOSSDEBUG=2 to generate descriptive error messages.
When you specify the -xer option, the -debug option is enabled and the -noDebug is ignored.
-decodeOnly | -encodeOnly
Informs the compiler whether it should generate decoding or encoding routines for the Time-Optimized Encoder/Decoder.
Default Behavior
By default, the compiler generates encoder and decoder routines.
Remarks
When you use SOED and -xer or -cxer is not specified, the information generated into the control table is used for encoding and decoding, therefore -decodeOnly | -encodeOnly has no effect.
When -xer or -cxer is specified, you can use -decodeOnly | -encodeOnly to reduce the amount of the Space-Optimized library code linked to your final application.
-defines | -noDefines
Informs the compiler whether it should generate #define for constants in the header file.
Example
When you specify the -noDefines option, the #define My_PDU 1 is replaced with const unsigned int My_PDU = 1.
-designerWarnings
Instructs the ASN.1 compiler to generate additional warning messages for protocol designers writing ASN.1 specifications.
Remarks
Additional warning messages are issued when:
- -per, -uper, -cper, or -cuper is used, but the compiler finds a SET, SEQUENCE, or CHOICE type that contains a single component and no extension marker. When you use PER, you cannot add fields, therefore a structured type with only one field is inefficient.
- -per, -uper, -cper, or -cuper is specified and there is more than one unreferenced type in the root module. This might cause problems to determine the PDU number when decoding, because PER encodings have no tag information. In this case, the application developer must pass the desired PDU number to the decoder.
- ObjectSetFromObject notation is used for dummy information object sets, but a defined object set is missing in a table constraint.
- An information object CLASS is defined using the WITH SYNTAX notation, but an optional element is not enclosed in square brackets ("[]").
- A contents constraint includes only the ENCODED BY clause without a containing type defined, and automatic encoding/decoding is enabled.
- A WITH COMPONENTS clause that has the OPTIONAL or ABSENT keyword applied to a type defined with a DEFAULT value is present in the input ASN.1 specification.
-dtd
Generates multiple Data Type Definitions (DTD) files, one for each PDU. Usually, even when the XER encoding rules are requested, no separate DTD file is produced.
Remarks
The generated files have the .dtd extension and a filename prefix identical to the name generated for their corresponding PDU. The filename prefix and the extension are affected by the OSS.DTD, ASN1.Nickname directives, and by the -output and the -prefix options.
To generate a reference to your data definition file with ossEncode() while producing its XML output for a particular PDU, you must call the ossSetXmlDTD() function before you invoke the encoder.
See Also
-dualHeader
Instructs the ASN.1 compiler to generate a header file which can be used in C and C++ applications. This is achieved by generating preprocessor directives.
Example
#ifdef __cplusplus /* C++ code */ #else /* C code */ #endif
When you compile your application as C++, specify the D__cplusplus for your C++ compiler.
To compile the generated .c file in a C++ compiler, specify the -c++ option with the -dualHeader option.
See Also
-enablePartialDecode
Instructs the ASN.1 compiler to enable partial decoding in addition to standard decoding. Encoding is not affected. Partial decoding is only supported by the TOED runtime. That is, -enablePartialDecode cannot be used together with the -soedFile or -controlFile option.
The -enablePartialDecode option is supported by the BER, DER, PER, UPER, CPER, CUPER, OER, and COER encoding rules.
Default Behavior
The -enablePartialDecode option is disabled.
See Also
-errorFile errorFileName
Instructs the compiler to redirect all ASN.1 compiler messages to an error file. This is useful on platforms where you cannot redirect stdout and stderr to a file.
If an error is detected on the command line before you specify the -errorFile option, the message is written to stdout. To write all command-line error messages to the error file, specify first the -errorFile option.
Example
asn1 -err myErrs.err foo.asn
Remarks
If errorFileName does not have an extension, it will receive the .err extension (or "e" on the Tandem NonStop OS). If it has the .asn extension, it will be replaced by .err; otherwise, the errorFileName keeps the extension specified by you.
When the compiler is invoked again, existing error files with the same name are overwritten.
-exportDllAPI
Allows helper list API functions generated by the ASN.1 compiler to be exported from a control table or code file DLL. The functions can be used in your application during runtime. This option is available for the OSS ASN.1 Tools for Windows.
Remarks
When you specify the -exportDllAPI option, each API function generated by the ASN.1 compiler receives an additional qualifier that precedes the function declaration, OSS_EXPORT_DLL_DATA. The qualifier is a macro that exports the function from DLL.
To learn how to build a control table or code file as a DLL, from which the API functions marked by OSS_EXPORT_DLL_DATA are exported, check the samples/advanced/control_table for the exact build sequence.
Example
To link an application to the control table or code file and use the exported functions, you must redefine the OSS_EXPORT_DLL_DATA as follows:
#define OSS_EXPORT_DLL_DATA __declspec(dllimport)
Then, include the OSS-generated header file into the application code (if Microsoft Visual C is in use). The functions will immediately be visible to the application.
The -exportDllAPI option is used for the following ASN.1 specification with the -helperListAPI option:
M DEFINITIONS ::= BEGIN S ::= SEQUENCE OF BIT STRING END
The generated API functions:
/* creates an empty list */ OSS_EXPORT_DLL_DATA struct S * DLL_ENTRY oss_S(OssGlobal *_world); /* creates a list node for the given value of 'struct _BitStr' */ OSS_EXPORT_DLL_DATA S_node * DLL_ENTRY oss_S_node(OssGlobal *_world, struct _BitStr * _value); /* appends a value of 'struct _BitStr' to the end of the list */ OSS_EXPORT_DLL_DATA S_node * DLL_ENTRY oss_S_append(OssGlobal *_world, struct S * _list, struct _BitStr * _value); ...
See Also
-exportDllData
Allows initialized values generated by the ASN.1 compiler to be exported from a control table or code file DLL. The values can be used in your application during runtime. This option is available for the OSS ASN.1 Tools for Windows.
Example
When you use -exportDllData for the following ASN.1 specification:
TEST DEFINITIONS ::= BEGIN
PsType ::= SEQUENCE { letters PrintableString (SIZE(1..5)) }
docName PsType ::= { letters "abcde" }
END
The ASN.1 compiler generates at the bottom of the output header file:
OSS_EXPORT_DLL_DATA PsType docName;
The macro OSS_EXPORT_DLL_DATA exports the named variable from a control table or code file compiled as a DLL.
-extendOpenType
Generates an extra field called userfield of type void * in the OpenType structure. This field can be used in your application, but it is ignored by the encoder/decoder.
-externalName controlTableExternalName
Specifies the name of the external variable referencing the Space-Optimized Encoder/Decoder control table or the Time-Optimized Encoder/Decoder entry points. This variable is the last one generated in the .c and .h files.
Default Behavior
The external variable name is the same as the last input filename on the command line (without the .asn extension).
-genDirectives genDirFileName
Instructs the ASN.1 compiler to generate a .gen file that captures all directives from the ASN.1 input file as well as directives for names produced by the compiler (_setof1, for example).
Remarks
The optional operand genDirFileName specifies the name of the .gen file. If the filename is not specified, the ASN.1 compiler generates one from the last ASN.1 input file specified on the command line and substitutes .asn with .gen.
Limitations
The compiler does not generate the ASN1.Nickname or the OSS.TYPENAME directive for mangled names in definitions of internal OSS types (ObjectID, External, EmbeddedPDV, ABSTRACT_SYNTAX, TYPE-IDENTIFIER).
The compiler does not generate the OSS.ExtractType or the OSS.InlineType directive for elements of COMPONENTS OF and for elements of MACRO definition. These directives must be manually added into .gen files after the ASN.1 compiler has generated them.
See Also
-headerFile headerFileName | -noHeaderFile
Specifies whether a header file should be generated and what its name should be.
Remarks
The header file can be regarded as the ASN.1 definitions translated into C definitions.
-noHeaderFile specifies that no header file should be generated.
-headerFile filename specifies that a header file should be generated and be named filename.
-headerFile without a filename (the default) says that a header file should be generated and its name should be taken from the last input ASN.1 file. For example:
asn1 abc.asn def.asn ghi.asn -headerFile
creates a header file named ghi.h.
Having neither -noHeaderFile nor -headerFile specifies, since -headerFile is the default, the same thing as -headerFile without a filename.
To learn how the name given to the header file and its location are affected, see the -output option.
-hdebug
Instructs the ASN.1 compiler to generate compile-time type checking diagnostics in the generated helper macros. You can use it in your application during the development stage to enable compile-time type checking, in order to detect incorrect usage of the helper macros. It is not recommended to use the -hdebug option in a production environment because it might influence the performance of the application.
Example
In this example, the -helperMacros option is also applied:
| ASN.1 | without -hdebug | with -hdebug |
|---|---|---|
M DEFINITIONS ::= BEGIN
S ::= SEQUENCE {
i INTEGER OPTIONAL
}
END
|
/* sets "i" field value */
#define oss_S_i_set(outp, i_) \
{ \
(outp)->bit_mask |= i_present; \
(outp)->i = (i_); \
}
|
/* sets "i" field value */
#define oss_S_i_set(outp, i_) \
{ \
S *out = outp; \
(out)->bit_mask |= i_present; \
(out)->i = (i_); \
}
|
When you use -hdebug and you initialize a variable of a different type (other than SEQUENCE) with this macro, the C compiler generates a warning.
See Also
-help
Displays a list of all command-line options.
Example
By entering asn1 -help you can obtain a summary of valid command-line options:
OSS ASN.1 Compiler Version 12.0
Copyright (C) 2024 OSS Nokalva, Inc. All rights reserved.
Compiler parameters: (.D. indicates default)
<input> <...input> . one or more ASN.1 input files
-cont <ctrlfile> ... alias to -soed
-soed <soedfile> ... generate encoder/decoder control table
-nocont ... alias to -nosoed
-nosoed ... do not generate encoder/decoder control table
-cod <codefile> ... alias to -toed
-toed <codefile> .D. generate time-optimized encoder/decoder code
into <codefile>
-nocode ... alias to -notoed
-notoed ... do not generate time-optimized encoder/decoder code
-lean ... generate LED compatible header files
-syntax ... perform syntax checking only
-h <headerfile> .D. generate C include file into <headerfile>
-noh ... do not generate include file
-output name ... use name for output file names
-nooutput ... do not generate output files, same as syntaxonly.
-errorfile file ... write all messages to 'file' instead of stdout/stderr
-list <listfile> ... generate an ASN.1 combined listing into 'listfile'
-nolist .D. do not generate an ASN.1 combined listing
-mod <listfile> ... generate single ASN.1 module listings into 'listfile'
-nomod .D. do not generate single ASN.1 module listings
-gendir <genfile>... generate list of directives into <genfile>
-sort .D. rearrange generated C types to remove forward references
-nosort ... generate C types in the same order as the ASN.1 input
-shortennames ... shorten generated variable names to be 31 bytes max
-noshortennames .D. do not shorten generated names
-uniquepdu .D. check that pdu id's are unique
-nouniquepdu ... do not check that pdu id's are unique
-prefix id ... prefix variables with unique id
-externalname name . external variable name of encoder/decoder info
-useXmlNames ... generates C type and field names according to E-XER
"NAME" encoding instructions
-constraints .D. check constraints at runtime
-restrictedConstraintChecking
... do not ignore the OSS.NoConstrain directive
when -constraints is specified
-noconstraints ... do not check constraints at runtime
-userconstraints ... check user constraints (even for -noconstraints)
-nouserconstraints D do not check user constraints (even for -constraint)
-valuerefs ... generate valuereference info needed for IAAPI use
-novaluerefs .D. do not generate valuereference info needed for IAAPI use
-encodeonly ... generate only encoder routines
-decodeonly ... generate only decoder routines
-nostaticvalues ... initialize generated values at runtime
-test ... generate a program to encode/decode ASN.1 values
-notest .D. do not test encoding/decoding of all ASN.1 values
-debug .D. issue detailed trace data and error messages
-nodebug ... do not issue detailed trace data and error messages
to slightly improve CPU performance
-c .D. generate C compatible data types and names
-c++ ... generate C++ compatible data types and names
-dualheader ... generate headers files compatible with C and C++
-ansi .D. generate ansi c function prototypes
-defines .D. generate #define constants
-nodefines ... generate const-declarations instead of #define constants
-warning ... allow warning messages
-nowarning ... suppress warning messages
-dualheader ... generate headers files compatible with C and C++
-ansi .D. generate ansi c function prototypes
-defines .D. generate #define constants
-nodefines ... generate const-declarations instead of #define constants
-warning ... allow warning messages
-nowarning ... suppress warning messages
-suppress msg# ... suppress a specific message
-ignoresuppress ... ignore the SUPPRESS directive (display all messages)
-verbose ... display compilation progress messages
-noverbose .D. do not display compilation progress messages
-pedantic ... rigorously check all modules
-nopedantic .D. rigorously check only the root module(s)
-relaxedMode .D. automatically select command-line options that
result in relaxed compiler behavior, for example,
-allowBadValue, -noWarning, etc.
-norelaxedMode ... automatically select command-line options that
result in strict compiler behavior
-informatory ... allow informatory messages
-noinformatory ... suppress informatory messages
-ignoreError msg# .. ignore a specific error (issue a warning instead)
-designerWarnings .. issue additional warnings for protocol designers
-compat version# ... disable new features for backward compatibility
-allow badcase ... enable badcases for backward compatibility
-1990 ... all modules conform to 1990 ASN.1 syntax
-2021 .D. all modules conform to 2021 ASN.1 syntax
-per ... generate output file for Aligned PER encoder/decoder
-cper ... generate output file for Canonical Aligned PER encoder/decoder
-uper ... generate output file for Unaligned PER encoder/decoder
-cuper ... generate output file for Canonical Unaligned PER encoder/decoder
-ber .D. generate output file for BER encoder/decoder
-der ... generate output file for BER & DER encoder/decoder
-xer ... generate output file for Basic XER encoder/decoder
-cxer ... generate output file for Canonical XER encoder/decoder
-cer ... generate output file for BER & CER encoder/decoder
-exer ... generate output file for EXTENDED XER encoder/decoder
-oer ... generate output file for OER encoder/decoder
-coer ... generate output file for Canonical OER encoder/decoder
-json ... generate output file for JSON encoder/decoder
-jer ... alias to -json
-csv ... generate output for CSV encoder
-compress ... use encoding compression (all encoding rules)
-commandfile <file> ... read command line from 'file'
-minimize ... generate the smallest possible output files
-root ... treat all modules as root modules
-keepnames ... generate directives for keeping names
-extendopentype ... add a userfield to the OpenType structure
-charintegers ... generate char for INTEGERs constrained to small values
-pdusforopentypes... ignore NOPDU directive for opentypes
-nopdusforopen ... do not generate PDUs for info objects with -noconstraints
-shippable ... generate .h file suitable for shipment
-allowbadvalues ... allow generation of bad values
-sampleCode <pdus|values>
... generate a sample code to initialize, encode, decode
and traverse values of PDU types defined in the input
ASN.1 syntax
-noSampleCode ... do not generate a sample code
-relaySafe ... retain unrecognized extension additions at runtime
-norelaySafe .D. do not retain unrecognized extension additions at runtime
-autoencdec ... permit automatic encoding/decoding even if -noconstraint
is used
-splitforsharing <splfile> ... generate personal header for each ASN.1 module
-splitheaders <splfile> ... generate header for each ASN.1 module and
a header which includes all module headers
-messageFormat <format>
... display error messages in <format>:
'oss', 'emacs' or 'msvc'
-xsl ... generate default stylesheet for each PDU
-dtd ... generate document type definition file for each PDU
-assignments ... process type and value assignments defined outside
ASN.1 modules
-exportdlldata ... exports all the external variables from a control table
or code file DLL for Windows platforms
-comments .D. generate ASN.1 comments as C style comments without -c++
and as C++ comments with -c++ in header file
-noComments ... do not generate ASN.1 comments in header file
-CStyleComments ... generate C style comments into header file with -c++
-pdusforcontainingtypes
... ignore NOPDU directive for types referenced by a
contents constraint
-nopdusforcontainingtypes
... do not generate PDUs for types referenced by a
contents constraint
-noHelperAPI .D. do not generate helper and list API macros
-helperAPI ... generate helper macros and list API macros for
all ASN.1 types represented by C structures
-nohelperNames .D. do not generate context-based names
-helperNames ... generate context-based names for nested ASN.1
built-in types represented by C structures
-helperDefineNames . generate context-based names for #define constants
used for bit-masks, named bits and numbers
-helperEnumNames ... generate context-based names for enumerators
-nohelperMacros .D. do not generate helper macros
-helperMacros ... generate helper macros for all ASN.1 types
represented by C structures
-nohelperListAPI .D. do not generate helper list API macros
-helperListAPI ... generate helper list API macros for all
SET OF and SEQUENCE OF types
-exportDllAPI ... export all helper list API functions from control table
or code file DLL for Windows platforms
-hdebug ... generate compile-time type checking diagnostic inside
helper macros
-ignoreIncompleteItems
... ignore incomplete ASN.1 definitions of types and values
-ignoreRedefinedAssignments
... ignore redefined ASN.1 definitions of types and values
-reservedWords <reserved_words>
... treat words specified in the parameter and separated
by commas as reserved words in the generated files
that should be always mangled
-relaxPerToedIntegerRangeConstraint
... relax check for upper bound of integer range
constraints in TOED PER encoding functions
-useQualifiedNames <maxPrefixLevel>
... generate context-based names for enumerators, named
numbers and bits
-enablePartialDecode
... generate time-optimized full and partial decoders
-partialDecodeOnly
... generate time-optimized partial decoder only
-compactNoDecode
... generate compact time-optimized decoder for fields
marked by NODECODE directive
-rtoed ... generate redeveloped time-optimized code
-multi ... generate integration module for multiple RTOED code files
-avn ... generate output file for TOED ASN.1 value notation decoder
.. Nov 16 2024 ..
Remarks
You can obtain a synopsis of the command-line syntax by entering asn1 with no arguments:
OSS ASN.1 Compiler Version 12.0
Copyright (C) 2024 OSS Nokalva, Inc. All rights reserved.
asn1 <infile(s)> [-c | -c++ ] [-debug | -nodebug ]
[-ber ] [-1990 | -2021 ] [-short | -noshort ]
[-der ] [-sort | -nosort ] [-unique | -nounique ]
[-per ] [-cper ] [-warn | -nowarn ] [-inform | -noinform ]
[-uper] [-cuper] [-extern <name> ] [-defines | -nodefines ]
[-xer ] [-cxer] [-suppress msg# ] [-noout | -out <name> ]
[-cer ] [-ignoresuppress ] [-pedantic | -nopedantic ]
[-exer] [-charintegers ] [-encodeonly | -decodeonly ]
[-oer ] [-coer] [-useXmlNames ] [-constrain | -noconstrain ]
[-json] [-nostaticvalues ] [-relaySafe | -norelaySafe ]
[-avn ] [-messageFormat ] [-test | -notest ]
[-csv ] [-allowbadvalues ] [-sampleCode | -noSampleCode]
[-verbose ] [-compat ver# ] [-list <file> | -nolist ]
[-lean ] [-extendopentype ] [-errorfile <errorfile> ]
[-compress ] [-designerWarnings ] [-commandfile <commandfile> ]
[-minimize ] [-assignments ] [-allow badcase ]
[-valuerefs ] [-splitheaders <splfile> | -splitforsharing <splfile> ]
[-autoencdec ] [-userconstraints | -nouserconstraints ]
[-shippable ] [-pdusforopentypes | -nopdusforopentypes ]
[-dualheader ] [-cstylecomments ] [-pdusforcontainingtypes ]
[-prefix prfx ] [-ignoreError msg# ] [-nopdusforcontainingtypes ]
[-keepnames ] [-gen <gendirfl> ] [-modlist <file> | -nomodlist ]
[-syntax ] [-exportdlldata ] [-comments | -noComments ]
[-root ] [-compactNoDecode ] [-h <headerfile> | -nohheader ]
[-soed <ctrlfile>| -nosoedFile ]
[-rtoed ] [-multi ] [-toed <cdfile> | -notoedFile ]
[-hdebug ] [-helperEnumNames ] [-helperAPI | -noHelperAPI ]
[-exportDllAPI] [-helperDefineNames ] [-helperNames | -noHelperNames]
[-dtd ] [-enablePartialDecode] [-helperMacros | -noHelperMacro]
[-xsl ] [-partialDecodeOnly ] [-helperListAPI | -noHelperList ]
[-relaxPerToedIntegerRangeConstraint ] [-relaxedMode | -norelaxedMode]
[-reservedWords <reserved_words> ] [-restrictedConstraintChecking ]
[-ignoreRedefinedAssignments ] [-ignoreIncompleteItems ]
[-useQualifiedNames <maxPrefixLevel> ]
enter "asn1 -help" for more information
Default Behavior
Command-line help is not displayed when you specify input files.
-helperAPI | -noHelperAPI
Enables or disables a set of -helper options :
Remarks
When you specify -helperAPI and a negative option (-noHelperListAPI, for example), the latter takes precedence.
When you specify -noHelperAPI, you can also use a positive option (-helperNames, for example).
-helperDefineNames
Instructs the ASN.1 compiler to use context-based naming conventions for generated bit-masks with _present or _chosen extension, and for named bits and numbers.
To enable this option, -helperNames must be specified or implied. -helperAPI, -helperMacros, or -helperListAPI imply the -helperNames option.
Remarks
-helperDefineNames does not change user-defined names assigned with OSS.FIELDNAME, OSS.DefineName, or ASN1.Nickname to a field, named bit, or named number for which a #define is generated.
Example
| ASN.1 | C |
|---|---|
S ::= SEQUENCE {
a INTEGER OPTIONAL,
b INTEGER --<FIELDNAME "myInt"> -- OPTIONAL
}
I ::= INTEGER {int1(1), int2(2)}
|
typedef struct S {
unsigned char bit_mask;
# define S_a_present 0x80
# define myInt_present 0x20
int a;
int myInt; } S;
typedef int I;
#define I_int1 1
#define I_int2 2
|
See Also
- -helperAPI | -noHelperAPI
- -helperListAPI | -noHelperListAPI
- -helperMacros | -noHelperMacros
- -helperNames | -noHelperNames
- -helperEnumNames | -noHelperEnumNames
-helperEnumNames
Instructs the ASN.1 compiler to use context-based naming conventions for generated enumerators.
To enable this option, -helperNames must be specified or implied. -helperAPI, -helperMacros, or -helperListAPI implies the -helperNames option.
Remarks
-helperEnumNames does not change user-defined names assigned to an enumerator using the ASN1.Nickname directive.
Example
| ASN.1 | C |
|---|---|
--<ASN1.Nickname Mod.Enum.en3 "my_name">--
Enum ::= ENUMERATED {en1, en2, en3}
|
typedef enum Enum {
Enum_en1 = 0,
Enum_en2 = 1,
my_name = 2
} Enum;
|
See Also
- -helperListAPI | -noHelperListAPI
- -helperMacros | -noHelperMacros
- -helperNames | -noHelperNames
- -helperDefineNames | -noHelperDefineNames
-helperListAPI | -noHelperListAPI
Informs the ASN.1 compiler whether it should generate a set of list manipulation API functions for each SET OF or SEQUENCE OF type specified in the input ASN.1 syntax which is represented as a DLINKED-PLUS C structure.
Example
M DEFINITIONS ::= BEGIN
Names ::= SEQUENCE OF IA5String
END
Remarks
The compiler produces the following functions:
/* ****************************************** */ /* Helper List API functions for 'Names' list */ /* ****************************************** */ /* creates an empty list */ struct Names * DLL_ENTRY oss_Names(OssGlobal *_world); /* creates a list node for the given value of 'char *' */ Names_node * DLL_ENTRY oss_Names_node(OssGlobal *_world, char * _value); /* appends a value of 'char *' to the end of the list */ Names_node * DLL_ENTRY oss_Names_append(OssGlobal *_world, struct Names * _list, char * _value); /* adds a value of 'char *' to the beginning of the list */ Names_node * DLL_ENTRY oss_Names_prepend(OssGlobal *_world, struct Names * _list, char * _value); /* adds a value of 'char *' to the certain position in the list */ Names_node * DLL_ENTRY oss_Names_insert(OssGlobal *_world, struct Names * _list, Names_node * _prev, char * _value); /* unlinks and frees node of list, doesn't free the node value */ char * DLL_ENTRY oss_Names_unlink(OssGlobal *_world, struct Names * _list, Names_node * _node);
You can use the previous functions to programmatically create list values:
Names n = oss_Names(world);
oss_Names_append(world, n, OSS_STR("Mary"));
oss_Names_prepend(world, n, OSS_STR("John"));
oss_Names_append(world, n, OSS_STR("Susan"));
OSS_STR is a macro that copies a string to the new memory (defined in OSS header files).
-helperListAPI option implies -helperNames and overrides the OSS.NoHelperListAPI directives.
List API functions are not produced for types that have the UNBOUNDED representation. To generate and use helper list API functions for these types, apply the DLINKED-PLUS directive.
With generated API functions you can automatically create a new list type, and add or remove list elements. Also, you can hide internals such as the exact operations performed to maintain a doubly-linked list of nodes in a consistent state. Additionally, if a memory handle is installed by a call to ossCreateMemoryHandle(), generated functions allocate output memory for the value using this handle.
See Also
-helperMacros | -noHelperMacros
Informs the ASN.1 compiler whether it should generate C helper macros for PDUs. -helperMacros implies -helperNames and overrides the OSS.NoHelperMacro directive.
You can use generated macros to automatically create C structure values, and access and modify those values. They hide internals such as the use of a bit mask field to indicate the presence of optional fields, memory allocation and input data copying. When you call the ossCreateMemoryHandle() API function, memory handle is installed, and all generated macros allocate memory from that handle.
The compiler generates the following types of macros:
- type_new / type_new_pdu
- Allocates a new empty value for the type. It can also assign another block of memory to store the value for "length-value pair" structures (SEQUENCE OF with the UNBOUNDED representation, for example).
- type_copy / type_copy_pdu
- Creates a complete copy of this value in the newly allocated memory. The input data is not referenced by the resulting value; however, a copy of it is created.
- type_copy_nullterm
- Has the same function as the previous one; however, it also calculates the length of the data with the strlen() function.
- type_setv
- Sets the length and value fields of a given structure.
- type_setv_nullterm
- Has the same function as the previous one; however, the data length is calculated by the strlen() function.
- type_field_get
- Returns the value of a given field of a SEQUENCE, SET, or CHOICE.
- type_field_set
- Sets a field value for SEQUENCE, SET, or CHOICE.
- type_field_is_present
- Checks if the optional or the default field is present in a SET or SEQUENCE type.
- type_field_omit
- Disables the optional field.
- type_field_default
- Indicates that the default value for the field must be used.
- type_which
- Indicates which alternative is present in a CHOICE type.
- type_copy_encoded and type_set_encoded
- For open types and types with contents constraints, they perform the same actions (copy the encoded data or set a pointer to it) as type_copy and type_setv macros perform for length-value types.
- type_copy_decoded and type_set_decoded
- For open types and types with contents constraints, they provide a decoded value of a type within the open type or contents constraint, either by copying it or by setting a reference to an existing type value.
Example
M DEFINITIONS ::= BEGIN
BTreeNode ::= SEQUENCE {
name IA5String,
left BTreeNode OPTIONAL,
right BTreeNode OPTIONAL
} --<PDU>--
END
The compiler generates the following helper macros:
typedef struct BTreeNode {
char *name;
struct BTreeNode *left; /* NULL for not present */
struct BTreeNode *right; /* NULL for not present */
} BTreeNode;
/* allocates memory for an empty instance of the sequence type */
#define oss_BTreeNode_new(world) \
(BTreeNode *)ossGetInitializedMemory(world, sizeof(BTreeNode))
/* allocates memory for BTreeNode_PDU */
#define oss_BTreeNode_new_pdu(world) \
oss_BTreeNode_new(world)
/* gets "name" field value */
#define oss_BTreeNode_name_get(inp) \
(inp)->name
/* sets "name" field value */
#define oss_BTreeNode_name_set(outp, name_) \
(outp)->name = (name_)
/* allocates memory for a string of given length */
#define oss_BTreeNode_name_new(world, length_) \
oss__CharStr_new(world, length_)
/* allocates memory and returns a copy of an input string */
#define oss_BTreeNode_name_copy(world, value_) \
oss__CharStr_copy(world, value_)
/* gets "left" field value */
#define oss_BTreeNode_left_get(inp) \
(inp)->left
/* sets "left" field value */
#define oss_BTreeNode_left_set(outp, left_) \
(outp)->left = (left_)
/* checks if "left" field value is present */
#define oss_BTreeNode_left_is_present(inp) \
((inp)->left != NULL)
/* indicates that "left" field value is absent */
#define oss_BTreeNode_left_omit(outp) \
(outp)->left = NULL
/* Macros for "left" field operate with 'BTreeNode' type; you may use macros
* after this type declaration to create its values */
/* gets "right" field value */
#define oss_BTreeNode_right_get(inp) \
(inp)->right
/* sets "right" field value */
#define oss_BTreeNode_right_set(outp, right_) \
(outp)->right = (right_)
/* checks if "right" field value is present */
#define oss_BTreeNode_right_is_present(inp) \
((inp)->right != NULL)
/* indicates that "right" field value is absent */
#define oss_BTreeNode_right_omit(outp) \
(outp)->right = NULL
/* Macros for "right" field operate with 'BTreeNode' type; you may use macros
* after this type declaration to create its values */
To create the following value:
tree BTreeNode ::= {
name "Root",
left { name "l",
right { name "lr" }
},
right { name "r" }
}
you can use these macros:
BTreeNode *tree, *l, *r, *lr; tree = oss_BTreeNode_new(world); oss_BTreeNode_name_set(tree, oss_BTreeNode_name_copy(world, "Root")); oss_BTreeNode_left_set(tree, l = oss_BTreeNode_new(world)); oss_BTreeNode_name_set(l, oss_BTreeNode_name_copy(world, "l")); oss_BTreeNode_right_set(l, lr = oss_BTreeNode_new(world)); oss_BTreeNode_name_set(lr, oss_BTreeNode_name_copy(world, "lr")); oss_BTreeNode_right_set(tree, r = oss_BTreeNode_new(world)); oss_BTreeNode_name_set(r, oss_BTreeNode_name_copy(world, "r"));
Remarks
To generate helper macros for individual ASN.1 types, use the OSS.HelperMacro directive.
See Also
-helperNames | -noHelperNames
Informs the ASN.1 compiler whether it should use context-based (helper) naming conventions for the generated C structures derived from built-in ASN.1 types. -helperAPI, -helperMacros, and -helperListAPI imply -helperNames.
Remarks
The -helperNames option implies the following changes in the header file:
- A limited set of C representations is supported for ASN.1 types. The DLINKED-PLUS representation is used by default for SET OF and SEQUENCE OF types with structured and pointer elements. The UNBOUNDED representation is used for SET OF and SEQUENCE OF types with simple non-pointer elements (INTEGER without the HUGE directive, REAL with the DOUBLE directive, BOOLEAN, NULL and ENUMERATED).
- C structures derived from built-in ASN.1 types are extracted and their names are produced by the compiler.
- Names produced by the compiler for all structures that are not derived from built-in simple types are created based on the position of the built-in type within a complex user-defined type. Built-in simple types that are represented by a structure have intuitive names: "_BitStr" or "_BmpStr".
- References to structures within other C structures are generated as pointers. Note that the POINTER directive is supported only for a limited set of simple ASN.1 types.
Example
| ASN.1 | with -noHelperNames | with -helperNames |
|---|---|---|
S ::= SEQUENCE {
a BMPString,
b CHOICE {
c BOOLEAN,
d INTEGER
}
}
|
typedef struct S {
struct {
unsigned int length;
unsigned short *value;
} a;
struct {
unsigned short choice;
# define c_chosen 1
# define d_chosen 2
union {
ossBoolean c;
int d;
} u;
} b;
} S;
|
typedef struct _BmpStr {
unsigned int length;
unsigned short *value;
} _BmpStr;
typedef struct S_b {
unsigned short choice;
# define c_chosen 1
# define d_chosen 2
union {
ossBoolean c;
int d;
} u;
} S_b;
typedef struct S {
struct _BmpStr *a;
struct S_b *b;
} S;
|
See Also
-ignoreError errorNumber
Instructs the ASN.1 compiler to treat certain errors as warnings.
You can use this option to generate a header file and a control table or code file without correcting your ASN.1 specification. Note that the values generated in the control table or code file are not valid according to the ASN.1 standard.
Remarks
You can ignore the following message numbers: 49, 73, 76, 77, 305, 319, 365, 811, 832, 1078, 1130, 1162, 1191, 1207, 1211, and 1339.
See Also
-ignoreIncompleteItems
Instructs the ASN.1 compiler to treat certain errors related to undefined ASN.1 types and values as warnings, and to ignore incomplete ASN.1 definitions that directly or indirectly reference undefined ASN.1 types and values.
Remarks
You can use this option to generate a header file and a control table or code file without correcting your ASN.1 specification, when undefined and incomplete ASN.1 items are not used by the application. Note that the compiler will not consider the ASN.1 types that are referenced only by ignored incomplete types as PDUs, unless you apply the PDU directive.
To see the incomplete items ignored by the compiler, use the -verbose option.
-relaxedMode implies the -ignoreIncompleteItems option.
Example
In this example, S is incomplete because B is not defined:
M DEFINITIONS ::= BEGIN
S ::= SEQUENCE { a A, b B }
A ::= INTEGER
END
See Also
-ignoreRedefinedAssignments
Instructs the ASN.1 compiler to ignore all duplicate definitions within the same ASN.1 module, and to issue warnings instead of errors.
Remarks
-relaxedMode implies the -ignoreRedefinedAssignments option.
See Also
-ignoreSuppress
Instructs the compiler to ignore the OSS.SUPPRESS directive within an ASN.1 module definition.
-informatoryMessages | -noInformatoryMessages
Informs the compiler whether it should generate informatory messages.
Remarks
When you use -relaxedMode or -noWarningMessages, the -noInformatoryMessages option is implied.
NOTE: The order in which -informatoryMessages | -noInformatoryMessages, -warningMessages | -noWarningMessages and -relaxedMode | -noRelaxedMode appear on the command line is important. The rightmost option takes precedence.
See Also
-keepNames
Generates a .gen file that contains directives which isolate the .h file when the input changes.
Remarks
The ASN.1 compiler might generate different names for a given type each time the ASN.1 file is compiled, which requires further changes in your code. To avoid this, use the -keepNames option. When the ASN.1 file needs to be recompiled, the .gen file is considered as the first input file on the command line, with the files and command-line options previously specified. Even when the input contains changes, the compiler will generate the same names.
Example
Initial ASN.1 input:
Rec ::= SEQUENCE {
a SEQUENCE OF SET {name IA5String, age INTEGER},
b SEQUENCE OF SET {height REAL, weight INTEGER}
}
Changed input:
Rec ::= SEQUENCE {
b SEQUENCE OF SET {height REAL, weight INTEGER},
a SEQUENCE OF SET {name IA5String, age INTEGER}
}
The -keepNames option will insulate your program from the element-order change.
When you use only the -keepNames option, the compiler treats the input as if -genDirectives (specified without the optional genDirFilename parameter) is also present.
The name of the .gen file is obtained by changing the suffix of the last input file to .gen (unless -output is specified).
The .gen file includes all directives from the ASN.1 input stream and for each name that might be changed in a subsequent run of the ASN.1 compiler.
For the following ASN.1 input:
Module DEFINITIONS ::= BEGIN
Type ::= INTEGER {one(1), two(2), five(5)}
S ::= SEQUENCE {flagColor ENUMERATED {red, white, blue}}
END
when -keepNames is specified, the compiler generates the following code in the .gen file :
Directives artificially generated for the names to be kept: --<OSS.TYPENAME Module.Type"Type">-- --<ASN1.Nickname Module.Type.one one>-- --<ASN1.Nickname Module.Type.two two>-- --<ASN1.Nickname Module.Type.five five>-- --<OSS.TYPENAME Module.S "S">-- --<ASN1.Nickname Module.S.flagColor.red red>-- --<ASN1.Nickname Module.S.flagColor.white white>-- --<ASN1.Nickname Module.S.flagColor.blue blue>--
See Also
-lean
Instructs the ASN.1 compiler to generate header files compatible with the Lean Encoder/Decoder (LED).
Default Behavior
By default, the -lean option is disabled.
Remarks
Similar to the Space-Optimized Encoder/Decoder (SOED), LED is table-driven; however it is faster than SOED and the size of the generated .c file is smaller than that of SOED or TOED.
NOTE: The LED library is not included in the OSS ASN.1 Tools; it is an add-on product that is available for common platforms like Linux, Windows, and Solaris, and may not be available for your embedded system port. If you are interested in LED for your platform, contact Sales <info@oss.com>.
When you specify the -lean option, consider the following:
- -noDebug is implied by default.
- When -lean is used with -controlFile or -soedFile, you can link your application code with the LED library file (libasn1lean.a, asn1lean.lib, or asn1lemd.lib, for example). As a result, all calls to ossEncode() and ossDecode() will use LED. To link the generated files with the SOED library file, specify the C-compiler option DOSS_SOED_ONLY_USED. -soedFile and -controlFile are implied by default, and therefore can be omitted.
- Certain runtime functions are not supported. For a list of restrictions, see the ASN.1/C Runtime section. To use LED with these functions, specify both the LED and the SOED library files on the command line of your linker. Place the LED library file before the SOED library file and specify the DOSS_USE_SOED_AND_LED C-compiler option.
- When you use LED and SOED, the generated C structures are different therefore you must write a different application program for each platform. To allow SOED to work with -lean generated structures, compile the ASN.1 with -lean and C-compile the application with DOSS_USE_OSS_FULL_SOED_ONLY.
- Only C representations that ensure efficiency are allowed.
- When you use -lean with -codeFile or -toedFile, the ASN.1 compiler generates an output C file that includes TOED. The generated header file contains C representations supported by LED and your application code is linked with the TOED library.
See Also
-listingFile [listingFileName] | -noListingFile
Specifies whether the compiler should generate an ASN.1 composite listing of root modules, containing all macro instances and parameterized items expanded, and all external references resolved.
Remarks
The listingFileName is the name of the output listing file. If you don't specify it, the default name is the last command-line input filename, with the .lst extension.
If no error conditions are detected in the input, the listing file contains valid ASN.1 that can be used as input by any ASN.1 compiler.
See Also
-messageFormat format-scheme
Controls the format of the error, warning, or informatory messages issued by the ASN.1 compiler for further parsing by a compatible text editor. This helps you automatically find the location in the input file for which the message was issued.
Remarks
Three format schemes are available:
- oss
- The default message format scheme used by the ASN.1 compiler.
Format:
file, line [(module)]: code: message.
Example:
msgfmt.asn, line 9 (Module-1): A0217W: The identifier 'address' is missing from the value and is assumed. - emacs
- The format scheme is compatible with many text editors.
Format:
file[:module:]line:[position:] - msvc
- The format scheme is compatible with the Microsoft development tools.
Format:
file(line[,position]) : [moduleName:] code: message.
Example:
MySchema.asn (9,29) : MyModule: warning A0217W: The identifier 'address' is missing from the value and is assumed.
-modListingFile [listingFilename] | -noModListingFile
Instructs the compiler to generate a module listing file that contains information from multiple ASN.1 modules.
Remarks
The listingFileName is the name of the output listing file. If you don't specify it, the default name is the last command-line input filename, with the .lst extension.
See Also
-minimize
Specifies the automatic selection of command-line options, which results in the most compact control table.
Remarks
When you use -minimize, the following options are automatically selected:
When you use -minimize with -xer | -cxer, the -debug is used with -noConstraints and -compat noValues.
-multi
Generates an integration module for multiple RTOED code files.
Remarks
Follow these steps when using the -multi option:
- Generate the code files separately using the -rtoed option for each input ASN.1 specification.
- Use the -multi option to generate the integration module.
- C-compile all the code files and the integration module.
- Link the resulting object files to your application.
Note that the -multi option can be used only for the RTOED code files.
See Also
-noStaticValues
Informs the ASN.1 compiler that it must not statically initialize any variable generated from the ASN.1 value notation. All variables are initialized in the ossinit() function through the executable code.
Remarks
This option is useful in certain embedded system software products that do not work properly when external (static) variables are initialized through a C initializer.
- output [outputFilename | outputDirectoryName] | -noOutput
Specifies whether output files should be generated.
Remarks
The outputDirectoryName optional parameter specifies the directory where the output files are generated.
outputfileName specifies the name of the output file.
When outputDirectoryName or outputfileName is not used, the prefix of the last .asn input file is considered as the output filename.
When neither parameter is specified, the prefix of the last .asn input file is used for the output filenames. However, when these parameters are specified, the last node after the last slash is used as the prefix for the output files. For example, if xyz/abc is the parameter, then the output filename prefix is abc. If xyz/abc/ is the parameter, then there is no output filename prefix because the node after the last slash is empty; the files are named only with extensions such as .cpp and .h.
Example
asn1 foo.asn -output abc
If a subdirectory named abc/ is present under the current working directory, the ASN.1 compiler places the output files foo.h and foo.c in this subdirectory. Otherwise, the ASN.1 compiler generates the following output files in the current working directory:
abc.h abc.c
asn1 foo -output xyz/abc
If the xyz/ subdirectory does not exist, the ASN.1 Compiler will try to create it. If the named subdirectory is created, the compiler generates the abc.h and abc.c files under this subdirectory.
The previous command line creates the xyz/ directory with the abc/ subdirectory and places the output files within it.
-noOutput instructs the compiler to suppress all output except error messages.
-partialDecodeOnly
Instructs the compiler to replace standard decoding with partial decoding. In this case, no standard encoding or decoding functions are generated, and constraint checking is disabled (-noConstraint). Partial decoding is only supported by the TOED runtime. That is, -partialDecodeOnly cannot be used together with the -soedFile or -controlFile option.
The -partialDecodeOnly option is supported by the BER, DER, PER, UPER, CPER, CUPER, OER, and COER encoding rules.
Default Behavior
The -partialDecodeOnly option is disabled.
See Also
-pdusForContainingTypes | -noPdusForContainingTypes
Instructs the compiler to treat types referenced by contents constraints as PDUs, even when the OSS.NOPDU directive is specified.
-noPdusForContainingTypes instructs the compiler to ignore types referenced by contents constraints. In this case, the encoding or decoding of BIT STRING and OCTET STRING types defined with contents constraints is not performed at runtime.
-pdusForOpenTypes | -noPdusForOpenTypes
Instructs the compiler to treat Open Types created by the ASN1.DeferDecoding or the OSS.ENCODABLE directive as PDUs, even when the OSS.NOPDU directive is specified.
The -noPdusForOpenTypes option instructs the compiler to ignore open types created by the ASN1.DeferDecoding or the OSS.ENCODABLE directive. This option causes the ASN.1 compiler to issue the following error message:
C0923E: Implementation limit exceeded; too many fields in module for ASN.1 schemas with a large number of PDU types.
Remarks
When you use the -noPdusForOpenTypes option, you must also specify -noConstraints, otherwise it is ignored.
The -autoEncDec option overrides -noPdusForOpenTypes.
See Also
-pedantic
Instructs the ASN.1 compiler to thoroughly check the input file syntax.
Remarks
If a type is not defined and it is neither directly nor indirectly referenced by the root modules, the compiler does not consider it an error.
-pedantic implies the -syntaxOnly option, therefore no .h or .c file is generated.
-prefix prefix
Specifies the prefix for the global generated names in your C program file.
Remarks
Use the -prefix option in application programs that support multiple abstract syntaxes, where the same typedef struct tags or manifest constant names are used in the generated files. When you add a prefix to the global generated names, the output files can be C compiled without a multiple declaration error.
-relaxedMode | -noRelaxedMode
Controls the automatic selection of command-line options.
Default Behavior
Starting with version 9.0, the -relaxedMode option is enabled by default.
Remarks
When you specify -relaxedMode, the following options are automatically selected:
- -allow BadValues
- -allow MixedCaseForSomeBuiltInTypesNames
- -allow UnderscoresInAsn1Names
- -ignoreError
- -ignoreIncompleteItems
- -ignoreRedefinedAssignments
- -noWarningMessages
Note that certain warning messages are not suppressed when you use this option. To suppress all warnings, specify the -noWarningMessages option.
-noRelaxedMode implies the -warningMessages option.
To enable warnings or informatory messages when -relaxedMode is enabled, specify the -relaxedMode option, and then -warningMessages or -informatoryMessages.
To disable warnings or informatory messages when -noRelaxedMode is enabled, specify the -noRelaxedMode option, and then -noWarningMessages or -noInformatoryMessages.
-relaxedMode was introduced in version 7.0 and -noRelaxedMode was introduced in version 8.7.0.
-relaxPerToedIntegerRangeConstraint
Changes the default behavior of the TOED PER encoder. It applies only to PER encodings.
Default Behavior
By default, the PER encoder enforces range constraints even when constraint checking is disabled.
In the following example, value 49 or 54 cannot be used because PER reserves only 2 bits to represent all numbers in the specified range:
Z ::= INTEGER (50..52)
00 represents 50 01 represents 51 10 represents 52 11 represents 53
Value 53 is outside the range of values allowed by the (50..52) constraint.
-relaxPerToedIntegerRangeConstraint instructs the compiler to generate TOED code to enable you to force the encoding of a disallowed, but possible, value (53, as illustrated in the previous example). Thus, the compiler checks all possible bit patterns for the respective field.
When you use the -relaxPerToedIntegerRangeConstraint, the upper bound is extended and the number is the next power of 2.
Example
| ASN.1 | without -relaxPerToedIntegerRangeConstraint | with -relaxPerToedIntegerRangeConstraint |
|---|---|---|
Y ::= INTEGER (15..19) |
15 to 19 |
15 to 22 (a range of 2^3) |
X ::= INTEGER (0..15) |
0 to 15 |
0 to 15 (a range of 2^4) |
W ::= INTEGER (-5..5) |
-5 to +5 |
-5 to +10 (a range of 2^4) |
NOTE: If constraint checking is enabled, the encoder ignores the -relaxPerToedIntegerRangeConstraint option.
See Also
-relaySafe | -noRelaySafe
Enables the relay-safe decoding and re-encoding of messages with extension addition fields in SEQUENCE, SET, and CHOICE types.
Remarks
Without -relaySafe, if a firewall that supports H.323 version 1 receives an H.323 version 2 message containing fields that are undefined in version 1, the decoder skips those fields and returns only the version 1 fields to the firewall application. When the firewall decodes and re-encodes the message with a new IP address, the message is re-encoded as a version 1 message because the version 2 fields were skipped during decoding.
If -relaySafe is enabled, the decoder retains the value of the fields added in version 2. When the message is re-encoded by the firewall application, the encoder automatically inserts the version 2 fields in the newly encoded message. The result is a message compliant with version 2 with the new IP address.
When you use -relaySafe, a field to store unknown extensions is generated in the representation of the SEQUENCE, SET, and CHOICE types.
NOTE: You cannot re-encode unknown extension fields with a set of encoding rules that differ from the initial ones.
-reservedWords keyword [, keyword...]
Defines keywords that are not automatically supported by the ASN.1 compiler.
Default Behavior
By default, the ASN.1 compiler applies a disambiguation algorithm to guarantee that all generated names do not conflict with C or C++ compiler keywords, for example: "double", "default", "const". However, certain platforms have keywords that are not automatically supported by the ASN.1 compiler.
Example
In the following example, the C/C++ compiling would fail because for the Microsoft C/C++ Optimizing Compiler, bind and send are reserved keywords. However, if you use -reservedWords send, bind, the following code is generated:
| ASN.1 | without -reservedWords | with -reservedWords |
|---|---|---|
Enum ::= ENUMERATED {send, bind}
|
typedef enum Enum {
send = 0,
bind = 1
} Enum;
|
typedef enum Enum {
Enum_send = 0,
Enum_bind = 1
} Enum;
|
Remarks
When you use -reservedWords, the names generated by the compiler that match the keyword are changed. They take either the prefix derived from the ASN.1 module where the corresponding top-level ASN.1 item is defined, or the names of the outer components, if the conflicting names belong to the inner components.
NOTE: If a user-defined type name is assigned using one of the OSS-specific directives: Nickname, TYPENAME, or FIELDNAME, and it matches the word specified in the -reservedWords option, the directive takes precedence. User-defined type names cannot be changed.
-restrictedConstraintChecking
Instructs the compiler not to ignore the OSS.NoConstrain directive in the presence of the explicit -constraints option.
Remarks
When you use -constraints with -restrictedConstraintChecking, the ASN.1 compiler enables runtime constraint checking for all types except for the ones on which the OSS.NoConstrain directive was applied.
NOTE: To use -restrictedConstraintChecking, you must specify the -constraints option.
See Also
-root
Instructs the ASN.1 compiler to treat all input modules as root modules.
Default Behavior
By default, only the last module specified on the command line is treated as a root module.
Example
The following line:
MyBoolean ::= BOOLEAN
Generates the following C header definition:
#define MyBoolean_PDU 1
The ASN.1 compiler assigns tags in sequential order:
- The first PDU encountered receives the tag "1".
- The second PDU receives the tag "2" etc.
To identify the PDU, use the #defined name (MyBoolean_PDU, for example) in your code, and not the number.
Remarks
When you use the -root option, all modules are thoroughly checked, and all unreferenced types in all modules are considered PDUs.
A Protocol Data Unit (PDU) is a protocol message that contains data defined by an ASN.1 type. PDUs can be encoded and decoded. For each PDU, the OSS ASN.1 compiler #defines an identification tag in the header file.
See Also
-rtoed
Instructs the ASN.1 compiler to generate code for the RTOED runtime. In the generated code, all function pointers are constant, so the C compiler toolchain can place them in read-only memory. This protects the pointers from being maliciously overwritten.
This option is incompatible with the -controlFile | -soedFile ASN.1 compiler option.
See Also
-sampleCode [pdus | values] | -noSampleCode
Instructs the compiler to generate sample code that shows how to use C-representations of PDU types defined in the input ASN.1 file, to call the encoder and decoder, and to traverse and print the decoded value.
The -noSampleCode option instructs the compiler to suppress sample code generation invoked by the OSS.SampleCode directive in the ASN.1 input file.
Remarks
The ASN.1 input file may define both the PDU types and the PDU values. To generate sample code, use the following parameters:
- no parameters
- Generates sample code for both types and values.
- pdus
- Generates sample code only for PDU types.
- values
- Generates sample code only for PDU values.
To customize sample values (CHOICE, SEQUENCE OF, and SET OF) you can use -sampleCode with the OSS.SampleCode directive.
To use -sampleCode, the input ASN.1 file must contain PDUs (or values). Also, make sure the the following options are not selected:
Note that a type is considered a PDU if it is not referenced by any other types, it is not imported, and it is not used in information object sets or as a type in the ContentsConstraint.
See Also
-shippable
Instructs the ASN.1 compiler to generate a special version of header file (.h) suitable for distribution in a toolkit.
Remarks
If you have purchased a toolkit builder license, the product installation includes a file named ossship.h.
If you have a license, you can distribute the ossship.h (with the OSS Nokalva .h file generated with the -shippable option) to your customers.
When you specify the -shippable option, the .c file is not generated. The generated .h file will #include the ossship.h shippable file instead of the OSS Nokalva ossasn1.h internal header file. Therefore your customers can compile their code without unresolved symbol errors.
Note that even if you have purchased the toolkit builder's license, you cannot ship the produced .c files or the internal OSS Nokalva header files to your customers.
When you specify the -shippable option, the .h file produced can be used only for distribution to your customers.
For information about the ossship.h header file, contact Sales <info@oss.com>.
-shortenNames | -noShortenNames
Specifies whether long variable names should be shortened to 31 characters by the ASN.1 compiler. This option accommodates maximum name length requirements that exist in certain C compilers.
Default Behavior
By default, the -noShortenNames option is implied on most platforms.
See Also
-soedFile [soedCFileName] | -noSoedFile
The -soedFile option is an alias for the -controlFile option.
Informs the ASN.1 compiler whether it should generate a control table for the Space-Optimized Encoder/Decoder or the Lean Encoder/Decoder when the -lean option is also specified.
The optional parameter specifies the output C filename (control table file). If the parameter is absent and the -output option is not used, the name of the output C file is the last command-line input filename, with the .c (or .cpp) extension.
The -noSoedFile option specifies that a control table C file should not be generated. This option is useful when you only want the the ASN.1 compiler to generate only the header file.
Default Behavior
By default, -soedFile and -noSoedFile are disabled. These options are mutually exclusive.
See Also
-sort | -noSort
Indicates whether forward references should be eliminated or preserved in the compiler-generated header file.
Default Behavior
Because C imposes restrictions on forward references, by default, -sort is enabled.
Remarks
-noSort option preserves the order of the generated data types as that of the ASN.1 types in the input file. This is useful when comparing the ASN.1 definitions to the generated header file; however, if there are forward references, unsorted output results in C compiler errors.
-splitForSharing [splitFilename]
Indicates that generated multiple header files can be used autonomously. This option is useful when you use only a subset of a large ASN.1 specification in your application.
Remarks
When -splitForSharing is enabled and ASN.1 definitions change but they belong to a module that you do not use, you don't need to recompile your application.
Also, the compiler generates an .spl file that preserves the indices and names across several versions of an ASN.1 specification. To specify a filename, use the optional argument splitFilename.
See Also
-splitHeaders [splitFilename]
Instructs the compiler to allow multiple header files generated for a single ASN.1 specification, by placing the data structures for each particular ASN.1 module in a separate header file.
Remarks
When you specify the -splitHeaders option, each generated header file contains the data definitions for a particular module. The corresponding PDU constants and pointer to the control table/code file is generated in a master header file whose name is derived from the last input ASN.1 filename. The master header file #includes all the individual header files produced. To use the generated data structures, #include the master header file in your application code. As a result, all the individual header files will be automatically included.
Additionally, the ASN.1 compiler generates a file with the .spl extension. This file contains global compiler directives for storing the names and indices of the types generated in the multiple header files.
To modify your ASN.1 specification and to regenerate multiple files, you must pass the .spl file on the command line prior to all files that contain your ASN.1 specification. Therefore you will not have to change your application program if you make minor changes to the input ASN.1 specification.
Although multiple header files are generated, only one control table/code file is produced for each ASN.1 specification. However, under the split-headers mode, you can use more than one control table/code file in a single application with a common set of ASN.1 modules without name conflict problems.
Also, if you compile the control table/code file as a DLL, you can load it at runtime. For more information, see the Linking related questions in the Knowledge Center.
To learn how to generate control tables for simultaneous use, see the following procedure:
- Specify the -splitHeaders option and ASN.1 compile your first ASN.1 specification. Then, retrieve the generated .spl file.
- Pass the .spl file as the first file on the command line and compile your second ASN.1 specification. Then, retrieve the second generated .spl file.
- Pass the second .spl file as the first file on the command line and compile your third ASN.1 specification. Then, retrieve the third generated .spl file.
Repeat this process for each ASN.1 specification that you use.
After you have produced the appropriate files, #include into your application the master header files corresponding to the modules you want to use. Then, to load a particular control table/code file, use the ossinit(), ossWinit(), or the ossUinit() function.
Additionally, to have all input modules translated and processed, use -splitHeaders with the -root option.
See Also
-suppress messageNumber
Instructs the compiler to suppress a specific warning or informatory message.
Remarks
You can specify -suppress more than once on the command line.
messageNumber can be either the complete message identifier (A0210W ,for example) or the numeric part (210, for example).
-syntaxOnly
Instructs the ASN.1 compiler to perform only a syntax check on the ASN.1 input. This is useful if you don't need to generate C code (when developing ASN.1 schemas, for example).
See Also
-test | -wTest
This option is deprecated.
See Also
-toedFile [toedCFileName] | -noToedFile
Informs the ASN.1 compiler whether it should generate an output C file containing the Time-Optimized Encoder/Decoder.
This option is an alias for the -codeFile ASN.1 compiler option.
Remarks
If you don't specify a C filename and the -output option, the output C filename will be the last command-line input filename, with the .c (or .cpp) extension.
The -noToedFile option informs that a C file should not be generated. This is useful when you need only a header file to be generated.
The -toedFile and -soedFile options are mutually exclusive.
See Also
-uniquePDU | -noUniquePDU
Specifies whether Protocol Data Unit (PDU) tags should be unique.
The -uniquePDU option specifies that the tags for all PDUs must be unique.
-noUniquePDU informs the compiler that PDUs can have identical tags.
Default Behavior
By default, when BER or DER is expected to be used at runtime, the compiler issues a warning message upon detecting duplicate PDU tags.
Remarks
When the -uniquePDU option is specified and the compiler encounters a duplicate PDU tag, it generates an error message. If -noUniquePDU is enabled, no error or warning message is generated.
When neither option is specified, the compiler issues only warning messages.
Note that in some ASN.1 specifications such as the Presentation Layer Protocol (ISO/IEC 8823/ITU-T X.226), PDUs don't have unique tags. In other ASN.1 specifications, such as the Association Control Service Element (ACSE), PDU tags are unique.
-userConstraints | -noUserConstraints
Specifies whether user-defined constraints and constraint-checking function prototypes should be generated into the control table and the header file, respectively.
Remarks
When you use the -userConstraints option with -noConstraints, information for user-defined constraints is generated into the control table, and information for other constraints is excluded.
When you use -noUserConstraints with -constraints, user-defined constraint information is excluded from the control table, and information for other constraints is included.
When you use -userConstraints with an ASN.1 type definition that uses a user-defined constraint, as follows:
OddNumber ::= INTEGER (CONSTRAINED BY {-- Must be an odd number--})
code is generated into the control table. To verify if the constraint imposed on values of type OddNumber, the encoder/decoder calls the user-written function prototype as follows:
OddNumber_fn(OssGlobal *world, OddNumber *value, void **handle);
When you specify -userConstraints, you must write constraint checking functions for all user-defined constraints. Also, make sure the OSS.NoConstrain directive is not specified.
When you specify -noUserConstraints, no code is generated to call functions at runtime, therefore you do not need to write functions to check user-defined constraints.
NOTE: User-defined constraints are not supported by TOED.
-useQualifiedNames
Instructs the ASN.1 compiler to add a prefix to:
- Enumerators generated for ENUMERATED types.
- Constants generated for named numbers of INTEGER types.
- Constants generated for named bits of BIT STRING types.
For nested unnamed types, the qualified names additionally contain the appropriate field names that may result in long identifiers. The optional maxPrefixLevel operand allows to abbreviate such names by using only the specified number of nested fields.
Default Behavior
By default, the -useQualifiedNames option is disabled.
Example
T ::= SEQUENCE {
outerField SEQUENCE {
innerField ENUMERATED {en1, en2, en3}
}
}
| without -useQualifiedNames | with -useQualifiedNames | with -useQualifiedNames 1 |
|---|---|---|
typedef enum T_outerField_innerField {
en1 = 0,
en2 = 1,
en3 = 2
} T_outerField_innerField;
|
typedef enum T_outerField_innerField {
T_outerField_innerField_en1 = 0,
T_outerField_innerField_en2 = 1,
T_outerField_innerField_en3 = 2
} T_outerField_innerField;
|
typedef enum T_outerField_innerField {
innerField_en1 = 0,
innerField_en2 = 1,
innerField_en3 = 2
} T_outerField_innerField;
|
Remarks
This option does not change any user-defined names assigned using the ASN1.Nickname directive.
-useXMLNames
Causes generated names in the output header and C file to be the same as the names used for the components of the corresponding E-XER encoding. The OSS ASN.1 Compiler derives the name of these components from the E-XER NAME encoding instruction.
Remarks
If the NAME encoding instruction is absent, the -useXMLNames option does not affect the generated output files.
Example
| ASN.1 schema | E-XER encoding |
|---|---|
S ::= SEQUENCE {
r [NAME AS "Red"] IA5String,
g [NAME AS "Green"] IA5String,
yellow [NAME AS CAPITALIZED] IA5String,
black [NAME AS UPPERCASED] IA5String
}
|
<?xml version="1.0" encoding="UTF-8"?> <S xmlns:asn1="urn:oid:2.1.5.2.0.1"> <Red>shirt</Red> <Green>trousers</Green> <Yellow>hat</Yellow> <BLACK>shoes</BLACK> </S> |
| .h with -useXMLNames | .h without -useXMLNames |
|---|---|
typedef struct S {
char *Red;
char *Green;
char *Yellow;
char *BLACK;
} S;
|
typedef struct S {
char *r;
char *g;
char *yellow;
char *black;
} S;
|
-valueRefs | -noValueRefs
Specifies whether special information about Value References should be generated into the control table. This information enables the IAAPI (Interpretive ASN.1 Application Program Interface) to dynamically determine what values are present in the compiler input.
-verbose | -noVerbose
Specifies whether ASN.1 compiler status messages should be issued.
Remarks
-verbose instructs the ASN.1 compiler to issue status messages.
-noVerbose instructs the ASN.1 compiler to suppress status messages.
-warningMessages | -noWarningMessages
Specifies whether compiler warning and informatory messages should be generated.
Default Behavior
By default, these options are disabled and certain warning messages are not suppressed. To suppress all warnings, specify the explicit -noWarningMessages option.
Remarks
-warningMessages implies the -informatoryMessages option.
-noWarningMessages implies the -noInformatoryMessages option.
When -noRelaxedMode is used, the -warningMessages option is implied.
The order in which -warningMessages | -noWarningMessages and -relaxedMode | -noRelaxedMode options appear on the command line is important. The rightmost option takes precedence.
See Also
-xsl
Generates multiple default stylesheet files, one for each PDU.
Default Behavior
By default, the ASN.1 compiler does not generate any XML stylesheets.
Remarks
Normally, even when the XER encoding rules are requested, no separate stylesheet is produced.
You can use your own XML stylesheets or you can use customized versions of the previously generated ones.
The generated stylesheets have the .xsl extension and a filename prefix identical to the name generated for their corresponding PDU. You can specify a different filename prefix and extension using the OSS.Stylesheet directive.
If you need ossEncode() to generate a reference for your stylesheet when producing the XML output for a particular PDU, call the ossSetXmlStylesheet() function before you invoke the encoder.
To change the name of the generated .xsl file, you can use the -output and the -prefix options.
See Also
This documentation applies to the OSS® ASN.1 Tools for C release 12.0 and later.
Copyright © 2025 OSS Nokalva, Inc. All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means electronic, mechanical, photocopying, recording or otherwise, without the prior permission of OSS Nokalva, Inc.
Every distributed copy of the OSS® ASN.1 Tools for C is associated with a specific license and related unique license number. That license determines, among other things, what functions of the OSS ASN.1 Tools for C are available to you.