Arguments For the Command Line splitter xmlsplit.exe

Each argument may optionally begin with a single forward slash(new in version 1.3.4). Othewise, the first character of each argument is a single letter(it may be upper or lower case) denoting the argument, followed by the equals sign, followed by a value. A single space separates each argument. Spaces within each argument are not allowed, with the exception of file names, which must be enclosed in double quotes, and the /r argument if attributes are included in the root element. The arguments may appear in any order. Note that arguments specifying element or attribute names are case-sensitive because XML is case-sensitive.

If XmlSplit completes the operation successfully, an exit code of Zero is returned. If an error occurs, a positive integer is returned. The meaning of the exit codes is listed in the Exit Codes section.

/? Displays a brief definition of all the arguments in the console window. If followed by other arguments, the script is not executed but the value of all arguments on the command line are displayed in the console window which may be helpful in diagnosing problems with a script.

/a=attribute name example: /a=ID specifies an attribute named "ID"

Applies only to the third split method. The XML file is read and when an element having an attribute with the specified name and at the specified depth occurs, its value is stored. All nodes and content are written to the output file until an element is read that has the specified attribute at the specified depth and the value of the attribute is different from the stored attribute value. At that point, the output file is closed and the next output file is started.

/b=Write Byte Order Mark example: /b=1 specifies that no Byte Order Mark(BOM) is to be written.

Determines if the split files will have a BOM written in the header of the file. The BOM is used by XML parsers and other computer programs to determine the encoding. If the encoding is UTF-16 and no BOM is written to the split files, some XML programs, including XMLMax, will not be able to read the split files. The default value is 1. If the b parameter is omitted, no BOM is written. Note that no BOM is written for iso-8859-1 files regardless of which value is specified as per convention. A BOM is always written for UTF-16 big endian because without it many programs will assume little endian since it is more common in MS Windows files.

1: No BOM is written
2: A BOM is written for UTF-8 and UTF-16 encoded files.

/c=encoding example: /c=2 specifies Unicode encoding.

optional encoding to use when creating the output files. If this argument is missing or is not a valid value, files are written in the encoding of the source XML document provided it is one of the encoding listed below. Note that if iso-8859-1 is specified, an XmlDeclaration node is automatically inserted at the beginning of each split file with the encoding attribute set to iso-8859-1 because that is the only way most XML parsers are able to distinguish iso-8859-1 from utf-8. The exception is if an include file(/I argument) is specifed and the include file contains an XmlDeclaration in which case it is up to the user to ensure that the XmlDeclaration contains the appropriate value for the encoding attribute. Valid values are:

1: UTF-8
2: UTF-16
3: iso-8859-1
4: UTF-16 big-endian

/d=depth example: /d=2 specifies a depth of two

Required. Depth in the XML hierarchy. It must be a positive integer greater than zero. The root element always has a depth of zero. The default value is one because that is the value most commonly used. A value greater than one is generally used in special circumstances and caution should be exercised because it may produce unexpected results, including split files that are not proper XML files (not well-formed).

Split vs Extraction

If a depth greater than one is specified, an extraction occurs rather than a split. Only elements that match the split criteria are written to the output file. Node types other than elements, such as comments, that occur before and after the a matching element are also written. Elements that do not match are not written because if they occur at a different depth, a file with unclosed elements would result, which is not a well-formed XML file. In the sample books.xml, each book element occurs at a depth of one, with first-name occuring at a depth of three. using the first split method to split every 10th element at a depth of three with the name "first-name" results in a split file containing first-name elements only.

/e=element name example: /e=author

Optional. Applies to split methods 1 and 6. If specified, a new split file is created when the name of the element being read is identical to the name specified by this argument and all other other criteria for the split method are met.

/f=frequency example: /f=1000 specifes every 1000th element is written to a separate file.

required for split method number one only. The XML file is read and all nodes and content are written to the output file. Elements at the specified depth are counted until the frequency value is reached. At that point, the output file is closed and the next output file is started.

/g=search string example: /g=book

Optional. Applies to split methods 5. A new split file is created when the node types specifed in the /n argument occur and the value of the node contains the text specified by this argument.

/h=header element example: /h=true

Optional. Applies to all split methods. The term "header element" is used here to refer to the first element under the root element. If this argument is used, the header element, including all of its descendant nodes, is written to each of the split files. Note that the value provided for this argument can be any string and does not have to be the name of the header element. "true" is used in the above example. /p>

/i=include file. example: /i="c:\temp\includethisfile.xml"

Optional. Identifies a file to insert in each output file.

If the root parameter is not specified, the include file is inserted at the beginning of each split file.

If the root parameter is specified, the insertion point of the include file is determined by the occurence of an XmlDeclaration in the include file:
if it starts with an XmlDeclaration the include file is inserted at the beginning of each split file;
otherwise it is inserted immediately after the start tag of the root element.

