TOP

ASN-1Step Directives Reference

Applies to: ASN-1Step 8.2

ASN1.DeferDecoding

Defers the decoding of a particular component within a SEQUENCE, SET, or CHOICE structure. By default, all components of CHOICE, SET, or SEQUENCE are decoded with their containing type.

Format

--<ASN1.DeferDecoding absoluteReference>--

The encoding of the type that absoluteReference refers to will be skipped while decoding the PDU so errors in it will not reported.

Remarks

The ASN1.DeferDecoding directive

  • Only affects BER and DER. While this directive affects the behavior of the encoder/decoder, it has no effect on the actual encoding that is produced.
  • Cannot be used with PER or XER.
  • Cannot be applied to an ANY type or open type component.

Example

--<ASN1.DeferDecoding Module.Type.setComponent>--
Module DEFINITIONS ::= BEGIN
    Type ::= SET {
        setComponent INTEGER,
        b BOOLEAN
    }
END

Note that the type referred to by the absolute reference becomes a PDU. The following command:

asn1step filename -listPduIdentifiers

produces this output:

ASN1STEP: List of valid PDU numbers and associated PDU names:

       1.  Type
       2.  Type-setComponent-encodable

See Also

↩Directives Index


ASN1.HugeInteger

Sets a special representation for INTEGERs whose size is not supported by the operating system in use. By default, INTEGER types are represented as machine dependent 16-bit, 32-bit, or 64-bit numbers.

Format

--<ASN1.HugeInteger absoluteReference>--

absoluteReference refers to an ASN.1 INTEGER type that will be represented using the HugeInteger representation, which consists of a series of octets that contain the integer in binary format.

Example

--<ASN1.HugeInteger LengthModule.LengthData.lengthOfSolarSystem>--

LengthModule DEFINITIONS ::= BEGIN
    LengthData ::= SEQUENCE {
        lengthOfSolarSystem  INTEGER,
        units  ENUMERATED
                {nm(-9), mkm (-6), mm(-3), cm(-2), m(0), km(3)} DEFAULT mm
    }
END

For the ASN.1 syntax above, the XER encoding that contains the big INTEGER value of 5913000000000000000000 (which does not fit a 64-bit integer) is successfully decoded:

ASN1STEP: Decoding PDU #1 from file 'LengthData.xer':

<LengthData>
<lengthOfSolarSystem> 5913000000000000000000&l/lengthOfSolarSystem>
</LengthData>
Successfully decoded in 93 bytes.
rec1value LengthData ::=
{
  lengthOfSolarSystem '01408B5BFB9554C40000'H
}

If the directive is not specified, ASN-1Step reports the following error while decoding:

D0023E: Integer or enumerated value too long: 1844674407370955161;
check field 'lengthOfSolarSystem' of PDU #1 'LengthData' at line 2 position 42.

See Also

↩Directives Index


ASN1.PDU

Specifies that one or more ASN.1 types should be treated as protocol data units. By default, all unreferenced types (defined types not referenced by any other type) are considered PDUs by ASN-1Step, so they can be encoded/decoded as complete units.

Format

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

type is an absolute reference that specifies which ASN.1 types should be treated as PDUs.

Remarks

The PDU directive can have three syntaxes:

  • OSS Old-Style Syntax - the old-style OSS-specific directive, --<PDU>-- , cannot have any operands. Rather, its placement determines its scope: local or global.
  • OSS New-Style Syntax - the new-style OSS-specific directive, --<OSS.PDU [type]>--, must have no more than one operand referring to an ASN.1 type. When no operands are given, this directive has the same effect as the old-style global PDU directive. When an operand is present, this directive has the same effect as the old-style local PDU directive. This directive can be placed anywhere in the ASN.1 input when specified with an operand.
  • Standard Directive Syntax - the standard directive, --<ASN1.PDU operand(s)>--, must have one or more operands referring to ASN.1 types that should be treated as PDUs.

Example

--<ASN1.PDU Module.Type>--

Module DEFINITIONS ::= BEGIN
TypeRef ::= Type
Type ::= SET { b BOOLEAN }
END

In the example above, the SET type will be treated as a PDU, even though it is referenced in another type definition.

Passing the notation above through ASN-1Step with the following command:

asn1step filename -listPduIdentifiers

generates this output:

ASN1STEP: List of valid PDU numbers and associated PDU names:

       1.  Type
       2.  Type-setComponent-encodable

See Also

↩Directives Index


ASN1.Version

Specifies the year of the ASN.1 standard in use for 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.

Format

--<ASN1.Version version moduleName [{ oid }]>--

