The Command Line

Command-line options allow you greater flexibility over the behavior of the ASN-1Step program. The following sections describe the command-line syntax used by the ASN-1Step executable.

Command-line Syntax

Command-line keyword options are prefixed by a hyphen (-). They can be shortened to the fewest number of characters needed to differentiate them from other keywords. Command-line keyword options are not case-sensitive; they can be specified in all uppercase, all lowercase, or mixed case.

Some keywords accept operands; keyword operands are not prefixed with a hyphen.

If two contradictory command-line options are specified, the rightmost option is used.

Examples of ASN-1Step Invocation

The following asn1step invocations show alternative ways to specify the input filename. All three invocations will encode the myName value reference contained in input1.asn to a file named myName.per, using the Packed Encoding Rules.

asn1step input1.asn myName.per -encodeValue myName

asn1step input1 myName.per -encode myName

asn1step input1 -encode myName -per

These invocations show alternative ways to specify the -noWarning command-line option. Both invocations will suppress all warning messages while compiling the contents of input1.asn. Notice that the second invocation uses an abbreviated form of -noWarning.

asn1step -syntaxOnly input1 -noWarning

asn1step -syntaxOnly input1 -now

The following ASN-1Step invocation will decode the contents of the input.ber file using the Basic Encoding Rules (BER). The decoder's trace data will be written to tracefile.txt.

asn1step input1 input.ber -traceFile tracefile.txt

Note that tracefile.txt, the last command-line token, is not prefixed with a hyphen (-) since it is an operand to the -traceFile option that preceeds it.

This ASN-1Step invocation will encode a value from the inputValueFile.txt file to the output.per file using the Packed Encoding Rules (PER).

asn1step input1 output.per -encodeValue inputValueFile.txt

The following ASN-1Step invocation will re-encode a BER-encoded message from the input.ber file to the output.per file using the Packed Encoding Rules (PER).

asn1step input1 input.ber -per -output output

This invocation will redirect the output of the -test option to a file.

asn1step input.asn -test > test.out

Specifying Input and Output Files

Important notes about specifying input filenames on the command line:

1. Items on the command line that do not start with a hyphen and are not keyword option operands are considered to be input or output filenames.
2. .asn is the default file extension for input files; if the filename lacks an extension, the .asn extension is added to it before the file is opened. To specify a filename without an extension, place a single '.' at the end of the filename prefix.
3. The filename extension of an input file that contains an encoded PDU determines which encoding rules will be used to decode the value:
   • A .ber extension signals that the Basic Encoding Rules (BER) will be used.
   • A .der extension signals that the Distinguished Encoding Rules (DER) will be used.
   • A .per extension signals that the aligned version of the Packed Encoding Rules (PER) will be used.
   • A .uper extension signals that the unaligned version of the Packed Encoding Rules (UPER) will be used.
   • A .cper extension signals that the canonical version of the Packed Encoding Rules (CPER) will be used.
   • A .cuper extension signals that the canonical unaligned version of the Packed Encoding Rules (CUPER) will be used.
   • A .cer extension signals that the Canonical Encoding Rules (CER) will be used.
   • A .oer extension signals that the Octet Encoding Rules (OER) will be used.
   • A .coer extension signals that the Canonical Octet Encoding Rules (COER) will be used.
   • A .xer extension signals that the XML Encoding Rules (XER) will be used.
   • A .cxer extension signals that the Canonical XML Encoding Rules (CXER) will be used.
   • A .exer extension signals that the Extended XML Encoding Rules (E-XER) will be used.
   • A .json extension signals that the JavaScript Object Notation Encoding Rules (JSON) will be used.
   • A .txt extension signals that standard ASN.1 value notation will be used.
   • A .csv extension signals that the Comma-Separated Value (CSV) format will be used.
4. When XER is in use along with the -encodeValue option, the filename extension of an input file can specify that the file contains an XML stylesheet (.xsl) or an XML Data Type Definition (.dtd or .pdtd). See -dtd and -xsl for more details on this topic.
5. The -getFiles <path>,<ber|per|der|uper|xer|cxer|cer|exer|oer|coer|json|csv|cdr>[,<hex|bin|csvFlags>] command can be used to specify the location that can be empty for the current directory. Input encoding files are filtered based on the file name extension, which correspond to the encoding rules used, and an optional 'flags' argument specifies a non-default file format: 'hex' or 'bin' for text files created with binary encoding rules, and CSV flags separated by ',' for CSV files.
6. The filename extension of an output file that will contain an encoded PDU determines which encoding rules will be used to encode the value:
   • A .ber extension signals that the Basic Encoding Rules (BER) will be used.
   • A .der extension signals that the Distinguished Encoding Rules (DER) will be used.
   • A .per extension signals that the aligned version of the Packed Encoding Rules (PER) will be used.
   • A .uper extension signals that the unaligned version of the Packed Encoding Rules (UPER) will be used.
   • A .cper extension signals that the canonical version of the Packed Encoding Rules (CPER) will be used.
   • A .cuper extension signals that the canonical unaligned version of the Packed Encoding Rules (CUPER) will be used.
   • A .cer extension signals that the Canonical Encoding Rules (CER) will be used.
   • A .oer extension signals that the Octet Encoding Rules (OER) will be used.
   • A .coer extension signals that the Canonical Octet Encoding Rules (COER) will be used.
   • A .xer extension signals that the XML Encoding Rules (XER) will be used.
   • A .cxer extension signals that the Canonical XML Encoding Rules (CXER) will be used.
   • A .exer extension signals that the Extended XML Encoding Rules (E-XER) will be used.
   • A .csv extension signals that the Comma-Separated Value (CSV) format will be used.
   • A .cdr extension signals that encoding rules for each record are determined based on the CDR record header settings. Currently BER, PER, UPER, and XER are supported.
   • A .json extension signals that the JSON Encoding Rules will be used.
7. The -putFiles <path>[,<fileNamePrefix>[,<firstNumSuffix>]] command can be used to specify the location for output files along with a common file name prefix, which is suffixed with an underscore and a number suffix that starts with the specified 'firstNumSuffix' or 1. The number suffix is increased by '1' for other files.
8. Similar to most language compilers, the ASN-1Step utility expects input files to be plain text files.

Order of Input ASN.1 Files

The order of the input files on the command-line can be important. Files that contain definitions referenced by other files should be placed first (left to right) on the command line. For example, if the file myModules.asn references macro definitions in macro.asn, invoke ASN-1Step as:

prompt%> asn1step macro.asn myModules.asn

Note that the last ASN.1 file specified on the command-line has a special role. If the -root command-line option is not specified, then the last (or only) module in this right-most ASN.1 input file is taken as the central ASN.1 module in the specification. In this case, only this last module has its PDUs encoded/decoded; ASN.1 definitions from other files are only read if they are referenced from within this last module.

Command-line Messages

Detailed descriptions of most of the messages issued by ASN-1Step can be found at ASN.1 Compiler Errors or ASN.1 Runtime Errors. Additionally, some usage related messages are listed at ASN-1Step Errors.

---