The include file may begin with an XmlDeclaration node and may contain comments and other node types. It may be used in conjunction with an append file. It does not have to be a well-formed XML file, but each node in it must have correct XML syntax.

/j=Preserve Structure example: /j=true

Optional. Applies to split methods 1 and 6. This option ensures that all split files have the identical structure as the source XML document from the start of the file up to the first element that matches the split criteria. Each node that occurs in the source XML prior to the first element that matches the split criteria is written to the start of each split file. If any of these nodes are open elements, their corresponding end tags are written to the end of each split file to ensure that all elements are closed and properly nested.

Note: this option is not compatible with the following options: root element, header element, threshold element, include file, append file, WriteDTD. These options are ignored if the Preserve Structure option is specified.

The registration key that was provided upon purchase of this program. To register the program, run the program once using only the "k" parameter and the registration key. If the key is valid, the exit code will be zero, Please notify the vendor at support@xponentsoftware.com if the registration fails.

/n=node list example: /n=comment,cdata,processinginstruction

Optional. Applies to split method 5. This argument must be a comma delimited list containing any of the following node types: comment, cdata or processinginstruction. A new split file is created when any of the node types listed in this argument occur and the depth in the XML hierarchy is one.

/o=output file. example o="c:\temp\output.xml"

Required. A fully qualified file name. It must be enclosed in double quotes. Auto-incremented file names are created using this file name by inserting a number at the last position before the extenstion, for example, "c:\temp\output1.xml", "c:\temp\output2.xml", etc. The output file does not need to be an existing file, but XmlSplit must have permissions needed to create files in the specified folder.

/p=append file. example: /p="c:\temp\filetoappend.xml"

Optional. Identifies a file to append to each output file. It may be used in conjunction with an append file. It does not have to be a well-formed XML file, but each node in it must have correct XML syntax.

/r=root element. example /r=rootelement"

Optional. A string comprising a properly named XML element. The specified root is used to create the root node for each split file. Note that by default the root element of the source XML file is not written to any of the split files. Therefore, the /r argument assures that each split file has a document root. Markup characters(XML angle brackets) must not be included and will result in an error if they are included. XmlSplit inserts the required markup when the output files are written. Attributes are permitted. Alternatively, a root may be written to each split file by using an include file (/i argument) with the root start tag, along with any attributes, and an append file(/p argument) with the root end tag. However, do not use this method and the /r agrument or the split files will have two roots and will not be well-formed XML.

This argument should not be enclosed in quotes with the following exception:
If attributes, such as a namespace, are included with a root in the /r argument, the entire argument must be enclosed in double quotes with single quotes around each attribute value, as in this example:
/r="book xmlns:f='http://www.xponentsoftware.com/xslt/fragmentation'"

If the attributes are enclosed in double quotes, XmlSplit will fail and return an error value for the exit code. The Wizard will automatically replace double quotes for attributes with single quotes and enclose the entire root in quotes as needed when it generates the script. The Wizard also has a command button that inserts the entire root start tag including any attributes it has into the root node textbox in the dialog. Note that when you use this button, if the attributes have double quotes they are not replaced until you click the Generate button.

/s=split method example: /s=1 or /s=1 specifies method number one.

The split method must be an integer in the range 1-5 as defined below:
1: split every nth element at depth equal to the depth argument
2: split when an element's tag name changes at depth equal to the depth argument
3: split when value of the attribute argument changes in an element at depth equal to the depth argument.
4. split when the namespace in score changes, optionally in the specified element name and at the specified depth.
5. split when any of the node types specified by the /n argument occurs at a depth of one and optionally containing the text specified in argument g. 6. split when specified number of bytes are written and optional element name occurs at specified depth.

/t=threshold element. example: /t=book

Optional. A named XML element at which to begin processing. It is used to to skip over unwanted elements at the beginning of the XML document. XmlSplit reads until the it reaches the first occurence of the named element and then begins evaluation of the other parameters.

/w=write DOCTYPE node. example: /w=1

Optional. An integer from 1 to 3:
If an XmlDocumentType node occurs in the source XML document, this argument controls if and when it is written. The following lists the possible values and their meaning.
1: write DOCTYPE to every split file
2: write DOCTYPE to first split file only
3: write DOCTYPE to none of the split files

The wizard has a drop down combo box that lists the above options. It is disabled if the XML file does not have a DOCTYPE node, in which case the script generated by the Wizard will not have the /w argument.

/x=Xml File example: /x="c:\temp\myXML.xml""

specifies the Xml file to be split. The file name must be enclosed in double quotes.

/z=Split File Size example: /z=5000000

Used with split method 6. The Xml file is split after the specified number of bytes have been written.