version refers to a year that an ASN.1 standard was published by ITU-T (e.g., 1990, 1994, 1997, 2002, 2008, or 2015). moduleName is a mandatory operand that specifies the module to which the directive is applied. oid is an optional OBJECT IDENTIFIER for unique module identification.

Example

--<ASN1.Version 2008 LengthModule>--

LengthModule DEFINITIONS ::= BEGIN
	LengthData ::= SEQUENCE {
		INTEGER,
		BOOLEAN	
	}
buffer LengthData ::= { 255, TRUE }
END

When the following command is executed for the notation above

asn1step filename -syntaxOnly -noRelaxedMode

ASN-1Step will print this warning message (among others):

"filename", line 5 (LengthModule): A0427W: Mixed 1990 and 2015 ASN.1 syntax: "missing identifier" on line 5
 and "ASN1VER 2008 directive" on line 3.
                INTEGER,
                ^

If the directive is commented out, no warnings are issued.

See Also

↩Directives Index


ASN1.WorkingSet

Identifies those parts of the ASN.1 input that are central to the application. All names (types, values, information objects, etc.) defined in the working set are directly available for use by the application. By default, the ASN.1 compiler chooses a working set by examining the type of compiler directives present. See Default Determination of the Working Set below for details.

Format

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

WSName is the name of the working set. Although required for consistency with other ASN.1 Tools, it is otherwise ignored. absoluteReference refers to a module name, type reference, value reference, object class reference, object reference, or object set reference. When a module name is referenced, the ASN1.WorkingSet directive has the same effect as that of the OSS.ROOT directive: all unreferenced types in this module are considered PDUs.

Remarks

Items in the ASN.1 specification that are not included in the working set are available to the application only when they are referenced from the working set.

A component of a SET, SEQUENCE, CHOICE, SET OF, or SEQUENCE OF cannot be added to a working set on its own.

To extend an existing working-set, specify another instance of the ASN1.WorkingSet directive containing the existing working-set name and the ASN.1 item to be added. In the following ASN.1, both module1 and module14 will be included in commonSet:

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

Examples

Including a type reference in a working set does not necessarily make it a PDU. In the following ASN.1, MyWorkingSet does not explicitly include A.Foo; it is included implicitly since A.Foo is referenced by A.Bar. The result is two types in the working set that reference each other; so neither is a PDU (unless the implementation makes them so).

--<ASN1.WorkingSet MyWorkingSet A.Bar>--

A DEFINTIONS ::= BEGIN
    Foo ::= SEQUENCE OF Bar
    Bar ::= SEQUENCE {a INTEGER, b Foo OPTIONAL}
    Z ::= BOOLEAN
END

In this example, Type1, Type2, and Type4 are directly available to the application as PDUs; Type3 is not.

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

Default Determination of the Working Set

ASN-1Step derives the working set by considering four types of directives, in the following order:

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

Based on the presence or absence of these directives in the input, ASN-1Step assumes one of these four modes:

Default working set
All input module names are included in the working set.
Root default
Only the last module is included in the working set.
Working set
The working set includes only modules explicitly specified by the ASN1.WorkingSet and the OSS.ROOT directives.
Root
No module is included in the working set unless it is specified in an OSS.ROOT directive.

Different sets of directives in the ASN.1 input determine which ASN.1 Compiler mode is used, as shown in the following table. 1 means a directive is present, 0 means a directive is absent, and 1/0 indicates that a directive can be present or absent with no effect on mode selection.

Directive Types Present in Input ASN.1 Compiler Mode
ASN1.WorkingSet Other ASN1.* Directives OSS.ROOT Other OSS.* Directives
0 1 0 0 Default Working Set
0 0 0 0 Root Default
0 1/0 0 1
1 1/0 1 1/0 Working Set
0 1 1 1/0
1 1/0 0 1/0
0 0 1 1/0 Root

See Also

↩Directives Index


OSS.DECIMAL | OSS.DOUBLE | OSS.MIXED

These directives specify internal representations for ASN.1 REAL type values. By default, the ASN.1 REAL type is represented as a MixedReal.

Format

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

absoluteReference refers to a component in the ASN.1 syntax that is intended for the specified representation.

Remarks

When the OSS.DECIMAL directive is used, the internal representation of a null-terminated character string is used with the following form:

[-]nnnnn.nnnnn[E[-]nnnnn]

When the OSS.DOUBLE directive is used, the C double data type is used to represent values.

When the OSS.MIXED directive is used, the value being encoded is represented as follows, permitting either a decimal or binary representation:

{ mantissa nnn, base {10|2}, exponent nnn.}

When specified globally, these directives can take an absolute reference that specifies which ASN.1 syntax component is intended for the desired representation.

