X12Writer Component

Properties   Methods   Events   Config Settings   Errors  

The X12Writer component generates X12 documents with a clear, straightforward API.

Syntax

nsoftware.EDISDK.X12Writer

Remarks

The component allows you to create an EDI document from scratch, one segment at a time. Here's how a document would normally be created:

1. Call LoadSchema to load the necessary schemas for the transactions that will be used.
2. Specify where to write the output document by setting the OutputFile, or check the OutputData property after writing.
3. Create a new interchange start segment by setting the fields of the Interchange property and call the StartInterchange method. Once the interchange is complete, call EndInterchange to add the interchange footer.
4. If you want to create a functional group, set the fields of the FunctionalGroup property and then call the StartFunctionalGroup. Once all the transactions in the group have been created, call EndFunctionalGroup to add a footer for the group.
5. To start a transaction, call the StartTransactionSet method. Once all segments have been added, call EndTransactionSet to add a footer to the transaction.
6. To begin a segment, call the StartSegment method and pass in the tag for the segment. Once all the elements in the segment have been added, call EndSegment to add the segment terminator.
7. To write a basic element to the current segment, call the WriteElement method.
8. To write a composite element, call the StartCompositeElement method, then call the WriteComponent method for each component, and finally call EndCompositeElement to end the element.

Property List

The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the component with short descriptions. Click on the links for further details.

Delimiters Property (X12Writer Component)

Contains the delimiters for the EDI Document.

Syntax

• C#
• VB.NET

public X12Delimiters Delimiters { get; }

Public ReadOnly Property Delimiters As X12Delimiters

Remarks

This property contains the delimiters that will be used when writing the EDIFACT document. If the document uses delimiters other than the default, change the properties of this object to write the document correctly.

This property is read-only and not available at design time.

FileWriteMode Property (X12Writer Component)

Determines how the output file is opened for writing.

Syntax

• C#
• VB.NET

public X12WriterFileWriteModes FileWriteMode { get; set; }

enum X12WriterFileWriteModes {
  fwmCreate,
  fwmOverwrite,
  fwmAppend
}

Public Property FileWriteMode As X12writerFileWriteModes

Enum X12WriterFileWriteModes
  fwmCreate
  fwmOverwrite
  fwmAppend
End Enum

Default Value

0

Remarks

When OutputFile is set, this property determines how the file will be opened.

This property is not available at design time.

FunctionalGroup Property (X12Writer Component)

Contains the current functional group information for the EDI Document.

Syntax

• C#
• VB.NET

public X12FunctionalGroup FunctionalGroup { get; }

Public ReadOnly Property FunctionalGroup As X12FunctionalGroup

Remarks

The functional group information is used when writing the functional group header (GS) and trailer (GE) segments. The properties of this object must be changed before calling StartFunctionalGroup to write the functional group correctly. After calling StartFunctionalGroup changing the properties of this object will change the values for the next functional group only.

This property is read-only and not available at design time.

Interchange Property (X12Writer Component)

Contains the current interchange information for the EDI Document.

Syntax

• C#
• VB.NET

public X12Interchange Interchange { get; }

Public ReadOnly Property Interchange As X12Interchange

Remarks

The interchange information is used when writing the interchange header (ISA) and trailer (IEA) segments. The properties of this object must be changed before calling StartInterchange to write the interchange correctly. After calling StartInterchange changing the properties of this object will change the values for the next interchange only.

This property is read-only and not available at design time.

OutputData Property (X12Writer Component)

The output data that has been written so far.

Syntax

• C#
• VB.NET

public string OutputData { get; set; }

Public Property OutputData As String

Default Value

""

Remarks

OutputData contains the entire EDI document that has been written so far. If writing to a file or stream, this property will be empty.

This property is not available at design time.

OutputFile Property (X12Writer Component)

The name of the output file to which the EDI data will be written.

Syntax

• C#
• VB.NET

public string OutputFile { get; set; }

Public Property OutputFile As String

Default Value

""

Remarks

FileWriteMode property determines how the file is opened for writing. If OutputFile is empty, no file will be written and the OutputData property will contain the EDI data instead.

This property is not available at design time.

SegmentSuffix Property (X12Writer Component)

The suffix that is appended to the end of a segment.

Syntax

• C#
• VB.NET

public X12WriterSegmentSuffixes SegmentSuffix { get; set; }

enum X12WriterSegmentSuffixes {
  ssNone,
  ssCR,
  ssLF,
  ssCRLF
}

Public Property SegmentSuffix As X12writerSegmentSuffixes

