|
The Command Line |
Command-line Options |
Directives |
Converting to/from CSV Format |
Frequently Asked Questions
Specifies the ASN.1 version used in the input ASN.1 specification file.
The -1990 option indicates that the ASN.1 specification conforms only to the 1990 version of ASN.1. ASN-1Step supports ASN.1:1990, including these features:
The -2015 option indicates that the ASN.1 specification conforms to the 2015 version of ASN.1. ASN-1Step supports ASN.1:2015, including these features:
ASN-1Step lets you mix the 1990 and 2015 syntaxes, but issues warnings since this behavior is not allowed by X.680 (2015) ISO/IEC 8824-1:2015.
When using ASN.1:2015 syntax, ASN-1Step complains when:
The -1993, -1994, -1997, -2002, and -2008 compiler options are equivalent to the -2015 option.
ASN-1Step starts out in neutral mode, expecting either ASN.1 version. Once syntax unique to ASN.1:1990 or ASN.1:2015 is detected, ASN-1Step exits neutral mode and checks for conformance to the detected version, generating messages for any violations. However, starting in neutral mode could cause a longer ASN.1 specification debugging cycle, especially when creating new ASN.1 specifications.
This option instructs ASN-1Step to encode all value references specified in the input ASN.1 specification. It works as if the -encodeValue option, with one or more encoding rule options, was specified for each value reference in the input notation.
When the -output option is not specified, each value reference is encoded using the specified encoding rules. The output filenames will have prefixes derived from the value reference names and extensions derived from the encoding rules. This is similar to how the -encodeValue option works.
When the -output <prefix> option is specified, one file is created for each encoding rule, with concatenated messages for all values. The filename prefix matches the prefix specified in the option and the file extension is derived from the encoding rule. If the -concatenate is also specified and the output file already exists, the new records are concatenated to the content of the output file. In this case, the concatenated records must belong to the same PDU. Otherwise, if records were created using PER or if the syntax has PDUs with non-unique tags, the decoder cannot automatically decode all concatenated messages from such a file.
The -allEncode option is turned off.
This option instructs ASN-1Step to accept input syntax that deviates from the standard, as specified by the argument. Use with caution and only when absolutely necessary.
The option takes a single argument, but can be specified more than once when multiple arguments are needed, for example:
asn1step foo.asn -allow BadValues -allow UniversalTags
Instructs ASN-1Step to use explicit automatic tagging not only for untagged but also for tagged CHOICE types, open types, and "DummyReference" types, based on the interpretation of clause 31.2.7 c of the X.680 2002 ASN.1 standard.
In the following example, if -allow BadExplicitAutomaticTagging is specified, ASN-1Step uses explicit automatic tagging for the ch field that has the tagged CHOICE type. If -allow BadExplicitAutomaticTagging is not specified, ASN-1Step uses implicit tagging for this field.
We stand with Ukraine
B4114 DEFINITIONS AUTOMATIC TAGS ::= BEGIN
Seq ::= [65] SEQUENCE { ch Cho }
Cho ::= [65] CHOICE { b BOOLEAN }
s Seq ::= { ch b : TRUE }
END
This option is implied by the default -relaxedMode option and instructs ASN-1Step to continue the current process when a content error is found in the value notation of restricted character strings (i.e., NumericString, PrintableString, and VisibleString), OBJECT IDENTIFIERs, or extensible types with missing mandatory extension additions.
myPhoneNumber NumericString ::= "(800) 555-1212 EXT-6"
myObjectID OBJECT IDENTIFIER ::= {0 26}
This value notation will cause ASN-1Step to exit with an error message, unless -allow BadValues is specified.
According to the ASN.1 standard, the NumericString type allows only numbers (0-9) and white space in its contents. The OBJECT IDENTIFIER type allows no value larger than 4 for its second node.
ASN-1Step does not truncate BIT STRING, restricted string, or OCTET STRING values defined with extensible size constraints when the UNBOUNDED or NULLTERM representation is used. Nor will it truncate SEQUENCE OF or SET OF types.
To instruct ASN-1Step to treat the errors as warnings, use the -ignoreError option.
This option also instructs ASN-1Step to issue the A1007W warning message, instead of the A1006E error message in some cases of type-value mismatch in ENUMERATED, SET, SEQUENCE, or CHOICE value assignments. For ENUMERATED types, differences in the named values set are allowed. For SET, SEQUENCE, and CHOICE types, differences in field tags and in the extension marker position are allowed.
This option is implied by the default -relaxedMode option. It instructs ASN-1Step to accept mixed-case names for some ASN.1 built-in types, provided that types with these names are not already defined in the ASN.1 input.
This option currently supports mixed-case names for these built-in types:
M DEFINITIONS ::= BEGIN Type ::= IA5STRING value Type ::= "abc" END
This is normally an invalid ASN.1 syntax since 'IA5STRING' is used but is not defined.
If -allow MixedCaseForSomeBuiltInTypesNames is not specified the compiler reports the following errors:
"test.asn", line 2 (M): A0256W: 'IA5STRING' is referenced, but is not defined. "test.asn", line 2 (M): A0052E: 'IA5STRING' is not defined.
The -allow MixedCaseForSomeBuiltInTypesNames option allows you to compile such ASN.1 syntax; the compiler will assume that the 'IA5STRING' is a misspelling of the built-in type 'IA5String':
"test.asn", line 2 (M): A1277W: 'IA5STRING' is assumed to be a misspelling of the built-in type 'IA5String'.
This option is implied by the default -relaxedMode option. It instructs ASN-1Step to accept ASN.1 names that contain the underscore character ("_") after the initial character.
M DEFINITIONS ::= BEGIN Some_Type ::= INTEGER END
If -allow UnderscoresInAsn1Names is not specified ASN-1Step reports the following errors:
"test.asn", line 2 (M): A1271E: The low line character ('_') is not among the permitted characters for ASN.1 names.
Please use the '-allow UnderscoresInAsn1Names' command line option to force the compiler to accept such invalid names.
Some_Type ::= INTEGER
^
"test.asn", line 2 (M): A0120E: Parsing error: expecting '::=', '{' or an ASN.1 Type but found illegal character.
Some_Type ::= INTEGER
^
Instructs ASN-1Step to accept UNIVERSAL class tags that are normally prohibited. This option is enabled by default in trial versions of ASN-1Step.
Use UNIVERSAL class tags for
Any other UNIVERSAL tags are rejected.
If you use a UNIVERSAL tag for a CHARACTER STRING or OCTET STRING type, ASN-1Step will redefine the type to a restricted character string type according to its tag number.
M DEFINITIONS IMPLICIT TAGS ::= BEGIN
B-ignore ::= [UNIVERSAL 1] IMPLICIT BOOLEAN
CS-ignore ::= [UNIVERSAL 29] CHARACTER STRING
OS-ignore ::= [UNIVERSAL 4] OCTET STRING
GT-ignore ::= [UNIVERSAL 24] GeneralizedTime
UTCT-ignore ::= [UNIVERSAL 23] UTCTime
U8-ignore ::= [UNIVERSAL 12] UTF8String
BMP-ignore ::= [UNIVERSAL 30] BMPString
CS-U8 ::= [UNIVERSAL 12] CHARACTER STRING
OS-U8 ::= [UNIVERSAL 12] OCTET STRING
CS-BMP ::= [UNIVERSAL 30] CHARACTER STRING
OS-BMP ::= [UNIVERSAL 30] OCTET STRING
END
In this example, the CS-U8 type is treated as a UTF8String. Following is one of the warning messages issued:
"test.asn", line 2 (M): A0307W: OSS has relaxed the standards to allow the definition of a type with tag [UNIVERSAL 1].
This is normally invalid ASN.1. The tag will be ignored.
B-ignore ::= [UNIVERSAL 1] IMPLICIT BOOLEAN
^
The -allow UniversalTags option is turned off.
These options instruct ASN-1Step to create sample values in ASN.1 value notation format for PDU types present in the ASN.1 input. The options have the following syntax:
-allSampleAsn1Values [[<flags>][,<outFileName>]] -sampleAsn1Value <pduTypeName>[,[<flags>][,<outFileName>]]
By default, the ASN.1 value listing created with these options is printed to stdout. You can change this behavior using the optional <flags> and <outFileName> parameters.
The <flags> parameter is one or two of the following flags, separated by colons:
The <outFileName> parameter specifies the output file name to be used for ASN.1 value listing, the parameter is ignored if the FILE flag is specified in <flags>.
Consider the following ASN.1 example (bcas.asn):
Bcas DEFINITIONS ::= BEGIN
BBCard ::= SEQUENCE {
name IA5String (SIZE (1..60)),
team IA5String (SIZE (1..60)),
age INTEGER (1..100),
position IA5String (SIZE (1..60)),
handedness ENUMERATED {left-handed(0), right-handed(1), ambidextrous(2)},
batting-average REAL
}
END
Issue the following command:
asn1step bcas.asn -allSampleAsn1Values
After execution, you should see output similar to the following:
ASN1STEP: Creating sample values for all PDU types
samplevalue-BBCard Bcas.BBCard ::= {
name "name",
team "team",
age 1,
position "position",
handedness left-handed,
batting-average 0
}
C0043I: 0 error messages, 0 warning messages and 0 informatory messages issued.
This command
asn1step bcas.asn -sampleAsn1Value BBCard,FILE:MOD
will create the bcas-samplevalues.asn file with the following content:
OSS-SAMPLE-VALUES-MODULE
DEFINITIONS ::=
BEGIN
IMPORTS
BBCard
FROM Bcas;
samplevalue-BBCard BBCard ::= {
name "name",
team "team",
age 1,
position "position",
handedness left-handed,
batting-average 0
}
END
This command:
asn1step bcas.asn -sampleAsn1Value BBCard,MOD,myBcasValues.asn
will create the myBcasValues.asn file with the same content as in the bcas-samplevalues.asn from the previous example.
These options are turned off.
Instructs ASN-1Step to generate ASN.1 value notation for an input encoded message when the -decodePdu option is used or implied.
The output ASN.1 value notation is placed in a text file whose name, by default, is based on the corresponding input encoding file (e.g., myValue.ber.txt for an input encoding file named myValue.ber). Use the -output option to specify a different name for the text file.
asn1step bcas.asn -decodePdu BBCard bcas.ber -asn1value
In the above example, the input BER-encoded value stored in the bcas.ber file will be decoded and the corresponding ASN.1 value will be written to the bcas.ber.txt file. If several input files with encoded values are specified along with the -decode, -asn1Value, or -output options, all values are added to one text file with the same prefix as the -output option parameter, with the .txt extension. If the -concatenate option is also specified and the output file already exists, the new ASN.1 values are appended to the end of the existing text file.
The -asn1Value option is turned off.
Instructs ASN-1Step to process type and value assignments found outside defined input modules.
Module1 DEFINITIONS ::= BEGIN
MyInt ::= INTEGER
END
ExtraModularType ::= INTEGER
Module2 DEFINITIONS ::= BEGIN
MyBit ::= INTEGER
END
If the -assignments option is not specified, ASN-1Step issues an error because ExtraModularType is outside of a BEGIN-END ASN.1 module.
The -assignments option is turned off.
Allows automatic encoding and decoding of open types when constraint checking is disabled (-noConstraints).
The -autoEncDec option is turned off.
Specifies that BER, DER, PER Aligned or Unaligned, OER, or C-OER encoded data should be read/written to a text file containing binary characters (i.e., '0's and '1's). For example, the following command issued for samples/sample.asn:
asn1step sample.asn sample.ber -bin -encodeValue myName
will produce a text file named sample.ber that contains:
00010110 00000011 01001111 01010011 01010011
The optional numGroupChars argument specifies the number of '0's and '1's that should be printed before a white space is inserted. By default, numGroupChars has a value of 8.
ASN-1Step writes the output encoded data to a binary file and expects the input encoded data to be contained within a binary file.
The -autoEncDec option is turned off.
Specifies the name of the text-file containing command-line options for the current invocation of ASN-1Step. This option is useful on systems that do not permit long command lines or do not support command-line continuation characters. Options contained in the file are treated as if they were entered on the command line. The file can consist of several lines; ASN-1Step will read all of them.
The following command invokes ASN-1Step using the command-line tokens contained in the tenLinesOfOptions.opt text file :
asn1step -commandFile tenLinesOfOptions.opt
Command files can contain comments. The "--" characters specify the beginning of a comment. They can be placed anywhere on the line. The comment continues until a subsequent "--" is reached or the line ends.
The -commandFile option is turned off.
Can be used along with the -output option to instruct ASN-1Step to preserve the content of the output file, if it exists. New records will be added to the end of the existing output file when this option is specified.
The -concatenate option is turned off.
The -constraints option instructs ASN-1Step to check constraints.
The -noConstraints option specifies that no constraint checking is done, which results in a slightly faster execution.
The -constraints option is turned on.
Instructs the compiler to convert ASN.1 to or from the Comma-Separated Value (CSV) format. The -csv option can be used with the -allEncode, -encodeValue, -decodePDU, or -test option. You can specify one or more comma-separated flags immediately after the option.
In the following example, -csv is used with -encodeValue. The myCard ASN.1 value is encoded as myCard.csv using CSV column format. OCTET STRING type values without the OSS.PrintFunctionName directive and an OSS conversion function are converted to TBCD. The '=' character is a column separator, and extra CSVs are created for a maximum of 3 components from each SET OF and SEQUENCE OF value.
asn1step bcas.asn -encodeValue myCard -csv tbcd,column,=,3
In the next example, -csv is used with -decodePDU. The input value encoded in CSV is stored in the myCard.csv file, which is decoded using the ascii, noheader, ':' flags. The flags assume that the CSV has a row format, the header is absent, and ':' is used as a column separator. OCTET STRING type values are converted from ASCII to the internal format if they do not have the OSS.PrintFunctionName directive with an OSS conversion function.
asn1step bcas.asn -decodePDU BBCard myCard.csv -csv nohead,ascii,':'
When decoding succeeds, CSVs will not be re-encoded with the same flags. Conversely, when decoding is successful using BER, PER, or other encoding rules, re-encoding is performed.
When decoding fails, ASN-1Step attempts to determine the format of the input .csv file and decode it. If this decoding succeeds, then the .csv file is re-encoded using the flags from the -csv option to create the output myCard.csv file. If it fails, the error from the first decoding is re-issued.
For OCTET STRING type values that do not have the OSS.PrintFunctionName directive with an OSS conversion function, you can select the ASCII, BCD, or TBCD format.
When the OCTET STRING type values have the OSS.PrintFunctionName directive containing an OSS conversion function as a parameter in the input ASN.1 syntax, then the values are always converted to the format related to the function name: BCD, TBCD, ASCII, IP address, or a time stamp format.
Flag names can be truncated.
| CSV Flag | Description |
|---|---|
| ascii | Converts values of OCTET STRING types (that do not have OSS.PrintFunctionName directives with an OSS conversion function) from ASCII when decoding input CSVs and to ASCII when creating output CSVs. |
| column | Indicates that the input or output CSVs are placed on a separate line, possibly following an optional CSV header name and a column separator. |
| bcd | Converts OCTET STRING type values (that do not have the OSS.PrintFunctionName directive with an OSS conversion function) to or from BCD. |
| dashes | Converts GeneralizedTime type values and values of OCTET STRING types that have the OSS.PrintFunctionName directive with the ossPrintOctetAsTimeStamp parameter to or from the following time stamp format: YYYY-MM-DD HH:MM:SS. Example: 2007-11-07 11:36:49 |
| digit | Prints BOOLEAN and ENUMERATED type values as their related integers. |
| noauto | Indicates that open type values are not automatically decoded. If the XER encoding rules are available, open type values are printed in XML. Otherwise, the first available encoding rules are used to handle open type values, either in XML or in hexadecimal format (for binary encoding rules). |
| noheader | Indicates that the CSV header is absent. |
| pduname | Indicates that the header name in the first column has the PDU name prefix. |
| singlenames | Indicates that the CSV header includes single field names for the innermost simple types. |
| slashes | Converts GeneralizedTime type values and values of OCTET STRING types that have the OSS.PrintFunctionName directive with the ossPrintOctetAsTimeStamp parameter to or from the following time stamp format: MM/DD/YY HH:MM:SS. Example: 06/01/00 11:36:49 |
| spaces | Indicates that column separators may have surrounding spaces in the input CSV. Also, when converting to CSV, an extra space character is added before and after the column separator. |
| tbcd | Converts OCTET STRING type values (that do not have the OSS.PrintFunctionName directive with an OSS conversion function) to or from TBCD. |
| text | Indicates that the input or output CSV is a null-terminated string in which Unicode characters are represented as UTF-8 encodings in text format using \x##, a special C-style character sequence. |
| <number> | Identifies the maximum number of components of each SET OF and SEQUENCE OF type values for which an extra CSV should be created. To avoid significant performance degradation, the number is limited to 50. The total number of additional CSVs for each SET OF and SEQUENCE OF type is limited to 50. |
| ':' | Is used as a column separator. |
| '=' | Is used as a column separator. |
| ';' | Is used as a column separator for Windows platforms. |
When -csv is specified without parameters, the following flags are used by default to create CSVs:
ASN.1:
PersonnelRecord ::= SEQUENCE {
name PrintableString,
number INTEGER OPTIONAL,
status BOOLEAN,
children SEQUENCE OF ChildInformation
}
ChildInformation ::= SET {
name PrintableString,
gender ENUMERATED {girl(0), boy(1)},
time GeneralizedTime OPTIONAL
}
value PersonnelRecord ::= {
name "Nancy",
number 201,
status TRUE,
children {
{name "James", gender boy, time "20020312123517"},
{name "Martha", gender girl, time "20100820045240"}
}
}
Command line:
asn1step csvtest.asn -encode value -csv
CSV:
name,number,status,children_name,children_gender,children_time
"Nancy",201,TRUE,"James",boy,20020312123517.000
"Nancy",201,TRUE,"Martha",girl,20100820045240.000
Command line:
asn1step csvtest -encode value -csv 1,=,column,spaces,dashes,pduname
CSV:
PersonnelRecord_name = "Nancy"
number = 201
status = TRUE
children_name = "James"
children_gender = boy
children_time = 2002-03-12 12:35:17
Command line:
asn1step csvtest.asn -encode value -csv noheader,digit,slashes
CSV:
"Nancy",201,1,"James",1,03/12/02 12:35:17
"Nancy",201,1,"Martha",0,08/20/10 04:52:40
The -csv option is turned off.
Specifies the maximum nesting level inside a PDU type, starting from which values of simple types should NOT be included in the output CSV. The -csvMaxLevel option is used to create a subset of a PDU CSV. In most cases, you won't be able to decode this partial CSV. If the specified maximum level cannot include at least one simple type value, the resulting CSV could be empty.
Mod DEFINITIONS AUTOMATIC TAGS ::= BEGIN Seq ::= SEQUENCE {
a SEQUENCE { b BOOLEAN },
c INTEGER,
d IA5String
}
value Seq ::= {
a { b TRUE},
c 10,
d "Test"
}
Command line:
asn1step test -encode value -csv
Output CSV:
a_b,c,d
TRUE,10,"Test"
Command line:
asn1step test.asn -encode value -csv -csvMaxLevel 1
Output CSV:
c,d
10,"Test"
The -csvMaxLevel option is turned off.
Specifies the minimum nesting level inside a PDU type, which is used as a starting point to include simple type values in the output CSV. For the topmost SET, SEQUENCE, or CHOICE types, the deepest level is 0. This option is used to create a subset of a PDU CSV. In most cases, you won't be able to decode this partial CSV because, once some values and separators are skipped, the CSV structure no longer corresponds to the PDU type structure.
Mod DEFINITIONS AUTOMATIC TAGS ::= BEGIN Choice ::= [12] CHOICE {
a SEQUENCE { b BOOLEAN },
c SEQUENCE { d INTEGER }
}
value Choice ::= c : { d 10 }
Command line:
asn1step test.asn -encode value -csv
Output CSV:
a_b,c_d
,10
Command line:
asn1step test.asn -encode value -csv -csvMinLevel 1
Output CSV:
c_d
10
The -csvMinLevel option is turned off.
The -debug option instructs ASN-1Step to issue detailed trace data and error messages. The -noDebug option instructs ASN-1Step to disable tracing and detailed error messages. Disabling such detailed tracing slightly improves CPU performance.
The -debug option is turned on.
Provides greater control over the decoding conducted by ASN-1Step. Specify one or more valid decoding flags, separated by commas or colons, immediately after the option. To disable a flag, precede it by an exclamation point ("!").
The valid decoding flags are:
AUTOMATIC_ENCDEC
DEBUGPDU
DEBUG_ERRORS
DONT_DO_DECODED
DONT_DO_ENCODED
DONT_FREE_ENCODED
IGNORE_DEFER_DECODING
IGNORE_PDU_TAG
NOCONSTRAIN
NOTRAPPING
OSS_RELAXED
OSS_SKIP_UNKNOWN_CONTENT
OSS_TRAPPING
STRICT_CONSTRAINT_CHECKING
STRICT_ENCODING_DECODING_RULES
USE_COMPRESSION
Instructs ASN-1Step to decode the PDU defined in the input ASN.1 specification, given its encoding in a separate file. The name of this file can appear before or after the -decodePdu option on the command line.
The -decodePdu option requires an argument that names the PDU in your ASN.1 specification to which the input encoding pertains. For example, you can first use the -listPduId option to learn the names and numbers of the PDUs available for encoding/decoding. Then, you can specify this name or number as an argument to -decodePdu:
asn1step bcas.asn -decodePdu BBCard myCard.xer
Unless PER is used or the input syntax contains PDUs with non-unique tags, ASN-1Step can determine the PDU name or number by specifying the 0 argument:
asn1step bcas.asn -decodePdu 0 myCard.ber
Automatic determination of the PDU number is possible only when the input ASN.1 syntax has unique PDU tags and PER (Aligned or Unaligned) is not used.
ASN-1Step can also decode multiple concatenated PDUs contained within a single input encoding file. It will decode all messages contained in the input file, but all such concatenated messages must be encoded with the same encoding rules.
If the input file contains concatenated messages that pertain to various PDUs, the default decodePdu 0 option enables decoding of such messages. To use this feature, your ASN.1 specification must have unique PDU tags and the encoding rules in use cannot be PER (Aligned or Unaligned).
The inputFilename filename extension determines which encoding rules are used to decode the value:
You can re-encode an input encoding using a different set of encoding rules by specifying one of the available encoding rules options. For example:
asn1step bcas.asn -decodePdu BBCard myCard.ber -per
will re-encode the BER-encoded myCard value using Aligned PER. The output PER encoding will be written to a file named myCard.ber.per. Use the -output option to specify a different name for the output encoding file; if multiple input encoding files are specified, only the output file produced from the first input file will have its name affected.
ASN-1Step can create concatenated records when re-encoding several input files. When -decodePdu and -output are specified and re-encoding or value notation creation is requested, all records encoded with the same encoding rules and all values are added into the same file. The filename prefix is derived from the parameter specified in the -output option, and the extension is derived from the encoding rule or is .txt for value notation. If the -concatenate option is specified and the output file already exists, the new records are appended at the end of the existing output file.
ASN-1Step supports the Comma-Separated Value (CSV) format. Note that -decodePDU behaves differently when used with an input .csv file and the -csv <flags> option compared to the other encoding rules.
Use the -csv <flags> option to
-decodePdu 0 is assumed when ASN-1Step encounters input encoding files on the command line and no option is specified.
Allows ASN-1Step trial users to better experience the capabilities of ASN-1Step by accessing the built-in Bcas or PersonnelRecord sample ASN.1 specifications.
Specify the -demo option followed by either the Bcas or PersonnelRecord argument, then specify any ASN-1Step option to try out the various features of ASN-1Step.
List the available value references in the Bcas specification by entering the following:
asn1step -demo Bcas -valueRefTable
Output
ASN1STEP: List of valid valuereferences and associated PDU numbers:
1 myCard
Now encode the available value reference using PER:
asn1step -demo Bcas -encodeValue myCard -per
Output
ASN1STEP: Encoding of valuereference 'myCard' for PDU #1:
Encoding to the file 'myCard.per' using PER ALIGNED encoding rule...
BBCard SEQUENCE [fieldcount (not encoded) = 6]
name IA5String [length = 5.0]
"Casey"
team IA5String [length = 13.0]
"Mudville Nine"
age INTEGER [length (not encoded) = 0.7]
32
position IA5String [length = 10.0]
"left field"
handedness ENUMERATED [length (not encoded) = 0.2]
2
batting-average REAL [length = 3.0]
1 * 2^-2
Total encoded length = 37.0
Encoded successfully in 37 bytes:
10436173 6579304D 75647669 6C6C6520 4E696E65 3E486C65 66742066 69656C64
800380FE 01
Next, analyze and decode the encoded data file as follows:
asn1step -demo Bcas -decodePdu BBCard myCard.per
Output
ASN1STEP: Decoding PDU #1 from file 'myCard.per':
rec1value BBCard ::=
{
--TYPE INFORMATION: SEQUENCE
--OFFSET: 0,0
name "Casey",
--TYPE INFORMATION: IA5String (SIZE(1..60))
--OFFSET: 0,0; LENGTH: 6,0
--length: <.000100> (decoded as 5)
--padding: <00>
--contents: .43.61.73.65.79
team "Mudville Nine",
--TYPE INFORMATION: IA5String (SIZE(1..60))
--OFFSET: 6,0; LENGTH: 14,0
--length: <.001100> (decoded as 13)
--padding: <00>
--contents: .4D.75.64.76.69.6C.6C.65.20.4E.69.6E.65
age 32,
--TYPE INFORMATION: INTEGER (1..100)
--OFFSET: 20,0; LENGTH: 0,7
--contents: <.0011111>
position "left field",
--TYPE INFORMATION: IA5String (SIZE(1..60))
--OFFSET: 20,7; LENGTH: 11,1
--length: <0.01001> (decoded as 10)
--padding: <000>
--contents: .6C.65.66.74.20.66.69.65.6C.64
handedness ambidextrous,
--TYPE INFORMATION: ENUMERATED {left-handed,right-handed,ambidextrous}
--OFFSET: 32,0; LENGTH: 0,2
--contents: <.10>
batting-average { mantissa 1, base 2, exponent -2 }
--TYPE INFORMATION: REAL
--OFFSET: 32,2; LENGTH: 4,6
--padding: <000000>
--length: .03 (decoded as 3)
--type of real number encoding: .80
--exponent: .FE
--mantissa: .01
}
--TOTAL LENGTH: 37,0
Successfully decoded 37 bytes.
rec1value BBCard ::=
{
name "Casey",
team "Mudville Nine",
age 32,
position "left field",
handedness ambidextrous,
batting-average { mantissa 1, base 2, exponent -2 }
}
For your reference, following are the Bcas and PersonnelRecord ASN.1 specifications.
Bcas
Bcas DEFINITIONS ::= BEGIN
BBCard ::= SEQUENCE {
name IA5String (SIZE (1..60)),
team IA5String (SIZE (1..60)),
age INTEGER (1..100),
position IA5String (SIZE (1..60)),
handedness ENUMERATED
{left-handed(0), right-handed(1), ambidextrous(2)},
batting-average REAL
}
myCard BBCard ::= {
name "Casey",
team "Mudville Nine",
age 32,
position "left field",
handedness ambidextrous,
batting-average {250, 10, -3}
}
END
PersonnelRecord
EmployeeRecord DEFINITIONS ::= BEGIN
PersonnelRecord ::= [APPLICATION 0] SET {
name Name,
title [0] VisibleString,
number EmployeeNumber,
dateOfHire [1] Date,
nameOfSpouse [2] Name,
children SEQUENCE OF ChildInformation DEFAULT {}
}
ChildInformation ::= SET {
name Name,
dateOfBirth Date
}
Name ::= [APPLICATION 1] SEQUENCE{
givenName VisibleString,
initial VisibleString,
familyName VisibleString
}
EmployeeNumber ::= [APPLICATION 2] INTEGER
Date ::= [APPLICATION 3] VisibleString -- YYYY MMDD
personnelRecord PersonnelRecord ::= {
name {givenName "John", initial "P", familyName "Smith"},
title "Director",
number 51,
dateOfHire "19710917",
nameOfSpouse {givenName "Mary", initial "T", familyName "Smith"},
children
{
{name {givenName "Ralph", initial "T", familyName "Smith"},
dateOfBirth "19571111"},
{name {givenName "Susan", initial "B", familyName "Jones"},
dateOfBirth "19590717"}
}
}
END
The -demo option is turned off.
Instructs ASN-1Step to generate additional warning messages for protocol designers writing ASN.1 specifications.
Additional warning messages are issued in the following situations:
The -designerWarnings option is turned off.
Instructs ASN-1Step to generate multiple Data Type Definitions (DTD) files, one for each PDU. Normally, a separate DTD file is not produced, even when the XML encoding rules (XER) are requested.
The DTD filenames will be the same as the PDU type names, with the .dtd suffix added.
When -encodeValue is specified, ASN-1Step can generate a reference for your DTD when producing its XML output for a particular PDU. Just pass the desired .dtd file on the ASN-1Step command line.
asn1step bcas.asn -xer -encodeValue myValue ValueType.dtd
Only one .dtd file is allowed per invocation of ASN-1Step. When multiple -encodeValue options are used, the .dtd specified is used in the XER encoding of the last value reference.
NOTE: To have ASN-1Step generate a system reference to your DTD, leave the filename extension as .dtd. To have ASN-1Step generate a public reference to your DTD, change the filename extension to .pdtd.
The -dtd option is turned off.
Provides greater control over the encoding conducted by ASN-1Step. Specify one or more valid encoding flags, separated by commas or colons, immediately after the option. To disable a flag, precede it by an exclamation point ("!").
The valid encoding flags are:
AUTOMATIC_ENCDEC
BACK_ALIGN
COMPACT_XER_ENCODING
DEBUGPDU
DEBUG_ERRORS
DEFAULT_ALIGN
DEFINITE
DETERMINE_ENC_LENGTH
DONT_DO_DECODED
DONT_DO_ENCODED
DONT_OPTIMIZE_XMLNS
FRONT_ALIGN
IGNORE_DEFER_DECODING
INDEFINITE
NOCONSTRAIN
NOTRAPPING
NO_XML_DECLARATION
OSS_AUTO_ENCODE_WITHOUT_CHECKING_CONSTRAINT
OSS_RELAXED
OSS_TRAPPING
RELAY_OPEN_TYPE_IN_HEX
STRICT_CONSTRAINT_CHECKING
STRICT_PER_ENCODING_OF_DEFAULT_VALUES
USE_COMPRESSION
Instructs ASN-1Step to encode the valuereference specified in the input ASN.1 specification. Trace data produced during encoding is also printed to standard output when this option is in use.
Encode values in a text file
In addition to encoding value references specified directly in the input ASN.1 syntax, you can encode one or more values included in a separate text file whose name is passed to -encodeValue as a parameter. The file may contain one or more ASN.1 values in the form
<valueName> <PduTypeName> ::= <value_notation>
or simply
<value_notation>
In the latter case, you must include a PDU identifier (pduId) along with the text file name in the parameter passed to the -encodeValue option.
For example, to encode the ASN.1 value from the valueFile.txt input file to the outFile.per output file using packed encoding rules, specify
asn1step syntax.asn -encodeValue valueFile.txt outFile.per
where syntax.asn includes
Mod DEFINITIONS ::= BEGIN
MyStr ::= IA5String
END
valueFile.txt:
value MyStr ::= "Hello World!"
Output
ASN1STEP: Encoding of value notation from 'valueFile.txt' for PDU #1: Encoding to the file 'outFile.per' using PER ALIGNED encoding rule... MyStr IA5String [length = 12.0] "Hello World!" Total encoded length = 13.0 Encoded successfully in 13 bytes: 0C48656C 6C6F2057 6F726C64 21
The following command encodes the ASN.1 value in valueFile.txt with all available encoding rules. A valueFile.txt.* file is generated for each set of encoding rules, where * is the file extension derived from the encoding rules.
asn1step syntax.asn -encodeValue valueFile.txt
outputFileName
The output filename specifies where the encoded data will be written. It can appear before or after the -encodeValue option on the command line. Also, the filename extension determines which encoding rules are used to encode the value:
Specify specific encoding rules
Specify an encoding rules option along with the -encodeValue keyword to instruct ASN-1Step to encode the named value or one or more values from the input text file using the specified encoding rules. The output encoding file will have a name that is derived from the value or text file to be encoded. For example, to encode a value named myValue using DER, just specify
asn1step syntax.asn -encodeValue myValue -der
ASN-1Step will create a DER-encoding of myValue in the file myValue.der.
To encode a PDU type value with a PDU id of "1" (obtained with -listPduIdentifiers) from valueFile.txt using DER, just specify
asn1step syntax.asn -encodeValue 1,valueFile.txt -der
ASN-1Step will create a DER-encoding of that value in the myValue.der file.
Use optional flags
When used in conjunction with -encodeValue, the -xer, -cxer, or -exer option can be followed by the optional COMPACT_XER_ENCODING, NO_XML_DECLARATION, and DONT_OPTIMIZE_XMLNS flags. When specifying two or more flags, separate them with a comma (",") or colon (":"), for example,
asn1step syntax.asn -encodeValue val -xer COMPACT_XER_ENCODING:NO_XML_DECLARATION
Create concatenated records
ASN-1Step can create concatenated records when encoding several value references at once. When several -encodeValue options are specified with one or more encoding rule options along with the -output<prefix> option, ASN-1Step encodes all specified value references using the specified encoding rules and creates one or more output encoding files. The filenames will have the same prefix as the prefix parameter and the file extensions will be derived from the encoding rules used to encode the values. In addition, if the -concatenate option is specified and the output file already exists, the new records are appended to the content of the output file. In this case, you must make sure that the concatenated records belong to the same PDU. Otherwise, if records were created using PER encoding rules or if the syntax has non-unique PDU tags the decoder will not be able to automatically decode all concatenated messages.
By default, this option is turned off and ASN-1Step only performs a syntax check on the input files.
Redirects ASN-1Step error, warning, and informatory messages to a named error file. This is useful on platforms that do not have a simple mechanism for redirecting stdout and stderr to a file.
If an error is detected on the command line before the -errorFile option, the message is written to stdout instead of to the error file. List the -errorFile option first on the command line (as shown below) so that all messages resulting from errors on the command line are written to the error file:
asn1step -err myerrs.err foo.asn -test
A suffix of .err is appended to errorFilename if it does not already have an extension. If errorFilename has an extension of .asn, it is replaced with .err; otherwise, errorFilename will keep the extension that you specify. Note that existing error-files with the same name as that specified will be overwritten by a new invocation of ASN-1Step.
The -errorFile option is turned off.
Offers greater control over the encoding and decoding conducted by ASN-1Step. Specify one or more valid common encoding and decoding flags, separated by commas or colons, immediately after the option. To disable a flag, precede it by an exclamation point ("!").
You can find a list of valid common encoding and decoding flags in the -decFlags and -encFlags sections.
Controls the indentation size for a JSON encoding generated by ASN-1Step. Specify a positive integer argument immediately after this option. A negative integer (-1, for example) enables compact encoding mode.
The encoder indents two spaces.
Specifies that BER, DER, PER (Aligned or Unaligned), OER, or C-OER encoded data will be read or written to a text file that contains hexadecimal characters (i.e., '0' to 'F').
The optional numGroupChars argument specifies the number (in the range of 1 to 72) of hexadecimal characters that should be printed before a white space is inserted. By default, numGroupChars has a value of 8.
The following command, issued for samples/sample.asn,
asn1step sample.asn sample.ber -hex -encodeValue myName
will produce a text file named sample.ber that contains
16034F53 53
ASN-1Step writes the output encoded data to a binary file and expects the input encoded data to be contained within a binary file.
Displays a summary of all valid command-line options.
By entering asn1step -help you can obtain a summary of valid command-line options:
OSS ASN-1Step Version 8.2
Copyright (C) 2017 OSS Nokalva, Inc. All rights reserved.
Compiler parameters: (.D. indicates default)
<input> <...input> . one or more ASN.1 input files
<pdufile.<ber|per|der|uper|xer|cxer|cer|exer|oer|coer|json|csv|cdr> <...>
... one or more files containing encoded PDUs (binary by
default), suffixes determine encoding rules
-demo <Bcas|PersonnelRecord>
... run pre-defined ASN.1 syntax Bcas or PersonnelRecord
-syntax ... perform syntax checking only
-output name ... generate XSL/DTD files at specified location or use name
as the prefix in file names to store re-encoded values
-nooutput ... do not generate output encoded files
-tracefile file ... write encoder/decoder information to 'file'
-notrace ... do not print encoder/decoder tracing information
-printper flags ... configure PER analyzer output
-setnesting limit... nesting limit for decoding SET or SEQUENCE types
-stringnest limit... nesting limit for decoding constructed strings
-errorfile file ... write all messages to 'file' instead of stdout/stderr
-uniquepdu .D. check that pdu id's are unique
-nouniquepdu ... do not check that pdu id's are unique
-useXmlNames ... generates C type and field names according to E-XER
"NAME" encoding instructions
-hexchar <grpDigits>
... read input encoding from or write output encoding to
a text file with hexadecimal characters, <grpDigits>
specifies a digit-spacing format for the output
-binchar <grpDigits>
... read input encoding from or write output encoding to
a text file with binary characters, <grpDigits>
specifies a digit-spacing format for the output
-constraints .D. check constraints at runtime
-restrictedConstraintChecking
... do not ignore the OSS.NoConstrain directive
when -constraints is specified
-noconstraints ... do not check constraints at runtime
-relaxper ... ignore minor PER violations on decode
-norelaxper .D. input PER-encoded PDU must strictly conform to PER
-relaxber ... ignore minor BER violations on decode
-norelaxber .D. input BER-encoded PDU must strictly conform to BER
-test ... test encoding/decoding of all ASN.1 valuereferences
-notest .D. do not test encoding/decoding of all ASN.1 values
-debug .D. issue detailed trace data and error messages
-nodebug ... do not issue detailed trace data and error messages
to slightly improve CPU performance
-decodepdu <pduId|pduTypeName>
... decode all PDU files using a PDU id or a type name
-allencode ... encode all valuereference from input ASN.1 file
-encodevalue <valuereference|[pduId,]inFileName>
... encode specified valuereference from input ASN.1 file
or encode one or more value notations from input text
file using specified PDU id
-concatenate ... concatenate one or more new encoded records to the
content of the output file whose prefix is specified
in the -output option
-listpduid [true]... print table of PDU numbers available for decoding,
<true> prints numbers of unreferenced PDU types and
some types marked with PDU directives
-valuereftable ... print table of valuereferences available for encoding
-sampleAsn1Value <pduTypeName>[,[<flags>][,<outFileName>]]
... create sample value for the specified PDU type from
ASN.1 input
-allSampleAsn1Values [[<flags>][,<outFileName>]]
-warning ... allow warning messages
-nowarning ... suppress warning messages
-suppress msg# ... suppress a specific message
-ignoresuppress ... ignore the SUPPRESS directive (display all messages)
-verbose ... display compilation progress messages
-noverbose .D. do not display compilation progress messages
-pedantic ... rigorously check all modules
-nopedantic .D. rigorously check only the root module(s)
-relaxedMode .D. automatically select command-line options that
result in relaxed compiler behavior, for example,
-allowBadValue, -noWarning, etc.
-norelaxedMode ... automatically select command-line options that
result in strict compiler behavior
-informatory ... allow informatory messages
-noinformatory ... suppress informatory messages
-ignoreError msg#... ignore a specific error (issue a warning instead)
-designerWarnings... issue additional warnings for protocol designers
-allow badcase ... allow slight deviations from the ASN.1 standard
-1990 ... all modules conform to 1990 ASN.1 syntax
-2015 ... all modules conform to 2015 ASN.1 syntax
-per .D. use Aligned PER to encode and decode PDUs
-uper .D. use Unaligned PER to encode and decode PDUs
-ber .D. use BER to encode and decode PDUs
-der .D. use DER to encode and decode PDUs
-xer <flags> .D. use XER to encode and decode PDUs using specified flags
-cxer .D. use Canonical XER to encode and decode PDUs
-cer .D. use CER to encode and decode PDUs
-exer <flags> .D. use EXTENDED XER to decode and to encode with specified
flags separated by ':' or ','; supported flags are
NO_XML_DECLARATION, COMPACT_XML_ENCODING,
DONT_OPTIMIZE_XMLNS
-oer .D. use OER to encode and decode PDUs
-coer .D. use Canonical OER to encode and decode PDUs
-json <flags> .D. use JSON to encode and decode PDUs using specified flags
-csv <flags> ... use CSV format to encode and decode PDUs with optional
flags separated by ',':
<';'|':'|'='> ... alternative column separators
<'noheader'| ... do not print CSV header or
'singlename'> ... print a compact CSV header
'text' ... do not use UTF-8 file format for CSV
with Unicode characters
'column' ... print values on separate lines
'spaces' ... add spaces around column separators
'pduname' ... add a PDU name to the first header name
<num> ... maximum number of additional CSVs for
SET OF and SEQUENCE OF
'digit' ... print numbers for BOOLEAN and ENUMERATED
'noauto' ... print Open Type values in XML or hex
<'ascii'|
'bcd'|'tbcd'> ... format for OCTET STRING values
<'dashes'|
'slashes'> ... format for GeneralizedTime values
-csvMinLevel lvl ... include in the CSV only those simple type values
that are nested at the specified level or deeper
-csvMaxLevel lvl ... include in the CSV only those simple type values
that are nested not deeper than the specified level
-jsonIndent indent ... use given indentation for JSON output
-commandfile <file> ... read command line from 'file'
-root ... treat all modules as root modules
-pdusforopentypes... ignore NOPDU directive for opentypes
-nopdusforopen ... do not generate PDUs for info objects with -noconstraints
-allowbadvalues ... allow generation of bad values
-relaySafe .D. retain unrecognized extension additions at runtime
-norelaySafe ... do not retain unrecognized extension additions at runtime
-autoencdec ... permit automatic encoding/decoding even if -noconstraint
is used
-messageFormat <format>
... display error messages in <format>:
'oss', 'emacs' or 'msvc'
-asn1value ... generate ASN.1 value notation in text file when decoding
-xsl ... generate default stylesheet for each PDU
-dtd ... generate document type definition file for each PDU
<file.xsl> ... XSL stylesheet file for XER encoder
<file.dtd> ... system DTD file for XER encoder
<file.pdtd> ... public DTD file for XER encoder
-assignments ... process type and value assignments defined outside
ASN.1 modules
-pdusforcontainingtypes
... ignore NOPDU directive for types referenced by a
contents constraint
-nopdusforcontainingtypes
... do not generate PDUs for types referenced by a
contents constraint
-ignoreIncompleteItems
... ignore incomplete ASN.1 definitions of types and values
-ignoreRedefinedAssignments
... ignore redefined ASN.1 definitions of types and values
-truncatePrintedStrings num#
... truncates long prited strings at the position
specified by the <num>
-flags ... instruct the encoder and decoder to use flags separated
by ':' or ','; to turn off a flag, precede it by '!'
-encflags ... instruct the encoder to use the flags separated
by ':' or ','; to turn off a flag, precede it by '!'
-decflags ... instruct the decoder to use the flags separated
by ':' or ','; to turn off a flag, precede it by '!'
-offset num ... find the first record to decode at offset 'num'
in the input encoding
-recordOffset num .. start decoding at offset 'num' inside each record
-noCDRHeadersDetection
... do not automatically detect and skip CDR headers
You can obtain a synopsis of the command-line syntax by entering asn1step with no arguments:
> asn1step
OSS ASN-1Step Version 8.2
Copyright (C) 2017 OSS Nokalva, Inc. All rights reserved.
asn1step <infile(s)> [<inASN1file(s)> | -demo <Bcas | PersonnelRecord>]
[-ber ] [-root] [-1990 | -2015 ] [-constrain | -noconstrain ]
[-der ] [-test | -notest ] [-unique | -nounique ]
[-cer ] [-warn | -nowarn ] [-verbose | -noverbose ]
[-per ] [-debug | -nodebug ] [-pedantic | -nopedantic ]
[-uper] [-assignments ] [-relaxper | -norelaxper ]
[-oer ] [-suppress msg# ] [-binchar <grpDigits> ]
[-coer] [-ignoresuppress ] [-relaxber | -norelaxber ]
[-xer <flags>] [-pdusforopentypes ] [-out <path> | -nooutput ]
[-exer <flags>] [-nopdusforopentype] [-messageFormat <format> ]
[-cxer] [-notrace | -tracefile <tracefile> ]
[-csv <flags>] [-csvMinLevel level] [-csvMaxLevel <level> ]
[-json <flags>] [-jsonIndent <indent>]
[-asn1value ] [-printper flags] [-commandfile <commandfile> ]
[-dtd ] [-xsl ] [-allowbadvalues ] [-inform | -noinform ]
[-ignoreError message# ] [-hexchar <grpDigits> ]
[-autoencdec ] [-designerWarnings ] [-errorfile <errorfile> ]
[-listpduid ] [-ignoreIncomplete ] [-decodepdu <pduId|pduName>]
[-syntax ] [-pdusforcontainingtypes] [-nopdusforcontainingtypes]
[-allencode ] [-valueRefTable] [-encodevalue <valRef|[pduId,]valfile>]
[-concatenate ] [-setNesting limit] [-restrictedConstraintChecking ]
[-relaxedMode |-norelaxedMode ] [-allow <badcase argument> ]
[-relaySafe |-norelaySafe ] [-ignoreRedefinedAssignments ]
[-sampleAsn1Value|-allSampleAsn1Values] [-stringNesting lmt ]
[-flags <flags>] [-encflags <flags>] [-decflags <flags> ]
[-offset num ] [-recordOffset num ] [-noCDRHeadersDetection ]
[-truncatePrintedStrings num ]
enter "asn1step -help" for more information
Command-line help is not displayed when input files are specified.
Instructs ASN-1Step to treat certain error message numbers, specified by errorNumber, as warnings instead. Use this option to test the encoding and decoding of PDUs without correcting your ASN.1 specification. However, be aware that the values used are invalid according to the ASN.1 standard.
The current version of ASN-1Step can ignore only the following message numbers: 49, 76, 77, 305, 319, 811, 832, 1078, 1130, 1162, 1207, and 1211.
All the above errors are ignored via the default -relaxedMode option.
Instructs ASN-1Step to treat certain errors related to undefined ASN.1 types and values as warnings, and to ignore incomplete ASN.1 definitions that directly or indirectly reference undefined ASN.1 types or values. This allows you to check PDUs that are fully defined even when the input syntax contains some undefined ASN.1 definitions.
ASN.1 types that are referenced only by ignored incomplete types are still not considered to be PDUs by ASN-1Step, unless the global or local PDU directive is applied.
Use the -verbose option along with -ignoreIncompleteItems to see the incomplete items that ASN-1Step ignored.
M DEFINITIONS ::= BEGIN
A ::= SEQUENCE {
a1 A1,
a2 A2,
b B1
}
A1 ::= INTEGER
A2 ::= BOOLEAN
B ::= REAL
END
In the test.asn example above, type reference A references type B1, which is undefined.
Output of the "asn1step test.asn -noRelaxedMode" command:
"test.asn", line 5 (M): A0256W: 'B1' is referenced, but is not defined. "test.asn", line 5 (M): A0052E: 'B1' is not defined. C0043I: 1 error message, 1 warning message and 0 informatory messages issued.
Partial output of the "asn1step test.asn -ignoreIncompleteItems -verbose" command:
C0284I: Syntax checking file 'test.asn'. "test.asn", line 5 (M): A0256W: 'B1' is referenced, but is not defined. "test.asn", line 2 (M): C1215W: The definition of the type identified by the absolute reference 'M.A' is incomplete and will be ignored. C0285I: Global checking abstract syntax. C0043I: 0 error messages, 2 warning messages and 3 informatory messages issued.
NOTE: The "asn1step test.asn" command gives the same result as "asn1step test.asn -ignoreIncompleteItems" because -relaxedMode is turned on by default, which implies -ignoreIncompleteItems.
The -ignoreIncompleteItems option is implied by the default -relaxedMode option and is turned off if -noRelaxedMode is specified.
Instructs ASN-1Step to treat some errors caused by incorrectly redefined ASN.1 types and values as warnings, and to ignore all duplicate definitions within the same ASN.1 module.
M DEFINITIONS ::= BEGIN Type ::= INTEGER Type ::= INTEGER END
In the test.asn example above, Type is defined twice in the same ASN.1 module, which is normally invalid ASN.1.
The "asn1step test.asn -noRelaxedMode" command without -ignoreRedefinedAssignments results in these errors:
"test.asn", line 3 (M): A0146E: Type 'Type' is illegally redefined.
Type ::= INTEGER
^
C0043I: 1 error message, 0 warning messages and 0 informatory messages issued.
The "asn1step test.asn -ignoreRedefinedAssignments" command results in the following:
C1310I: No critical errors found, but message(s) were suppressed due to the compiler's default permissive mode. Compile with -noRelaxedMode to see all messages. C0245I: 1 warning message suppressed, 0 informatory messages suppressed. To see the suppressed messages use the option -warningMessages. C0043I: 0 error messages, 0 warning messages and 1 informatory message issued.
NOTE: The command "asn1step test.asn" gives the same result as "asn1step test.asn -ignoreRedefinedAssignments" because -relaxedMode is turned on by default, which implies -ignoreRedefinedAssignments.
The -ignoreRedefinedAssignments option is implied by the default -relaxedMode option.
Instructs ASN-1Step to ignore any OSS.SUPPRESS directives within an ASN.1 module definition. So, if the module definition contains an OSS.SUPPRESS directive, but the -ignoreSuppress option is specified, messages will not be suppressed.
All messages identified by the OSS.SUPPRESS directive are suppressed.
Specifies whether ASN-1Step should generate informatory messages.
When either -relaxedMode or -noWarningMessages is specified, the -noInformatoryMessages option is implied.
When either -norelaxedMode or -warningMessages is specified, the -informatoryMessages option is implied.
The order in which -informatoryMessages | -noInformatoryMessages, -warningMessages | -noWarningMessages, and -relaxedMode | -noRelaxedMode appear on the command line is important. The rightmost option is enforced, which overrides any effects of the previous options.
The -noInformatoryMessages option is implied via the default -relaxedMode option.
Instructs ASN-1Step to display a table of the PDUs available for decoding in the input ASN.1 specification.
The option accepts the optional true parameter that instructs ASN-1Step to display only a subset of unreferenced ("true") PDU type names and some types marked with the PDU directive.
If the -noDebug option is specified along with -listPduIdentifiers, only available PDU numbers are printed, all PDU identifiers are printed as <anonymous>.
--<OSS.PDU Mod.P>--
Mod DEFINITIONS AUTOMATIC TAGS ::= BEGIN
P ::= SEQUENCE {
id PCLASS.&id ({P-Set}),
value PCLASS.&Type ({P-Set}{@id})
}
PCLASS ::= CLASS {
&id INTEGER UNIQUE,
&Type
}
P-Set PCLASS ::= { {&id 1, &Type VisibleString} | {&id 2, &Type P} }
I ::= INTEGER
END
The command line "asn1step test.asn -listPduId" results in the following:
ASN1STEP: List of valid PDU numbers and associated PDU names:
1 P
2 I
3 P-Set-VisibleString
The command line "asn1step test.asn -listPduId true" results in the following:
ASN1STEP: List of valid unreferenced and/or user-defined PDU numbers and associated PDU names:
1 P
2 I
The -listPduIdentifiers option is turned off.
Sets the format of the error, warning, and informatory messages issued by ASN-1Step. A mandatory parameter specifies which format scheme is used.
Two format schemes are available:
"filename.asn", line [(moduleName)]: code: messageExample:
"msgfmt.asn", line 7 (Module-10): A0217W: The identifier 'address' is missing from the value and is assumed.
mySeq Seq ::= {int 5, bool TRUE, "350 5th Avenue"}
^
filename.asn:[moduleName:]line:[position:] code: messageExample:
msgfmt.asn:Module-10:7:38: A0217W: The identifier 'address' is missing from the value and is assumed.
You can feed the second format scheme to a parser or compatible text editor to help automatically find the location in the input file where the message was issued.
Instructs ASN-1Step to suppress automatic detection and skip CDR headers for certain file formats.
The following file formats are supported:
The -noCDRHeadersDetection option is turned off.
Instructs ASN-1Step to locate the first record to decode by skipping num bytes at the beginning of the input encoding.
If the input file contains an encoding in text, binary, or hexadecimal format, num bytes is calculated after skipping any number of spaces between digits and after converting from text to binary format.
The -offset option can be used to skip the 3GPP header (included in CDR files) that occupies 50 or 54 bytes. For CDR files, if you use the -offset option with the -recordOffset recNum option, ASN-1Step will skip a CDR header that occupies 4 bytes at the beginning of each record.
Skip 100 bytes at the beginning of text.ber and start decoding:
asn1step test.asn test.ber -offset 100
Start decoding the first record at offset 54 and the next records at offset 4:
asn1step test.asn -decode PduName test.ber -offset 50 -recordOffset 4
-offset is turned off; however, ASN-1Step automatically tries to detect and skip CDR headers in the input file with BER-based encoded messages.
The following file formats are supported:
To suppress automatic detection, use the -noCDRHeadersDetection command-line option.
Specifies where output files are generated.
The -output option also permits you to choose a filename prefix for output files containing re-encoded values created by the -decodeValue option or values in the ASN.1 value format created by the -asn1Value option. However, if multiple separate input files are present only the output file corresponding to the first input file will have its name affected.
You can also choose a filename prefix for output files containing encoded values created by the -encodeValue or -allEncode options. Also, if multiple separate input files are present when a re-encoding action is requested, all records created with the same encoding rule are concatenated in the same output file with the extension corresponding to this encoding rule. In addition, if the -concatenate option is specified and the output file already exists, the new records are appended at the end of the existing output file.
The -noOutput option instructs ASN-1Step to suppress all output other than error messages.
asn1step -encodeValue valueName syntax.asn -ber -output C:\MyAsn1
ASN-1Step places its output files in the present working directory.
The -pdusForContainingTypes option instructs ASN-1Step to always treat types referenced by contents constraints as PDUs.
The -noPdusForContainingTypes option instructs ASN-1Step to not assign PDU numbers to types referenced by contents constraints. In this case, the automatic encoding or decoding of BIT STRING and OCTET STRING types defined with CONTAINING will not be performed.
Both options are turned off.
These options tell ASN-1Step whether to treat open types created by either the ASN1.DeferDecoding or OSS.ENCODABLE directive as PDUs.
When -pdusForOpenTypes is used, open types created by any of the ways listed below are treated as PDUs, even when the OSS.NOPDU directive is specified (globally or locally):
When -noPdusForOpenTypes is used, the compiler does not generate PDU numbers for any open types. For ASN.1 notations with a large number of PDU types, this option can help to prevent the following ASN.1 compiler error:
C0923E: Implementation limit exceeded; too many fields in module.
The -noPdusForOpenTypes option can only be used together with the -noConstraints option, otherwise it will be ignored.
Both the -pdusForOpenTypes and -noPdusForOpenTypes options are turned off, and only unreferenced types can become PDUs.
Instructs ASN-1Step to thoroughly check the entire abstract syntax.
The -pedantic option specifies that the entire abstract syntax is to be thoroughly syntax checked. Normally ASN-1Step does not consider it an error if a type is referenced but never defined, so long as it is neither directly nor indirectly referenced by the root modules. The -pedantic option implies the -syntaxOnly option, so no values are encoded or decoded; only a syntax check is performed.
The -pedantic option is turned off, -noPedantic is implied.
Offers greater control over the output PER analysis conducted by ASN-1Step.
You must specify one or more valid PER analyzer flags, separated by commas or colons, immediately after this option.
The valid flags and their descriptions are listed in the following table:
| PER Analysis Flag | Description |
|---|---|
| OSS_ASN_ONLY | Print ASN.1 value notation only |
| OSS_HEXBYTES | Print full bytes with hexadecimal notation |
| OSS_SEPARATE_ASN | Separate ASN.1 values |
| OSS_NOBRACES | Do not print braces |
| OSS_PRINT_ABSREF | Print absolute references for sub-fields |
| OSS_PRINT_OFFSET | Print length and offset for sub-fields |
| OSS_PRINT_NUMBERS | Print indentation level numbers |
| OSS_PRINT_TYPE_INFO | Print ASN.1 type information |
| OSS_PRINT_COMMENTS | Print additional comments |
The following PER analyzer flags are used: OSS_PRINT_OFFSET, OSS_HEXBYTES, OSS_PRINT_TYPE_INFO, OSS_PRINT_COMMENTS
Instructs ASN-1Step to start decoding by skipping
If the input file contains an encoding in text, binary, or hexadecimal format, num bytes is calculated after skipping any number of spaces between digits and after converting from text to binary format.
The -recordOffset option can be used along with the -offset num option, which instructs ASN-1Step to find the first record to decode at -offset num at the beginning of the input encoding.
Start decoding each record at offset 10:
asn1step test.asn test.ber -recordOffset 10
Start decoding the first record at offset 54 and the next records at offset 4:
asn1step test.asn -decode PduName test.ber -offset 50 -recordOffset 4
-recordOffset is turned off; however, ASN-1Step automatically tries to detect and skip CDR headers in the input file with BER-based encoded messages.
The following file formats are supported:
To suppress automatic detection, use the -noCDRHeadersDetection command-line option.
Automatically selects command-line options that result in relaxed or strict compiler behavior.
When -relaxedMode is specified, these options are automatically enabled:
Some significant warning messages are not suppressed when -relaxedMode is used. Use the -noWarningMessages option to suppress all warnings.
-norelaxedMode cancels the options enabled by -relaxedMode and implies the -warningMessages option.
To enable warning or informatory messages when -relaxedMode is specified, specify -warningMessages or -informatoryMessages after -relaxedMode on the command line.
To disable warning or informatory messages when -norelaxedMode is specified, specify -noWarningMessages or -noInformatoryMessages after -norelaxedMode on the command line.
The -relaxedMode option is turned on.
The -relaxBER option instructs ASN-1Step to silently ignore minor violations to the BER standard while decoding an encoding.
-relaxBER instructs ASN-1Step to silently ignore the following types of violations:
I ::= INTEGER (0..MAX)and the following encoding of a 123 decimal value is passed to the BER decoder
0x02, 0x03, 0x80, 0x00, 0x7bthe decoder normally issues an error message saying that a negative unsigned integer was encountered, which is in strict accordance with the ITU-T Standards. Now, if the -relaxBER option is specified, the decoder decodes the above encoding silently as if it were
0x02, 0x04, 0x00, 0x80, 0x00, 0x7b
0x02, 0x03, 0x00, 0x00, 0x7bthe decoder normally complains that the integer value encoding is unnecessary long, which is in strict accordance with the Standards. If the -relaxBER option is specified, the decoder decodes such encodings silently.
The -noRelaxBER option is implied.
The -relaxPER option instructs ASN-1Step to silently ignore minor violations to the PER standard while decoding an encoding.
-relaxPER instructs ASN-1Step to silently ignore the following types of violations:
Foo1 ::= VisibleStringcould have the following standard and valid PER ALIGNED encoding
04 6E6E6E6Ewhere the first octet (04) defines the length of the contents (in this case, the length is four octets long). However, some applications could incorrectly encode the length field so that the length value can still be retrieved but the format of the length field is non-standard, for example,
1004 6E6E6E6ENormally, the PER decoder issues an error message on receiving such an encoding, since the length determinant is encoded with too many octets. Note that, according to the ASN.1 standard, a two octet length, as shown above, should only be used when the length is larger than 127. To work around such problematic encodings, specify the -relaxPER option to instruct the decoder to retrieve the correct value of the length field while ignoring its incorrect format.
The -noRelaxPER option is implied.
When specified, -noRelaySafe instructs the decoder to skip unrecognized extension additions. Otherwise, unrecognized extensions are always preserved.
By default, the -relaySafe option is implied. ASN-1Step safely relays unknown extension additions when decoding and re-encoding messages with such additions in SEQUENCE, SET, and CHOICE types. The -noRelaySafe option instructs ASN-1Step to silently ignore unknown extension additions when decoding and re-encoding messages.
When -noRelaySafe is used, and the firewall supported version 1 of H.323 is used, and later a version 2 H.323 message containing some added fields (not defined in version 1) is received, the decoder will skip over these added fields and return only the version 1 fields to the firewall application. The problem with this is that if the firewall is to decode and re-encode the message with a new IP address, it would re-encode the message as a version 1 message since the version 2 fields were skipped over during decoding. With relay-safe decoding and encoding, the decoder will retain the value of the fields added in version 2 and, when the message is re-encoded by the firewall application, the encoder will automatically insert the version 2 fields back into the newly encoded message, resulting in a version-2-compliant message with the new IP address - even though the firewall understands only version 1 messages and even though the firewall has no clue as to what is contained in the version 2 fields.
NOTE: You cannot re-encode the unknown extension fields with a set of encoding rules that differ from those that were used to encode them originally.
The -relaySafe option is turned on.
Instructs ASN-1Step not to ignore the OSS.NoConstrain directive when the explicit -constraints option is present.
When you use -constraints with -restrictedConstraintChecking, ASN-1Step enables runtime constraint checking for all types except those that have the OSS.NoConstrain directive applied.
NOTE: The -restrictedConstraintChecking option has no effect unless the -constraints option is explicitly specified.
The -restrictedConstraintChecking option is turned on.
Instructs ASN-1Step to treat all input modules as root modules.
When you use the -root option, all modules are thoroughly checked for syntax, and all unreferenced types in all modules are considered PDUs.
Only the last module specified on the command line is treated as a root module.
This option gives you control over the nesting limit of structured types (SEQUENCE, SET, SEQUENCE OF, SET OF, and CHOICE). You must specify a positive integer argument immediately after this option. Specify zero for unlimited nesting.
nestingLimit is 64.
This option gives you control over the nesting limit of a constructed string encoding. You must specify a positive integer argument immediately after this option. Specify zero for unlimited nesting.
nestingLimit is 10.
Instructs ASN-1Step to suppress a specific warning or informatory message.
You can specify -suppress more than once on the command line.
messageNumber can be either the complete message identifier, such as A0210W, or only the numeric portion, such as 210.
The -suppress option is turned off.
Instructs ASN-1Step to perform only a syntax check on the ASN.1 input. This is useful when you do not need to encode or decode any values but only wish to check an abstract syntax for correctness.
The -syntaxOnly option is turned on.
Instructs ASN-1Step to test the encoding and decoding of all value references in the input ASN.1 specification.
The -ber, -cer, -der, -per, -uper, -oer, -coer, -xer, -cxer, -exer, -json, and -csv arguments are optional to the -test keyword and instruct ASN-1Step as to which encoding rules should be tested. By default, all available encoding rules are tested.
The following flags can be specified with the -csv option:
| Flag | Description |
|---|---|
| ';' or ':' or '=' | Alternative column separators |
| 'noheader' | Do not print CSV header |
| 'singlename' | Print a compact CSV header |
| 'text' | Do not use UTF-8 file format for CSV with Unicode characters |
| 'column' | Print values on separate lines |
| 'spaces' | Add spaces around column separators |
| 'pduname' | Specify a PDU name for the first header name |
| <num> | Maximum number of additional CSVs for SET OF and SEQUENCE OF |
| 'digit' | Print numbers for BOOLEAN and ENUMERATED values |
| 'noauto' | Print Open Type values in XML or hexadecimal format |
| 'ascii' or 'bcd' or 'tbcd' | Specify the format for OCTET STRING values |
| 'dashes' or 'slashes' | Specify a time stamp format for GeneralizedTime values |
-test is turned off and -noTest is assumed.
Instructs ASN-1Step to write all encoder/decoder trace information to the specified traceFilename file when the -decodePdu or -test option is used.
This option is turned off.
Instructs ASN-1Step to truncate long printed strings at the position specified by the num parameter.
If num is 0; no truncation occurs.
A ::= IA5String a A ::= "12345678901234567890123456789012345678901234567890"
For the syntax above, value A will be printed as follows:
value A ::= "12345678901234567890123456789012345 ..."
This is the result when -truncatePrintedStrings 48 is specified:
value A ::= "123456789012345678901234567890123456789012345678 ..."
Strings longer than 35 characters are automatically truncated.
The -uniquePDU option specifies that the tags for all PDUs must be unique. When the -noUniquePDU option is specified, ASN-1Step will not issue a warning message when it finds a non-unique PDU tag.
ASN-1Step issues a warning message when it detects non-unique PDU tags and BER or DER is in use.
Instructs ASN-1Step to display a table of all value references in the input ASN.1 specification that are available for encoding. Each available value reference is listed along with the PDU number of its base type. Refer to section 3.1.2 for an example of how to use this option.
The -valueRefTable option is turned off.
Specifies whether ASN-1Step should issue detailed status messages.
These messages display information such as the current input filename and detailed ossinfo information.
The -noVerbose option is enabled.
Specifies whether ASN-1Step should issue warning and informatory messages.
-warningMessages implies the -informatoryMessages option; -noWarningMessages implies the -noInformatoryMessages option.
When -norelaxedMode is used, the -warningMessages option is implied.
The order in which the -warningMessages/-noWarningMessages and -relaxedMode/-norelaxedMode options appear on the command line is important. The rightmost option takes precedence.
The -noWarningMessages option is implied by the default -relaxedMode option. However, some significant warning messages are not suppressed in the default mode. To suppress all warnings, specify the -noWarningMessages option.
Allows you to generate multiple default stylesheet files, one for each PDU.
Normally, separate stylesheets are not produced, even when the XER encoding rules are requested. Instead, you can use your own XML stylesheets or customize those previously generated.
Every stylesheet produced has an .xsl file extension and a filename prefix matching the generated name of its corresponding PDU. You can specify a different filename prefix and extension using the OSS.Stylesheet directive.
You can instruct ASN-1Step to generate a reference for your stylesheet when producing its XML output (i.e., -encodeValue is specified) for a particular PDU by passing the desired .xsl file on the ASN-1Step command line, for example,
asn1step bcas.asn -xer -encodeValue myValue ValueType.xsl
Only one .xsl file is allowed per invocation of ASN-1Step. When multiple -encodeValue options are used, the .xsl specified is used in the XER encoding of the last value reference.
ASN-1Step does not generate XML stylesheets.
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.