When specified globally without an absolute reference, the OSS.DECIMAL and OSS.DOUBLE 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 they are placed next to.

Example

The following ASN.1 notation shows the various ways to determine the REAL type representation:

--<OSS.DECIMAL Module.DREAL>--
Module DEFINITIONS ::= BEGIN
	MREAL ::= REAL --<MIXED>--
	DREAL ::= REAL -- DECIMAL due to the new style directive
	BREAL ::= REAL --<DOUBLE>--

	r REAL ::= 3.14159265358979323846264338327950288
	m MREAL ::= r
	d DREAL ::= r
	b BREAL ::= r
END

Output excerpts from the "asn1step filename -test -per" command shows that the m and d values are encoded the same way without loss of precision, but b is printed and encoded differently due to its binary representation. Also, the number of bytes required to store the decoded value differs for m (pure decimal representation) and d (mixed decimal representation):

        Tracing Information from Decoder...

MREAL REAL [length = 42.0]
  "31415926535897932384626433832795028 ..."
Total encoded length = 43.0

PDU successfully decoded, in 64 bytes

...
        Tracing Information from Decoder...

DREAL REAL [length = 42.0]
  "31415926535897932384626433832795028 ..."
Total encoded length = 43.0

PDU successfully decoded, in 56 bytes

...
        Tracing Information from Decoder...

BREAL REAL [length = 9.0]
  884279719003555 * 2^-48
Total encoded length = 10.0

PDU successfully decoded, in 8 bytes

↩Directives Index


OSS.DEFINITE | OSS.INDEFINITE

Instructs the compiler to use the definite or indefinite length form when encoding PDUs.

Format

--<OSS.DEFINITE [absoluteReference]>--
--<OSS.INDEFINITE [absoluteReference]>--

absoluteReference refers to an ASN.1 component in the specification that is a PDU.

Remarks

When specified globally, these directives require an absolute reference to the targeted PDU. If these directives are applied to non-PDU ASN.1 types there is no effect. When specified globally without an absolute reference, OSS.DEFINITE and OSS.INDEFINITE sets the type of length encoding for all PDUs in their scope. When specified locally, these directives do not take any arguments and affect only the type they are placed next to.

Example

--<OSS.INDEFINITE>--

Module DEFINITIONS ::= BEGIN
	DataPacket ::= SEQUENCE {
		username        IA5String,
		userID          INTEGER
	}
	dataPacket DataPacket ::= {username "John", userID 10}
END

The example above illustrates both directives. --<OSS.INDEFINITE>-- sets a global default for indefinite length encoding. Consequently, DataPacket will be encoded using the indefinite length form, since no other directives are applied to it. But if --<OSS.DEFINITE>-- is specified, DataPacket will be encoded using the definite length form. After passing these notations using the following command, see the output below.

asn1step filename -ber -encodeValue dataPacket

Output

In the first case, when --<OSS.INDEFINITE>-- is specified:

ASN1STEP: Encoding of valuereference 'dataPacket' for PDU #1:

Encoding to the file 'dataPacket.ber' using BER encoding rule...
DataPacket SEQUENCE: tag = [UNIVERSAL 16] constructed; length = indef
  username IA5String: tag = [UNIVERSAL 22] primitive; length = 4
    "John"
  userID INTEGER: tag = [UNIVERSAL 2] primitive; length = 1
    10
EOC
Encoded successfully in 13 bytes:
30801604 4A6F686E 02010A00 00

In the second case, when --<OSS.DEFINITE>-- is specified:

ASN1STEP: Encoding of valuereference 'dataPacket' for PDU #1:

Encoding to the file 'dataPacket.ber' using BER encoding rule...
DataPacket SEQUENCE: tag = [UNIVERSAL 16] constructed; length = 9
  username IA5String: tag = [UNIVERSAL 22] primitive; length = 4
    "John"
  userID INTEGER: tag = [UNIVERSAL 2] primitive; length = 1
    10
Encoded successfully in 11 bytes:
30091604 4A6F686E 02010A

Default Behavior

The compiler uses the definite length form.

↩Directives Index


OSS.DTD

Instructs the compiler to generate a separate DTD (XML Data Type Definition) for a specified PDU. By default, no DTDs are produced by ASN-1Step unless the -dtd option is specified.

Format

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

absoluteReference refers to a PDU in the ASN.1 input for which to generate a separate XML DTD. NewName is an optional argument that specifies a new, full pathname for the generated DTD. When absoluteReference is not specified, a DTD will be produced for each and every PDU in the input syntax. This form of the OSS.DTD directive (i.e., a global directive application) is identical in behavior to the -dtd command-line option. Although the OSS.DTD directive can appear anywhere white space is allowed, the OSS prefix must be present.

