TOP

ASN-1Step Directives

Applies to: ASN-1Step 10.5

Directives, similar to command-line options, control ASN-1Step output. Unlike command-line options, directives can be added to the ASN.1 schema files.

Format

Every directive begins with "--<" and ends with ">--". All directives are case-sensitive and have the following format:

  --<[prefix.]directive [absoluteReference] [operand1[, operand2]...[, operandx]]>--

Where

  • prefix is the directive type.
  • directive is the name of the directive.
  • absoluteReference specifies the ASN.1 item(s) the directive will be applied to.
  • operand1...operandx is one or more tokens used to configure the directive as outlined in the Directives Reference. Note that operands are mandatory for some directives and optional for others.

Directives at the Local, Module, or Global Level

Local

Directives are specified in-line (old method). Example:

A ::= [1] REAL --<DECIMAL>--

Directives reference a specific item (preferred method). Example:

--<OSS.DECIMAL MyModule.A>--

Module

Directives are specified at the module level, before BEGIN, and do not reference any specific item. Example:

MyModule DEFINITIONS --<OSS.DECIMAL>-- ::= BEGIN ...

Global

Directives are specified outside modules, usually in a directives file, and do not reference any specific item. Example:

--<OSS.DECIMAL>--
MyModule DEFINITIONS ::= BEGIN ...

Contradictory Directives

It is possible to specify contradictory directives, such as OSS.DEFINITE and OSS.INDEFINITE. If this occurs, the last directive specified is used and the previous ones are ignored.

Directive Types

ASN-1Step recognizes three types of directives: Standard, OSS-specific, and OSS-specific legacy-style.

Standard Directives

Syntax

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

Remarks

A standard directive can be placed anywhere in the ASN.1 syntax provided it appears before the referenced item. Standard directives usually have an ASN1 prefix.

Standard directives can also be written as OSS-specific directives with the OSS prefix instead of ASN1. For example,

--<ASN1.Version 2021 Module>--

is equivalent to:

--<OSS.Version 2021 Module>--

Example

--<ASN1.WorkingSet Module1, Module2, Module3>--

OSS-Specific Directives

Syntax

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

Remarks

OSS-specific directives are used in the ASN.1 input wherever spaces or tabs are allowed: locally, at the module-level, and globally. When used globally, specify the directives before the first module definition.

The OSS prefix should be present when the directive is being specified globally, even though its presence is not mandatory. Likewise, when an OSS-specific directive is used at the module-level, the OSS prefix is not required. However, directives specified at the local-level should not be prefixed with OSS.

The following OSS-specific directives can be used without absolute references and have the same effect as the corresponding legacy-style directives specified globally:

OSS.DECIMAL / OSS.DOUBLE / OSS.MIXED
OSS.DEFAULTVALUE / OSS.NODEFAULTVALUE
OSS.DEFINITE / OSS.INDEFINITE
OSS.EXTENSIBLE / OSS.INEXTENSIBLE
OSS.LONGLONG / OSS.HUGE
OSS.PDU / OSS.NOPDU

Example

--<OSS.DTD XModule.StringType>--

OSS-Specific Legacy-Style Directives

Syntax

--<directive...>--

Remarks

OSS-specific legacy-style directives are the same as non-legacy versions, except the OSS prefix is never used. Most of these directives cannot globally specify that a directive affects only particular type instances. Historically, they were used as inline directives.

These directives can have local, module, or global scope, depending on placement. When specified locally, multiple legacy-style directives can be specified together when separated by vertical bars ('|'). For example, the following two directive specifications are equivalent:

A ::= [1] REAL  --<PDU>--  --<DECIMAL>--
A ::= [1] REAL  --<PDU | DECIMAL>--

Example

A ::= [1] REAL --<DECIMAL>--

Precedence

OSS-specific directives take precedence over OSS-specific legacy-style directives.

Standard directives also take precedence over OSS-specific legacy-style directives.

Precedence is also affected by a directive's scope: local, module, or global. OSS-specific directives specified at the local level take precedence over those at the global level.

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.

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

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.

Applying Directives to Parameterized Types

When you apply a directive to a parameterized type definition, that directive is applied to every instance of the type. For example, when the OSS.PDU directive is applied to a parameterized type, all instances of this type are treated as PDUs. Likewise, when the ASN1.WorkingSet directive is applied to a parameterized type, all instances of the type are included in the working set.

Instances of Parameterized Types

Applying a directive to an instance of a parameterized type affects only that particular instance.

Example

--<OSS.Truncate Mod.S.f1 2>--
Mod DEFINITIONS ::= BEGIN
    Sof {Type} ::= SEQUENCE OF Type
    S ::= SET {
        f1 [2]Sof{INTEGER},
        f2 [3]Sof{BOOLEAN}
    }
    s S ::= {   f1 { 1, 2, 3},
                f2 {TRUE, FALSE, TRUE}}
