TOP

ASN.1/Java Compiler Directives Reference

Applies to: ASN.1/Java 7.1

This section lists the compiler directives and provides a detailed description of their function. The compiler directives on this page are grouped into two categories:

Standard Directives (ASN1.*)

The format of a standard directive is:

--<ASN1.nameOfDirective [absoluteReference] [directiveOperand(s)]>--

nameOfDirective can be one of the following:

  • ConstraintFunction
  • DeferDecoding
  • Nickname
  • PDU
  • RealRepresentation
  • Remove
  • Version
  • WorkingSet

absoluteReference is used for uniquely specifying one or more components in ASN.1.

The absolute reference notation is similar to the syntax used in many programming languages to access components within named structures and records. The outermost structure is listed first using its identifier followed by a period ("."). A component of the outermost structure can be listed next. If a component is placed within a nested structure, a period is added after the name of the containing structure, and the component is listed next.

There are four methods of specifying ASN.1 components:

  • Using a component identifier.
  • Using an asterisk ("*") for specifying all rows in the SEQUENCE OF and SET OF arrays.
  • Using an INTEGER index for specifying which element is intended in a SEQUENCE, SET, or CHOICE.
  • Using the dollar sign ("$") followed by a number index to reference a particular CONSTRAINED BY clause.

For example, for the following ASN.1 definition:

MyMod DEFINITIONS ::= BEGIN
   Comp1 ::= SET OF SEQUENCE {
      a   INTEGER,
      b	  OCTET STRING OPTIONAL,
      c	  CHOICE {
                  nest1  BOOLEAN,
                  nest2  BIT STRING
                 }
       }
    Comp2 ::= IA5String
END

The absolute reference for:

  1. the entire module is: MyMod
  2. the SET OF structure is: MyMod.Comp1
  3. the SEQUENCE series is: MyMod.Comp1.*
  4. the INTEGER is: MyMod.Comp1.*.a or MyMod.Comp1.*.1
  5. the OCTET STRING is: MyMod.Comp1.*.b or MyMod.Comp1.*.2
  6. the CHOICE is: MyMod.Comp1.*.c or MyMod.Comp1.*.3
  7. the BOOLEAN is: MyMod.Comp1.*.c.nest1 orMyMod.Comp1.*.c.1
  8. the BIT STRING is: MyMod.Comp1.*.c.nest2 or MyMod.Comp1.*.c.2
  9. the IA5String is: MyMod.Comp2

To access ASN.1 types located within CONSTRAINED BY clauses, specify the dollar sign ("$") followed by a number index indicating a particular CONSTRAINED BY. This number index can be optionally followed by a colon (":") and another number index or a component identifier that indicates a particular component within the CONSTRAINED BY braces. If the colon and the index or the identifier following it are left out, the first component within the CONSTRAINED BY is targeted by default.


--<ASN1.ConstraintFunction absoluteReference ["]className["]>--

Specifies the name of a Java class that is used to check a user-defined constraint.

The absoluteReference refers to a component within a module that has a user-defined constraint attached.

The className argument is the name of the constraint-checking class to be used. The class name can be a quoted or an unquoted string. Use a quoted string if the class name is a fully qualified (period-separated) class name. If the className argument is omitted, the ASN.1 compiler will issue an error message. The Java class specified with the className argument must implement the com.oss.asn1.ExternalChecker interface.

Example

In the following example, the my.OddChecker.isValid(AbstractData odd) application class method is used to check if the OddInteger type is indeed odd. The custom class used to check the constraints must implement the com.oss.asn1.ExternalChecker interface; otherwise, a runtime error would occur. If the constraining class name is not provided, the name of the constraining class will default to OddInteger_fn.

--<ASN1.ConstraintFunction Module.OddInteger "my.OddChecker">--

Module DEFINITIONS ::= BEGIN
    OddInteger ::= INTEGER (CONSTRAINED BY {-- odd --} )
END

Remarks

This directive can be used only with types with a CONSTRAINED BY clause.

The ASN1.ConstraintFunction directive must be placed before the user-defined type it references. User-defined constraint-checking methods are generated only if the -userConstraints compiler option is enabled.

By default, the name of the constraining class is typereference_fn.

See Also


--<ASN1.DeferDecoding absoluteReference>--

Does not allow the compiler to automatically decode a particular component within a CHOICE, SEQUENCE, or SET structure when its containing type is marked for decoding.

The type referred to by the absolute reference will result in extra methods generated by the ASN.1 Java compiler, which enables access to the still-encoded portion of the deferred component and allows encoding/decoding of the deferred component.

Example

ASN.1 Java
--<ASN1.DeferDecoding Module.Type.setComponent>--
  
  Module DEFINITIONS ::= BEGIN
     Type ::= SET {
             setComponent INTEGER,
                        b BOOLEAN 
             }
  END
public class Type extends Set {

     public Type(){...}
     public Type(INTEGER setComponent, BOOLEAN b) {...}
     public Type(long setComponent, boolean b) {...}
     public INTEGER getSetComponent(){...}
     public byte[] getEncodedSetComponent(){...}
     public void setSetComponent(long setComponent){...}
     public void setSetComponent(INTEGER setComponent){...}
     public void decodeSetComponent(Coder coder){...}
     public void encodeSetComponent(Coder coder){...}
     ...
}

The methods shown above in bold are generated only when the DeferDecoding directive is set.

Remarks

The ASN1.DeferDecoding directive is not supported for the PER coder, because PER fields are not easily skipped over.

By default, all components of CHOICE, SET, or SEQUENCE types are decoded with their containing type.

See Also


--<ASN1.HugeInteger absoluteReference>-- | --<OSS.HUGE [absoluteReference]>--

Sets a special representation for INTEGERs whose size is not limited by the long Java integer type. By default, INTEGER types are represented by the com.oss.asn1.INTEGER class (it uses the long Java type, which is sufficient for representing 64-bit numbers). When either directive is used, the corresponding INTEGER types are represented by the com.oss.asn1.HugeInteger class.

When specified globally, absoluteReference refers to INTEGER types represented using the HugeInteger directive. The HugeInteger representation consists of a structure that contains a pointer to a CHARACTER STRING and a length field. When specified locally, the directives take no operands.

Example

Using a local directive:

ASN.1 Java
HugeInt DEFINITIONS ::= BEGIN
     A ::= INTEGER --<HUGE>--
     END
public class A extends HugeInteger {
     ...
     }

Using a global directive:

ASN.1 Java
--<ASN1.HugeInteger LengthModule.LengthData.lengthOfSolarSystem>--

LengthModule DEFINITIONS ::= BEGIN
LengthData ::= SEQUENCE {
  lengthOfSolarSystem  INTEGER,
  units ENUMERATED{mm(0), cm(1), m(2), km(3), lightyears(4)} 
                 DEFAULT mm
  }
END
public class LengthData extends Sequence {
...
/**
  * Construct with components.
  */
 public LengthData(HugeInteger lengthOfSolarSystem, Units units)
    {
      setLengthOfSolarSystem(lengthOfSolarSystem);
      setUnits(units);
     }
...
// Methods for field "lengthOfSolarSystem"
  public HugeInteger getLengthOfSolarSystem()
      {
       return (HugeInteger)mComponents[0];
      }
  public void setLengthOfSolarSystem(HugeInteger lengthOfSolarSystem)
      {
       mComponents[0] = lengthOfSolarSystem;
      }
...
}

--<ASN1.Nickname absoluteReference [["]nickname["]]>--

Provides an alias to a name from an ASN.1 module to be used in the application program. By default, the name used in the generated data structures is derived from the input ASN.1 syntax.

The absolute reference specifies the name of a module, type reference, value reference, object class reference, object reference, object set reference, identifier or field name, element of a SET or SEQUENCE, anonymous component of a SET or SEQUENCE, or an identifier in a named number list.

The nickname parameter should follow the naming rules of the target programming language.

Example

In the following notation, the MTN nickname is used for the MyTypeName type, which is an element of MySequence within MyModule.

--<ASN.1.Nickname MyModule.MySequence.MyTypeName MTN>--

The following example illustrates how to name types and identifiers:

ASN.1 Java
  --<ASN1.Nickname Module.UserData Monkey>--
  --<ASN1.Nickname Module.UserData.* Gorilla>-- 
  --<ASN1.Nickname Module.UserData.*.1 Gibbon>-- 
  --<ASN1.Nickname Module.UserData.*.fvalue Mandrill>--
        
 Module DEFINITIONS ::= BEGIN 
   UserData ::= SET OF SEQUENCE { 
      key    INTEGER, 
      fvalue OCTET STRING OPTIONAL 
   } 
 END   
public class Monkey extends SetOf {
    ...
    public static class Gorilla extends Sequence {
        ...
        /**
          * Construct with components.
          */
        public Gorilla(long Gibbon, OctetString Mandrill)
        {
            setGibbon(Gibbon);
            setMandrill(Mandrill);
        }
        ...
    }
    ...
}

The above ASN.1 example is equivalent to:

Module DEFINITIONS ::= BEGIN
   UserData ::= SET --<TYPENAME "Monkey">-- OF SEQUENCE {
                key    INTEGER --<FIELDNAME "Gibbon">--,
                value  OCTET STRING --<FIELDNAME "Mandrill">-- OPTIONAL
     } --<TYPENAME "Gorilla">--
END

Note that "*" refers to the SEQUENCE type, and 1 refers to the first element in the SEQUENCE (the key). In ASN.1:1990, you can omit identifiers for elements of a SEQUENCE, SET, or CHOICE, therefore you can use the number notation to give a name to every component of these constructs. Note that identifiers are mandatory in ASN.1:2015.

The following example shows how to name an item in a named number list:

ASN.1 Java
  --<ASN1.Nickname Module.E.enum1 " new_enum1">-- 
  --<ASN1.Nickname Module.B.bit1 " new_bit1">-- 
  --<ASN1.Nickname Module.I.int1 " new_int1">-- 
  
  Module DEFINITIONS ::= BEGIN 
     E ::= ENUMERATED {enum1(1), enum2(2)} 
     B ::= BIT STRING {bit1(4), bit2(8)}
     I ::= INTEGER {int1(10), int2(8)} 
  END
public class E extends Enumerated {
     ...
     // Named list definitions.
     public static final E new_enum1 = new E(1);
          ...
     }

public class B extends BitString {
     ...
     // Named list definitions.
     public static final int new_bit1 = 4;
          ...
     }

public class I extends INTEGER {
     ...
     // Named list definitions.
     public static final I new_int1 = new I(10);
        ...
}

See Also


--<ASN1.PDU type [, type ] ... >--

Instructs the compiler to treat one or more ASN.1 types as Protocol Data Units (PDUs).

The types following the directive are operands that specify which ASN.1 types should be treated as PDUs. Note that these types should be specified using the absolute reference notation.

By default, unreferenced types (user defined types that are not referenced by any other type) are considered PDUs by the compiler, and they can be encoded and decoded as complete units.

Example

In the following example, MyType is treated as a PDU, even if it is referenced in another type definition. Note that the types in the directive must be specified using the absolute reference notation.

--<ASN1.PDU Module.Type>--
  
Module DEFINITIONS ::= BEGIN
     TypeRef ::= Type
     Type ::= SET { b BOOLEAN }
END

Type will be treated as a PDU, even though it is referenced in another type definition.

See Also

OSS.PDU


--<ASN1.RealRepresentation realKind [type1 [, type2, ... ]]>--

Enables you to select the representation (binary, decimal, or mixed) to be used for ASN.1 values of type REAL. This directive can be applied to particular REAL types, or can specify a default for all REAL types. By default, the REAL type is represented by the com.oss.asn1.Real class or compiler-generated classes which extend the com.oss.asn1.Real class.

The realKind operand can be: binary, decimal, or mixed, and it specifies how the REAL type should be represented in the generated .java files.

binary
Is implemented by the com.oss.asn1.Real class that uses the double Java type internally. It is the default.
decimal
Corresponds to the com.oss.asn1.DecimalReal class. The DecimalReal class represents the REAL value as a character string of the form: [ ]nnnnn.nnnnn[E[ ]nnnnn].
mixed
Corresponds to the com.oss.asn1.MixedReal class. The MixedReal class can use either binary or decimal representation, and can be selected by the user or depend on the encoded form of the REAL value.

A list of affected types can be specified after the realKind operand using the absolute reference notation. If no type references are specified, the ASN1.RealRepresentation directive sets the default representation for REAL types locally, on the module-level, or globally, according to its location.

Example

ASN.1 Java
--<ASN1.RealRepresentation mixed Module.Type.a1.b2>--
Module DEFINITIONS ::= BEGIN
   MyType ::= SEQUENCE {
      a1 SET { b1 INTEGER, b2 REAL},
      a2 REAL
   } 
END
// Methods for field "b2"
public MixedReal getB2()
public void setB2(MixedReal b2);

// Methods for field "a2"
public double getA2();
public void setA2(double a2);

In the above example, the com.oss.asn1.MixedReal class is used to represent field b2 of field a1 of type Type, while field a2 of the type Type is represented by the com.oss.asn1.Real class.

Remarks

For a global effect, the ASN1.RealRepresentation directive must be used with no type references and placed before the first module in the ASN.1 input.

See Also

OSS.DECIMAL | OSS.MIXED


--<ASN1.Remove absoluteReference [, absoluteReference ] ...>--

Instructs the ASN.1 compiler to ignore certain ASN.1 types or components. The compiler does not generate code for these types. This is useful when you want to omit certain parts of an ASN.1 specification without modifying the original ASN.1 source.

absoluteReference can refer to: defined types, defined values, members of CHOICE types (excluding the last component specified), components that are marked OPTIONAL in a SEQUENCE or SET type, componenst that have a DEFAULT value in a SEQUENCE or SET type, information object classes, information objects that are not included in information object sets, information object sets.

The ASN1.Remove directive informs the compiler that an ASN.1 item should be treated as if it was not included in the ASN.1 source text, in other words, no associated code is generated in the .java files for this type for use by the application. However, removal of components leads to encodings that are perfectly compatible with counterpart applications that do not use the ASN1.Remove directive. By default, all parts of the ASN.1 input are included in the compiler-generated files.

Example

In the following example, after compiling the syntax, an empty class structure S with no component accessor or mutator methods is generated in the .java file:

ASN.1 Java
--<ASN1.Remove Mod.Int>--
--<ASN1.Remove Mod.S.a>--
--<ASN1.Remove Mod.i>--
  
Mod DEFINITIONS ::= BEGIN
   S ::= SET { a SET OF SET OF SEQUENCE {
                 b Int 
                 } OPTIONAL 
        }
   Int ::= INTEGER
   i Int ::= 10
END
public class S extends Set {

    /**
     * The default constructor.
     */
    public S()
    {
    }
 ...
}

Also, no static final member variable is created in the Mod.java module class to represent the value i.

--<ASN1.Remove Mod.bit, Mod.Int>--
--<ASN1.Remove Mod.Set.a.b.c.d.*.e>--
  
Mod DEFINITIONS ::= BEGIN
   Int ::= INTEGER
     A ::= SEQUENCE {a Int OPTIONAL, b BIT STRING}
   a A ::= { a 1, b bit}
  bit BIT STRING ::= '0'B
  C ::= CHOICE { a Int }
  Set ::= SET {
     a SET {
       b SET {
        c SET {
            d SET OF SET {
              e INTEGER OPTIONAL
            }
          }
        }
     }
   } 
   s Set ::= { a { b { c { d { {e 3}, {e 4}, {e 5} } } } } }
  END

The .rmv file will contain the following Remove directives for types, values, components that reference items marked for removal:

--<ASN1.Remove Mod.s>--
"s" contains values for the component e marked for removal.
--<ASN1.Remove Mod.C>--
"C" references the type Int marked for removal.
--<ASN1.Remove Mod.a>--
"a" contains the reference to the defined value bit marked for removal.
--<ASN1.Remove Mod.A.a>--
The defined type Int for the component A.a is marked for removal.

Remarks

When an ASN.1 item is marked for removal, any references to the item must also be removed (by using the ASN1.Remove directive). If errors related to missing references occur and the -genDirectives or the -keepNames command-line option is specified, the OSS ASN.1 compiler automatically generates the ASN1.Remove directives in a file with an .rmv extension (this file will have the same prefix as the .gen file).

The generated .rmv file can be passed at the command-line (before any compiler options) to let the compiler automatically remove the types that are causing problems.

Under special circumstances, the ASN1.Remove directives cannot be generated into the .rmv file. In such a case, you should successively call the ASN.1 compiler several times (correcting the syntax) until the ASN.1 notation compiles correctly.

The listing file generated with the -listingFile command-line option omits removed items entirely. To get a full listing with removed items included, use the -modListingFile command-line option.

Standard directives applied to or found inside ASN.1 items marked for removal have no effect.

The ASN1.Remove directive applied to the fields of a parameterized type results in removing those fields from each instance of the parameterized type, and therefore we do not recommend it.

Removing fields from a type that is referenced in the COMPONENTS OF type notation results in removing those fields from each type specified with the COMPONENTS OF type notation.


--<ASN1.ValueInFile absoluteReference>-- | --<OSS.NOCOPY absoluteReference>-- | --<OSS.OBJHANDLE absoluteReference>--

The ASN1.ValueInFile directive specifies that values can be huge, and may require special handling at runtime. Currently, huge values are supported only with oss.jar, the space-optimized encoder/decoder runtime library (SOED).

Remarks

Certain applications need to process huge data. The following values can become huge:

  • SEQUENCE OF or SET OF
  • OCTET STRING, BIT STRING
  • Character strings: IA5String, UTF8String, or BMPString
  • Open types that carry the value of the above types
  • Unknown extensions that are values of the above types

X.509 applications might encounter huge CRLs (SEQUENCE OF or SET OF). Applications that employ cryptographic signing may need to work with huge binary strings that represent the data to be signed. To avoid out-of-memory crashes, you can use the ValueInFile directive to indicate which components of a value can become huge. The runtime provides special handling for these components. That is, it no longer assumes that the value is stored in memory but instead resides in the external storage, such as a disk file or a TCP/IP socket.

Special processing of huge data means extra expense and poorer performance. Using the ASN1.ValueInFile, OSS.OBJHANDLE, and NOCOPY directives, you can explicitly control which data requires special handling. The OBJHANDLE and NOCOPY directives are aliases for ValueInFile and are provided to maintain compatibility with other OSS ASN.1 compilers (for languages other than Java).

The absoluteReference refers to the ASN.1 types specified in the following table:

ASN.1 type Representing class Effect of the directive
BIT STRING
OCTET STRING
HugeBitString
HugeOctetString
The contents are represented as ByteStorage rather than as byte[] array.
BMPString
GeneralString
GraphicString
IA5String
ObjectDescriptor
NumericString
PrintableString
TeletexString
UTF8String
VideotexString
VisibleString
HugeBMPString
HugeGeneralString
HugeGraphicString
HugeIA5String
HugeNumericString
HugeObjectDescriptor
HugePrintableString
HugeTeletexString
HugeUTF8String16
HugeVideotexString
HugeVisibleString
The contents are represented as CharStorage rather than as String.
open type
component with the ASN1.DeferDecoding directive applied
HugeOpenType
HugeDeferredComponent
The encoded component is represented as ByteStorage rather than as byte[] array.
SET OF
SEQUENCE OF
HugeSetOf
HugeSequenceOf
The elements are represented as ObjectStorage rather than as an array.
extensible CHOICE
SEQUENCE or SET in relaySafe mode
HugeRelaySafeChoice
HugeRelaySafeSequence
HugeRelaySafeSet
Unknown extensions are internally stored as ByteStorage rather than as byte[] array.

Example

--<ASN1.ValueInFile Test.HugeBinaryData>--
Test DEFINITIONS ::= BEGIN
    HugeBinaryData ::= OCTET STRING
END
When ASN1.ValueInFile is specified: When ASN1.ValueInFile is not specified:
public class HugeBinaryData extends HugeOctetString {
    ...
}
public class HugeBinaryData extends OctetString {
    ...
}

There are local forms of NOCOPY and OBJHANDLE, but not of ASN1.ValueInFile. The following three examples are equivalent:

--<ASN1.ValueInFile Test1.HugeBinaryData>--
Test1 DEFINITIONS ::= BEGIN
    HugeBinaryData ::= OCTET STRING
END


Test2 DEFINITIONS ::= BEGIN
    HugeBinaryData ::= OCTET STRING  --<OSS.OBJHANDLE>--
END


Test3 DEFINITIONS ::= BEGIN
    HugeBinaryData ::= OCTET STRING  --<OSS.NOCOPY>--
END

Directives are not limited to ASN.1 type references, but may also apply to individual components of a SEQUENCE or SET.

Example

--<ASN1.ValueInFile Test.Signed.data>--
Test DEFINITIONS ::= BEGIN
    Signed ::= SEQUENCE {
        signature  BIT STRING,
        data       OCTET STRING
    }
END

Test DEFINITIONS ::= BEGIN
    Signed ::= SEQUENCE {
        signature  BIT STRING,
        data       OCTET STRING --<OBJHANDLE>--
    }
END

When the OSS ASN.1/Java compiler maps input ASN.1 definitions to Java classes, it chooses special representative classes for types that have the ValueInFile (or NOCOPY, OBJHANDLE) directive. These representations are quite different from default representations (as the HugeInteger class differs from the INTEGER), therefore type compatibility and API compatibility with default representations are not maintained. For example, HugeSequenceOf does not inherit from AbstractContainer and does not provide all the methods available for SequenceOf.

For information on Java classes that handle huge values, see the OSS ASN.1/Java Universal Classes section (classes typically begin with the word Huge, for example, HugeOctetString).

For information on using the Storage interface to work with huge values, refer to the Storage Interface section.

Remarks

  • The constraint checker ignores any constraints imposed on data that has the ValueInFile directive applied.
  • DER does not support huge SET OF (an exception is thrown); however, DER supports a SET that has huge unknown extensions (as well as a SET with components that are huge values).
  • The ValueInFile feature is not supported for the CER, XER, and E-XER coders.
  • When decoding huge values, the huge value is copied from the encoding, thus causing two copies: one in the input stream and the second in ByteStorage.

--<ASN1.WorkingSet WSName absoluteReference [, absoluteReference] ... >--

Enables you to select from the input ASN.1 schema a subset of types that can be used in your application. In other words, the ASN1.WorkingSet directive enables you to specify, using one directive, all PDUs (the types of the messages to encode and decode). Values, information objects, etc. defined in the working set are also represented in the compiler generated code.

The ASN1.WorkingSet directive replaces the default compiler behavior of assigning PDUs for non-referenced types. You can access certain parts of the ASN.1 specification that are not included in the working set by referencing them from the parts in the working set.

WSName is a working set name required for consistency between the ASN.1/C product and the ASN.1/C++ and ASN.1/Java products; otherwise it is ignored.

absoluteReference refers to a module name, type reference, value reference, object class reference, object reference, or object set reference. If absoluteReference is a module name, this directive has the same effect as the OSS.ROOT directive.

By default, the ASN.1 compiler chooses a working set by examining the type of compiler directives that are present.

Example

In the following example, Type1, Type2 and Type4 are directly available to the application as PDUs. Type3 is not available as a PDU.

--<ASN1.WorkingSet WSName Module2, Module3.Type4>--
Module2 DEFINITIONS ::= BEGIN
   Type1 ::= SET { typeComponent INTEGER, b BOOLEAN 
                }
   Type2 ::= INTEGER
END
  
Module3 DEFINITIONS ::= BEGIN
   Type3 ::= SET { aComponent INTEGER, b BOOLEAN }
   Type4 ::= IA5String
END

Remarks

You can extend a set by adding more than one module. For example, both module1 and module14 are included in commonSet:

--<ASN1.WorkingSet commonSet module1>--
--<ASN1.WorkingSet commonSet module14>--

The ASN1.WorkingSet directive does not affect pairs of cross referencing types. In the following example, when using a working set, neither Foo nor Bar will become a PDU:

Foo ::= SEQUENCE OF Bar
Bar ::= SEQUENCE {a INTEGER, b Foo}

A component of a SET, SEQUENCE, CHOICE, SET OF, or SEQUENCE OF cannot be added to a working set by itself.

The default determination of the Working Set

By default, the ASN.1 compiler computes the working set by considering four types of directives, in the following order of precedence:

  1. ASN1.WorkingSet directives
  2. Other ASN.1 standard directives
  3. OSS.ROOT directives
  4. Other OSS-specific standard directives

Based on the presence or absence of these directives in the input, the ASN.1 compiler assumes one of the following four modes of operation:

Default working set (dws)
All input module names are included in the working set. Additionally, when the -genDirectives command-line option is specified, the compiler generates an ASN1.WorkingSet directive for each module name in the .gen file.
Root default (rd)
Only the last module is included in the working set. In this mode, when the -genDirectives command-line option is specified, no ASN1.WorkingSet or OSS.ROOT directive is included in the .gen file.
Working set (ws)
The ASN.1 compiler includes modules specified by the ASN1.WorkingSet and the OSS.ROOT directive in the working set. Additionally, when the -genDirectives command-line option is specified, all modules from the working set have the ASN1.WorkingSet directive generated in the .gen file, even if they were included via the OSS.ROOT directive. However, when the -root option or the global OSS.ROOT directive is specified, both ASN1.WorkingSet and OSS.ROOT directives are generated in the .gen file.
Root (r)
Unless you specify the OSS.ROOT directive, no module is included in the working set. Additionally, when you specify the -genDirectives command-line option, the compiler generates an OSS.ROOT directive with one or more module name arguments (one argument for each module in the working set) in the .gen file.

The following table illustrates how the above four modes are used by the ASN.1 compiler (x = present, blank = absent):

Directive Type Types of Directives Present in Input
OSS.ROOT         x x x x x x x        
Other OSS.* directive     x x   x     x x     x   x
ASN1.WorkingSet             x x x x   x x x x
Other ASN1.* directive x     x       x x   x     x x
ASN.1 Compiler Mode dws rd rd rd r r ws ws ws ws ws ws ws ws ws

See Also


OSS Directives (OSS.*)

OSS directives can be placed in the ASN.1 schema files where spaces or tabs are allowed (locally, at the module-level, and globally). When used globally, they must be specified before the first module definition. To capture these directives in a .gen file, use the -genDirectives command-line option.

--<OSS.ASN1VER [absoluteReference] version>--

Enables you to specify the year of the ASN.1 standard used in a particular ASN.1 module. This directive is useful for applications that use several versions of ASN.1 source.

By default, before detecting a particular type of notation, the compiler uses neutral mode. After the compiler detects notation particular to a version, it switches out of neutral mode and enforces conformance to that standard.

Remarks

When specified globally, the OSS.ASN1VER directive can take an absolute reference which can be a name of an ASN.1 module or some component within a module that should be treated being part of the ASN.1:version syntax. version can take on the values: 1990, 1993, 1994, 1997, 2002, 2008, and 2015. If specified globally without an absolute reference, the OSS.ASN1VER directive sets the default version of the entire ASN.1 input.

When specified locally, the OSS.ASN1VER directive does not take an absolute reference and only affects the type next to which it is placed.

Example

The following example shows how to allow unnamed elements to be used in a SEQUENCE:

--<OSS.ASN1VER Module.NoNames 1990>--

Module DEFINITIONS ::= BEGIN
   NoNames ::= SEQUENCE {
        BOOLEAN,
        BOOLEAN,
        INTEGER
   }
END

See Also

-1990 | -2015


--<OSS.BMPSTRING [absoluteReference]>--

Enables representation of ASN.1 UTF8String types in Java via the com.oss.asn1.AbstractString16 class which can contain two byte characters (Unicode). This is the default representation for the ASN.1 BMPString type.

absoluteReference refers to an item in the ASN.1 syntax that is declared as a UTF8String. When used without arguments, this directive can only operate as a local directive.

When specified globally, the OSS.BMPSTRING directive should take an absolute reference specifying a UTF8String type which is intended for the desired representation. When specified locally, this directive does not take any arguments and only affects the type next to which it is placed.

Example

In the following example, TwoByteGlobal is set to the BMPString representation by a global OSS-prefixed directive specified with an absolute reference. TwoByteLocal is set to the BMPString representation through the use of a local directive. Default has no OSS.BMPSTRING directives applied to it, but it uses the same representation because it is the default representation. Compiler-generated Java classes for the above ASN.1 types extend the com.oss.asn1.UTF8String16 class.

ASN.1 Java
--<OSS.BMPSTRING Module.TwoByteGlobal>--

Module DEFINITIONS ::= BEGIN
  Default        ::= UTF8String
  TwoByteLocal   ::= UTF8String --<BMPSTRING>--
  TwoByteGlobal  ::= UTF8String
END
public class Default extends UTF8String16 {
     ...
}

public class TwoByteLocal extends UTF8String16 {
     ...
}

public class TwoByteGlobal extends UTF8String16 {
     ...
}

Remarks

With the BMPSTRING and UNIVERSALSTRING representations, character data will be automatically converted to the UTF-8 format before encoding and converted from UTF-8 format after decoding.

No attempt is made at runtime to ensure that the Java value contains a valid UTF-8 encoded character string. The string octets are passed to the encoder unmodified as the user places them. Also, unmodified data octets are used to fill the Java value when decoding. It is the user's responsibility to provide valid UTF-8 data before calling the encoder and to interpret the UTF-8 data received from the decoder.

See Also


--<OSS.DECIMAL [absoluteReference]>--
--<OSS.MIXED [absoluteReference]>--

Specify representations for the ASN.1 REAL type.

