Running XBinder from the Command-line

---

The XBinder distribution contains a command-line compiler executable as well as a graphical user interface (GUI) wizard (Windows version only) 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.0.x
 
Copyright (c) 2002-2004 Objective Systems, Inc. All Rights Reserved.
 

 
Usage: xbinder <filename> options
 

 
	<filename>         XML schema source file name
 

 
  options:
 
	-xml               generate XML encode/decode functions
 
	-soap              add logic to format/parse SOAP headers
 
	-trace             add trace diag msgs to generated code
 
	-c                 generate C code
 
	-c++ or -cpp       generate C++ code
 
	-config <file>     specify configuration file
 
	-nodecode          do not generate decode functions
 
	-noencode          do not generate encode functions
 
	-warnings          Output compiler warning messages
 
	-o <directory>     Output file directory
 
	-I <directory>     Import file directory
 
	-all               Compile all dependent files
 
	-w32               Generate Windows code (default = GNU)
 
	-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
 
	-useNSPfx          Use namespace prefixes in C/C++ code

	-modularize        Handle included schemas as separate modules
 

 
  additional code generation options:
 
	-genMake           generate makefile 
 
	-genTest           generate test code
 
	-genWriter         generate writer test program
 
	-genReader         generate reader test program
 
	-genFree           generate memory free functions (C only)
 
	-genPrint [<filename>] or
 
	-print [<filename>] generate print functions
 
	-usePDU <element>  use PDU for writer/reader test program
 

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). It is anticipated that additional language bindings will be added in the future (C# and Java), and additional binary encoding rules (such as ASN.1 BER and PER) to allow more compact and lightweight messages to be produced for a given schema.

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.
-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.
-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.
-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. That is what the functions generated using this option do.
-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 depending on the setting of the -w32 command line option described next.
-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 the print the decoded field values to standard output.
-gentest	None	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.
-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.
-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).
-noencode	None	This option suppresses the generation of encode functions.
-nodecode	None	This option suppresses the generation of decode functions.
-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.
-soap	None	Add logic to generated 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.
-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.
-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.