IBM InfoSphere Streams Version 4.1.0

Operator ASN1Encode

SPL standard and specialized toolkits > com.ibm.streams.teda 1.0.2 > com.ibm.streams.teda.encoder.binary > ASN1Encode

Primitive operator image not displayed. Problem loading file: ../../image/tk$com.ibm.streams.teda/op$com.ibm.streams.teda.encoder.binary$ASN1Encode.svg

The ASN1Encode operator creates ASN.1 DER-encoded data from XML documents that fit to the provided ASN.1 specification.

This operator requires a structure definition document, the ASN.1 specification, which describes the ASN.1 data structures.

The ASN1Encode operator provides following features:

  • Support the ASN.1-encoding for one or more ASN.1 elements (also called protocol data unit, or PDU)
  • Support of the following ASN.1 constructs:
    • Containers
      • CHOICE, SET, and SEQUENCE
    • Primitive types
      • BIT STRING, BMPString, BOOLEAN, ENUMERATED, GeneralizedTime, GeneralString, GraphicString, IA5String, INTEGER, ISO646String, NULL, NumericString, ObjectDescriptor, OBJECT IDENTIFIER, OCTET STRING, PrintableString, REAL, RELATIVE-OID, T61String, TeletexString, UniversalString, UTCTime, UTF8String, VideotexString, and VisibleString
    • Repetition
      • SET OF and SEQUENCE OF
    • Optional
      • OPTIONAL and DEFAULT (limited to the primitive types)
  • Support of basic constraints verification
  • The ability to send invalid XML documents to an error port.

The operator does not support:

  • Window configurations

The ASN1Encode operator does not throw exceptions or catch any exceptions that might be thrown, for example by a fused downstream operator.

Instead of using this operator, you can use the asn1-data-from-xml command line tool to create ASN.1 DER-encoded data files. The command line tool requires the same XML inputs as this operator. It is typically used to create test data that can be parsed with the ASN1Parse operator.

Behavior in a consistent region

The ASN1Encode operator can be an operator within the reachability graph of a consistent region. It cannot be the start of a consistent region.

XML document format
The ASN1Encode operator as well as the asn1-data-from-xml command line tool transform XML documents that fit to the provided ASN.1 specification. The following rules describe how to create valid XML documents for different ASN.1 grammar constructs. The rule descriptions use the following ASN.1 grammar to provide examples. MyModule DEFINITIONS IMPLICIT TAGS ::= BEGIN Sample ::= SEQUENCE { orders [0] SEQUENCE OF Order OPTIONAL, ... } Order ::= SEQUENCE { size [0] PaperSize DEFAULT "a4", count [1] INTEGER (0..100) DEFAULT 1, color [2] Color DEFAULT "white", ordered [3] GeneralizedTime, ... } PaperSize ::= ENUMERATED { a0 (0), a1 (1), a2 (2), a3 (3), a4 (4), a5 (5) } Color ::= ENUMERATED { black (0), white (1), red (2), green (3), yellow (4) } END Provide valid XML: Use an XML editor to create valid XML documents, or use, for example, the xmllint command line tool to verify the validity.

Summary

Ports
This operator has 1 input port and 2 output ports.
Windowing
This operator does not accept any windowing configurations.
Parameters
This operator supports 5 parameters.

Required: structureDocument

Optional: payloadAttribute, pdu, checkConstraints, debugDecoder

Metrics
This operator does not report any metrics.

Properties

Implementation
C++
Threading
Always - Operator always provides a single threaded execution context.

Input Ports

Ports (0)

The ASN1Encode operator is configurable with a single input port.

The input port schema must be a tuple with at least one rstring or xml attribute, which holds the payload. The payload is the XML representation of the data to be ASN.1-encoded. If more than one rstring or xml attribute exists, use the payloadAttribute parameter to specify the attribute that contains the payload.

Properties

Output Ports

Assignments
This operator allows any SPL expression of the correct type to be assigned to output attributes. Attributes not assigned in the output clause will be automatically assigned from the attributes of the input ports that have the same name and type. If there is no such input attribute, an error is reported at compile-time.
Output Functions
DataAssignmentFunctions
<any T> T AsIs(T)

Returns the input value.

blob Data()

Returns the ASN.1-encoded data.

rstring PDU()

Returns the pdu name that specifies which kind of PDU or PDUs is in the blob.

ErrorAssignmentFunctions
<any T> T AsIs(T)

Returns the input value.

rstring Snippet()

Returns the XML snippet that the operator cannot transform into the ASN.1 format.

ASN1EncodeTypes.ErrorCode ErrorCode()

Returns the error code. The corresponding message explains why the operator cannot transform the XML input into the ASN.1 format.

rstring Info()

Returns additional error information.

Ports (0)

Properties

Ports (1)

Properties

Parameters

This operator supports 5 parameters.
payloadAttribute

Specifies the input xml or rstring attribute, which holds the payload. The payload is an XML representation of the data to be ASN.1-encoded. If more than one xml or rstring attribute exists in the input port schema, this parameter must exist. If not, the single xml or rstring attribute is automatically selected.

If the payload attribute is an rstring attribute, the value can have several XML root elements, for example, <test>...</test><test>...</test>.

Properties

structureDocument

Specifies the path name or names of the structure definition document or documents, the ASN.1 grammar file that describes the ASN.1 data structures.

The structure definition document is used at SPL compile time. If you modify the document, recompile the SPL application. After the application is recompiled, the structure definition document is not required for job submission.

A relative path is relative to the SPL application directory, which is the current working directory where the sc command is run. For example, if you specify the relative path "etc/StructureDefinition.asn" and run the sc command from the /home/myapp directory, the compiler looks for the StructureDefinition.asn document in the /home/myapp/etc directory.

Properties

pdu

Defines the name or names of the root ASN.1 structure or structures (PDU) that the parser needs to XML decode and ASN.1 encode. Typically, the operator determines the PDU or PDUs automatically. It selects the PDU or PDUs, which has no parent structure defined.

You can specify any ASN.1 name even if the ASN.1 structure has a parent structure in the ASN.1 grammar.

Properties

checkConstraints

Enables or disables ASN.1 constraints verification.

Verified constraints are:

  • Restrictions on the allowed character set for ASN.1 primitive types
  • Constraints in the user-provided ASN.1 grammar (the structure definition document).

By default, this parameter is set to true, verifies these constraints.

Properties

debugDecoder

Generates symptoms that can help you troubleshoot a malfunction during runtime on the ASN.1 decoding and encoding level. If you set this parameter to true, it debugs the runtime of the ASN.1 decoder and encoder, producing a large amount of console traces and significantly reducing performance.

Properties