TOP

ASN.1/Java Compiler Options Reference

Applies to: ASN.1/Java 7.1

The following compiler options are sorted alphabetically. For a list of options sorted by category, see ASN.1/Java Compiler Options.

-1990 | -2015

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 full support for the 1990 version of ASN.1, including: macro notations, ANY DEFINED BYs, and named types that have no identifiers. The compiler flags any syntax which follows a standard newer than 1990.

The -2015 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 full support for the 2015 version of ASN.1, including: automatic tagging, information object class, component relation constraints, table constraints, user-defined constraints, parameterization, version brackets, subtype notations, TIME, OID-IRI and RELATIVE-OID-IRI types.

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:2015, 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 (2015) ISO/IEC 8824-1:2015 standard, and the compiler generates warnings.

When using ASN.1:2015 syntax, the compiler issues warnings or errors under the following circumstances:

  • 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, which signals the start of an ASN.1 module.

-allow argument

Enables the compiler to retain a previous behavior specified by an argument. Use this option sparingly, only when it is absolutely necessary for a specific task.

The option takes a single argument. If you use multiple compatibility options, it can be specified more than once.

Example

asn1 foo.asn -allow BadValues -allow BadSerialFROM 

Arguments

-allow BadExplicitAutomaticTagging

Instructs the ASN.1/Java 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
-allow MixedCaseForSomeBuiltInTypesNames

Instructs the compiler to accept mixed case names for certain ASN.1 built-in types, if types with such names are not already defined in the ASN.1 input. The -allow MixedCaseForSomeBuiltInTypesNames is enabled by the default -relaxedMode option.

The following built-in types currently support mixed-case names:

  • INTEGER without named numbers
  • BOOLEAN
  • NULL
  • Restricted character string types (UTF8String, NumericString, PrintableString, TeletexString, T61String, VideotexString, IA5String, GraphicString, VisibleString, ISO646String, GeneralString, UniversalString and BMPString)
  • Time types (TIME, DATE, TIME-OF-DAY, DATE-TIME and DURATION)
  • GeneralizedTime and UTCTime
  • OID-IRI and RELATIVE-OID-IRI
  • ObjectDescriptor

Example

M DEFINITIONS ::=  BEGIN
   Type ::= IA5STRING
   value Type ::= "abc"
END

If -allow MixedCaseForSomeBuiltInTypesNames is not specified, the compiler reports the following errors:

"test.asn", line 3 (M): A0256W: 'IA5STRING' is referenced, but is not defined.

"test.asn", line 3 (M): A0052E: 'IA5STRING' is not defined.

"test.asn", line 3 (M): A1277W: 'IA5STRING' is assumed to be a misspelling of the built-in type 'IA5String'.

Remarks

The compiler assumes that the IA5STRING is the IA5String built-in type .

-allow namedBitThatExceedsConstraint

When a named bit is larger than the size of a BIT STRING, the compiler issues an error and stops. This flag instructs the compiler to issue a warning instead.

Version Information

The -allow namedBitThatExceedsConstraint option is available in version 7.0 and later.

-allow UnderscoresInAsn1Names

Instructs the ASN.1 compiler to accept ASN.1 names that contain the underscore character ("_") after the initial character. The -allow UnderscoresInAsn1Names option is enabled by the default -relaxedMode option.

Example

M DEFINITIONS ::= BEGIN
   Some_Type ::=INTEGER
END
-allow ValueForTypeWithIncompatRootFields

Instructs the ASN.1 compiler to not report a type-value mismatch when the type of the referenced value differs from the required type only by the position of the extension marker within the fields of a SET, SEQUENCE, or CHOICE type.

Example

M DEFINITIONS ::= BEGIN
   Choice1 ::= [0] CHOICE
      {
         f1   INTEGER,
         f2   REAL,
         f3   BOOLEAN
       }

    Choice2 ::= [1] CHOICE
       {
           f1   INTEGER,
           f2   REAL,
           ...  , 
           f3   BOOLEAN
       }

    choice1 Choice1 ::= f3:FALSE
    choice21 Choice2 ::= choice1
END
-allow ValueForTypeWithIncompatFieldsTags

Instructs the ASN.1 compiler to not report a type-value mismatch when the type of the referenced value differs from the required type only by the tags of the fields of a SET, SEQUENCE, or CHOICE type, including automatic tags.

Example

M DEFINITIONS ::= BEGIN
    Choice1 ::= [0] CHOICE
        {
           f1  [0]   INTEGER,
           f2  [1]   REAL,
           f3  [2]   BOOLEAN
         }

    Choice2 ::= [1] CHOICE
        {
           f1  [2]   INTEGER,
           f2  [1]   REAL,
           f3  [0]   BOOLEAN
         }

    choice1 Choice1 ::= f3:FALSE
    choice21 Choice2 ::= choice1
END

-allow BadValues

Instructs the ASN.1/Java compiler to continue the current compilation if a content error occurs in the value notation of restricted character strings (for example, NumericString, PrintableString, and VisibleString), OBJECT IDENTIFIER types.

Example

The following value notation causes 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 greater than 39 for its second node.

When the -allow BadValues option is specified, the compiler does not truncate the values of the following types:

  • IA5String, PrintableString, VisibleString, NumericString
  • SEQUENCE OF, SET OF

To instruct the ASN.1 compiler to treat errors as warnings, use the -ignoreError compiler option.

If a type-value mismatch is present in value assignments of ENUMERATED, SET, SEQUENCE, or CHOICE types, the -allow BadValues option also instructs the ASN.1 compiler to issue the A1007W warning message instead of the A1006E error message.

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.

By default,the -allow BadValues option is disabled.


-assignments

Instructs the ASN.1 compiler to process type and value assignments found outside input modules.

Example

If the -assignments option is specified, the behavior of the ASN.1 compiler for the following ASN.1 specification:

    I ::= INTEGER
    B ::= BOOLEAN

is the same as for the specification:

NoModuleName DEFINITIONS AUTOMATIC TAGS ::=
BEGIN
    I ::= INTEGER
    B ::= BOOLEAN
END

-autoEncDec | -noAutoEncDec

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.

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. To enable automatic encoding/decoding, use the enableAutomaticEncoding() method.

When you use the -constraints option (runtime constraint checking is enabled) -autoEncDec has no effect on runtime performance.

Use the -noAutoEncDec option to save runtime space. However, by omitting code used by the automatic encoding/decoding feature, -noAutoEncDec overrides the runtime enabling of automatic encoding/decoding. In this case, since enableAutomaticEncoding() would have no effect, the application must be prepared to manually encode and decode open types.

See Also


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

Specifies the encoding rules available at runtime:

  • Basic Encoding Rules (-ber)
  • CER (-cer)
  • Canonical Octet (-coer)
  • Canonical XER (-cxer)
  • Distinguished Encoding Rules (-der)
  • Extended XER (-exer)
  • JSON Encoding Rules (-json)
  • Octet (-oer)
  • Aligned PER (-per)
  • Unaligned PER (-uper)
  • Basic XER (-xer)

Remarks

When you specify the -json, -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. For example, if you specify -der -per -xer, the PER encoding rules are 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 -json -uper -xer -cxer -cer -exer -oer -coer
SOED BER PER
UPER
DER
BER
JSON UPER
PER
XER XER
CXER
CER
BER
E-XER OER C-OER
OER
TOED BER PER DER
BER
JSON UPER XER CXER N/A E-XER OER C-OER
LED BER PER
UPER
DER
BER
JSON UPER
PER
XER XER
CXER
N/A E-XER OER OER
C-OER

To use multiple sets of encoding rules, add one of the following lines of code to create another Coder object:

BERCoder berCoder = getBERCoder();

CERCoder cerCoder = getCERCoder();

COERCoder coerCoder = getCOERCoder();

CXERCoder cxerCoder = getCXERCoder();

DERCoder derCoder = getDERCoder();

