ASN.1/Java Compiler Directives

The ASN.1/Java compiler directives enable you to control the compiler output. They can be added to the ASN.1 schema files or can be included in a separate directive file.

Index

The following table contains compiler directives listed by category. Note that a directive may belong to more than one category. Use the check boxes to display a particular group of directives: basic, advanced, or deprecated.

Format

Compiler directives are case-sensitive and have the following format:

 --<[prefix.]Directive [Operand(s)]>--

Directives appear as comments to compilers that do not support them. The following examples illustrate three equivalent ways to specify directives:

  --<OSS.UNBOUNDED>-- --<OSS.ROOT Module1>--

  --<OSS.UNBOUNDED>--
  --<OSS.ROOT Module1>--

  --<OSS.UNBOUNDED>--
  --<OSS.ROOT
  --Module1>--

When you specify contradictory directives, the last one takes precedence. The two examples below achieve the same effect:

 <OSS.UNBOUNDED>     <OSS.BMPSTRING>  
 <OSS.BMPSTRING>

If a directive accepts one or more operands, they are listed after the name of the directive. Multiple operands are separated by commas:

--<OSS.ROOT Module1, Module2, Module3>--

Directives typically accept directiveOperand(s) consisting of one or more tokens used to configure the named directive as outlined on the following pages. Note that the presence of directiveOperand(s) is mandatory for some directives, but optional for others.

Types

There are three types of compiler directives:

• Standard directives
• OSS-specific directives
• OSS-specific legacy-style directives

--<ASN1.directive...>--

--<OSS.directive... >--

--<directive...>--

--<ASN1.WorkingSet Mod>--

--<OSS.FLOAT Mod.TypeX>--

A ::= [1] INTEGER  --<PDU>--  --<HUGE>--
A ::= [1] INTEGER  --<PDU | HUGE >--

OSS-specific directives take precedence over legacy ones. In the following example, the legacy directive <TYPENAME "Acme"> is ignored.

--<OSS.TYPENAME Sample.Name OSS>--

Sample DEFINITIONS EXPLICIT TAGS ::= BEGIN
     Name ::= [1] OBJECT IDENTIFIER --<TYPENAME "Acme">--
END

Likewise, standard directives take precedence over legacy directives.

--<ASN1.Nickname Module.Int ASN1_Nicknamed_Int>--

Module DEFINITIONS ::= BEGIN
     Int ::= INTEGER --<TYPENAME "OSS_Specific_New_Name">--
END

In the example above, the TYPENAME renaming mechanism is ignored and the following is generated in the java file:

public class ASN1_Nicknamed_Int extends INTEGER {
     ...
}

Local OSS-specific new-style directives take precedence over global OSS-specific new-style directives:

--<OSS.MIXED>--

Module DEFINITIONS ::= BEGIN
     A ::= [1] REAL --<DECIMAL>--
     B ::= [2] REAL
     C ::= [3] REAL
END

In the notation above, class A will extend the DecimalReal class while B and C will extend the MixedReal class.

Certain standard directives and their operands have no effect on the compiler-generated output files. However, they can be specified in the ASN.1 input file. Each time the OSS ASN.1 compiler parses a directive which has no effect, the compiler prints one of the following two informatory messages:

• If the -genDirectives command- line option was not specified:

  C0492I:	There are unused standard directives.  Specify the  genDirectives command line option, then look at all lines containing "WARNING:" in the generated .gen file.

• If -genDirectives was specified:

  C0064I:	There are unused standard or OSS-specific directives. Look at lines containing "WARNING:" in the .gen file.

In the second case, the compiler prints out a commented informatory warning in the .gen file:

--<ASN1.ConstraintFunction Module>-- -- WARNING: could not use the -- directive

Absolute References

An absolute reference uniquely specifies one or more components in ASN.1 syntax. The notation is similar to that used by many programming languages to access components within named structures and records. The outermost structure is listed first using its identifier followed by a dot ("."). A component of the outermost structure (which could also be a structure) can be listed next. When the desired component is within a nested structure, a dot is added after the name of the containing structure and then the desired component is listed.

You can specify ASN.1 components using

• A component's identifier.
• An asterisk ("*") to select all rows in a SEQUENCE OF or SET OF array.
• An INTEGER index to designate an element in a SEQUENCE, SET, or CHOICE.
• A dollar sign ("$") followed by a number index to reference a particular CONSTRAINED BY clause.
• Two dollar signs ("$$") followed by an index number to reference a particular WITH COMPONENT or WITH COMPONENTS clause.

Example

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

In the ASN.1 definition above, the absolute reference for the

• Entire module is MyMod
• SET OF structure is MyMod.Comp1
• SEQUENCE series is MyMod.Comp1.*
• INTEGER is MyMod.Comp1.*.a or MyMod.Comp1.*.1
• OCTET STRING is MyMod.Comp1.*.b or MyMod.Comp1.*.2
• CHOICE is MyMod.Comp1.*.c or MyMod.Comp1.*.3
• BOOLEAN is MyMod.Comp1.*.c.nest1 or MyMod.Comp1.*.c.1
• BIT STRING is MyMod.Comp1.*.c.nest2 or MyMod.Comp1.*.c.2
• IA5String is MyMod.Comp2

To access ASN.1 types located within CONSTRAINED BY clauses, you must 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 which 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.