When the OSS.DECIMAL directive is used, the type is represented by the com.oss.asn1.DecimalReal class, which stores a REAL value as a character string of the form "[ ]nnnnn.nnnnn[E[ |+]nnnnn]".

When the OSS.MIXED directive is used, the type is represented by the com.oss.asn1.MixedReal class, which can store the REAL value both as a double and as a character string.

Example

The following ASN.1 notation shows the various ways of determining the representation of the REAL type:

ASN.1 Java
Module DEFINITIONS ::= BEGIN
     Decimal ::= REAL (WITH COMPONENTS {..., base (10) } )
     Binary  ::= REAL (WITH COMPONENTS {..., base (2) } )
     BinaryAlso ::= REAL
     Mixed   ::= REAL --<MIXED>--
END
public class Decimal extends DecimalReal {...
public class Binary extends Real {  ...
public class BinaryAlso extends Real {  ...
public class Mixed extends MixedReal {  ...

Remarks

Note that global directives will override the default representation of a base constraint. However, such a global directive does not take precedence over the local directives.

By default, the REAL type is represented by the com.oss.asn1.Real class, which stores REAL values as double unless the base component of ASN.1 REAL is constrained to be 10. In the latter case, com.oss.asn1.DecimalReal is used.

When specified globally, these directives can take an absolute reference specifying which component of the ASN.1 syntax is intended for the desired representation. If specified globally without an absolute reference, the OSS.DECIMAL and OSS.MIXED directives determine the default representation for all REAL types within their scope.

When specified locally, these directives do not take any arguments and only affect the type next to which they are placed.

Important Note

double is provided as the default representation. The ASN.1 standard implies that values encoded in base 10 must be represented in a format suitable for base 10 and values encoded in base 2 must be represented in a format suitable for base 2. This is done to avoid losing precision in conversions to and from their floating point representation. To ensure that no precision is lost, you can constrain the type REAL to base 2 or base 10. To ensure that the Java representation can encode and decode without conversion, you can use the MIXED directive.

See Also

ASN1.RealRepresentation


--<OSS.DTD [<absoluteReference> ["<OptionalNewName>.dtd"]]>--

Instructs the compiler to generate a Document Type Definition (DTD) for the specified ASN.1 types in the input definitions. The optional absolute reference refers to any ASN.1 type reference in the input ASN.1 syntax for which you wish to have a separate XML DTD generated. OptionalNewName is an optional argument that allows you to specify a filename for the DTD file which will be generated.

When the absoluteReference is missing, it is assumed that DTDs are produced for all PDUs in the input ASN.1 syntax. When the OSS.DTD directive is used globally, its behavior is identical to the -dtd ASN.1 compiler option.

Remarks

The directive has two forms:

  • --<OSS.DTD>--
  • --<OSS.DTD Module.Type ["filename"]>--

Each form specifies that a DTD file is produced for:

  • all PDUs in the ASN.1 notation
  • a particular PDU

If filename is omitted, then the DTD file name defaults to the typename, with the .dtd suffix appended.

If filename is present, it can be an absolute filename or a relative filename. If the filename is absolute (for example, starts with a slash '/' on a Unix system) then all directories in its pathname should exist. Other filenames are relative to the type's module package directory and all subdirectories in the relative pathnames will be created as needed.

Note: Do not specify the same file name in more than one directive, otherwise the file will be overwritten and its contents will be unpredictable.

The first directive instructs the compiler to generate a DTD for a particular type that is identified by the absoluteReference, and can optionally specify the name for the .dtd.

The optional filename parameter in the directive can take the following forms:

  • The filename, for example, MyType.dtd. The MyType.dtd file is generated in the type's module package directory.
  • A relative pathname, for example, dtds/MyType.dtd. The pathname is treated relatively starting from the type's module package directory. For example, if the project directory is myproject, the type's package directory is mymodule, then the file MyType.dtd is generated in the myprojects/dtds directory. No check for possible name conflicts is performed. Make sure there are no name conflicts.
  • An absolute pathname, such as /home/user/dtds/MyType.dtd. The file is generated in the absolute path specified. In this case, all subdirectories in the pathname must exist; the compiler will not attempt to create the directories in the absolute pathname.

By default, no DTDs are produced by the ASN.1 compiler.

NOTE: Unless -xer is specified, the -dtd option and the OSS.DTD directive have no effect.

See Also


--<OSS.ENCODABLE [absoluteReference]>--

Enables you to provide your own encoding for a particular component of a type. This directive should be used with the DeferDecoding directive. A new method (in addition to the methods generated by the DeferDecoding directive) is generated in the Java class of the ENCODABLE component as:

setEncodedXXX()

where XXX is replaced by the name of the field. Note that using the ENCODABLE directive without the DeferDecoding directive will not cause the additional method to be generated.

Be aware that this method can create incorrect encodings which are difficult to trace.

Example

ASN.1 Java
--<ASN1.DeferDecoding Module.SetType.s>--
--<OSS.ENCODABLE Module.SetType.s>--
Module DEFINITIONS ::= BEGIN
   SetType ::= SET {
        s   SEQUENCE {
            a   INTEGER OPTIONAL,
            b   BOOLEAN
            } ,
        p   PrintableString
        }
END
public void setEncodedS(byte[] encoded);
  

See Also

ASN1.DeferDecoding


--<OSS.FIELDNAME [absoluteReference] ["]newName]["]>--
--<OSS.TYPENAME [absoluteReference] [["]newName]["]>--

The OSS.FIELDNAME directive specifies the field name that should be generated into the .java file where the compiler would have generated a name derived from the ASN.1 identifier of the corresponding SET, SEQUENCE, or CHOICE component.

The OSS.TYPENAME directive specifies a name for a user-defined type that should be generated into the .java file where the compiler would have generated a name derived from the ASN.1 input.

When specified globally, these directives have an absolute reference that refers to the ASN.1 component that is renamed in the generated file, and a new name either with or without double quotation marks. When specified locally, there is no absolute reference, but a new name (in double quotation marks) must be provided. In both cases, newname must be a valid Java name.

Default Behavior

By default, names are derived from the ASN.1 definition.

Example

ASN.1 Java
--<OSS.TYPENAME Module.RenamedStr "asciiStr">--

Module DEFINITIONS ::= BEGIN
  RenamedStruct    ::= [4] SEQUENCE {
     lunchPrepared   BOOLEAN --<FIELDNAME "lunchReady">--,
     cost            REAL
     }

  DefaultNameStr   ::= [5] IA5String
  RenamedStr       ::= [6] IA5String
END
public class RenamedStruct extends Sequence {
  ...
  // Methods for field "lunchReady"
  public boolean getLunchReady()
  {
      return ((BOOLEAN)mComponents[0]).booleanValue();
  }

  public void setLunchReady(boolean lunchReady)
  {
      ((BOOLEAN)mComponents[0]).setValue(lunchReady);
  }

}

public class DefaultNameStr extends IA5String {

}

public class asciiStr extends IA5String {

}

Remarks

Make sure the names you specify conform to the Java language conventions. For example, the asciiStr class name in the above example is specified to start with a lowercase letter, which is not encouraged in Java.

The effect of the directives is absolute; the ASN.1 compiler for Java will not try to change them, even if they are invalid. If the specified name conflicts with another one that was derived from an ASN.1 identifier or type reference, the compiler for Java will modify the derived name.

See Also

ASN1.Nickname


--<OSS.FUNCNAME [absoluteReference] ["]FunctionName["]>--

Specifies a name for a class that checks user-defined constraints. By default, the name of the Java class that the encoder/decoder will call before encoding and after decoding a user-constrained value is derived from the name of the type reference or identifier with which the constraint is associated. For example:

Y ::= INTEGER (CONSTRAINED BY { -- Must be a power of 2 -- })

The default constraint-checking class name is Y_fn.

When specified globally, the OSS.FUNCNAME directive takes an absolute reference to a type that has a user-defined constraint. FunctionName is the name to be used for the constraint-checking class. Note that when using OSS.FUNCNAME globally, it must be specified before the type to which it applies.

When specified locally, the OSS.FUNCNAME directive does not take an absolute reference and affects only the type in whose user-defined constraint it is placed.

Example

ASN.1 Java
  --<OSS.FUNCNAME Module.DataCard.c "checkForPowerOf2">--
  
Module DEFINITIONS ::= BEGIN
  DataCard ::= SEQUENCE {
     a BOOLEAN,
     b BOOLEAN,
     c INTEGER (CONSTRAINED BY { -- Must be a power of 2 --})
   }
END
public class DataCard extends Sequence {
     ...
}

The user will provide the CheckForThePowerOf2 class that will be used to check user-constraint, imposed on field c:

public class CheckForPowerOf2 implements ExternalChecker {
     …
     public boolean isValid(AbstractData value)
                                throws UserValidateFailedException
     {
          INTEGER number = (INTEGER)value;
          long n = number.longValue();
          int nbits = 0;

          if (n < 0)
               n = --n;

          while (n != 0) {
               if ((n & 1) != 0)
                    ++nbits;
               if (nbits > 1)
                    throw new UserValidateFailedException
                                                 ("Not a power of 2");
               n >>= 1;
     }

     return true;
}

NOTE: User-defined constraint-checking functions are only generated if the -userConstraints compiler option is specified.

See Also

ASN1.ConstraintFunction


--<OSS.INCLUDES "configFilename"[, "configFilename"...]>--

Specifies the name of one or more configuration files that you can add to the ASN.1 input. This is useful when defining different sets of compiler directives that can be included or excluded, depending on the application.

Example

In the following example, directives from file1.cfg and file2.cgf are inserted at the location of the OSS.INCLUDES directive:

--<OSS.INCLUDES "file1.cfg", "file2.cfg" >--
Sample1 DEFINITIONS EXPLICIT TAGS ::= BEGIN
     Name1 ::= INTEGER
     Name2 ::= BOOLEAN
END

Remarks

The OSS.INCLUDES directive can be specified only globally and must have at least one configuration filename as an operand. The configuration file must contain global directives.

Directives obtained by specifying the OSS.INCLUDES directive can be used only in a single ASN.1 module definition and override any conflicting directives in the asn1dflt file.

The Java source file will not mention the OSS.INCLUDES directive, but it will be generated as if the directives in the configuration files were declared at the instance of the OSS.INCLUDES directive.

By default, no configuration files are inserted into the ASN.1 input.


--<OSS.NoConstrain [absoluteReference]>--

Identifies types or components for which constraint checking should be disabled. The directive disables all constraint checking for the type, including checking of the default permitted alphabet for CHARACTER STRING types. For ENUMERATED types, it disables the subtype constraints, but it does not disable checking for valid enumerators.

Example

When the -constraint option is not specified, all constraints for type S are disabled. When the -userConstraints option is specified, constraint checking of user-constraints is enabled.

--<OSS.NoConstrain Module.S>--
 
Module DEFINITIONS ::= BEGIN
   S ::= INTEGER (1..10 | 300) (CONSTRAINED BY { })
END

In the following example, PrintableString abc is passed at run time and constraint violation errors are not issued. Although the OSS.NoConstrain directive is not explicitly applied to the ShortABCs type, constraint checking for this type is disabled because the type is composed of types marked with OSS.NoConstrain.

--<OSS.NoConstrain Mod.ABConly>--
--<OSS.NoConstrain Mod.ShortString>--
--<OSS.PDU>--
 
Mod DEFINITIONS ::= BEGIN
   ABConly ::= PrintableString (FROM ("A" | "B" | "C"))
   abc ABConly ::= "The wrong string"
    
   ShortString ::= PrintableString (SIZE(1 | 3 ))
   shStr ShortString ::= "The long string"
    
   ShortABCs ::= PrintableString (ABConly INTERSECTION ShortString)
   shABC ShortABCs ::= "ABCDD"
END

In the following example, although the -constraint option is specified, the automatic encoding and decoding is not performed at run time:

--<OSS.NoConstrain ContConstr.O>--
  
ContConstr DEFINITIONS::= BEGIN
   O ::= OCTET STRING (CONTAINING INTEGER)
END

Remarks

The OSS.NoConstrain directive cannot be specified locally. Also, it has no effect if -constraint is explicitly specified, except when it is applied to a BIT STRING or OCTET STRING type constrained by contents constraint. In this case, it disables automatic encoding and decoding of the contained type.

If the -userConstraints option is used with the OSS.NoConstrain directive, all constraints except for user-constraints are disabled for the specified type or field.

By default, constraint checking is enabled.

See Also


--<OSS.NODEFAULTVALUE [absoluteReference]>--

Informs the ASN.1 compiler to treat items marked with the ASN.1 DEFAULT keyword as items marked with the OPTIONAL keyword.

When specified globally, the absoluteReference operand refers to an ASN.1 type marked as DEFAULT. When specified globally without an operand, the OSS.NODEFAULTVALUE directive affects all types marked as DEFAULT.

When specified locally, the OSS.NODEFAULTVALUE directive takes no operands and affects only the type next to which it is placed.

Example

--<OSS.NODEFAULTVALUE Module.DataCard.a>--
  
Module DEFINITIONS ::= BEGIN
    DataCard ::= SEQUENCE {
      a [0] BOOLEAN DEFAULT TRUE,
      b [1] BOOLEAN DEFAULT TRUE,
      c [2] BOOLEAN
     }
END

--<OSS.OBJECTID>-- | --<OSS.ENCODED>--

Allows the compiler to represent OBJECT IDENTIFIER types as structures of a given size. The Java representation of OBJECT IDENTIFIER types is not limited to any particular size, therefore this directive will have no effect on the code generated for OBJECT IDENTIFIER types, but it will be possible to create values of a size specified in the directive.


--<OSS.PACKAGE absoluteReference "package_name">--

By default, all Java class definitions that correspond to a single ASN.1 module are generated into the <project_name>.<module_name> package. For example, if the project name is project, the Java files generated for the ASN.1 module Module have the following first statement:

package project.module;

The .java files are placed into the module subdirectory of the project directory. You can use the OSS.PACKAGE directive to specify a different output package name for the module. This directive has the following format:

--<OSS.PACKAGE absoluteReference "package_name">--

absoluteReference refers to an ASN.1 module to which the directive is applied.

package_name is the name of a Java package that contains the Java class definitions generated for absoluteReference.

Example

The following PACKAGE directive changes the default package name for the module Module to foo.bar.module.

--<OSS.PACKAGE Module "foo.bar.module">--

The .java files that the compiler generates for the definitions within Module contain the following package statement:

package foo.bar.module;

The .java files are placed into the module subdirectory within the bar subdirectory within the foo directory. The location of the top-level directory is determined by the -path command-line parameter that specifies the default current working directory.


--<OSS.PDU [absoluteReference]>--
--<OSS.NOPDU [absoluteReference]>--

Instructs the compiler to send or receive ASN.1 types as protocol data units.

When specified globally, the OSS.PDU | OSS.NOPDU directive can take an absolute reference that specifies which component of the ASN.1 syntax is intended. If specified globally without an absolute reference, the OSS.PDU | OSS.NOPDU directive sets a default for all types within their scope.

When specified locally, these directives do not take any arguments and only affect the type next to which they are placed.

Example

ASN.1 Java
--<OSS.PDU Module.NameString>--

Module DEFINITIONS ::= BEGIN
     MiddleAgeClubCard ::= SEQUENCE {
             name            NameString,
             phoneNumber     PhoneString,
             age             AgeInt
     }
     NameString ::=  IA5String (SIZE (40))
     PhoneString ::= NumericString (SIZE (15)) --<PDU>--
     AgeInt ::= INTEGER (45..54)
END
MiddleAgeClubCard
NameString
PhoneString

Note that AgeInt is not a PDU, because it is referenced in the SEQUENCE MiddleAgeClub and does not have a PDU directive applied.

Remarks

The OSS.PDU and ASN1.PDU directives can be applied to types included in root modules. To treat all input modules as root modules, either specify the -root compiler option or include the global OSS.ROOT directive in your ASN.1 specification.

See Also


--<OSS.ROOT [moduleName[{objectIdentifier}] ...]>--

Identifies ASN.1 modules that are used as root modules. In a root module, all unreferenced types are considered PDUs. In addition, the scope of non-root modules is to supply external references to root modules. By default, the last ASN.1 input file specified at the command line contains the root module.

Example

--<OSS.ROOT DirectorySystemProtocol{joint-iso-ccitt ds(5) modules(1) dsp(12)}>--

Remarks

The OSS.ROOT directive can only be used globally and can take one or more operands. The operand can be a module reference (moduleName) or a module reference followed by a built-in objectIdentifier value. If no operands are provided, all input modules are considered root modules.

See Also


--<OSS.SampleCode [pdus|values] [absoluteReference]>--
--<OSS.SampleCode parameter [absoluteReference]>--
--<OSS.NoSampleCode [absoluteReference]>--

Instructs the compiler whether to generate a sample application containing sample code for PDU types and value references identified by it.

The directive accepts two types of syntax; the first allows you to select those PDU types and value references that should be included in the sample code when generating the sample application. The second allows you to control how the compiler creates sample values for some ASN.1 types.

The pdus or values parameters are only accepted when the directive is specified globally and applied to an ASN.1 module or to all ASN.1 input (the absolute reference is absent).

When the OSS.SampleCode directive is applied to all ASN.1 input, it has the same effect as the -sampleCode command-line option with the same parameter.

parameter is mandatory, and can be either count:number ( number is a non-negative integer) or selection.

When parameter is set to count: number, the directive specifies the default number of items to be used by the compiler when it automatically creates values for SEQUENCE OF or SET OF types for use in the sample code. If OSS.SampleCode has an unspecified count parameter for a specific SEQUENCE OF or SET OF type, then the compiler uses 1 as the default number of SEQUENCE OF or SET OF items.

When parameter is set to selection, the directive refers to a CHOICE alternative. If OSS.SampleCode has an unspecified selection parameter for a specific CHOICE type, then the compiler selects the first CHOICE alternative by default. If there are several such directives assigned to different alternatives of the same CHOICE type, then the compiler creates as many sample values as needed to cover all selected alternatives.

Example

The compiler generates sample code for all values, except for those defined in Module2:

--<OSS.ROOT>--
--<OSS.SampleCode values>--
--<OSS.NoSampleCode Module2>--
  
Module1 DEFINITIONS ::= BEGIN
   A ::= OCTET STRING
   value1 A ::= '00'H
END
  
Module2 DEFINITIONS ::= BEGIN
   B ::= INTEGER
   value2 B ::= 1
END

The following example shows how to customize generation of sample values:

--<OSS.SampleCode pdus Module>--
--<OSS.SampleCode selection Module.S.b>--
  
Module DEFINITIONS ::= BEGIN
   S ::= CHOICE {
      a IA5String,
      b SEQUENCE --<SampleCode count:3>-- OF INTEGER
   }
END

The compiler creates the sample application containing test code for the following value:

samplevalue1-S S ::= b : {
    0,
    0,
    0
}

Remarks

Compared to the –sampleCode command-line option, the OSS.SampleCode directive provides more control over the sample code that is created.

You can use the OSS.SampleCode directive more than once in the ASN.1 input.

The OSS.NoSampleCode directive can be used to exclude PDUs or values from sample applications.

Applying OSS.SampleCode results in the same sample code as when using the –sampleCode command-line option.

The –sampleCode | –noSampleCode options overrides the OSS.SampleCode | OSS.NoSampleCode directive.

See Also

-sampleCode | -noSampleCode


--<OSS.Stylesheet [<absoluteReference> ["<OptionalNewName>.xsl"]]>--

Instructs the ASN.1 compiler to generate a separate XML stylesheet with your filename for any particular PDU. This directive gives you more control over the default XML stylesheets generated by the ASN.1 compiler.

The absolute reference refers to any ASN.1 type reference in the input ASN.1 syntax for which a separate XML Stylesheet is generated. OptionalNewName is an optional argument that allows you to specify a new full pathname for the XSL that will be generated.

When absoluteReference is not specified, a stylesheet is generated for every PDU in the input syntax.

Remarks

The OSS.Stylesheet has two forms:

  • --<OSS.Stylesheet>--
  • --<OSS.Stylesheet Module.Type ["filename"]>--

Each form of the directive specifies that an XSL file is generated for:

  • all PDUs in the ASN.1 notation.
  • a particular PDU.

If filename is omitted, then the XSL file name defaults to the type name, with the .xsl suffix appended.

If filename is present, it can be absolute or relative. If filename is absolute (for example, it starts with a slash ("/") on a Unix system) then all directories in its pathname should exist. Other (non-absolute) filenames are relative to the type's module package directory, and all subdirectories in the relative pathnames will be created as needed.

NOTE: Do not specify the same filename in several directives, because the file will be overwritten and its contents will be unpredictable.

The optional filename parameter in the directive can take the following forms:

  • A filename, such as MyType.xsl. The MyType.xsl file is generated in the type's module package directory.
  • A relative pathname, like xsls/MyType.xsl. The pathname is treated relatively starting from the type's module package directory. For example, if the project directory is myproject, the type's package directory is mymodule, then the MyType.xsl file is generated in the myprojects/mymodule/xsls directory. No check for possible name conflicts is performed. You must ensure that there are no name conflicts.
  • An absolute pathname, such as /home/user/xsls/MyType.xsl. The file is generated in the absolute path specified. In this case, all subdirectories in the pathname must exist; the compiler will not attempt to create the directories in the absolute pathname.

The OSS.Stylesheet directive and the -xsl option have no effect if the -xer option is not specified.

See Also


--<OSS.SUPPRESS messageID[, messageID]...>--

The compiler does not print specific informatory and warning messages when this directive is used. OSS.SUPPRESS is especially useful when compiling abstract syntaxes that contain specifications that are not fully compliant with the ASN.1 standard.

Remarks

By default, informatory and warning messages are not suppressed.

The OSS.SUPPRESS directive can be used only globally and takes one or more operands (messageID) specifying which message needs to be suppressed. This messageID can be either the full message identifier or just the numeric part of the message number.

Example

Message A0178W indicates that the first digit of a number in a module definition should be non-zero.

--<OSS.SUPPRESS A0178W>--

Sample DEFINITIONS ::= BEGIN
     Age ::= INTEGER
     legalAge Age ::= 021
END

Note that the OSS.SUPPRESS directive does not affect the Java-representation. Its only effect is that the following warning message is not generated for the above syntax:

A0178W: The first digit should not be zero unless the number is a single digit.
        legalAge Age ::= 021

See Also


--<OSS.UNBOUNDED>--

Specifies the representation of CHARACTER STRING, BIT STRING, and OCTET STRING types.

Except for UTF8String, UNBOUNDED is the default representation in Java and therefore this directive has no effect unless it is used to override a global directive. For UTF8String where the default is the BMPSTRING representation (Unicode), UNBOUNDED has the effect of forcing representation with one byte per character rather than with the default of two bytes per character. Using the table below as an example, you will notice that the UNBOUNDED directive only affects the representation of UTF8String.

Types Default class representation UNBOUNDED representation
PrintableString
PrintableString PrintableString
UTF8String
UTF8String16 UTF8String
UTF8String  --<NOCOPY>--  
HugeUTF8String16 HugeUTF8String
BIT STRING
BitString BitString
OCTET STRING
OctetString OctetString
SEQUENCE OF
SequenceOf SequenceOf
SET OF
SetOf SetOf

--<OSS.UNIVERSALSTRING [absoluteReference]>--

Instructs the compiler to represent a UTF8String type as a com.oss.asn1.UTF8String32 class that stores a string value as an array of four-byte characters (UCS-4), which is the same representation as the one for the UniversalString type. By default, the UTF8String is represented with the com.oss.asn1.UTF8String16 class that stores a UTF8String value as a regular Java string.

When specified globally, the OSS.UNIVERSALSTRING directive takes an absolute reference that refers to certain UTF8String in the ASN.1 syntax. When specified locally, this directive takes no operands and only affects the type next to which it is placed.

Example

ASN.1 Java
--<OSS.UNIVERSALSTRING Module.FourByteGlobal>--

Module DEFINITIONS ::= BEGIN
  TwoByteDefault   ::= [1] UTF8String
  TwoByteLocal     ::= [2] UTF8String --<BMPSTRING>--
  FourByteGlobal   ::= [3] UTF8String
  FourByteLocal    ::= [4] UTF8String --<UNIVERSALSTRING>--
END
public class TwoByteDefault extends UTF8String16 {  ...
public class TwoByteLocal extends UTF8String16 {  ...
public class FourByteGlobal extends UTF8String32 {  ...
public class FourByteLocal extends UTF8String32 {  ...

See Also

OSS.BMPSTRING


--<OSS.UserClass absoluteReference "[[.][packagename.]]classname">--

Allows you to use user-defined Java classes instead of compiler-generated or predefined universal classes that would have otherwise been used by default. User-defined classes must extend the compiler-generated classes or predefined universal classes they are replacing.

The absoluteReference refers to an ASN.1 type to which the directive is applied. The type can be an ASN.1 type reference or a component of a structured type. If it is a type reference, absoluteReference has the form: Module.Type. If the type is a component type, absoluteReference has the form: Module.Type.field.

classname is the name of the user-defined Java class.

The fully qualified name of the user-defined class depends on the presence of an optional dot (".") and an optional packagename. If packagename and the dot (".") are omitted, the user-defined class is placed into the same package as the corresponding compiler-generated or universal class. If the name starts with a dot ("."), the user-defined class is placed into a package under the project package and has a fully qualified name, projectname.packagename.classname. If the dot (".") is not present, the user-defined class can be placed in any package outside the project package.

If the OSS.UserClass directive is applied to a type for which the compiler generates a Java class, the compiler-generated class is declared abstract.

Example

--<OSS.UserClass Module.Type "UserClass">--

Module DEFINITIONS ::= BEGIN
     Type ::= INTEGER
     OtherType ::= Type
END

For the above notation, the ASN.1 compiler-generates class Type is abstract. You need to provide the user-defined class UserClass which extends Type in the package project.module. Compiler-generated classes that extend Type will continue extending Type and not UserClass.

package project.module;

public abstract class Type extends INTEGER {  ... }
public class OtherType extends Type {  ... }

The compiler references the specified user-defined class wherever it would otherwise reference the compiler-generated or universal class.

--<OSS.UserClass Tortoise.Length "Turtle.Size">--

Tortoise DEFINITIONS ::= BEGIN
   Length ::= INTEGER
   Description ::= SEQUENCE {
                  a Length
                  }
   value Description ::= { a 123 }
END

For the above notation, the compiler will replace references to Length with references to Size. You need to provide the user-defined class Size which extends Length in the package Turtle.

package project.tortoise;
abstract public class Length extends INTEGER {  ... }
public class Description extends Sequence {
    public Description(Turtle.Size a) {  ... }
    public Turtle.Size getA() {  ... }
    public void setA(Turtle.Size a) {  ... }
    ...
}

public static Description value= new Description(new turtle.Size(123));

Remarks

The OSS.UserClass directive cannot be applied to the ENUMERATED type because the classes which the compiler generates for ENUMERATED must not be extended.

The OSS.UserClass directive should be used with caution. Make sure you do not override a non-final method defined in the compiler-generated or universal class with a user-defined class. This could cause errors at runtime.

The user-defined class should provide the same set of constructors as its base class. Failing to do so could cause Java compile-time errors. The user-defined class should not declare its default constructor as private, otherwise the runtime decode() method would fail due to an inability to create UserClass objects.

Make sure you do not omit packagename when applying the UserClass directive to an instance of an ASN.1 built-in type. If a starting dot (".") or a packagename is not present, and the directive is applied to an ASN.1 built-in type, the user-defined class should be placed into the com.oss.asn1 package; however, this is not recommended, as it can cause name conflicts.

To override the method used to print values of the ASN.1 type to which this directive applies, the user-defined class should implement the Printable interface.

See Also

Printable


--<OSS.VALUE absoluteReference>--
--<OSS.NOVALUE absoluteReference>--

Specifies whether each ASN.1 value references a corresponding Java-initialized variable, and must be generated in the Java module class file. The presence or absence of the initialized variables in the compiler output is globally controlled by the -valueRefs | -noValueRefs command-line option while the directives apply to individual value references. By default, the compiler uses -valueRefs, therefore value references are generated. To suppress the -valueRefs command-line option for individual values, use the OSS.NOVALUE directive.

When specified globally, these directives can take an absolute reference to any ASN.1 user-defined type that is specified in a value reference. When specified globally without arguments, these directives set a default for all value references within their scope.

When specified locally, the OSS.VALUE | OSS.NOVALUE directives does not take any arguments and affects only the value reference next to which they are placed.

Example

The following ASN.1 notation demonstrates the local and global use of the OSS.VALUE and OSS.NOVALUE directives (note that the local OSS.VALUE directive overrides the global OSS.NOVALUE directive):

ASN.1 Java
--<OSS.NOVALUE Module.IdInt>--

Module DEFINITIONS ::= BEGIN
     ASCIIStr                     ::= IA5String
     name ASCIIStr                ::= "John"
     age INTEGER --<NOVALUE>--    ::= 57
     IdInt                        ::= INTEGER
     idNumAbsent IdInt --<VALUE>--::= 767543
     idNumPresent IdInt           ::= 354876
END
public abstract class Module extends ASN1Module {

// Value references
public static final ASCIIStr name = new ASCIIStr("John");
public static final idInt idNumAbsent = new IdInt(767543);
}

Note that the age value is absent due to a local --<NOVALUE>--. The idNumAbsent is present because the local --<VALUE>-- overrides the global --<OSS.NOVALUE>-- directive.


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.