EXERCoder exerCoder = getEXERCoder();

JSONCoder jsonCoder = getJSONCoder();

OERCoder oerCoder = getOERCoder();

PERAlignedCoder perCoder = getPERAlignedCoder();

PERUnalignedCoder uperCoder = getPERUnalignedCoder();

XERCoder xerCoder = getXERCoder();

Version Information

The JSON encoding rules are supported in the SOED runtime in version 7.0 and later.


-commandFile <File>| commandFileName <File>

Instructs the ASN.1 compiler to take files and options from File as if they were found at the command line. This option is useful when you have many input files or options specified.

Example

To compile input.asn using the command-line options included in the tenLinesOfOptions.opt text file, issue the following command:

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


-compat <option>

Instructs the compiler to generate files compatible with previous versions of the OSS ASN.1 compiler.

NOTE: OSS does not guarantee compatibility between different versions of the ASN.1 Tools released more than 10 years apart.

Remarks

This option takes a single operand or flag, and can be specified more than once. For example:

asn1 foo.asn -compat JavaSharing -compat oldinnerclassreference

For more information about arguments that can be specified with the -compat option, see Backward Compatibility.


-constraints | -noConstraints

The -constraints option instructs the compiler to generate information in the Java files for runtime constraint checking.

The -noConstraints option disables generation of information in the Java files for runtime constraint checking. The size of the generated code is smaller and can be executed faster.

If the -constraints option is specified or implied, you can disable runtime constraint checking by calling the disableEncoderConstraints()method.

See Also

disableEncoderConstraints()


-debug | -noDebug

Enables or suppresses generation of debugging information.

When the -debug option is specified, run-time diagnostic messages are more legible (note that there is an impact on size).

When the -noDebug option is specified, you can preserve run-time memory size by limiting the information on run-time diagnostic messages (note tha there is an impact on legibility).

Remarks

When the -xer, -cxer, or -exer option is specified, -noDebug is ignored.


-decodeOnly | -encodeOnly

The -decodeOnly | -encodeOnly option is reserved for future use with the –toed option and currently has no effect.


-designerWarnings

Instructs the ASN.1 compiler to generate additional warning messages for protocol designers writing ASN.1 specifications. By default, no additional warnings are issued.

Remarks

Additional warning messages are issued if:

  • The -per or -uper option 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.
  • The -per or -uper option is specified and there is more than one unreferenced type in the root module. This might cause problems in determining 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.
  • The -warningMessages or -noRelaxedMode option is specified.
  • An Information Object Class has optional fields that are not reflected as optional within the respective WITH SYNTAX clause. For the following example:
    MYCLASS ::= CLASS {
        &data INTEGER OPTIONAL,
        &Type
    } WITH SYNTAX { &data &Type }
    
    the following warning message is issued:
    A0587W: A Setting for OPTIONAL field ' &data' is defined not inside an OptionalGroup in the DefinedSyntax.
    

-dtd

Generates multiple Data Type Definitions (DTD) files, one for each PDU.

By default, the .dtd file is generated in the directory of the corresponding ASN.1 module package and it is called ClassName.dtd. For the baseball example, the generated DTD is located in the baseball/bcas directory and it is called BBCard.dtd .

Remarks

The -dtd option (and the OSS.DTD directive) is available only for the XER Encoding Rules. Also, -dtd has no effect when the -noOutput or -syntaxOnly option is used.

See Also

cxer | xer | xsl


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

asn1pjav -err myerrs.err foo.asn

Remarks

When errorFileName does not have an extension, it receives the .err extension (or "e" on the Tandem NonStop OS). When it has the .asn extension, it is 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.


-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 file name is not specified, the ASN.1 compiler generates one from the last ASN.1 input file specified at the command line and replaces .asn with .gen.

By default, the -genDirectives option is disabled.

See Also


-help

Displays a summary of all valid command-line options.

Example

By entering asn1pjav –help you can obtain a summary of valid command-line options:

OSS ASN.1 Compiler for Java Version 7.0
Copyright (C) 2016 OSS Nokalva, Inc.  All rights reserved.

Compiler parameters: (.D. indicates default)
  <input> <...input> . one or more ASN.1 input files
  -1990            ... all modules conform to 1990 ASN.1 syntax
  -2015            ... all modules conform to 2015 ASN.1 syntax
  -allow badcase   ... enable badcases for backward compatibility
  -allowbadvalues  ... allow generation of bad values
  -assignments     ... process type and value assignments defined outside
                       ASN.1 modules
  -autoencdec      .D. generate metadata for automatic decoding of open types
  -ber             .D. generate output file for BER encoder/decoder
  -cer             ... generate output file for BER & CER encoder/decoder
  -coer            ... generate output file for Canonical OER encoder/decoder
  -commandfile <file> ... read command line from 'file'
  -compat feature  ... disable new features for backward compatibility
  -constraints     .D. check constraints at runtime
  -cxer            ... generate output file for Canonical XER encoder/decoder
  -debug [0..2]    .D. issue detailed trace data and error messages. When
                       used together with -toed, the numeric argument
                       specifies the debug level.
  -decodeonly      ... generate only decoder methods
  -der             ... generate output file for BER & DER encoder/decoder
  -designerWarnings... issue additional warnings for protocol designers
  -dtd             ... generate document type definition file for each PDU
  -encodeonly      ... generate only encoder methods
  -errorfile file  ... write all messages to 'file' instead of stdout/stderr
  -exer            ... generate output file for EXTENDED XER encoder/decoder
  -gendir <genfile>... generate list of directives into <genfile>
  -helperAPI       ... generate specific helper API's selected via a keyword:
                       'opentype' - helper API's for constrained opentypes
                       'pdudecoder' - helper API's for PDU decoding
  -ignoreError msg#... ignore a specific error (issue a warning instead)
  -ignoreIncompleteItems
                   ... ignore incomplete ASN.1 definitions of types and values
  -ignoreRedefinedAssignments
                   ... ignore redefined ASN.1 definitions of types and values
  -ignoresuppress  ... ignore the SUPPRESS directive (display all messages)
  -indexinfoobjectsets ... generate extra methods to index information
                       object sets for faster automatic decoding
  -informatory     ... allow informatory messages
  -jiaapi          ... generate JIAAPI support classes
  -json            ... generate output file for JSON encoder/decoder
  -keepnames       ... generate directives for keeping names
  -lean            ... generate reduced typeinfo for JLED encoder/decoder
  -limitbigenums num#  ... helps to avoid 64K limit for big enums
  -limitcons num#  ... limits number of arguments in a constructor
  -limitmethodsize lines# ... split generated methods to avoid 64K
                       method size limit
  -list <listfile> ... generate an ASN.1 combined listing into 'listfile'
  -messageFormat   <format>
                   ... display error messages in <format>:
                       'oss', 'emacs' or 'msvc'
  -mod <listfile>  ... generate single ASN.1 module listings into 'listfile'
  -noSampleCode    ... do not generate a sample code
  -noautoencdec    ... do not generate metadata for automatic decoding of
                       open types
  -noconstraints   ... do not check constraints at runtime
  -nodebug         ... do not issue detailed trace data and error messages
                       to slightly improve CPU performance
  -noHelperAPI     ... do not generate specific helper API's selected via a keyword:
                       'opentype' - helper API's for constrained opentypes
                       'pdudecoder' - helper API's for PDU decoding
  -noinformatory   ... suppress informatory messages
  -nolist          .D. do not generate an ASN.1 combined listing
  -nomod           .D. do not generate single ASN.1 module listings
  -nooutput        ... do not generate output files, same as syntaxonly.
  -noparamtypesuperclass  .D. do not create a class for shareable parameterized
                       types
  -nopdusforopen   ... do not generate PDUs for info objects with -noconstraints
  -nopedantic      .D. rigorously check only the root module(s)
  -norelaxedMode   ... automatically select command-line options that
                       result in strict compiler behavior
  -norelaySafe     .D. do not retain unrecognized extension additions at runtime
  -notest          .D. do not test encoding/decoding of all ASN.1 values
  -nouniquepdu     ... do not check that pdu id's are unique 
  -nouserconstraints D do not check user constraints (even for -constraint)
  -novaluerefs     ... do not generate Java values for all valuereferences
  -noverbose       .D. do not display compilation progress messages
  -nowarning       ... suppress warning messages
  -oer             ... generate output file for OER encoder/decoder
  -output name     ... use name for ASN.1/Java package
  -paramtypesuperclass  ... create a class for shareable parameterized types
  -path   path     ... generate package at specified location
  -pdusforopentypes... ignore NOPDU directive for opentypes
  -pedantic        ... rigorously check all modules
  -per             ... generate output file for Aligned PER encoder/decoder
  -prefix id       ... prefix variables with unique id
  -relaxedMode     .D. automatically select command-line options that
                       result in relaxed compiler behavior, for example,
                       -allowBadValue, -noWarning, etc.
  -relaySafe       ... retain unrecognized extension additions at runtime
  -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
  -root            ... treat all modules as root modules
  -sampleCode <pdus|values>
                   ... generate a sample code to initialize, encode, decode
                       and traverse values of PDU types defined in the input
                       ASN.1 syntax
  -soed            .D. generate Java code compatible with SOED runtime
  -splitbigenums num#  ... helps to avoid 64K limit for big enums
  -splitsamplecode <depth#> ... split sample value creation methods
                       to avoid 64K method size limit
  -splittypeinfo num# ... set limit for the number of fields in SET/SEQ/CHOICE
                       to split static initializers of typeinfo avoid 64K
                       method size limit
  -splitvalues     ... split static value initializers into methods to avoid
                       64K method size limit
  -suppress msg#   ... suppress a specific message
  -syntax          ... perform syntax checking only
  -test            ... generate a program to encode/decode ASN.1 values
  -toed            ... generate Java code compatible with TOED runtime
  -uniquepdu       .D. check that pdu id's are unique 
  -uper            ... generate output file for Unaligned PER encoder/decoder
  -userconstraints ... check user constraints (even for -noconstraints)
  -valuerefs       .D. generate Java values for all valuereferences
  -verbose         ... display compilation progress messages
  -warning         ... allow warning messages
  -xer             ... generate output file for Basic XER encoder/decoder
  -xsl             ... generate default stylesheet for each PDU

