This section lists the compiler options alphabetically and provides a thorough description of their function.
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:
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:
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.
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:
The -1993, -1994, -1997, -2002, -2008 and -2015 compiler options are equivalents of the -2021 option.
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.
For example:
asn1 foo.asn -allow BadValues -allow BadSerialFROM
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.
We stand with Ukraine
B4114 DEFINITIONS AUTOMATIC TAGS ::= BEGIN
Seq ::= [65] SEQUENCE { ch Cho }
Cho ::= [65] CHOICE { b BOOLEAN }
s Seq ::= { ch b : TRUE }
END
The -allow BadExplicitAutomaticTagging compiler option is available in version 10.5 and later.
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:
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.
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.
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}
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:
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.
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.
S ::= PrintableString (FROM("ABC")) (FROM("DEF"))
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.
Instructs the ASN.1 compiler to ignore a tag conflict for an untagged extensible CHOICE inside an extensible SEQUENCE.
S ::= SEQUENCE {
a INTEGER,
c C OPTIONAL,
...,
e BMPString,
...
}
C ::= CHOICE {
c1 [0] INTEGER,
c2 [1] IA5String,
...
}
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).
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
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.
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.
Type ::= IA5STRING value Type ::= "abc"
The compiler will assume that the IA5STRING is the built-in type IA5String.
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.
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.
Some_Type ::= INTEGER
The option instructs the ASN.1 compiler to accept tags of the UNIVERSAL tag class.
You can use the UNIVERSAL tag class for:
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.
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
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.
Instructs the ASN.1 compiler to process type and value assignments found outside input modules.
Module1 DEFINITIONS ::= BEGIN
MyInt ::= INTEGER
END
ExtraModularType ::= INTEGER
Module2 DEFINITIONS ::= BEGIN
MyBit ::= INTEGER
END
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.
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.
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.
Specifies the encoding rules available at runtime:
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.
These 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. 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 | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 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 |
| TOED | BER | PER | DER BER |
UPER | XER | CXER | N/A | E-XER | OER | COER | JSON | CPER | CUPER | AVN |
| 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 |
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 */
The -json compiler option is available since version 10.3.
The -avn compiler option is available since version 11.1.
Instructs the compiler to generate header files and control table or code file for a C or C++ application.
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.
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.
| 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; |
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.
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
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.
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.
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.
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).
The -compactNoDecode option is disabled.
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.
Instructs the compiler to generate header and .c files compatible with previous versions of the OSS ASN.1 compiler.
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.
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.
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.
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.
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.
For SOED: -constraints.
For TOED and LED: -noConstraints.
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.
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.
By default, when -C++ is enabled, single-line ASN.1 comments are transferred using C++ comments.
To disable ASN.1 comments to be transferred to the header file, specify the -compat noASN.1Comments option.
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.
Unless the -lean option is specified, the -debug option is used by default.
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.
Informs the compiler whether it should generate decoding or encoding routines for the Time-Optimized Encoder/Decoder.
By default, the compiler generates encoder and decoder routines.
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.
Informs the compiler whether it should generate #define for constants in the header file.
When you specify the -noDefines option, the #define My_PDU 1 is replaced with const unsigned int My_PDU = 1.
Instructs the ASN.1 compiler to generate additional warning messages for protocol designers writing ASN.1 specifications.
Additional warning messages are issued when:
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.
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.
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.
#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.
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.
The -enablePartialDecode option is disabled.
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.
asn1 -err myErrs.err foo.asn
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.
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.
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.
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); ...
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.
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.
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.
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.
The external variable name is the same as the last input filename on the command line (without the .asn extension).
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).
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.
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.
Specifies whether a header file should be generated and what its name should be.
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.
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.
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.
Displays a list of all command-line options.
By entering asn1 -help you can obtain a summary of valid command-line options:
OSS ASN.1 Compiler Version 11.3
Copyright (C) 2023 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
-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
-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
... 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
-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
.. Sep 4 2023 ..
You can obtain a synopsis of the command-line syntax by entering asn1 with no arguments:
OSS ASN.1 Compiler Version 11.3
Copyright (C) 2023 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 ]
[-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
Command-line help is not displayed when you specify input files.
Enables or disables a set of -helper options :
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).
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.
-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.
| 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
|
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.
-helperEnumNames does not change user-defined names assigned to an enumerator using the ASN1.Nickname directive.
| 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;
|
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.
M DEFINITIONS ::= BEGIN
Names ::= SEQUENCE OF IA5String
END
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.
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:
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"));
To generate helper macros for individual ASN.1 types, use the OSS.HelperMacro directive.
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.
The -helperNames option implies the following changes in the header file:
| 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;
|
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.
You can ignore the following message numbers: 49, 73, 76, 77, 305, 319, 365, 811, 832, 1078, 1130, 1162, 1191, 1207, 1211, and 1339.
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.
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.
In this example, S is incomplete because B is not defined:
M DEFINITIONS ::= BEGIN
S ::= SEQUENCE { a A, b B }
A ::= INTEGER
END
Instructs the ASN.1 compiler to ignore all duplicate definitions within the same ASN.1 module, and to issue warnings instead of errors.
-relaxedMode implies the -ignoreRedefinedAssignments option.
Instructs the compiler to ignore the OSS.SUPPRESS directive within an ASN.1 module definition.
Informs the compiler whether it should generate informatory messages.
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.
Generates a .gen file that contains directives which isolate the .h file when the input changes.
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.
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>--
Instructs the ASN.1 compiler to generate header files compatible with the Lean Encoder/Decoder (LED).
By default, the -lean option is disabled.
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:
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.
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.
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.
Three format schemes are available:
Instructs the compiler to generate a module listing file that contains information from multiple ASN.1 modules.
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.
Specifies the automatic selection of command-line options, which results in the most compact control table.
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.
Generates an integration module for multiple RTOED code files.
Follow these steps when using the -multi option:
Note that the -multi option can be used only for the RTOED code files.
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.
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.
Specifies whether output files should be generated.
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.
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.
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.
The -partialDecodeOnly option is disabled.
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.
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.
When you use the -noPdusForOpenTypes option, you must also specify -noConstraints, otherwise it is ignored.
The -autoEncDec option overrides -noPdusForOpenTypes.
Instructs the ASN.1 compiler to thoroughly check the input file syntax.
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.
Specifies the prefix for the global generated names in your C program file.
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.
Controls the automatic selection of command-line options.
Starting with version 9.0, the -relaxedMode option is enabled by default.
When you specify -relaxedMode, the following options are automatically selected:
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.
Changes the default behavior of the TOED PER encoder. It applies only to PER encodings.
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.
| 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.
Enables the relay-safe decoding and re-encoding of messages with extension addition fields in SEQUENCE, SET, and CHOICE types.
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.
Defines keywords that are not automatically supported by the ASN.1 compiler.
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.
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;
|
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.
Instructs the compiler not to ignore the OSS.NoConstrain directive in the presence of the explicit -constraints option.
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.
Instructs the ASN.1 compiler to treat all input modules as root modules.
By default, only the last module specified on the command line is treated as a root module.
The following line:
MyBoolean ::= BOOLEAN
Generates the following C header definition:
#define MyBoolean_PDU 1
The ASN.1 compiler assigns tags in sequential order:
To identify the PDU, use the #defined name (MyBoolean_PDU, for example) in your code, and not the number.
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.
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.
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.
The ASN.1 input file may define both the PDU types and the PDU values. To generate sample code, use the following parameters:
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.
Instructs the ASN.1 compiler to generate a special version of header file (.h) suitable for distribution in a toolkit.
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>.
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.
By default, the -noShortenNames option is implied on most platforms.
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.
By default, -soedFile and -noSoedFile are disabled. These options are mutually exclusive.
Indicates whether forward references should be eliminated or preserved in the compiler-generated header file.
Because C imposes restrictions on forward references, by default, -sort is enabled.
-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.
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.
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.
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.
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:
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.
Instructs the compiler to suppress a specific warning or informatory message.
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).
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).
This option is deprecated.
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.
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.
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.
By default, when BER or DER is expected to be used at runtime, the compiler issues a warning message upon detecting duplicate PDU tags.
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.
Specifies whether user-defined constraints and constraint-checking function prototypes should be generated into the control table and the header file, respectively.
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.
Instructs the ASN.1 compiler to add a prefix to:
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.
By default, the -useQualifiedNames option is disabled.
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;
|
This option does not change any user-defined names assigned using the ASN1.Nickname directive.
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.
If the NAME encoding instruction is absent, the -useXMLNames option does not affect the generated output files.
| 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;
|
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.
Specifies whether ASN.1 compiler status messages should be issued.
-verbose instructs the ASN.1 compiler to issue status messages.
-noVerbose instructs the ASN.1 compiler to suppress status messages.
Specifies whether compiler warning and informatory messages should be generated.
By default, these options are disabled and certain warning messages are not suppressed. To suppress all warnings, specify the explicit -noWarningMessages option.
-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.
Generates multiple default stylesheet files, one for each PDU.
By default, the ASN.1 compiler does not generate any XML stylesheets.
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.
This documentation applies to the OSS® ASN.1 Tools for C release 11.3 and later.
Copyright © 2024 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.