Enum X12WriterSegmentSuffixes
  ssNone
  ssCR
  ssLF
  ssCRLF
End Enum

Default Value

0

Remarks

Possible values are:

This property is not available at design time.

TransactionSet Property (X12Writer Component)

Contains the current transaction set information for the EDI Document.

Syntax

• C#
• VB.NET

public X12TransactionSet TransactionSet { get; }

Public ReadOnly Property TransactionSet As X12TransactionSet

Remarks

This property holds the current transaction set information for the EDI document. It is used by the StartTransactionSet method to create a new transaction set header. The properties of this object must be changed before calling StartTransactionSet to write the transaction set correctly. After calling StartTransactionSet changing the properties of this object will change the values for the next transaction set only.

This property is read-only and not available at design time.

Close Method (X12Writer Component)

Closes the writer.

Syntax

• C#
• VB.NET

public void Close();

Async Version
public async Task Close();
public async Task Close(CancellationToken cancellationToken);

Public Sub Close()

Async Version
Public Sub Close() As Task
Public Sub Close(cancellationToken As CancellationToken) As Task

Remarks

Calling Close will close the writer and release any resources associated with it. After calling Close, the writer cannot be used unless it is re-initialized.

Config Method (X12Writer Component)

Sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

public string Config(string configurationString);

Async Version
public async Task<string> Config(string configurationString);
public async Task<string> Config(string configurationString, CancellationToken cancellationToken);

Public Function Config(ByVal ConfigurationString As String) As String

Async Version
Public Function Config(ByVal ConfigurationString As String) As Task(Of String)
Public Function Config(ByVal ConfigurationString As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

EndCompositeElement Method (X12Writer Component)

Closes the current composite element.

Syntax

• C#
• VB.NET

public void EndCompositeElement();

Async Version
public async Task EndCompositeElement();
public async Task EndCompositeElement(CancellationToken cancellationToken);

Public Sub EndCompositeElement()

Async Version
Public Sub EndCompositeElement() As Task
Public Sub EndCompositeElement(cancellationToken As CancellationToken) As Task

Remarks

Calling EndCompositeElement will close the current composite element. If no composite element is open, an error will be raised.

EndFunctionalGroup Method (X12Writer Component)

Closes the current functional group.

Syntax

• C#
• VB.NET

public void EndFunctionalGroup();

Async Version
public async Task EndFunctionalGroup();
public async Task EndFunctionalGroup(CancellationToken cancellationToken);

Public Sub EndFunctionalGroup()

Async Version
Public Sub EndFunctionalGroup() As Task
Public Sub EndFunctionalGroup(cancellationToken As CancellationToken) As Task

Remarks

Calling EndFunctionalGroup will close the current functional group. If no functional group is open, an error will be raised. This method will also write the required FunctionalGroup Trailer (GE) segment to the output.

EndInterchange Method (X12Writer Component)

Closes the current interchange.

Syntax

• C#
• VB.NET

public void EndInterchange();

Async Version
public async Task EndInterchange();
public async Task EndInterchange(CancellationToken cancellationToken);

Public Sub EndInterchange()

Async Version
Public Sub EndInterchange() As Task
Public Sub EndInterchange(cancellationToken As CancellationToken) As Task

Remarks

Calling EndInterchange will close the current interchange. If no interchange is open, an error will be raised. This method will also write the required Interchange Trailer (IEA) segment to the output.

EndSegment Method (X12Writer Component)

Finish writing the current segment

Syntax

• C#
• VB.NET

public void EndSegment();

Async Version
public async Task EndSegment();
public async Task EndSegment(CancellationToken cancellationToken);

Public Sub EndSegment()

Async Version
Public Sub EndSegment() As Task
Public Sub EndSegment(cancellationToken As CancellationToken) As Task

Remarks

Calling EndSegment will finish writing the current segment. If no segment is open or if a composite element is still open an error will be raised. This method will also write the segment delimiter and segment suffix to the output.

EndTransactionSet Method (X12Writer Component)

Closes the current transaction set.

Syntax

• C#
• VB.NET

public void EndTransactionSet();

Async Version
public async Task EndTransactionSet();
public async Task EndTransactionSet(CancellationToken cancellationToken);

Public Sub EndTransactionSet()

Async Version
Public Sub EndTransactionSet() As Task
Public Sub EndTransactionSet(cancellationToken As CancellationToken) As Task

Remarks

Calling this method will close the current transaction set. If no transaction set is open, an error will be raised. This method will also write the required Transaction Set Trailer (SE) segment to the output.

Reset Method (X12Writer Component)

Resets all properties to their default values.

Syntax

• C#
• VB.NET

public void Reset();

Async Version
public async Task Reset();
public async Task Reset(CancellationToken cancellationToken);

Public Sub Reset()

Async Version
Public Sub Reset() As Task
Public Sub Reset(cancellationToken As CancellationToken) As Task

Remarks

This method resets all properties of the component to their default values as specified in the property definitions.

SetOutputStream Method (X12Writer Component)

Sets the output stream where the EDI data will be written.

Syntax

• C#
• VB.NET

public void SetOutputStream(System.IO.Stream outputStream);

Async Version
public async Task SetOutputStream(System.IO.Stream outputStream);
public async Task SetOutputStream(System.IO.Stream outputStream, CancellationToken cancellationToken);

Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream)