Remarks

When the -dtd compiler option is specified, a DTD for each PDU in the input is generated into a separate file whose name is derived from that of the PDU.

NOTE: You can use DTDs to make XER output produced by ossEncode() editable in a non-ASN.1-specific XML tool.

Example

In the following example, two separate DTD files, StringType.dtd and AnotherNameForInt.dtd, are produced for their PDUs.

--<OSS.DTD XModule.StringType>--
--<OSS.DTD XModule.IntType "AnotherNameForInt.dtd">--

XModule DEFINITIONS ::= BEGIN
    StringType ::= UTF8String
    IntType ::= INTEGER
    studentName ::= <StringType>John H. Doe</StringType>
    studentAge ::= <IntType>23</IntType>
END

See Also

↩Directives Index


OSS.ENCODABLE

Enables support for DER (Distinguished Encoding Rules) applications that encode encrypted signatures. When OSS.ENCODABLE is applied to a CHOICE, SEQUENCE, or SET component, that component will be represented as an open type. Also, the type of the component becomes a PDU and can be encoded independently of the CHOICE, SEQUENCE, or SET in which it was embedded. By default, all components within a CHOICE, SEQUENCE, or SET are represented using their normal forms.

Format

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

Remarks

When specified globally, this directive requires an absolute reference to the targeted CHOICE, SEQUENCE, or SET component. When specified locally, this directive does not take any arguments and affects only the type that it is placed next to.

An encoded type to which the directive is applied will be skipped while decoding the PDU, so possible errors in it might be not reported.

Do not apply the OSS.ENCODABLE directive to a tagged type. To achieve the same effect for tagged types, use the ASN1.DeferDecoding directive.

This directive does not work when PER or XML is in use.

Example

OSS.ENCODABLE is applied at the local level in the following syntax:

--<OSS.ENCODABLE Module.A.data>--
Module DEFINITIONS ::= BEGIN
         A ::= SEQUENCE {
                id    [0] INTEGER,
                data  [1] OCTET STRING
         }
         a A ::= { id 10, data '123456789ABCDEF'H }
END

Passing the syntax through ASN-1Step with this command

asn1step filename -listPduIdentifiers

generates the following:

ASN1STEP: List of valid PDU numbers and associated PDU names:

       1  A
       2  A-data-encodable

Note that a separate PDU tag was generated for the type marked with the OSS.ENCODABLE directive.

See Also

↩Directives Index


OSS.ExerNumericBoolean

BOOLEAN types are encoded as numeric values of 0 and 1, instead of "true" and "false", when a GLOBAL-DEFAULTS MODIFIED-ENCODINGS encoding instruction is present. This is useful for

  • Reducing the size of encoded XML documents.
  • Exchanging information with decoders that understand only numeric BOOLEAN values.

Format

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

absoluteReference refers to the affected type.

Example

In the following example, the value p0 is encoded as <Presence>0</Presence> and not as <Presence>absent</Presence>:

  --<OSS.ExerNumericBoolean Test.Presence>--
  
  Test DEFINITIONS XER INSTRUCTIONS AUTOMATIC TAGS ::= BEGIN
     Presence ::= BOOLEAN
     p0 Presence ::= FALSE
     
     ENCODING-CONTROL XER
     GLOBAL-DEFAULTS MODIFIED-ENCODINGS
     TEXT Presence:false AS "absent"
     TEXT Presence:true AS "present"
  END

↩Directives Index


OSS.EXTENSIBLE | OSS.INEXTENSIBLE

Enables or disables decoder support for the rules of extensibility, which state that when decoding a PDU all elements of a SET or SEQUENCE whose tags are not defined in the input abstract syntax must be silently ignored.

Format

--<OSS.EXTENSIBLE [absoluteReference]>--
--<OSS.INEXTENSIBLE [absoluteReference]>--

Remarks

When specified globally, these directives can take an absolute reference that refers to the affected BIT STRING, SEQUENCE, or SET type. If specified globally without an absolute reference, the OSS.EXTENSIBLE and OSS.INEXTENSIBLE directives determine how the decoder handles extensible elements. When specified locally, these directives do not take any arguments and affect only the type they are placed next to.

The OSS.EXTENSIBLE directive functions the same as the ASN.1 formal extension marker ("..."). You can use either the directive or the extension marker, but not both.

Example

This example shows global and local use of the directives||; the local OSS.INEXTENSIBLE directive overrides the global OSS.EXTENSIBLE directive for Sample1.Name2.

