View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Brian Kaney > XML-ASCX12-0.04 > XML::ASCX12



Annotate this POD


New  1
Open  0
View/Report Bugs
Module Version: 0.04   Source  


XML::ASCX12 - ASCX12 EDI to XML Module


    use XML::ASCX12;
    my $ascx12 = new XML::ASCX12();
    $ascx12->convertfile("/path/to/edi_input", "/path/to/xml_output");


Module Description

XML::ASCX12 started as a project to process X12 EDI files from shipping vendors (i.e. transaction sets 110, 820 and 997). However, this module can be extended to support any valid transaction set (catalog).

Why are you doing this?

If you've ever taken a look at an ASCX12 document you'll see why. The EDI format is very compact, which makes is great for transmission. However this comes at a cost.

The main challenge when dealing with EDI data is parsing through the structure. Here we find loops within loops within loops. In this non-extensible, flat format, human parsing is nearly impossible and machine parsing is a task at best.

A quick background of how a typical EDI is formed:

        +---->  ISA - Interchange Control Header
        |          GS - Functional Group Header       <--------+
        |              ST - Transaction Set Header             |
    Envelope              [transaction set specific]  Functional Group
        |              SE - Transaction Set Trailer            |
        |          GE - Functional Group Trailer      <--------+
        +---->  ISE - Interchange Control Trailer

The Transmission Envelope can have one or more Functional Group. A Functional Group can have one or more Transaction Set. Then each specific catalog (transaction set) can have it's own hierarchical rules.

This sort of structure really lends itself to XML. So using the power of Perl, this module was created to make accessing EDI information easier.

To learn more, the official ASC X12 group has a website

Module Limitations

This is a new module and has a few limitations.

Style Guide

You will (hopefully) find consistent coding style throughout this module. Any private variable or method if prefixed with an underscore (_). Any static method or variable is named in ALL_CAPS.

The tabs are set at 4 spaces and the POD is physically close to the stuff it is describing to promote fantastic ongoing documentation.


We use the Carp module to handle errors. Some day there may be a better error handler and maybe an error object to reference, but for now it croaks when there is a problem.

XML::ASCX12::Catalogs module is required and probably part of this package, as is the XML::ASCX12::Segments.


Private Variables

These variables are not exported and not intended to be accessed externally. They are listed here for documentation purposes only.


Dynamic and keeps track of which loop we are on.


Static variable used to lookup bad XML characters.


Static variable containing the XML header for the output.

Public Methods

object = new([$segment_terminator], [$data_element_separator], [$subelement_separator])

The new method is the OO constructor. The default for the segment terminator is ASCII 85 hex. The default for the data element separator is ASCII 1D hex. The default for the sub-element separator is ASCII 1F hex.

    my $xmlrpc = new XML::ASCX12();

The defaults can be overridden by passing them into the constructor.

    my $xmlrpc = new XML::ASCX12('\x0D', '\x2A', '\x3A');

The object that returns is now ready to transform EDI files.

boolean = $obj->convertfile($input, $output)

This method will transform and EDI file to XML using the configuration information passed in from the constructor.

    my $xmlrpc = new XML::ASCX12();
    $xmlrpc->convertfile('/path/to/EDI.dat', '/path/to/EDI.xml');

You may also pass filehandles (or references to filehandles):

    $xmlrpc->convertfile(\*INFILE, \*OUTFILE);
string = $obj->convertdata($input)

This method will transform an EDI data stream, returning wellformed XML.

    my $xmlrpc = new XML::ASCX12();
    my $xml = $xmlrpc->convertdata($binary_edi_data);
string = XMLENC($string)

Static public method used to encode and return data suitable for ASCII XML CDATA

    $xml_ready_string = XML::ASCX12::XMLENC($raw_data);

Private Methods

string = _proc_segment($segment_data);

This is an internal private method that processes a segment using $LOOPNEST. It is called by convertfile() or convertdata() while looping per-segment.

string = _proc_segment_in_child($segment_data);

This is an internal private method that processes a segment using $IN_CHILD. It is called by _proc_segment() when $IN_CHILD is defined.

string = _proc_element($segment_code, @elements)

This is a private method called by _proc_segment(). Each segment consists of elements, this is where they are processed.

string = _openloop($loop_to_open, $last_opened_loop)

This is an internal private method. It will either open a loop if we can or return nothing.

void = _closeloop($loop_to_close, $last_opened_loop, $current_segment, $trigger)

This routine is a private method. It will recurse to close any open loops.

string = _execclose($loop_to_close)

Private internal method to actually return the XML that signifies a closed loop. It is called by _closeloop().

void = _unload_catalog()

Private method that clears out catalog data and loads standard ASCX12 structure. Also initializes ISA and GS data common to all Catalogs.

boolean = _CANHAVE($parent_loop, $child_loop)

This is a private static method. It uses the rules in the XML::ASCX12::Catalogs to determine if a parent is allowed to have the child loop. Returns 0 or 1.


Here are some things that would make this module even better. They are in no particular order:


Brian Kaney <>, Jay Powers <>

Copyright (c) 2004 Vermonster LLC. All rights reserved.

This library is free software. You can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

Basically you may use this library in commercial or non-commercial applications. However, If you make any changes directly to any files in this library, you are obligated to submit your modifications back to the authors and/or copyright holder. If the modification is suitable, it will be added to the library and released to the back to public. This way we can all benefit from each other's hard work!

If you have any questions, comments or suggestions please contact the author.


Carp, XML::ASCX12::Catalogs and XML::ASCX12::Segments

syntax highlighting: