TOP

ASN.1/C Compiler Options Reference

Applies to: ASN.1/C v11.3-11.3.1

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.

For example:

asn1 foo.asn -allow BadValues -allow BadSerialFROM

Arguments

-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

-constraints | -noConstraints


-ber | -der | -cer |-per | -uper | -cper | -cuper | -xer | -cxer | -exer | -oer | -coer | -json | -avn

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)

Remarks

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 */

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

-dualHeader


-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

-CStyleComments


-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

-C | -C++


-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

-helperListAPI


-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

-keepNames


-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

-helperMacros


-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 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 ..

Remarks

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

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


-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

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

-relaxedMode


-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

-genDirectives


-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

-modListingFile


-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

-listingFile


-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:

  1. Generate the code files separately using the -rtoed option for each input ASN.1 specification.
  2. Use the -multi option to generate the integration module.
  3. C-compile all the code files and the integration module.
  4. Link the resulting object files to your application.

Note that the -multi option can be used only for the RTOED code files.

See Also

-rtoed


-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:

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

-constraints


-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

OSS.ROOT


-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

OSS.SHORTENNAMES


-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

-toedFile


-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


-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:

  1. Specify the -splitHeaders option and ASN.1 compile your first ASN.1 specification. Then, retrieve the generated .spl file.
  2. 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.
  3. 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

-pedantic


-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

OSS.Stylesheet


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.