--<OSS.EXTENSIBLE>--
Sample DEFINITIONS EXPLICIT TAGS ::= BEGIN
        Name ::= SEQUENCE {
                a INTEGER,
                b BIT STRING 
        } --<PDU>--
        NameI ::= Name --<INEXTENSIBLE>--
END

A Name type value that contains an unknown extension

Name.xer:  <Name> <a>10</a> <b>011</b> <c>TRUE</c> </Name>

will be successfully decoded using the following command:

asn1step filename -decode Name Name.xer

Output

ASN1STEP: Decoding PDU #1 from file 'Name.xer':

Name SEQUENCE
  a INTEGER [length = 2]
    10
  b BIT STRING [length = 3]
    0x60
Total encoded length = 47
<Name> <a>10</a> <b>011</b> <c>TRUE</c> </Name>
Successfully decoded 47 bytes.
rec1value Name ::=
{
  a 10,
  b '011'B
}

However, decoding of the similar NameI type value will fail:

asn1step filename -decode NameI NameI.xer

Output

ASN1STEP: Decoding PDU #2 from file 'NameI.xer':

NameI SEQUENCE
  a INTEGER [length = 2]
    10
  b BIT STRING [length = 3]
    0x60
D0157E: Expecting value for a component of SET / SEQUENCE / CHOICE but XML tag
name does not match any component identifier: 'c'; check field 'b' (type:
BIT_STRING) of PDU #2 'NameI' at line 1 position 32.
 10 011 TRUE 
D0157E: Expecting value for a component of SET / SEQUENCE / CHOICE but XML tag
name does not match any component identifier: 'c'; check field 'b' (type:
BIT_STRING) of PDU #2 'NameI' at line 1 position 32.
S0012E: Decoding of PDU #2 failed with the return code '5'.

The local OSS.INEXTENSIBLE directive overrides the global OSS.EXTENSIBLE directive.

Default Behavior

The OSS.INEXTENSIBLE directive is implied.

↩Directives Index


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.

Format

--<OSS.ExtensibleUseType>--

Remarks

By default, the CHOICE data described above is decoded as data that matches the first alternative; all unknown elements or attributes are ignored. When OSS.ExtensibleUseType is present, the decoder treats such data as an unknown extension rather than a value of the first CHOICE alternative. The entire XML sub-element that matches the unknown extension is preserved in the special "unknown alternative" field by the decoder and can be safely re-encoded.

Example

ASN.1 specification

Test DEFINITIONS XER INSTRUCTIONS AUTOMATIC TAGS ::= BEGIN

T ::= [USE-TYPE] CHOICE {
    base SEQUENCE {i INTEGER},
    e1 SEQUENCE {i INTEGER, b BOOLEAN},
    ...
    } --<ExtensibleUseType>--

    ENCODING-CONTROL XER
    GLOBAL-DEFAULTS MODIFIED-ENCODINGS
    GLOBAL-DEFAULTS CONTROL-NAMESPACE
     "http://www.w3.org/2001/XMLSchema-instance" PREFIX "xsi"
END

For the following XML document

<T xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="e4">
<i>1</i>
<j>2</j>
</T>

the decoder produces the following results:

  • Without ExtensibleUseType, unknown content is skipped:
    Successfully decoded in 101 bytes.
    rec1value T ::= base : 
    {
        i 1
     }
    
    ASN1STEP: Re-encoding of 'value' of the PDU #1:
    
    Encoding to the file 'T.exer.exer' using EXER encoding rule...
    Encoded successfully in 58 bytes:
    <?xml version="1.0" encoding="UTF-8"?>
    <T>
      <i>1</i>
    </T>
    
  • With ExtensibleUseType, decoded and re-encoded data is represented as follows:
    Successfully decoded in 101 bytes.
    rec1value T ::= <unknown>
    
    ASN1STEP: Re-encoding of 'value' of the PDU #1:
    
    Encoding to the file 'T.exer.exer' using EXER encoding rule...
    Encoded successfully in 140 bytes:
    <?xml version="1.0" encoding="UTF-8"?>
    <T xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="e4">
      <i>1</i>
      <j>2</j>
    </T>

See Also

↩Directives Index


OSS.HUGE

Sets a special representation for integers whose size not supported by the operating system in use. By default, INTEGER types are represented as machine-dependent integers.

Format

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

Remarks

When specified globally, absoluteReference refers to an INTEGER that requires the HugeInteger representation. When specified locally, OSS.HUGE takes no operands and affects only the type it is placed next to.

The HugeInteger representation consists of a series of octets containing the integer in binary format.

NOTE: HUGE INTEGER values are printed as OCTET STRING values.

Example

HugeInt DEFINITIONS ::= BEGIN
    A ::= INTEGER --<HUGE>--
