|
The Command Line |
Command-line Options |
Directives |
Converting to/from CSV Format |
Frequently Asked Questions
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.
--<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.
The ASN1.DeferDecoding directive
We stand with Ukraine --<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
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.
--<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.
--<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.
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.
--<ASN1.PDU type [, type] ...>--
type is an absolute reference that specifies which ASN.1 types should be treated as PDUs.
The PDU directive can have three syntaxes:
--<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
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.
--<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.
--<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.
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.
--<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.
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>--
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
ENDIn 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
ASN-1Step derives the working set by considering four types of directives, in the following order:
Based on the presence or absence of these directives in the input, ASN-1Step assumes one of these four modes:
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 |
These directives specify internal representations for ASN.1 REAL type values. By default, the ASN.1 REAL type is represented as a MixedReal.
--<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.
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.
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
Instructs the compiler to use the definite or indefinite length form when encoding PDUs.
--<OSS.DEFINITE [absoluteReference]>--
--<OSS.INDEFINITE [absoluteReference]>--
absoluteReference refers to an ASN.1 component in the specification that is a PDU.
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.
--<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
The compiler uses the definite length form.
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.
--<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.
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.
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
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.
--<OSS.ENCODABLE [absoluteReference]>--
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.
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.
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
--<OSS.ExerNumericBoolean [absoluteReference]>--
absoluteReference refers to the affected type.
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
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.
--<OSS.EXTENSIBLE [absoluteReference]>--
--<OSS.INEXTENSIBLE [absoluteReference]>--
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.
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.
The OSS.INEXTENSIBLE directive is implied.
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.ExtensibleUseType>--
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.
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:
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>
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>
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.
--<OSS.HUGE [absoluteReference]>--
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.
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
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.
--<OSS.NoConstrain [absoluteReference]>--
When specified globally, absoluteReference refers to an ASN.1 type with a defined constraint. OSS.NoConstrain cannot be specified locally.
OSS.NoConstrain has no effect if -constraint is explicitly specified, except in the following situations:
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
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.
--<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.
In general, you can specify a global OSS.NODEFAULTVALUE and then apply OSS.DEFAULTVALUE with absolute references for particular fields.
--<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>
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.
--<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.
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.
--<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.
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.
--<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.
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
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.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.
When OSS.SelfCompleteWildcard is applied, the following is true:
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.
--<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"/>
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.
--<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.
--<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
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.
--<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.
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.
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
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.
--<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.
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.
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.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.
--<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
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.
--<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.
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.
--<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.
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.