TOP

ASN.1/C# Compiler Directives

Applies to: ASN.1/C# 5.0

The ASN.1/C# 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 override compiler options. They are case-sensitive and have one of the following formats:

--<OSS.Directive [reference] [Operands]>--
--<ASN1.Directive [reference] [Operands]>--

reference can be either a module, a type or a field, a file, depending on the directive.

Directives appear as comments to compilers that do not support them.

Example

--<OSS.Nickname MyZoo.VeryRareSpeciesOfMonkey MyMonkey>--

NOTE: The order in which directives appear is meaningful. Directives (including directive files) must precede the ASN.1 modules they are applied to. If contradictory directives are specified, the last one takes precedence.

Directive Types

There are three types of compiler directives:

  • Standard directives
  • OSS-specific directives
  • OSS-specific legacy-style directives
Standard OSS Legacy
Syntax
--<ASN1.directive...>--
--<OSS.directive... >--
--<directive...>--
Usage General usage in the industry. Unique to the OSS ASN.1 Tools. Everywhere, except in-line (next to an item). Inline usage is replaced with the ability to reference a particular item. Historically used as in-line directives. OSS directives at a module or global level are a better alternative.
Use the -genDirectives compiler option to save legacy directives into a .gen file to be used outside of the ASN.1 module.
Example
--<ASN1.WorkingSet Mod>--
--<OSS.DECIMAL Mod.TypeX>--
A ::= [1] REAL --<DOUBLE>--

If you use implementation-specific directives, note that the OSS ASN.1 compiler ignores them (for example: --<HP., --<TCSI. etc.), and issues warning messages during compilation.

When you have different scopes, local directives take precedence. The scopes can be:

Local
Directives are specified in-line (not recommended).
Example:
A ::= [1] REAL --<DOUBLE>--
Directives reference a specific item (recommended).
Example:
--<OSS.LONG MyModule.MyName>--
Module
Directives are specified at the module level, before BEGIN, and they do not reference any specific item.
Example:
ModuleName DEFINITIONS --<OSS.LONG>-- ::= BEGIN ...
Global
Directives are specified outside modules, usually in a directives file, and they do not reference any specific item.
Example:
--<OSS.LONG>--
ModuleName DEFINITIONS ::= BEGIN ...

Absolute References

An absolute reference uniquely specifies one or more components in ASN.1 syntax. 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 dot ("."). A component of the outermost structure can be listed next. If the desired component is placed within a nested structure, a dot is added after the name of the containing structure, and then the desired component is listed.

To specify an ASN.1 component, you can:

  • Use the component identifier.
  • Use an asterisk ("*") to specify all rows in SEQUENCE OF and SET OF arrays.
  • Use an INTEGER index to specify which element is intended in a SEQUENCE, SET, or CHOICE.
  • Use a dollar sign ("$") followed by an index number to reference a particular CONSTRAINED BY clause.
  • Use two dollar signs ("$$") followed by an index number to reference a particular WITH COMPONENT or WITH COMPONENTS 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 or MyMod.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, 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.

The following table contains examples of using absoluteReference:

ASN.1 module 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

This documentation applies to the OSS® ASN.1 Tools for C# release 5.0 and later.

Copyright © 2020 OSS Nokalva, Inc. All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means electronic, mechanical, photocopying, recording or otherwise, without the prior permission of OSS Nokalva, Inc.
Every distributed copy of the OSS® ASN.1 Tools for C# is associated with a specific license and related unique license number. That license determines, among other things, what functions of the OSS ASN.1 Tools for C# are available to you.