END

For the ASN.1 notation above, the XER encoding of the big INTEGER value 123456789101112 (which does not fit a 64-bit integer) can be decoded successfully:

ASN1STEP: Decoding PDU #1 from file 'A.xer':

<A>123456789101112</A>
Successfully decoded in 22 bytes.
rec1value A ::= '7048860F3A38'H

See Also

↩Directives Index


OSS.NoConstrain

Identifies those types or components for which constraint checking should be disabled. The directive turns off all constraint checking for the type, which includes checking the default permitted alphabet for character strings. For ENUMERATED types, OSS.NoConstrain disables subtype constraints but does not disable enumerator validation. By default, constraint checking is turned on.

Format

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

When specified globally, absoluteReference refers to an ASN.1 type with a defined constraint. OSS.NoConstrain cannot be specified locally.

Remarks

OSS.NoConstrain has no effect if -constraint is explicitly specified, except in the following situations:

  • The directive is applied to a CHARACTER STRING (unrestricted) or an EMBEDDED PDV type.
  • The directive 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.

Example

All constraints for S are disabled in the following example. However, if the OSS.NoConstrain directive is omitted then the "asn1step filename -encodeValue badval" command prints out a message about constraint violation.

--<OSS.NoConstrain Module.S>--

Module DEFINITIONS ::= BEGIN
    S ::= INTEGER (1..10 | 300)
END

In this example, PrintableString abc is passed without issuing a constraint violation error. Although the OSS.NoConstrain directive is not explicitly applied to the ShortABCs type, constraint checking for this type is disabled because it is composed of types that have OSS.NoConstrain applied.

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

See Also

↩Directives Index


OSS.DEFAULTVALUE | OSS.NODEFAULTVALUE

The OSS.DEFAULTVALUE and OSS.NODEFAULTVALUE directives inform ASN-1Step whether items with the ASN.1 DEFAULT tag shall be handled as if they have the OPTIONAL tag instead. By default, OSS.DEFAULTVALUE is implied; types with the DEFAULT tag use the specified default value when absent from the encoding.

Format

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

When specified globally, absoluteReference can be present and refers to an ASN.1 type with a DEFAULT tag. When specified globally without an operand, these directives affect all types with the DEFAULT tag. When specified locally, the directives take no operands and affect only the types they are placed next to.

Remarks

In general, you can specify a global OSS.NODEFAULTVALUE and then apply OSS.DEFAULTVALUE with absolute references for particular fields.

Example

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

After executing the following command

asn1step filename -encodeValue dataCard -cxer -noconstr

the following is printed. Note that a is represented as an OPTIONAL component because OSS.NODEFAULTVALUE is applied to it. On the other hand, b is still handled as a component with a default value, so it is present in the encoding because it is specified by the CXER encoding rules.

ASN1STEP: Encoding of valuereference 'dataCard' for PDU #1:

Encoding to the file 'dataCard.cxer' using CXER encoding rule...
DataCard SEQUENCE
  b BOOLEAN [length = 7]
    TRUE
  c BOOLEAN [length = 8]
    FALSE
Total encoded length = 50
Encoded successfully in 50 bytes:
<DataCard><b><true/></b><c><false/></c></DataCard>

↩Directives Index


OSS.PDU | OSS.NOPDU

Indicates whether an ASN.1 type can be sent or received as a protocol data unit. By default, unreferenced types (defined types not referenced by other types) are considered PDUs and can be encoded and decoded as complete units.

Format

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

When specified globally, absoluteReference specifies the ASN.1 components that the directive will be applied to. When specified globally without an operand, the OSS.PDU and OSS.NOPDU directives set the default for all types within their scope. When specified locally, these directives take no operands and affect only the type they are placed next to.

Remarks

The OSS.PDU and ASN1.PDU directives only affect types contained in root modules. To treat all input modules as root modules, either specify the -root compiler option (when compiling your ASN.1 syntax) or include the global OSS.ROOT directive in your ASN.1 specification.

Example

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

After passing the above notation through ASN-1Step with the command

asn1step filename -listPduIdentifiers

the following is generated:

ASN1STEP: List of valid PDU numbers and associated PDU names:

       1  MiddleAgeClubCard
       2  NameString
       3  PhoneString

Notice how AgeInt is not marked to be a PDU, since it is referenced in the MiddleAgeClubCard SEQUENCE and it does not have a PDU directive applied to it.

See Also

↩Directives Index


OSS.ROOT

Identifies the ASN.1 modules that are used as root modules. In a root module, all unreferenced types are considered PDUs. Also, non-root modules exist only to supply external references to root modules. By default, the last ASN.1 input file specified on the command line contains the root module.