END

Pass the notation above through ASN-1Step using

asn1step <filename> -per -test

and you will see that the third element of the f1 field is skipped during decoding, but all elements of the f2 field are decoded.

Types Used as Substitution Types

A directive cannot be applied to any of the following:

  • A type used as a substitution type in a parameterized type instance.
  • The fields of such a type.
  • A type that is a parameter in a parameterized type.

Example

These directives have no effect.

--<OSS.HUGE Test.T3.bt2.at1>--
--<OSS.PDU Test.T3.bt2>--
--<OSS.PDU Test.T2.bt2>--

Test DEFINITIONS ::= BEGIN
   T2 {X} ::= SEQUENCE {at2 BIT STRING, bt2 X OPTIONAL}
   T3 ::= T2 {T1}
   T1 ::= SET {at1 INTEGER, bt1 BOOLEAN}
END

If you change the type for bt2 to a "non-direct" reference to the X parameter (such as SET OF X), the OSS.PDU directives will succeed:

T2 {X} ::= SEQUENCE {at2 BIT STRING, bt2 SET OF X OPTIONAL}

Directives Index

Get detailed information about a directive by clicking on its name.

Option Description
ASN1.HugeInteger Sets a special representation for integers whose size is not supported by the operating system in use.
ASN1.PDU Specifies that one or more ASN.1 types should be treated as protocol data units.
ASN1.Version Specifies the year of the ASN.1 standard in use for a particular ASN.1 module.
ASN1.WorkingSet Identifies those parts of the ASN.1 input that are central to the application.
OSS.DECIMAL Causes the ASN.1 REAL type to be represented with a null-terminated character string.
OSS.DEFAULTVALUE Types with the DEFAULT tag use the specified default value when absent from the encoding.
OSS.DEFINITE Specifies that the definite length form should be used when encoding protocol data units (PDUs).
OSS.DTD Gives you greater control over the XML data type definitions that are produced by the ASN.1 compiler.
OSS.DOUBLE Causes the ASN.1 REAL type to be represented with a C double.
OSS.ENCODABLE Provides support to DER (Distinguished Encoding Rules) applications that encode encrypted signatures.
OSS.ExerNumericBoolean Instructs the E-XER encoder to produce numeric Boolean values (0 and 1) instead of textual values (true and false or their replacements).
OSS.EXTENSIBLE Enables decoder support for the rules of extensibility.
OSS.ExtensibleUseType Affects how unknown values of extensible CHOICE types with a final XER USE-TYPE encoding instruction are decoded. Each unknown value contains the xsi:type attribute with an unrecognized value.
OSS.GenOrderedValues Instructs ASN-1Step to generate ordered values for a type, identified by absolute reference, when the -generateMessages option is specified.
OSS.GenRandomValues Instructs ASN-1Step to generate random values for a type, identified by absolute reference, when the -generateMessages option is specified.
OSS.HUGE Sets a special representation for integers whose is size not supported by the operating system in use.
OSS.INDEFINITE Specifies that the indefinite length form should be used when encoding protocol data units (PDUs).
OSS.INEXTENSIBLE Disables decoder support for the rules of extensibility.
OSS.LONGLONG Causes the ASN.1 INTEGER type to be represented with a LONG_LONG on supported platforms.
OSS.MIXED Allows the ASN.1 REAL type to be represented with either a null-terminated character string or a C double.
OSS.NoConstrain Identifies those types or components for which constraint checking should be disabled.
OSS.NODEFAULTVALUE Instructs the ASN.1 compiler to treat DEFAULT components as if they were OPTIONAL components instead.
OSS.NOPDU Instructs the encoder/decoder not to treat an ASN.1 type as a protocol data unit.
OSS.PDU Instructs the encoder/decoder to treat an ASN.1 type as a protocol data unit.
OSS.ROOT Identifies the ASN.1 modules that are to be used as the root modules in which all unreferenced types are considered PDUs.
OSS.SelfCompleteWildcard Instructs the E-XER decoder to preserve wildcard contents in the decoded C value; allows checking of the digital signature of a wildcard after decoding.
OSS.Stylesheet Gives you greater control over the default XML stylesheets that are produced by the ASN.1 compiler.
OSS.SUPPRESS Disables printing of specific informatory and warning messages.
OSS.Truncate Instructs ASN-1Step to skip extra trailing elements in a SET OF or SEQUENCE OF type, which can speed up decoding of certain large PDUs.
OSS.USERFIELD Allows the generation of a locally defined user field that is of significance only to a particular application.

This documentation applies to release 10.5 and later of ASN-1Step®.

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