Running XBinder from the Command-line

---

The XBinder distribution contains a command-line compiler executable as well as a graphical user interface (GUI) wizard that can aid in the specification of compiler options. This section describes how to run the command-line version; the operation of the GUI is described in the online help files built into the wizard.

To test if XBinder was successfully installed, enter xbinder with no parameters as follows (note: if you have not updated your PATH variable, you will need to enter the full pathname):

	xbinder

You should observe the following display (or something similar):

XBinder Compiler, Version 1.2.x
Copyright (c) 2002-2007 Objective Systems, Inc. All Rights Reserved.

Usage: xbinder <filename> options

    <filename>         XML schema or WSDL source file name(s).
                         Multiple filenames may be specified.
                         * and ? wildcards are allowed.

  Basic options:
    -xml               Generate XML encode/decode functions
    -dom               Generate DOM encode/decode functions (C only)
    -sax               Generate SAX-based decoders (default is pull-parser)
    -c                 Generate C code
    -c++ or -cpp       Generate C++ code
    -config <file>     Specify schema bindings file.
    -nodecode          Do not generate decode functions
    -noencode          Do not generate encode functions
    -o <directory>     Output file directory
    -I <directory>     Import file directory
    -all               Compile all dependent files
    -modularize        Handle included schemas as separate modules
    -warnings          Output compiler warning messages
    -trace             Add trace diag msgs to generated code
    -compat <version>  Generate code compatible with previous
                         compiler version. <version> format is 
                         x.x (for example, 1.0)

  Options to alter generated code:
    -cppns <ns> 			Add given C++ namespace to generated code (C++ only)
    -fragments         Generate code to encode XML fragments
                         (start element, contents, end element)
    -static            Generate code that uses static memory
                         (when possible, C only)
    -lax               Generate code that does lax error checking
    -namespace         Specify a namespace prefix for all generated items
    -noheader          Do not add code to encode XML header (<? xml ...)
    -noderiv           Do not generated special derived type code
    -numDateTime       Use numeric structures for all date/time types
    -pdu <element>     Designate element to be a PDU
    -elemCasing <value> Set element name case to lower/upper
    -typeCasing <value> Set type name case to lower/upper
    -soap              Add logic to format/parse SOAP headers
    -useNSPfx          Use XSD namespace prefixes in C/C++ code

  Options for the generation of additional code:
    -genMake           Generate makefile 
    -genWriter         Generate writer test program
    -genReader         Generate reader test program
    -genFree           Generate memory free functions (C only)
    -genPrint          Generate print functions
    -genRWTest         Generate read/write test program
    -genTest           Generate test code
    -genValid          Generate validation functions
    -nocopy            Do not generate copy methods (C++ only)
    -usePDU <element>  Use PDU for writer/reader test program
    -w32               Use with '-genMake' to generate Windows NMAKE file
                         (default = GNU)

To use the compiler, at a minimum, a single XSD or WSDL source file must be provided along with at least one set of encoding rules and a target output language. The current version of XBinder supports the generation of C (-c option) or C++ (-cpp option) source code and the generation of code to encode/decode XML (-xml).

The source file specification can be a full pathname or only what is necessary to qualify the file. If directory information is not provided, the user's current default directory is assumed. Multiple source filenames may be specified on the command line to compile a set of files. The wildcard characters `*' and `?' are also allowed in source filenames (for example, the command `xbinder *.xsd -c -xml' will compile all XSD files in the current working directory).

The following table lists all of the command line options in alphabetical order and what they are used for:

Option	Argument	Description
-all	None	This option is used to tell the compiler to generate code for all dependent files in a given compilation. This includes the main XSD files specified on the command line as well as all imported and included schema files.
-c	None	Generate C source code.
-c++ -cpp	None	Generate C++ source code.
-cppns	<name>	This option causes the given name to be added to generated C++ code as a C++ namespace declaration.
-compat	<version>	This option causes code to be generated that is compatible with an older version of the XBinder compiler. The format of the version number is "n.n" (for example, 1.0).
-config	<filename>	This option is used to specify the name of a file containing configuration information for the source file being parsed. This is similar to the `binding schema' used with some other XML data binding applications.
-dom	None	Encode to or decode from a Document Object Model (DOM) tree structure instead of directly to/from XML text format. This allows processing unique to DOM to be done prior to serialization/deserialization (for example, XPath searches).
-elemCasing	lower or upper	This option is used to change the case of the first letter in element names in the C or C++ code from what is specified in the XSD file. This option is typically used when the XSD file contains type, element, and/or attribute names that are the same. It provide a way to make the name disambiguous in the generated C or C++ code. Typically, element names are set to lower case.   See -typeCasing for changing the case of type names.
-fragments	None	This option is used to generate additional encode functions that allows fragments (parts) of an XML document to be created without having to create an entire document. The start element, contents, and end element fragments for any given type can be created using these functions. This is useful for stream-oriented protocols such as XMPP.
-genfree	None	This option instructs the compiler to generate memory free utility functions. Memory free functions are C functions that allow all memory within a given structure to be freed. It is possible to free memory without these functions by using the rtxMemFree function on a context. This frees all memory held by the context. But some applications require the capability to free the memory associated with a given structure.
-genmake	None	This option is used to generate a makefile to build the generated code. The makefile is compatible with either the GNU make utility or the Visual Studio nmake utility. A Windows Visual Studio nmake file is generated if -w32 is added to the command-line.
-genreader	None	This option is used to generate a complete reader program similar to what can be found in the sample subdirectory. This program will read an encoded XML document from an input file, decode it, and then print the decoded field values to standard output.
-genrwtest	None	This option is used to generate a read/write test program. This program will read an XML document corresponding to a specified global element definition in the compiled schema document, decode it, and then re-encode it and write it to an output file.
-gentest	<xmlfile> (optional)	This option instructs the compiler to generate test utility functions. Test functions populate an instance of each global element defined within a schema with random test data to be encoded. The functions provide a good template for writing code to populate the generated programatic variables. The functions are written to <modulename>Test.c files where <modulename> is the base name of the XSD source file that was parsed.   If the optional XML filename argument is provided, the generated test functions will use data from the given XML instance instead of generating random test data.
-genvalid	None	This option is used to generate validation functions. These functions are used to validate a given XML instance against the compiled schema. The functions are written to <modulename>Vldt.c files where <modulename> is the base name of the XSD source file that was parsed.
-genwriter	None	This option is used to generate a complete writer test program similar to what can be found in the sample subdirectory. This program will populate a record with test data, encode the data into XML, and then write the encoded record to an output file.
-I	<directory>	This option is used to specify a directory that the compiler will search for XSD <import> and <include> items. Multiple -I qualifiers can be used to specify multiple directories to search.
-lax	None	This option causes decode/validation functions to be generated that contain less schema-validation error checking code. This can be useful for working with XML documents that are not completely valid with regards to the schema.
-modularize	None	This option is used when XSD <include> directives are included in a schema to tell the processor to put the generated code in separate output files based on the include file names. The default behavior if this is not used is to include all of the code in the main file that is including the definitions. This can only be used if the included files can be successfully compiled on their own (i.e. are not dependent on definitions from the parent module).
-namespace	<prefix>	This option causes a prefix to be prepended to all generated items (typedefs and functions). This makes it possible to disambiguate items with the same names that are in different schemas. Note that the -useNSPfx option can be used to use namespace prefixes that are defined in the XSD document for this purpose (see the description of this option below).
-noencode	None	This option suppresses the generation of encode functions.
-nodecode	None	This option suppresses the generation of decode functions.
-noderiv	None	Do not generate extra code for run-time derived type handling. This code makes it possible to decode complexContent types using xsi:type declarations.
-noheader	None	This option suppresses the generation of code within the encode functions to add the XML header line to generated documents. This is the first line in the document that begins with `<?xml'.
-numDateTime	None	This option causes numeric date/time structures to be used for all XSD data/time types (date, time, dateTime). The default is to use strings for these items.
-o	<directory>	This option is used to specify the name of a directory to which all of the generated files will be written.
-pdu	<element>	This option tells the compiler to recognize the given global element as a protocol data unit (PDU). A PDU is a main message type in the module for which encode and decode functions are generated. By default, the compiler only recognizes non-referenced global elements as PDU's. This allows this default behavior to be overridden.
-print	None	This option instructs the compiler to generate print utility functions. Print functions are debug functions that allow the contents of generated type variables to be written to stdout. The functions are written to <modulename>Print.c files where <modulename> is the base name of the XSD source file that was parsed.
-sax	None	This option causes SAX handlers to be generated for decoding XML documents. Prior to XBinder version 1.2, this was the default (and only) method for decoding XML messages. XBinder 1.2 uses a pull-parser by default for XML decoding.
-soap	None	This option causes additional code to be generated to add or parse SOAP envelope, body, and fault tags in XML messages. This allows the messages to be used in a SOAP client or server application.
-static	None	This option instructs the compiler to use static memory whenever possible when generating C source code. The array's size will be determined by the type's maxLength or length facet.
-trace	None	This option is used to tell the compiler to add trace diagnostic messages to the generated code. These messages cause printf statements to be added to the generated code to print entry and exit information into the generated functions. This is a debugging option that allows encode/decode problems to be isolated to a given production processing function. Once the code is debugged, this option should not be used as it adversely affects performance.
-typeCasing	lower or upper	This option is used to change the case of the first letter in type names in the C or C++ code from what is specified in the XSD file. This option is typically used when the XSD file contains type, element, and/or attribute names that are the same. It provides a way to make the name disambiguous in the generated C or C++ code. Typically, type names are set to upper case.   See -elemCasing for changing the case of element names.
-useNSPfx	None	This option instructs the compiler to add the namespace prefixes defined in the XSD source files to the generated C/C++ names. The format of the names generated when this is specified is <prefix>_<name>. This is useful when an XSD specification consists of multiple shemas defined in multiple namespaces and the same names are used for entities across the specifications but within different namespaces. This prevents name collisions in the generated code at the expense of creating more verbose names.
-usepdu	<element>	This option cause the given protocol data unit (i.e. global element) to be used as the basis for generated reader and writer programs. If not specified and the compiled schema contains multiple PDU types, a type will be chosen at random.
-warnings	None	Output information on compiler generated warnings.
-w32	None	This option causes the compiler to make adjustments to the code generation that are specific to the Windows operating system. For example the backslash character (\) is used as a path separator instead of forward slash (/). The format of the generated makefile is also in Visual Studio nmake format (see -genmake above).
-xml	None	Generate encode/decode functions that marshall programatic data to and from XML format.