Format

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

OSS.ROOT can only be specified globally and takes one or more operands to identify ASN.1 modules. 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.

Example:

common.asn:

--<OSS.ROOT Common>--
Common DEFINITIONS ::= BEGIN
	EXPORTS NameString,PhoneString,AgeInt;
	IMPORTS;
		NameString ::=  IA5String 
		PhoneString ::= NumericString 
		AgeInt ::= INTEGER 
END

application.asn:

Module DEFINITIONS ::= BEGIN
	EXPORTS;
	IMPORTS NameString,PhoneString,AgeInt FROM Common;
		MiddleAgeClubCard ::= SEQUENCE {
			name            NameString,
			phoneNumber     PhoneString,
			age             AgeInt
      }
	mCard MiddleAgeClubCard ::= {name "test",phoneNumber "123",age 22}
END

When the common.asn file contains OSS.ROOT, the command

asn1step common.asn application.asn -listPduIdentifiers

prints out the following:

1.	NameString
2.	PhoneString
3.	AgeInt

But if OSS.ROOT is missing then the output will be as follows:

   1. MiddleAgeClubCard

See Also

↩Directives Index


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.

Format

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

OSS.SelfCompleteWildcard can be applied to types with a final XER ANY-ELEMENT encoding instruction. It can be specified for a single type, for a module, or globally.

Remarks

When OSS.SelfCompleteWildcard is applied, the following is true:

  • Namespaces declared in outer XML elements are not re-declared in the decoded wildcard value.
  • The original order of namespaces and attributes is preserved, provided that the namespaces were declared before the attributes.

If the wildcard contents were normalized according to the W3C Canonical XML specification, the decoded wildcard value will match the original XML value, which enables post-decoding validation of the wildcard's digital signature.

You can use OSS.SelfCompleteWildcard to speed up E-XER decoding of wildcards if you know in advance that they self-complete and do not use namespace or entity declarations from the outer XML document.

Example:

--<OSS.SelfCompleteWildcard M.Root.w>--
M DEFINITIONS XER INSTRUCTIONS ::= BEGIN

Root ::= SEQUENCE {
    w [ANY-ELEMENT] UTF8String (CONSTRAINED BY {}) }

ENCODING-CONTROL XER
    GLOBAL-DEFAULTS MODIFIED-ENCODINGS
    NAMESPACE ALL AS "urn:Root" PREFIX "r"

END

For the following XML document, where n1:wildcard is an element wildcard

<Root xmlns="urn:Root">
<n1:wildcard xmlns:n1="urn:n1" xmlns:n2="urn:n2" n1:at1="1" n2:at2="2"/>
</Root>

the decoder produces what is literally the original:

<n1:wildcard xmlns:n1="urn:n1" xmlns:n2="urn:n2" n1:at1="1" n2:at2="2"/>

Without OSS.SelfCompleteWildcard, the decoder produces what is the wildcard value by default:

<n1:wildcard xmlns:n2="urn:n2" xmlns:n1="urn:n1" xmlns="urn:Root" n2:at2="2" n1:at1="1"/>

See Also

↩Directives Index


OSS.LONGLONG

Determines the internal representation of the ASN.1 INTEGER type. On a typical system, OSS.LONGLONG calls for a 64-bit integer. By default, when no subtype constraints are present, an ASN.1 INTEGER type is represented as a 32-bit C integer type. When a subtype constraint is present, the ASN-1Step chooses the smallest representation able to carry all required values.

Format

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

When specified globally, only INTEGERs without subtype constraints are affected. absoluteReference refers to an ASN.1 INTEGER type. When specified globally without an absolute reference, OSS.LONGLONG sets the default for all INTEGER types within its scope. When specified locally, the directive does not take any arguments and affects only the type it is placed next to. It also overrides any choices that ASN-1Step would have made based on a subtype constraint.

Example

--<OSS.LONGLONG>--
Module DEFINITIONS ::= BEGIN
		LONGLONGInt ::= INTEGER
		llint LONGLONGInt ::= 223372036854775807
END

The ASN.1 notation above illustrates the global use of the OSS.LONGLONG directive. The XER encoding of the 223372036854775807 big INTEGER value (which does not fit a 32-bit integer) can be decoded successfully:

ASN1STEP: Decoding PDU #1 from file 'A.xer':

<LONGLONGInt>223372036854775807</LONGLONGInt>
Successfully decoded in 22 bytes.
rec1value LONGLONGInt ::= 223372036854775807

↩Directives Index


OSS.Stylesheet

