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 2.0.x Copyright (c) 2002-2009 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. Language options (choose only one): -c Generate C code -c++ or -cpp Generate C++ code -c# or -csharp Generate C# code -java Generate Java code Basic options: -xml Generate XML encode/decode functions -config <file> Specify schema bindings file. -o <directory> Output file directory -I <directory> Import file directory -all Compile all dependent files -warnings Output compiler warning messages -compat <version> Generate code compatible with previous compiler version. <version> format is x.x (for example, 1.0) Options to reduce amount of generated code: -lax Generate code that does lax error checking -noderiv Do not generate special derived type code Options to alter generated code: -namespace Specify a namespace prefix for all generated items -nodatestamp Do not put date stamp in header -nomixed Do not generate string structure for mixed content -elemCasing <value> Set element name case to lower/upper -typeCasing <value> Set type name case to lower/upper Options for the generation of additional code: -genPrint or -print Generate print functions C/C++ basic options: -dom Generate DOM encode/decode functions (C only) -sax Generate SAX-based decoders (default is pull-parser) -modularize Handle included schemas as separate modules -nodecode Do not generate decode functions -noencode Do not generate encode functions -trace Add trace diag msgs to generated code C/C++ options to reduce amount of generated code: -compact Generate compact code -nocopy Do not generate copy methods (C++ only) -noheader Do not add code to encode XML header (<? xml ...) -noxmlns Do not generate namespace attributes in all structs C/C++ options to alter generated code: -c14n Generate C14N format encode functions -cppns <ns> Add given C++ namespace to generated code (C++ only) -derivModel extended|interface Set the derivation model to extended or inteface. -fragments Generate code to encode XML fragments (start element, contents, end element) -initlists Generate code that initializes lists to default (when possible) -noEncDefault Do not add schema default/fixed values to XML instance. -noNamedBits Do not generate named bits for EnumList, use regular list instead. -numDateTime Use numeric structures for all date/time types -pdu <element> Designate element to be a PDU -project <prj_name> Set project name -soap, -soap12 Generate code to format/parse SOAP v1.2 messages -soap11 Generate code to format/parse SOAP v1.1 messages -static Generate code that uses static memory (when possible, C only) -strict Generate code that does strict syntax checking -useNSPfx Use XSD namespace prefixes in C/C++ code -useflteq Use float equality functions to ignore rounding errors in floating-point comparisons -usestl Use C++ Standard Template Library (STL) (currently, only STL string type is used) C/C++ options for the generation of additional code: -genWriter Generate writer test program -genReader Generate reader test program -genFree Generate memory free functions (C only) -genKeyTest Generate code to test identity constraints (xsd:key, xsd:keyref, xsd:unique) -genFactory Generate Factory functions -genRWTest Generate read/write test program -genStubs Generate SOAP client stub functions from WSDL -genSkel Generate SOAP skeleton server program from WSDL -genClient Generate web service client test program from WSDL -genTest [<xmlfile>] Generate test code. If XML instance provided, this will be used; otherwise, random data -genValid Generate validation functions -usePDU <element> Use PDU for writer/reader test program -w32 Use with '-genMake' to generate Windows NMAKE file (default = GNU) C/C++ options for makefile or project generation: -genMake Generate makefile -genMakeLib [<libname>] Generate code in makefile to put all objects into a static library -genMakeDLL [<dllname>] Generate code in makefile to build shared object -makeopts <dynamiclib | staticlib | multithreaded> Use compilation options for dynamic, static, and multithreaded libraries. C/C++ compression options: -exicompress Add code to generated reader/writer to use Efficient XML Interchange (EXI) format -zip Add code to generated reader/writer to use standard gzip compression (requires zlib install) C# basic options: -csnsname <name> Name for C# namespace -csnspfx <prefix> C# namespace names will be this prefix, followed by schema name Java basic options: -pkgname <name> Name for Java package -pkgpfx <prefix> Java package names will be this prefix, followed by schema name
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) or encode/decode to DOM (-dom).
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 | 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. |
| -c14n | None | Generate encode functions which use Canonical XML (http:// www.w3.org/TR/xml-c14n) mode by default. |
| -compact | None |
Generate more compact code. This is useful for generating code for embedded applications where code-size footprint is important. The main optimization made to generate more compact code is the omission of error message text and parameter code. The -lax option can also be used to reduce the amount of generated code. |
| -compat | <version> | Generate code 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. |
| -cppns | <name> | This option is used to specify a C++ namespace declaration to be added to generated code. |
| -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). Note that this option is currently only available with C code generation (not C++). |
| -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 provides 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. |
| -exicompress | None | Add API calls to generated reader and writer programs to convert XML data to and from Efficient XML Interchange (EXI) format as described in http://www.w3.org/TR/2008/ WD-exi-20080919/. |
| -fragments | None | Generate additional encode functions that allow 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. |
| -genclient | None | Generate a sample web services client program. This option must be used with option -genTest. The sample client program populates a request messasge with test data, sends to the server, and waits to receive the response message. |
| -genfree | None | 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. |
| -genkeytest | None | Generate xsd:key related identity constraint test functions. These functions are used to validate the structure of data to ensure it is compliant with xsd:key, xsd:keyref, and xsd:unique constraints defined within the schema. |
| -genmake | None | 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. |
| -genmakelib | <libname> (optional) | Generate a makefile to put objects into a static library named <libname>. If <libname> is omitted, the parent directory name would be used as the base name for the library. |
| -genmakedll | <dllname> (optional) | Generate a makefile to build a shared object named <dllname>. If <dllname> is omitted, the parent directory name would be used as the base name for the DLL. |
| -genreader | None | 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 | 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. |
| -genskel | None | Generate a server skeleton program. This option must be used with option -genTest. The skeleton server receives a request message, populates response message with test data, and sends the response message back to the client. A stub (empty) function is generated for each WSDL operation. These functions should be supplied by the Web Service developers. In the generated server code, some comments are put in place for calling of the these functions. |
| -genstubs | None | Generate stub functions. A "stub", in web service terms, is a function that works like a remote procedure call. It sends a request to a server and then turns around and waits for a response. The stub functions can be called from a test client program for a web service. The functions are written to the <modulename>WSDLSoapClientStubs.c file where <modulename> is the base name of the WSDL source file that was parsed. |
| -gentest | <xmlfile> (optional) |
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 | 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 | 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 will be searched for XSD <import> and <include> items. Multiple –I qualifiers can be used to specify multiple directories to search. |
| -initlists | None | Generate linked list initialization functions for complex types that have a repeating element with a default value. |
| -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> | Add the given prefix 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). |
| -nodatestamp | None | Do not insert a date stamp in the header of each generated file. This can be useful when using a source control system to prevent identical source files from appearing different. |
| -noencode | None | Do not generate encode functions. |
| -nodecode | None | Do not generate decode functions. |
| -noderiv | None | Suppress generation of extra code for run-time derived type handling. This code makes it possible to decode complexContent types using xsi:type declarations. |
| -noheader | None | Do not add an XML header to generated documents. This the first line in the document that begins with ‘<?xml’. |
| -nomixed | None | Do not generate a special structure to hold mixed content items. The generated code will more closely match the schema layout. However, mixed content will not be supported. |
| -noNamedBits | None | Do not generate a named bits structure for enumerated list items. Many application use an XSD list of enumerated items to express a bit map like structure for the specification of properties. By default, XBinder generates a corresponding bit structure to make setting the properties easier. However, some applications may have a need to repeat an enumerated item in a list more than one time. In this case, specification of this option will cause a standard linked list structure to be used. |
| -noxmlns | None | Do not generate namespace attribute lists in all generated C structures. In general, advanced namespace processing is not needed for many applications and the addition of the namespace attributes lists adds a considerable amount of size to the code. |
| -numDateTime | None | Use numeric date/time structures 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> | 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. |
| None | 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. | |
| -project | <name> | Set project name. By default, parent directory name is the used for the project name. |
| -sax | None | Generate SAX handlers 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 | Generate additional code 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. The version of SOAP supported by this option is set to the highest version currently supported by the application. This is currently version 1.2. |
| -soap11 | None | Generate additional code to add or parse SOAP 1.1 envelope, body, and fault tags in XML messages. This allows the messages to be used in a SOAP 1.1 client or server application. |
| -soap12 | None | Generate additional code to add or parse SOAP 1.2 envelope, body, and fault tags in XML messages. This allows the messages to be used in a SOAP 1.2 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 | Add trace diagnostic messages to generated code. These messages cause printf statements to be added 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 | Add 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. |
| -useflteq | None | Generate code which uses functions that account for a small margin of error to compare floating-point numbers. |
| -usepdu | <element> | This option causes 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 unreferenced global elements, a global element will be chosen at random. |
| -usestl | None | Use Standard Template Library (STL) classes (currently, std::string and std::vector) in generated C++ code. By default, STL is not used in generated code. |
| -warnings | None | Output information on compiler generated warnings. |
| -w32 | None | Indicate code generation is being done for use on 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. |
| -zip | None | Add standard gzip compression function calls to generated reader and writer programs. This requires that zlib be installed on the target system. |