Remarks

You can obtain a synopsis of the command-line syntax by entering asn1pjav with no arguments:

OSS ASN.1 Compiler for Java Version 7.0
Copyright (C) 2016 OSS Nokalva, Inc.  All rights reserved.

asn1pjav <infile(s)> [-suppress msg#]      [-verbose | -noverbose]
  [-ber]          [-allowbadvalues  ]      [-warning | -nowarning]
  [-der]          [-errorfile file  ]      [-mod <listfile> | -nom]
  [-per]          [-ignoresuppress  ]      [-list <listfile> | -nol]
  [-lean]         [-limitcons num#  ]      [-messageFormat <format>]
  [-root]         [-compat feature  ]      [-pedantic | -nopedantic]
  [-uper]         [-commandfile file]      [-output name | -nooutput]
  [-jiaapi]       [-debug | -nodebug]      [-test      |  -notest    ]
  [-syntax]       [-designerWarnings]      [-relaySafe | -norelaySafe]
  [-keepnames]    [-gendir <genfile>]      [-uniquepdu | -nouniquepdu]
  [-path path]    [-ignoreError msg#]      [-valuerefs | -novaluerefs]
  [-prefix id]    [-pdusforopentypes]      [-autoencdec | -noautoencdec]
  [-splitvalues]  [-splittypeinfo num#]    [-constraints | -noconstraints]
  [-1990 | -2015] [-indexinfoobjectsets]   [-informatory | -noinformatory]
  [-userconstraints | -nouserconstraints]  [-reservedWords <reservd_words>]
  [-xer] [-cxer]  [-paramtypesuperclass    |-noparamtypesuperclass]
  [-exer] [-cer]  [-ignoreIncompleteItems] [-relaxedMode | -norelaxedMode]
  [-dtd] [-xsl ]  [-allow badcase   ]      [-assignments]
  [-ignoreRedefinedAssignments      ]      [-sampleCode   |-noSampleCode ]
  [-splitsamplecode <depth#>        ]      [-soed | -toed] [-oer]  [-coer]
  [-limitmethodsize <lines#>        ]      [-json]
  [-helperAPI <param> | -noHelperAPI <param> ]
  [-splitbigenums #n                ]      [-limitbigenums #n ]

enter "asn1phav -help" for more information

Default Behavior

Command-line help is not displayed when input files are specified.


-helperAPI <param> | -noHelperAPI <param>

Enables or disables the generation of optional helper APIs. A parameter is required that can be a single keyword or a comma-separated list of keywords. Using a list of keywords is the same as specifying multiple single-keyword options. The keywords are not case-sensitive and can be specified in any order. The keywords specify the types of helper API; currently, only opentype and pdudecoder are valid.

-helperAPI opentype

The -helperAPI opentype command-line option affects the representation of open type fields that are constrained by a component relation constraint.

If the -helperAPI opentype command-line option is specified and an open type field is constrained by a component relation constraint, the compiler will generate an extra class that represents the field's type. The extra class provides an application developer with methods that simplify handling of the constrained open type values.

-helperAPI pdudecoder

The -helperAPI pdudecoder option instructs the compiler to generate optimal PDU and PDU_ID classes that are used to auto-detect and decode PDUs from bits on the wire when the PDU's type is not known ahead of time.

PDU auto-detection is available only for the encoding rules that use "tags" to identify an encoded value's type. Currently the option works with BER, DER, CER, XER, and CXER. PDU auto-detection is not available for PER, UPER, OER, or C-OER.

The PDU and PDU_ID classes are inner classes of an ASN.1/Java project class.

See Also

Version Information

The -helperAPI <param> and -noHelperAPI <param> options are available in version 7.0 and later.


-ignoreError <number>

Instructs the ASN.1 compiler to treat certain errors as warnings.

You can use -ignoreError option to generate a code file without correcting your ASN.1 specification. Note that the values generated in the code file are not valid according to the ASN.1 standard.

Remarks

The following message numbers can be ignored: 49, 76, 77, 305, 319, 811, 1078, 1130, 1162, 1207 and 1211.

By default, all compiler error messages are generated.

See Also

-allow BadValues


-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 the -ignoreIncompleteItems option to generate Java classes without correcting your ASN.1 specification, when undefined and incomplete ASN.1 items are not used by the application.

To see which incomplete items were ignored by the compiler, use the -verbose option.

Example

In the following example, A references type B, which is not defined:

M DEFINITIONS ::= BEGIN
   A ::= SEQUENCE {
      a1 A1,
      a2 A2,
       b B1
   }
   A1 ::= INTEGER
   A2 ::= BOOLEAN
   B  ::= REAL
END

Without -ignoreIncompleteItems, the following messages are issued:

"test.asn", line 7 (M): A0256W: 'B1' is referenced, but is not defined.

"test.asn", line 7 (M): A0052E: 'B1' is not defined.

C0043I: 1 error message, 1 warning message and 0 informatory messages issued.

With -ignoreIncompleteItems and -verbose, the following messages are issued:

"test.asn", line 7 (M): A0256W: 'B1' is referenced, but is not defined.

"test.asn", line 4 (M): C1215W: The definition of the type identified by the absolute reference 'M.A' is 
incomplete and will be ignored.

C0285I: Global checking abstract syntax.

C0504I: Generating JAVA files.

C0043I: 0 error messages, 2 warning messages and 5 informatory messages issued.

The compiler generates the .java files only for complete ASN.1 types:

a/m/M.java
a/m/A1.java
a/m/A2.java
a/m/B.java

By default, the -ignoreIncompleteItems option is disabled.

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

The -relaxedMode option implies the -ignoreRedefinedAssignments option.

Example

The type reference Type is defined twice within the same ASN.1 module:

M DEFINITIONS ::= BEGIN
   Type ::= INTEGER
   Type ::= INTEGER
END

Without -ignoreRedefinedAssignments, the following messages are issued:

"test.asn", line 5 (M): A0146E: Type 'Type' is illegally redefined.
     Type ::= INTEGER
              ^
C0043I: 1 error message, 0 warning messages and 0 informatory messages issued.

With -ignoreRedefinedAssignments, the following messages are issued:

"test.asn", line 5 (M): A1270W: 'Type' has already been defined on line 3. Its redefinition is being ignored.

C0043I: 0 error messages, 1 warning message and 0 informatory messages issued.

See Also

-relaxedMode


-ignoreSuppress

Instructs the compiler to ignore the OSS.SUPPRESS directive in an ASN.1 module definition.

Default Behavior

By default, all messages identified by the OSS.SUPPRESS directive are suppressed.


-indexInfoObjectSets

Allows you to control which algorithm is used to implement the lookup of information object sets. Information object sets are used during automatic decoding of open types.

The -indexInfoObjectSets option instructs the compiler to generate additional methods in every Java class. The methods represent the information object sets of a particular information object class.

Default Behavior

By default, -indexInfoObjectSets is not invoked and a linear search of an information object in an information object set takes place each time an open type defined with a component relation constraint is automatically decoded.

Example

MyModule DEFINITIONS ::= BEGIN
    MY-CLASS ::= CLASS {
        &id ProcedureID UNIQUE,
        &Type
    }

    MyInfoObjectSet MY-CLASS ::= {
        {&id 1, &Type INTEGER} |
        {&id 2, &Type UTF8String}
    }
END

The following asn1pjav command-line is used: asn1pjav index myprotocol.asn.

Here is the generated code:

public class MY_CLASS_OSET extends IndexedInfoObjectSet {
    ...
    // Methods to index the information object set
    public static IndexProcedure getIndexProcedure();
    public static void setIndexProcedure(IndexProcedure procedure);
    public boolean indexById(Index index);
    public boolean indexByType(Index index); }

Note that the generated class inherits from the IndexedInfoObjectSet class (to provide a more compact and readable view, the bodies of the methods listed above are not shown). The class is an extension of the InfoObjectSet class and includes additional code to support indexing.

The first two methods generated above are defined to facilitate automatic indexing of information object sets of this class:

public static IndexProcedure getIndexProcedure();
public static void setIndexProcedure(IndexProcedure procedure);

To activate automatic indexing, create (and instantiate) a class that implements the IndexProcedure interface and pass the instance of this class to setIndexProcedure(). After setIndexProcedure() is called, your IndexProcedure is applied to every information object set of the MY_CLASS_OSET class as soon as it is instantiated:

MY_CLASS_OSET oSet = new MY_CLASS_OSET(new MY_CLASS[] {...}, ...);

You can use the methods generated in this example to index individual information object sets at any moment after they are created:

public boolean indexById(Index index); 
public boolean indexByType(Index index);

To index an individual information object set, create the class that implements the Index interface and pass the instance of this class into the indexByXXX() method. The method returns boolean to indicate if the method has successfully indexed the information object set.

If, for example, the information object set contains two information objects with duplicate values of the index column, and you have implemented the Index interface to not support duplicate values in the index column, indexing may fail.

When you use the -indexInfoObjectSets compiler option, no additional work in your application is required. Linear searching takes place for each information object set. However, we recommend that you use the -indexInfoObjectSets compiler option with the Index or DefaultIndex interface.

See Also


-informatoryMessages | -noInformatoryMessages

Informs the compiler whether it should generate informatory messages.

Default Behavior

The -noInformatoryMessages option is implied when the default -relaxedMode or the -noWarningMessages option is specified.

When -noRelaxedMode or -warningMessages is specified, the -informatoryMessages 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


-jiaapi

The Java Interpretive ASN.1 API (JIAAPI) is a collection of Java classes included with the ASN.1 Tools for Java. The Java IAAPI provides access to ASN.1 types, subtypes and value notations through an easy-to-use interface. This allows applications to create and encode data using ASN.1 without any knowledge of the data structure (for example, the number of components and their types). It also allows messages (PDUs) to be decoded, and the components of the messages to be accessed based on their data types.

When the -jiaapi option is specified, the compiler generates the following additional classes:

  • The JIA project class, one file per project, JIA<ProjectName>.java (output into the ASN1/Java project directory).
  • The JIA module class, one file per module, JIA<ModuleName>.java (output into the modules directories).

The -jiaapi option is helpful when using the JIAAPI; however, it is optional. You can also construct your own classes to extend the JIA Project class.

Example

The following ASN.1 syntax file, tst.asn is compiled with the -jiaapi option:

ModA DEFINITIONS ::= BEGIN
    A   ::= INTEGER
    a A ::= 1234
END

ModB DEFINITIONS ::= BEGIN
    B   ::= SEQUENCE { a ModA.A }
    b B ::= { a ModA.a }
END

The following JIA project class, JIATst, is generated:

public class JIATst {
 
    private static JIA_Project jia_project = new JIA_Project (
        new JIA_DefinedTypes(
            new JIA_DefinedType[] {
                new JIA_DefinedType("B", "tst.modb.B")
            }
        ),
        new JIA_Modules(
            new JIA_Module[] {
                tst.moda.JIAModA.jia_module,
                tst.modb.JIAModB.jia_module
            }
        )
    );
}

Two JIA module classes, JIAModA and JIAModB, are also generated:

public class JIAModA {

    public static JIA_Module jia_module = new JIA_Module(
        "ModA",
        JIA_Module.MODE_TAGGING_EXPLICIT,
        false,
        new JIA_DefinedTypes(
            new JIA_DefinedType[] {
                new JIA_DefinedType("A", "jiaapi.moda.A")
            }
        ),
        new JIA_ValueReferences(
            new JIA_ValueReference[] {
                new JIA_ValueReference("a", ModA.a)
            }
        )
    );
}

public class JIAModB {

    public static JIA_Module jia_module = new JIA_Module(
        "ModB",
        JIA_Module.MODE_TAGGING_EXPLICIT,
        false,
        new JIA_DefinedTypes(
            new JIA_DefinedType[] {
                new JIA_DefinedType("B", "jiaapi.modb.B")
            }
        ),
        new JIA_ValueReferences(
            new JIA_ValueReference[] {
                new JIA_ValueReference("b", ModB.b)
            }
        )
    );
}

Remarks

The -jiaapi command line option is ignored when it is specified along with the -lean command line option. A warning message is issued stating that -jiaapi is not compatible with -lean.


-keepNames

Generates a .gen file that contains directives which isolate the generated files when the input changes.

Default Behavior

The -keepNames option is disabled.

Remarks

The ASN.1 compiler can 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 at the command line, with the files and command-line options previously specified. Even when the input contains changes, the compiler generates the same names.

Example

Initial ASN.1 input Modified input
Rec ::= SEQUENCE {name Name, age Age}
Rec ::= SEQUENCE {name Name, ageAtMarriage Age}}

The -keepNames option insulates your program from the element-order change.

When the -keepNames option is specified, and -genDirectives is not specified, the compiler treats the input as if the -genDirectives option without the optional -genDirFilename parameter was specified. In this case, the compiler creates the .gen file with a name obtained by changing the suffix of the last file on the command line to .gen. The .gen file includes all directives from the ASN.1 input stream and directives for each name that can change in a subsequent run of the ASN.1 compiler for Java.

ASN.1 input Generated code (with -keepNames)
Module DEFINITIONS ::= BEGIN
    Type ::= INTEGER {one(1), two(2), five(5)}
    S ::= SEQUENCE {
           flagColor ENUMERATED {red, white, blue}
     }
END
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 Java files compatible with the Lean Encoder/Decoder (LED).

Remarks

When the -lean option is specified, the compiler prints condensed type information (metadata), which saves JVM memory space. This is useful when an application does not require the full function provided by the standard runtime. Condensed metadata means omitting the following:

  • ASN.1 type constraint information (equivalent to using the -noConstrain option to disable constraint checking at runtime).
  • ASN.1 type name and field name information (equivalent to using the -noDebug compiler option, which causes runtime trace output to contain Type instead of the actual type names and field # instead of the actual field names). Note that when the -xer, -cxer, or -exer option is specified, -lean has no effect.

Further space optimization is available by using the lean runtime in the osslean.jar file.

When -lean is specified, the OSS ASN.1 Java compiler issues warning messages if the input ASN.1 specification contains types or directives that are not supported by the lean runtime. The following types are not supported: REAL, EMBEDDED PDV, EXTERNAL, CHARACTER STRING, and UniversalString.

If the UNBOUNDED and UNIVERSALSTRING directives are used with the UTF8String type, the compiler issues warning messages because the only representation for the UTF8String type is BMPSTRING.

The generated Java classes can be used with either the full or the lean runtime libraries. It is not mandatory to use the osslean.jar file at runtime when the -lean option is specified.

Default Behavior

The -lean option is disabled.

See Also

The Java Lean Encoder/Decoder


-limitBigEnums <nnn>

Use this option when the amount of code needed to initialize named static final class instances that represent ENUMERATED or INTEGER types with named numbers exceeds the 64K limit. The <nnn> number argument is mandatory. When -limitBigEnums is specified and the number of enumerators or named numbers exceeds the <nnn> limit, the compiler does not generate any constants representing known enumerators or named numbers.

Example

In the following example, the application code retrieves enumerators using the valueOf(long) method:

public final class ITIScodes extends Enumerated {
     ...
     public static final class Value {
        public static final long stopped_traffic = 257;
        public static final long stop_and_go_traffic = 258;
        public static final long slow_traffic = 259;
         ...
     }
     ...
     public static ITIScodes valueOf(long value)
     {
         ...
     }
     ...
}

ITIScodes stopped_traffic =
ITIScodes.valueOf(ITIScodes.Value.stopped_traffic);

See Also

-splitBigEnums


-limitCons <nnn>

If an ASN.1 schema contains SET, SEQUENCE types, or Information Object classes with a very large number of elements, the constructor generated for these types might exceed the limit for the number of arguments imposed by many JVMs. This can result in a runtime application failure with a ClassFormatError exception thrown by the JVM with the following message:

Too many arguments in signature.

To avoid ClassFormatErrors, the compiler will not generate a constructor if the number of arguments exceeds the value (the default value is 200) specified by the -limitCons option.

Remarks

The -limitCons option requires a parameter, nnn, that specifies the maximum number of arguments allowed in the constructor. For example, by specifying -limitcons 10 as a command-line argument, the compiler will not generate constructors with more than ten arguments. Types that contain ten or fewer components will have constructors with arguments generated as usual.

See Also


-limitMethodSize <number>

Instructs the compiler to restructure the generated code so that the size of each method should contain <number> code lines. The number parameter indicates the number of lines of generated source code (one line of code corresponds to one Java statement). The minimum value of <number> is 100.The -limitMethodSize option is especially useful when the size of the generated ASN.1/Java TOED methods exceeds the 64K limit imposed by certain JVMs, in which case the compiler might throw the ClassFormatError exception.

Example

BigSet ::= [APPLICATION 3] IMPLICIT SET {
    attr001 [1] IMPLICIT IA5String OPTIONAL,
    attr002 [2] IMPLICIT IA5String OPTIONAL,
 	.    .   .   .   .
    attr99  [99]   IMPLICIT IA5String OPTIONAL,
    attr100 [100]  IMPLICIT IA5String OPTIONAL
 }
Without –limitMethodSize With –ber and –limitMethodSize 100
public int encodeValue(...)
{
    encodeValue1(...);
    encodeValue2(...);
    ...
    encode value100();
    ...
}
private int encodeValue(...)
{
    // Encode fields attribute1 ... attribute10
    ...
}

private int encodeValue1(...)
{
    // Encode fields attribute11 ... attribute20
    ...
}
. . .

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

Remarks

Three format schemes are available:

oss
The default message format scheme used by the ASN.1 compiler.
Format:
filename.asn, line:[(moduleName):] followed by the error or warning message itself .
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:
filename.asn[:moduleName:]line:[position:] followed by the error or warning message itself
msvc
The format scheme is compatible with the Microsoft development tools.
Format:
filename.asn(line[, position]) : [moduleName:] {error | warning} followed by the error or warning message itself
Example:
MySchema.asn (9,29) : MyModule: warning A0217W: The identifier 'address' is missing from the value and is assumed.

By default, the oss message format scheme is used.


-output <outputPackage> | -noOutput

Specifies whether output files should be generated.

Remarks

The outputPackage optional parameter specifies the directory in which the output files are generated and the name of the output file.

When outputPackage is not used, the prefix of the last .asn input file is considered the output filename.

Example

MyProtocol DEFINITIONS ::= BEGIN
   protocolID OBJECT IDENTIFIER ::= {iso standard 1 22 333}
   bufferSize INTEGER ::= 1024
   Data ::= SEQUENCE {
        name     PrintableString,
        id       INTEGER,
        married  BOOLEAN
    }
END

By default, the output package name is example. When the ASN.1 compiler for Java is invoked with the command asn1pjav example.asn, the following .java files are generated:

example/                                     // the project package
example/Example.java                         // the project class
example/myprotocol/                          // a module package
example/myprotocol/MyProtocol.java           // a module class
example/myprotocol/Data.java                 // a ASN.1 typereference class

The Example.java file contains the following statement:

package example;

The MyProtocol.java and Data.java files contain the following statement:

package example.myprotocol; 

When invoked with asn1pjav example.asn o com.acme.example, the ASN.1 compiler for Java generates the following output .java files:

com/acme/example/                                 // the project package
com/acme/example/Example.java                     // the project class
com/acme/example/myprotocol/                      // a module package
com/acme/example/myprotocol/MyProtocol.java       // a module class
com/acme/example/myprotocol/Data.java             // a ASN.1 typereference class

The Example.java file contains the following statement:

package com.acme.example;

The MyProtocol.java and Data.java files contain the following statement:

package com.acme.example.myprotocol.

Note that if the last package name consists of a single uppercase letter followed by all lowercase letters, conflicting names are generated for the package and the ASN1Project class. For example, -output com.oss.Baseball would generate a class called Baseball which extends ASN1Project and resides in the com.oss.Baseball package. This would cause a javac compiler error, as well as a warning from the OSS compiler:

C0591W: Java package name 'Baseball' is the same as project class name 'Baseball'. Consider altering the package name in the output option to contain all lowercase letters or additional uppercase letters, i.e. 'BASEBALL'.


-paramTypeSuperClass | noParamTypeSuperClass

Certain parameterized assignments contain an INTEGER or a SEQUENCE type with parameterized constraints on the right side of an assignment. The instantiation of this type of parameterized assignments is a constrained type.

Example

ParamType{parameters} ::= ActualType (parameterized constraint)
		
     Instance1 ::= ParamType{actual parameters1}
     Instance2 ::= ParamType{actual parameters2}

Instance1 and Instance2 are of the same type but have different constraints.

By default, the generated classes for the Instance1 and Instance2 parameterized types inherit from a universal class that corresponds to the type on the right side of the parameterized assignment of ParamType. For example:

class Instance1 extends ActualType { ...

class Instance2 extends ActualType {  ...

When the -paramTypeSuperClass option is specified, an extra class is generated for ParamType and the Instance1 and Instance2 classes inherit from the new class.

class ParamType extends ActualType {  ...

class Instance1 extends ParamType {  ...

class Instance2 extends ParamType {  ...

This is similar to inserting an auxiliary class in the middle of the inheritance hierarchy of the generated classes:

ParamTypeSuperClass

Effect of the -paramTypeSuperClass on the hierarchy of the generated classes

Also, if a parameterized type instance is used for a component of a SET, SEQUENCE, CHOICE, SET OF, or SEQUENCE OF type, then the generated Java class that corresponds to the outermost structured type references the ParamType class generated for the parameterized assignment.

Example

AString {INTEGER:maxSize} ::= VisibleString (SIZE(0..maxSize))

A ::= AString { 80 }
B ::= AString { 100 }
C ::= SET {
         a AString { 255 }
          }

The following Java classes are generated when the -paramTypeSuperClass option is specified:

public class AString extends VisibleString {  ... }

public class A extends AString {  ... }

public class B extends AString {  ... }

public class C extends Set {
         ...
        public C(Astring a) {  ... }
        public AString getA() {  ... }
        public void  setA(Astring a) {  ... }
         ...
}

NOTE: The -paramTypeSuperClass option has an effect only if the parameter has a governor. In the following example, UseParam does not inherit from Param even if -paramTypeSuperClass is specified:

Param {Type} ::= SEQUENCE {a Type, b Type}
UseParam ::= Param {INTEGER}

In the following example, -paramTypeSuperClass causes UseParam to inherit from Param.

Param {INTEGER:maxsize} ::= PrintableString (SIZE(maxsize))
UseParam ::= Param {20}

If directives are applied to the base parameterized type or instances of a parameterized type, the following rules apply:

  • If certain directives (that affect a general structure of the class by changing the field's name or the field's type or class name) are applied to an instance of a parameterized type and there are other instances that do not have directives applied, an extra super class is generated and all instances extend this class, except for the one that was modified by applying the directives.
  • If all instances have different directives, no extra class is generated.
  • If directives are applied to a base parameterized type, a super class is generated.
  • If directives are applied to a parameterized type and some or all instances have similar directives with similar names (no changes in the general structure occur), a super class is generated.

See Also

Parameterized Types


-path <outputDirectory>

Specifies the target output directory where the files are generated.

Default Behavior

By default, the output file names are assigned relative to the current working directory. This can be changed by specifying the -path option and providing a directory that already exist. When the package subdirectories do not exist, the compiler creates them within the target output directory. Note that the listing file and the file that captures directives from the ASN.1 input syntax are also placed in the target output directory.

Example

For the following command:

asn1pjav example -path com/acme

where example.asn is:

Module DEFINITIONS ::=
   A ::= INTEGER
END

The compiler generates the following Java files in the com/acme directory:

com/acme/example/                   // the project package
com/acme/example/Example.java       // the project class
com/acme/example/module/            // a module package
com/acme/example/module/Module.java // a module class
com/acme/example/module/A.java      // a ASN.1 typereference class

The Example.java file contains the following statement:

package example;

The Module.java and A.java files contain the following statement:

package example.module;

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

Default Behavior

By default, the -pdusForOpenTypes and -noPdusForOpenTypes options are disabled, and only unreferenced types may become PDUs.

Remarks

The -noPdusForOpenTypes option is ignored if the -noConstraints option is not specified.

The -autoEncDec option overrides -noPdusForOpenTypes.

See Also


-pedantic | noPedantic

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.

The -pedantic option implies the -syntaxOnly option, therefore no .java file is generated.


-prefix <prefix>

Specifies the prefix for the global generated names in your Java program file. The -prefix option is useful in multiple input ASN.1 syntaxes to avoid multiple declaration Java compiler errors resulting from conflicting names.

Example

ASN.1 without -prefix with -prefix
TEST DEFINITIONS  ::= BEGIN
   A ::= INTEGER
END
example/Example.java
example/test/Test.java
example/test/A.java
example/Example.java
example/my_test/My_Test.java
example/my_test/My_A.java

In this example, the prefix is added to module names and generated class names. The prefix may also affect Java values generated for value references and Java constants generated for named bits, named numbers, and enumerators.


-relaxedMode | -noRelaxedMode

Controls the automatic selection of command-line options.

Default Behavior

By default, 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.


-relaySafe | -noRelaySafe

Informs the ASN.1 compiler whether it should generate the instructions necessary for the decoder to preserve unknown extension additions for each extensible ASN.1 type. In this way, an application that needs to modify information in the extension root or in any recognized extensions, and then to re-encode, can do so without losing unknown extension additions. The encoder automatically reinserts into the encoding any unknown extension additions found while decoding.

Default Behavior

By default, the -noRelaySafe option is implied.

Remarks

When you specify the -relaySafe option, no additional changes in the code are required. Make sure you recompile the ASN.1 specification.

When you specify the -noRelaySafe option, the encoder/decoder silently ignores unknown extension addition values.


-reservedWords

Defines keywords that are not automatically supported by the ASN.1 compiler.

Default Behavior

By default, the -reservedWords option is disabled.

Example

asn1pjav fname.xsd -reservedWords word1,word2,...

For example, ASN.1 type Enum is defined as follows:

Enum ::= ENUMERATED {send, assert}

The XSD/FWS compiler command-line:

asn1pjav a.asn

The generated Enum.java class contains:

public final class Enum extends Enumerated {
    ...
    // Named list definitions.
    public static final Enum send =
        new Enum(0);
    public static final Enum assert =
        new Enum(1);
    private final static Enum cNamedNumbers[] = {
         send,
         assert
    };
    ...
}

The Enum class contains the identifier assert which might cause Java compiler warnings in certain versions:

m\Enum.java:48: warning: as of release 1.4, assert is a keyword, and may not be used as an identifier
    public static final Enum assert =
                             ^

To avoid these warnings, invoke the ASN.1 compiler as follows:

asn1pjav a.xsd -reserved assert

The generated Enum.java class contains:

public final class Enum extends Enumerated {
    ...
    // Named list definitions.
    public static final Enum send =
        new Enum(0);
    public static final Enum _assert =
        new Enum(1);
    private final static Enum cNamedNumbers[] = {
         send,
         _assert
    };
    ...
}

To change the name of the Enum class, invoke the ASN.1 compiler as follows:

asn1pjav a.xsd -reserved assert,Enum

The generated Enum.java class contains:

public final class Enum_ extends Enumerated {
    ...
    // Named list definitions.
    public static final Enum_ send =
        new Enum_(0);
    public static final Enum_ _assert =
        new Enum_(1);
    private final static Enum_ cNamedNumbers[] = {
         send,
         _assert
    };
    ...
}

See Also

Conflicts with Java reserved words


-root

Instructs the ASN.1 compiler to treat all input modules as root modules.

Default Behavior

By default, only the last module specified at the command line is treated as a root module.

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.


-sampleCode <pdus | values> | -noSampleCode

Instructs the compiler to generate sample code that shows you how to populate and use the generated Java-representations of PDU types defined in the input ASN.1 syntax.

The -noSampleCode option informs the compiler that it should not generate a sample application, even if the OSS.SampleCode directive is not specified in the ASN.1 input.

Default Behavior

By default, -sampleCode | -noSampleCode option is disabled.

Remarks

To generate sample code, use the following parameters:

values
Generates sample code only for PDU values.
pdus
Generates sample code only for PDU types.

If the parameter is absent, the compiler generates a sample application containing test code for each value reference in the ASN.1 input defined with a type that is a PDU, and for each value automatically created by the compiler for "true" PDU types.

When instructed to generate sample code, the ASN.1/Java compiler creates an additional samples subpackage directory inside the project directory. The sample code for a PDU Type that is defined inside a Module is placed into a project.samples.module.TypeSample Java class.

Sample classes are not intended to be instantiated and the sample code is static. A sample class contains the following methods:

createSampleValue()
Creates and returns a sample value of a PDU type when the -sampleCode pdus command-line option is used or both optional parameters are absent.
create_xxx_Value()
Creates and returns a sample value of valuereference xxx in the ASN.1 input that is defined with a PDU type when the -sampleCode values command-line option is used or both optional parameters are absent.
printValue()
Prints values.
encodeDecodeAndPrint()
Runs the encoder/decoder test over a single sample value.
main()
Invokes the encodeDecodeAndPrint() test for each sample value found in the class.

To customize sample values (CHOICE, SEQUENCE OF, and SET OF) you can use -sampleCode with the OSS.SampleCode directive.

The -sampleCode option has no effect if the input ASN.1 syntax does not contain PDUs or when the -noOutput or -syntaxOnly option is present.

When -sampleCode is specified with the values parameter and the input ASN.1 syntax has no valuereferences for PDU types, the option is ignored.

Version Information

The -sampleCode option is compatible with the -toed option in version 7.0 and later.

See Also


-splitBigEnums <nnn>

Reduces the size of a large JVM internal static initializer method by generating static _initMembers...() methods that split the large initializer into parts, which helps overcome the JVM 64K method size limit. The number argument is mandatory. The number of named items must be greater than the specified number argument, otherwise the option has no effect. The argument also specifies the size of the parts.

The -noSampleCode option informs the compiler that it should not generate a sample application, even if the OSS.SampleCode directive is not specified in the ASN.1 input.

Remarks

The –splitBigEnums option is supported for the following types: ENUMERATED, INTEGERs with named numbers, and BIT STRINGs with named bits.

The ASN.1/Java compiler generates representations of ENUMERATED that define class constants (public static final) for each enumerator. Additionally, the class defines an array that aggregates all known enumerators of the type. The Java compiler (javac) generates the code required to initialize the members into the static initializer method.

When an ENUMERATED contains a large number of enumerators, the amount of code required to initialize the class constants and the array of enumerators could exceed the 64K size limit of the JVM method. A similar problem could occur for an INTEGER type that defines a large number of named numbers or when a BIT STRING defines a large number of named bits. Currently, the -soed compiler option generates correct Java code when the number of enumerators does not exceed 1600 (for –toed, the limit is 2200).

For example, if there are 2000 enumerators and the -splitBigEnums argument is 500, the static array initializer for 2000 members is split into four static _initMembers...() methods, each of which initializes 500 members of the array.

Example

In the following example, the JVM 64K limit is exceeded:

ITIScodes ::= ENUMERATED  {
    -- Traffic Conditions
    stopped-traffic                            (257),
    stop-and-go-traffic                        (258),
    slow-traffic                               (259),
    heavy-traffic                              (260),
    -- ... >2400 enumerators follow
}

The ENUMERATED in the above example uses a single initializer for the compiler-generated array of enumerators.

     private final static ITIScodes cNamedNumbers[] = {
         new ITIScodes(),
         new ITIScodes(258),
         new ITIScodes(259),
         new ITIScodes(260),

         ... >2400 array members follow
     }

When the -splitBigEnums 500 option is used, the cNamedNumbers[] array is initialized as follows:

     private static void _initMembers0(ITIScodes[] members) {
         members[0] = new ITIScodes();
         members[1] = new ITIScodes(258);
         members[2] = new ITIScodes(259);
         members[3] = new ITIScodes(260);

         ... first 500 members follow
     }

     private static void _initMembers1(ITIScodes[] members) {
         members[500] = new ITIScodes(4364);

         ... other 500 members follow
     }

     private static void _initMembers2(ITIScodes[] members) {
         ...
     }

     ... other _initMembersN methods follow

     private static ITIScodes[] _initMembers() {
         ITIScodes[] members = new ITIScodes[2442];
         _initMembers0(members);
         _initMembers1(members);
         _initMembers2(members);
         _initMembers3(members);
         _initMembers4(members);
         return members;
     }
     private final static ITIScodes cNamedNumbers[] = _initMembers();

See Also

-limitBigEnums


-splitSampleCode <depth>

Instructs the compiler to generate auxiliary methods that provide initializations of PDU parts and are invoked from the createSampleValue() method, thus reducing the method size, to avoid the "code too large" error at Java compile time.

The ASN.1/Java -sampleCode option is used to generate sample Java code that illustrates API usage. The code is generated into project.samples.<module>.<type>.java classes, which include methods for initializing, printing and encoding/decoding sample values. The createSampleValue() method for types that have a huge number of components can be affected by the code too large error at Java compile time.

Remarks

The -splitSampleCode option can be used only when the -sampleCode option or the SampleCode directive is specified.

The -splitSampleCode option can be followed by an optional number parameter that specifies the nesting level of the code split. By default, the number takes a value of 1, that is, only the top-level code is split.

The -splitSampleCode option affects only code that initializes values of SEQUENCE, SET, SEQUENCE OF, or SET OF ASN.1 types that also have components of the above types.

Example

ASN.1

SampleType := SEQUENCE {

     f1 TypeOfField1,
     f2 TypeOfField2
}

TypeOfField1 ::= SEQUENCE {
     f1  SEQUENCE {
         f1 INTEGER
     },
     f2  INTEGER
}

TypeOfField2 ::= INTEGER
Without -splitSampleCode With -splitSampleCode used without a parameter With -splitSampleCode 2
public static SampleType createSampleValue()
{
    SampleType value = new SampleType();
    value.setF1(new TypeOfField1());
    {
        TypeOfField1 f1_2 = value.getF1();
        f1_2.setF1(new TypeOfField1.F1());
        {
            TypeOfField1.F1 f1_3 = f1_2.getF1();
            f1_3.setF1(new com.oss.asn1.INTEGER(0));
        }
        f1_2.setF2(new com.oss.asn1.INTEGER(0));
    }
    value.setF2(new TypeOfField2(0));
    return value;
}
public static SampleType createSampleValue()
{
    SampleType value = new SampleType();
    value.setF1(createSampleValue_f1());
    value.setF2(new TypeOfField2(0));
    return value;
}

public static TypeOfField1 createSampleValue_f1()
{
    TypeOfField1 value = new TypeOfField1();
    value.setF1(new TypeOfField1.F1());
    {
        TypeOfField1.F1 f1_3 = f1_2.getF1();
        f1_3.setF1(new com.oss.asn1.INTEGER(0));
    }
    value.setF2(new com.oss.asn1.INTEGER(0));
    return value;
}
public static SampleType createSampleValue()
{
    SampleType value = new SampleType();
    value.setF1(createSampleValue_f1());
    value.setF2(new TypeOfField2(0));
    return value;
}

public static TypeOfField1 createSampleValue_f1()
{
    TypeOfField1 value = new TypeOfField1();
    value.setF1(createSampleValue_f1_f1());
    value.setF2(new com.oss.asn1.INTEGER(0));
    return value;
}

public static TypeOfField1.F1 createSampleValue_f1_f1()
{
    TypeOfField1.F1 value = new TypeOfField1.F1();
    value.setF1(new com.oss.asn1.INTEGER(0));
    return value;
} 

See Also


-splitTypeInfo <nnn>

Each type in an ASN.1 schema (for which a Java class is generated) contains generated metadata information. The metadata is a value called c_typeinfo that contains debugging, constraint, and tagging information. If a SEQUENCE, SET, CHOICE, or Information Object class with a large number of elements is present, c_typeinfo could exceed the 64K limit imposed the JVM, in which case the JVM throws a ClassFormatError exception with the following message:

Code of a method longer than 65535 bytes.

To avoid this error, the c_typeinfo definition is split into separate init_fieldnnn() methods which are used in the c_typeinfo initializer. This reduces the size of the JVM internal initialization method. This is supported for types where the number of elements exceeds the value (default: 200) specified by the -splitTtypeInfo option.

Example

In the following example, the static variable that corresponds to c_typeinfo for a SEQUENCE with few elements is:

public static final TypeInfo c_typeinfo = new SequenceInfo( ... ); 

The number of elements is greater than nnn (default: 200), the TypeInfo initialization is split into separate methods for each field:

public static final TypeInfo c_typeinfo = new SequenceInfo(
                                       ...
                                       init_field0(),
                                       init_field1(),
                                       ...
                                       init_fieldN()
);
private static SequenceFieldInfo init_field0() { ... }
private static SequenceFieldInfo init_field1() { ... }
...
private static SequenceFieldInfo init_fieldN() { ... } 

This is supported for metadata of the following ASN.1 structured types: SEQUENCE, SET, and CHOICE, or for Information Object classes. The -splitTypeInfo option requires a parameter nnn, which specifies the maximum number of elements permitted before the TypeInfo is split. For example, if you specify -splittypeinfo 10 at the command line, the compiler splits TypeInfo if there are more than 10 elements in a SET, SEQUENCE, CHOICE, or CLASS.

See Also


-splitValues

Certain ASN.1 schemas may generate a large number of initialized static variables that correspond to ASN.1 value references and information object sets. Certain Java compilers combine these static initializations into one large internally defined method, therefore the size of the method might exceed the 64K method size limit imposed by JVMs, in which case the JVM may throw a ClassFormatError exception.

The -splitValues option instructs the ASN.1 Java compiler to generate variable initializers into separate private static init_XXXX() methods, which are used to assign a value to a static variable. This helps reduce the size of the JVM internal initialization method and helps you avoid ClassFormatError exception.

Example

By default, the static variable that corresponds to an ASN.1 valuereference is:

public static final Type value_name = new Type ( ... );

With the -splitValues option, the compiler generates:

public static final Type value_name = init_value_name();
private static Type init_value_name() { return new Type( ...); }

This occurs for values of the following ASN.1 structured types: SEQUENCE, SET, CHOICE, SEQUENCE OF, SET OF and information object sets.

See Also


-suppress <messageNumber>

Instructs the compiler to suppress a specific warning or informatory message.

Remarks

You can specify -suppress more than once at the command line.

messageNumber can be either the complete message identifier (A0210W ,for example) or the numeric part (210, for example).

See Also


-syntaxOnly

Instructs the ASN.1 compiler to perform the syntax check only once on the ASN.1 input. This is useful if you don't need to generate Java files when debugging an abstract syntax.

Default Behavior

By default, Java files are generated.

See Also

-pedantic


-test | -wTest

Instructs the ASN.1 compiler for Java to generate the Test.java file into the project package. The Test class contains the public static void main() method so the Test class can be run as a Java application. The purpose of the test application is to encode, decode, and print all value references in the ASN.1 input defined with a PDU type. This simplifies sample encoding generation and encoder/decoder testing (you don't need to write Java code).

The -noTest option does not generate the Test.java file described above.

Default Behavior

The -noTest option is implied.

Remarks

The Test application encodes or decodes values only if you incorporate value references into the ASN.1 syntax.

Only PDU type values are tested. By default, the compiler does not consider types referenced by other types as PDUs, except for types that have the PDU directive applied (ASN1.PDU or OSS.PDU).

If the test | -wtest option is implied and the ASN.1 syntax does not contain any value notation, that is, there are no predefined test cases, the compiler issues the C1261E error.


-toed | -soed

Instructs the ASN.1 compiler to generate Java code that is optimized either for speed or for size. Code optimized for speed is compatible with osstoed.jar, the time-optimized encoder/decoder library. Code optimized for size is compatible with oss.jar or osslean.jar, the space-optimized encoder/decoder libraries.

Default Behavior

By default, the -soed option is implied.

Remarks

The -toed and -soed options are mutually exclusive and the last one specified at the command line takes precedence.

Currently, the -ber | -der | -json, -oer | -coer, -per |-uper | -xer | -cxer and -constraints options are supported for -toed.

The following command-line options are ignored when specified with the -toed option:

  • -cer | -exer
  • -dtd
  • -indexInfoObjectSets
  • -jiaapi
  • -lean
  • -paramTypeSuperClass
  • -splitSampleCode
  • -splitTypeInfo
  • -userConstraints
  • -xsl

When the -constraints option is specified with the -toed option, the compiler generates the validate() method, which enables runtime constraint checking. Currently, the following constraints are supported for TOED:

  • INTERSECTION
  • UNION
  • EXCEPT
  • ALL EXCEPT
  • SingleValue
  • ContainedSubtype
  • ValueRange
  • SizeConstraint
  • InnerTypeConstraints
  • Permitted Alphabet
  • Type constraint
  • PatternConstraint
  • PropertySettings
  • DurationRange
  • TimePointRange
  • RecurrenceRange
  • Table constraint
  • Component relation constraint
  • Contents constraint

When the -constraints option is not specified, the validate() method is not generated.


-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. The -noUniquePDU option informs the compiler that PDUs can have identical tags.

Default Behavior

By default, 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 the -noUniquePDU option is enabled, no error or warning message is generated. When neither option is specified, the compiler issues only warning messages.

Note that in certain ASN.1 specifications (for example, the Presentation Layer Protocol (ISO/IEC 8823/ITU-T X.226)) PDUs don't have unique tags. In other ASN.1 specifications (for example, the Association Control Service Element (ACSE)) PDU tags are unique.


-userConstraints | -noUserConstraints

Specifies whether user-defined constraints should be generated into Java classes.

Default Behavior

By default, the -noUserConstraints option is enabled.

Remarks

When you specify the -userConstraints option with -noConstraints, information for user-defined constraints is generated into Java classes, and information for other constraints is excluded.

When you specify -noUserConstraints with -constraints, user-defined constraint information is excluded from the generated Java classes, and information for other constraints is included.

When you specify -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 OddNumber Java class. To verify if the constraint is imposed on values of type OddNumber, the encoder/decoder calls the isValid() method of the OddNumber_fn class.

When you specify -userConstraints, you must write constraint checking methods for all user-defined constraints (unless the OSS.NoConstrain directive is specified to disable constraint checking for a particular type).

When you specify -noUserConstraints, you do not need to write methods to check user-defined constraints.


-valueRefs | -noValueRefs

Informs the compiler whether it should generate information about value references.

The -valueRefs option instructs the ASN.1 compiler for Java to generate public static variables for all value references from an input ASN.1 notation. The value references can then be accessed from anywhere in the user application.

The -noValueRefs option suppresses information about value references.

Default Behavior

By default, the -valueRefs option is enabled.

Remarks

If the -test option is specified, the -noValueRefs option has no effect.


-verbose | -noVerbose

Specifies whether ASN.1 compiler status messages should be issued.

The -verbose option instructs the ASN.1 compiler to issue status messages. The -noVerbose option instructs the ASN.1 compiler to suppress status messages.

Default Behavior

By default, the -noVerbose option is enabled.


-warningMessages | -noWarningMessages

Specifies whether compiler warning and informatory messages should be generated.

Default Behavior

By default, the -noWarningMessages option is implied via -relaxedMode. To suppress all warnings, specify the -noWarningMessages option.

Remarks

The -warningMessages option implies the -informatoryMessages option. The -noWarningMessages option implies the -noInformatoryMessages option.

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 Extensible Stylesheet Language (XSLs) files, one for each PDU.

Remarks

If the -xer is not specified, the -xsl option and the OSS.Stylesheet directive have no effect. Also, when the -noOutput or -syntaxOnly option is used, the -xsl option has no effect.

By default, the XSL stylesheet file is generated in the directory of the corresponding ASN.1 module package and has the name ClassName.xsl. For the "baseball" example, the generated XSL stylesheet file is BBCard.xsl in the baseball/bcas directory.

See Also


This documentation applies to the OSS® ASN.1 Tools for Java release 7.1 and later.

Copyright © 2017 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 Java 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 Java are available to you.