Async Version
Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream) As Task
Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream, cancellationToken As CancellationToken) As Task

Remarks

This method sets the output stream for the component. The output stream must be writable. Calling Close will close the specified output stream. If OutputStream is set, no file will be written and the OutputData property will be null.

StartCompositeElement Method (X12Writer Component)

Starts a composite element within the current segment.

Syntax

• C#
• VB.NET

public void StartCompositeElement();

Async Version
public async Task StartCompositeElement();
public async Task StartCompositeElement(CancellationToken cancellationToken);

Public Sub StartCompositeElement()

Async Version
Public Sub StartCompositeElement() As Task
Public Sub StartCompositeElement(cancellationToken As CancellationToken) As Task

Remarks

This method starts a composite element within the current segment. The composite element can contain multiple component elements. The composite element is ended by calling the EndCompositeElement method. Component elements within the composite are added by calling the WriteComponent method.

StartFunctionalGroup Method (X12Writer Component)

Starts a new functional group in the EDI document.

Syntax

• C#
• VB.NET

public void StartFunctionalGroup();

Async Version
public async Task StartFunctionalGroup();
public async Task StartFunctionalGroup(CancellationToken cancellationToken);

Public Sub StartFunctionalGroup()

Async Version
Public Sub StartFunctionalGroup() As Task
Public Sub StartFunctionalGroup(cancellationToken As CancellationToken) As Task

Remarks

This method starts a new functional group in the EDI document. The functional group fields must be set using the appropriate properties before calling this method. The functional group is ended by calling the EndFunctionalGroup method. The functional group header segment (GS) is written to the output when this method is called.

StartInterchange Method (X12Writer Component)

Starts a new interchange in the EDI document.

Syntax

• C#
• VB.NET

public void StartInterchange();

Async Version
public async Task StartInterchange();
public async Task StartInterchange(CancellationToken cancellationToken);

Public Sub StartInterchange()

Async Version
Public Sub StartInterchange() As Task
Public Sub StartInterchange(cancellationToken As CancellationToken) As Task

Remarks

This method starts a new interchange in the EDI document. The interchange fields must be set using the appropriate properties before calling this method. The interchange is ended by calling the EndInterchange method. The interchange header segment (ISA) is written to the output when this method is called. If opening a new interchange would result in an invalid structure (for example, starting a new interchange before ending the previous one), an error will be raised.

StartSegment Method (X12Writer Component)

Starts a new segment with the specified tag.

Syntax

• C#
• VB.NET

public void StartSegment(string tag);

Async Version
public async Task StartSegment(string tag);
public async Task StartSegment(string tag, CancellationToken cancellationToken);

Public Sub StartSegment(ByVal tag As String)

Async Version
Public Sub StartSegment(ByVal tag As String) As Task
Public Sub StartSegment(ByVal tag As String, cancellationToken As CancellationToken) As Task

Remarks

This method starts a new segment with the specified tag. The segment is ended by calling the EndSegment method. Element values within the segment are added by calling the WriteElement method. Composite elements can be added to the segment by calling the StartCompositeElement method. If starting a new segment would result in an invalid structure (for example, starting a new segment before ending the previous one), an error will be raised.

StartTransactionSet Method (X12Writer Component)

Starts a new transaction set in the EDI document.

Syntax

• C#
• VB.NET

public void StartTransactionSet();

Async Version
public async Task StartTransactionSet();
public async Task StartTransactionSet(CancellationToken cancellationToken);

Public Sub StartTransactionSet()

Async Version
Public Sub StartTransactionSet() As Task
Public Sub StartTransactionSet(cancellationToken As CancellationToken) As Task

Remarks