To access ASN.1 types located within WITH COMPONENT or WITH COMPONENTS clauses, you must specify two dollar signs ("$$") followed by a number index indicating a particular WITH COMPONENT or WITH COMPONENTS.

The following example illustrates CONSTRAINED BY constraints applied within WITH COMPONENTS clauses:

--<OSS.FIELDNAME Mod.Type.$$1.data.$1:1.alt "my_alt">--
--<OSS.FIELDNAME Mod.Type.$$2.data.$1:1.fld "my_fld">--

Mod DEFINITIONS ::= BEGIN
Type ::= SEQUENCE {data OCTET STRING }
	 (WITH COMPONENTS{..., data (CONSTRAINED BY {CHOICE {alt BOOLEAN}})})
	 (WITH COMPONENTS{..., data (CONSTRAINED BY {SEQUENCE {fld INTEGER OPTIONAL}})})
END

In the above absolute reference, $$1.data.$1:1 refers to the type within the CONSTRAINED BY of the first WITH COMPONENTS clause. The first directive changes the name of the "alt" field to "my_alt". $$2.data.$1:1 refers to the type within the CONSTRAINED BY of the second WITH COMPONENTS clause. The second directive changes the name of the "fld" field to "my_fld".

The following example illustrates a CONTAINING constraint applied within WITH COMPONENTS clauses.

--<OSS.TYPENAME Mod.Type.$$1.bit.* "MyChoice">--
--<OSS.FIELDNAME Mod.Type.$$1.bit.*.alt "my_alt">--
--<OSS.FIELDNAME Mod.BaseType.other.fld "my_other_fld">--

Mod DEFINITIONS ::= BEGIN
BaseType ::= SEQUENCE {
	bit    BIT STRING OPTIONAL,
	other  SEQUENCE {
		fld INTEGER OPTIONAL
	} OPTIONAL
} 
Type ::= BaseType 
	(WITH COMPONENTS {..., bit 
		(CONTAINING 
			CHOICE {alt INTEGER}) }) 
END

In the first absolute reference, $$1.bit.* refers to the CHOICE type within the CONTAINING clause of the first WITH COMPONENTS clause applied to Type. $$1.bit.*.alt refers to the field of the CHOICE type. Note that you can use the "$$ <num> " syntax only for components whose names are explicitly included in the WITH COMPONENTS syntax (that is, for the bit field in the above example). The absolute references of the fields within the original type, BaseType, apply to the names within the original type and also to the ones within all the types that are created when using contents constraints within WITH COMPONENTS. Therefore, to change the names that are not included in the WITH COMPONENTS clause of the derived type, Type, you would need to change the names of the original type, BaseType.

Example

The following table contains examples of using absoluteReference:

MyMod DEFINITIONS ::= BEGIN
  Comp1 ::= SET OF SEQUENCE {
    a INTEGER,
    b OCTET STRING OPTIONAL,
    c CHOICE {
      nest1 BOOLEAN,
      nest2 BIT STRING
    }
  }
  Comp2 ::= BOOLEAN 
     (CONSTRAINED BY {--Just a comment--})
     (CONSTRAINED BY {
        SET {con1 NULL, con2 REAL}})
END 

referencing  entire module: MyMod
referencing  SET OF: MyMod.Comp1
referencing  SEQUENCE series: MyMod.Comp1.*
referencing  b: MyMod.Comp1.*.b or MyMod.Comp1.*.2
referencing  nest1: MyMod.Comp1.*.c.nest1 or MyMod.Comp1.*.c.1
referencing  con1: MyMod.Comp2.$2.con1 

Mod DEFINITIONS ::= BEGIN
  C ::= BOOLEAN 
    (CONSTRAINED BY {})
       (CONSTRAINED BY {
          INTEGER, -- "1st" parameter
          IA5String,
          CHOICE {
            f REAL (CONSTRAINED BY
               {SET {e NULL}})
          } -- "3rd" parameter
     })
END

referencing e: Mod.C.$2:3.f.$1.e

Mod DEFINITIONS ::= BEGIN
   Type ::= SEQUENCE {data OCTET STRING }
      (WITH COMPONENTS{..., data    -- "1st" inner subtype
         (CONSTRAINED BY { 
              CHOICE {
                  alt BOOLEAN
              }
      })})
      ((WITH COMPONENTS{..., data   -- "2nd" inner subtype
         (CONSTRAINED BY { 
              SEQUENCE {
                  fld1 INTEGER OPTIONAL
              }
      })}) |
      (WITH COMPONENTS{..., data    -- "3d" inner subtype
         (CONSTRAINED BY { 
              SEQUENCE OF SET {
                  fld2 INTEGER OPTIONAL
              }
      })}))
END

referencing alt: Mod.Type.$$1.data.$1:1.alt





referencing fld1: Mod.Type.$$2.data.$1:1.fld1





referencing fld2: Mod.Type.$$3.data.$1:1.*.fld2

Warning

An absolute reference cannot be extended inside of another type reference. For example, in the following ASN.1 definition

MyMod DEFINITIONS ::= BEGIN
     Foo ::= SEQUENCE {
             foo INTEGER
     }
     Bar ::= SEQUENCE {
             bar Foo
     }
END

the absolute reference for the INTEGER is MyMod.Foo.foo, not MyMod.Bar.bar.foo.