Gives you more control over the XML stylesheets produced by ASN-1Step. This directive instructs ASN-1Step to generate a separate XML stylesheet with your specified filename for any PDU. By default, unless the -xsl option is specified, stylesheets are not produced. When -xsl is specified, a stylesheet for each input PDU is generated into a separate file with a name derived from that PDU.

Format

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

absoluteReference refers to any PDU in the input ASN.1 that you want to generate a separate XML stylesheet for. When absoluteReference is not specified, a stylesheet is generated for every PDU in the input. OptionalNewName is an optional argument that allows you to specify a new name for the stylesheet that will be generated.

Remarks

Stylesheets can be used to make the XER output of the encode() method more visually appealing when viewed in a web browser.

The OSS.Stylesheet directive can appear anywhere whitespace is allowed; however, the OSS prefix and an absolute reference is required.

Example

For the following syntax, two separate stylesheet files are generated: StringType.xsl and AnotherNameForInt.xsl. Each contains default browser style information for their respective PDUs.

--<OSS.Stylesheet XModule.StringType>--
--<OSS.Stylesheet XModule.IntType "AnotherNameForInt.xsl">--

XModule DEFINITIONS ::= BEGIN
    StringType ::= UTF8String
    IntType    ::= INTEGER
    studentName ::= <StringType>John H. Doe</StringType>
    studentAge  ::= <IntType>23</IntType>
END

See Also

↩Directives Index


OSS.SUPPRESS

Disables printing of specific informatory and warning messages. This is useful when working with abstract syntaxes that are known to contain specifications that do not comply with the ASN.1 standard. By default, informatory and warning messages are suppressed when -noRelaxedMode is turned on.

Format

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

messageID identifies the message to be suppressed. It can be the full message identifier, such as A0178W, or only its numeric portion: 178. OSS.SUPPRESS can only be used globally and can take one or more messageIDs.

Example

In the following example, message A0178W warns 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

The directive's only effect is to suppress the following warning message:

"filename.asn", line 4 (Sample): A0178W: The first digit should not be zero unless the number is a single digit.
    legalAge Age ::= 021
                     ^

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

See Also

↩Directives Index


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.

Format

--<OSS.Truncate absoluteReference maxlimit>--

When specified globally, absoluteReference refers to the SET OF or SEQUENCE OF type for which all elements with an index greater than maxLimit should be ignored. maxLimit is an integer number between 1 and 16384. The OSS.Truncate directive cannot be specified locally.

Example

--<OSS.Truncate Mod.Records 3000>--

Mod DEFINITIONS ::= BEGIN
Records  ::= SEQUENCE OF Employee

Employee ::= SEQUENCE {
   name IA5String,
   position IA5String,
   salary REAL 
}
END

The notation above demonstrates use of the OSS.Truncate directive. The decoder will only process 3000 elements of the Records type. This type of truncation is useful when you are sure that

  • The information needed will not be at the end of the list of elements.
  • The desired information will not be contained in a large list of elements.

↩Directives Index


OSS.USERFIELD

Allows ASN-1Step to ignore some fields of ASN.1 SEQUENCE or SET types. The OSS.USERFIELD directive instructs the encoder to skip the field. It instructs the decoder to perceive an error upon receipt of a value which appears in the same context and has the same tag as the user field. By default, no user field is generated.

Format

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

When specified globally, absoluteReference refers to a field in an ASN.1 SET or SEQUENCE type. When specified locally, this directive takes no operands and only affects the type that it is placed next to.

Remarks

User fields can only appear in ASN.1 SEQUENCE or SET types and must be marked as either OPTIONAL or DEFAULT.

User fields are subjected to the same ASN.1 restrictions as non-user fields.

Some user fields declared as OPTIONAL might not have bit masks generated for them.

Example

--<OSS.USERFIELD Module.DataCard.controlGroup>--
Module DEFINITIONS ::= BEGIN
      DataCard ::= SEQUENCE {
                controlGroup    BOOLEAN DEFAULT FALSE ,
                name            PrintableString,
                numberOfCars    INTEGER (1..5)
      }
      dataCard DataCard ::= {controlGroup TRUE,name "John",numberOfCars 1}
END

When the above notation is passed through ASN-1Step using the

asn1step <filename> -per -test

command, the following is printed during encoding:

value DataCard ::=
{
  name "John",
  numberOfCars 1
}

...

Total encoded length = 6.0

PDU successfully encoded, in 6 bytes:
044A6F68 6E00

and decoding:

value DataCard ::=
{
  name "John",
  numberOfCars 1
}

The encoder and decoder behave as if the controlGroup field above was not present.

↩Directives Index


This documentation applies to release 8.2 and later of ASN-1Step®. For earlier versions, consult the PDF manual available in your product installation.

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.