This method starts a new transaction set in the EDI document. The transaction set fields must be set using the appropriate properties before calling this method. The transaction set is ended by calling the EndTransactionSet method. The transaction set header segment (ST) is written to the output when this method is called. If opening a new transaction set would result in an invalid structure (for example, starting a new transaction set before ending the previous one), an error will be raised.

WriteComponent Method (X12Writer Component)

Writes a component element value to the current composite element.

Syntax

• C#
• VB.NET

public void WriteComponent(string val);

Async Version
public async Task WriteComponent(string val);
public async Task WriteComponent(string val, CancellationToken cancellationToken);

Public Sub WriteComponent(ByVal val As String)

Async Version
Public Sub WriteComponent(ByVal val As String) As Task
Public Sub WriteComponent(ByVal val As String, cancellationToken As CancellationToken) As Task

Remarks

This method writes a component element value to the current composite element. The composite element must be started by calling the StartCompositeElement method before calling this method. The composite element is ended by calling the EndCompositeElement method. If this method is called when not within a composite element, an error will be raised.

WriteElement Method (X12Writer Component)

Writes an element value to the current segment.

Syntax

• C#
• VB.NET

public void WriteElement(string val);

Async Version
public async Task WriteElement(string val);
public async Task WriteElement(string val, CancellationToken cancellationToken);

Public Sub WriteElement(ByVal val As String)

Async Version
Public Sub WriteElement(ByVal val As String) As Task
Public Sub WriteElement(ByVal val As String, cancellationToken As CancellationToken) As Task

Remarks

This method writes an element value to the current segment. The segment must be started by calling the StartSegment method before calling this method. The segment is ended by calling the EndSegment method. If this method is called when not within a segment, an error will be raised.

Error Event (X12Writer Component)

Fires when an error occurs during message processing. Normally, the component fails with an error.

Syntax

• C#
• VB.NET

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, X12WriterErrorEventArgs e);

public class X12WriterErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As X12WriterErrorEventArgs)

Public Class X12WriterErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally, the component throws an exception.

ConnectionId is the associated client Id, ErrorCode contains an error code, and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

Output Event (X12Writer Component)

Fires when output data is written.

Syntax

• C#
• VB.NET

public event OnOutputHandler OnOutput;

public delegate void OnOutputHandler(object sender, X12WriterOutputEventArgs e);

public class X12WriterOutputEventArgs : EventArgs {
  public string Data { get; }
  public byte[] DataB { get; }
}

Public Event OnOutput As OnOutputHandler

Public Delegate Sub OnOutputHandler(sender As Object, e As X12WriterOutputEventArgs)

Public Class X12WriterOutputEventArgs Inherits EventArgs
  Public ReadOnly Property Data As String
  Public ReadOnly Property DataB As Byte()
End Class

Remarks

This event is fired when output data is written. The Data parameter contains the segment that was written.

X12Delimiters Type

The delimiters used in the X12 document.

Remarks

This type contains fields specifying the various delimiters used within the X12 document.

• Component
• Element
• Repetition
• Segment

Fields

Constructors

• C#
• VB.NET

public X12Delimiters();

Public X12Delimiters()

X12FunctionalGroup Type

A functional group of messages.

Remarks

This type represents a functional group of messages, with fields describing the values from the GS segment.

• AppReceiverCode
• AppSenderCode
• Date
• FunctionalIdentifierCode
• GroupControlNum
• ResponsibleAgencyCode
• Time
• Version

Fields

Constructors

• C#
• VB.NET

public X12FunctionalGroup();

Public X12FunctionalGroup()

X12Interchange Type

An interchange containing functional groups and transaction sets.

Remarks

This type represents an X12 interchange, with fields describing the values from the ISA segment.

• AckRequest
• AuthorizationInfo
• AuthorizationInfoQualifier
• Date
• InterchangeControlNum
• InterchangeControlVersionNum
• ReceiverID
• ReceiverIDQualifier
• SecurityInfo
• SecurityInfoQualifier
• SenderID
• SenderIDQualifier
• Time
• UsageIndicator

Fields

Constructors

• C#
• VB.NET

public X12Interchange();

Public X12Interchange()

X12TransactionSet Type

An X12 transaction set.

Remarks

This type represents an X12 transaction set, with fields describing the values from the ST segment.

• ImpConventionReference
• TransactionSetControlNum
• TransactionSetIDCode

Fields

Constructors

• C#
• VB.NET

public X12TransactionSet();

Public X12TransactionSet()

Config Settings (X12Writer Component)

Trappable Errors (X12Writer Component)

X12Writer Errors