The Properties
interface provides several operations for converting properties to and from command-line options.
On this page:
Converting Properties to Command-Line Options
The getCommandLineOptions
operation converts an initialized set of properties into a sequence of equivalent command-line options:
module Ice { local interface Properties { StringSeq getCommandLineOptions(); // ... }; };
For example, if you have set the Filesystem.MaxFileSize
property to 1024 and call getCommandLineOptions
, the setting is returned as the string "--Filesystem.MaxFileSize=1024"
. This operation is useful for diagnostic purposes, for example, to dump the setting of all properties to a logging facility, or if you want to fork a new process with the same property settings as the current process.
Converting Command-Line Options to Properties
The parseCommandLineOptions
operation examines the passed argument vector for command-line options that have the specified prefix:
module Ice { local interface Properties { StringSeq parseCommandLineOptions(string prefix, StringSeq options); // ... }; };
Any options that match the prefix are converted to property settings (that is, they initialize the corresponding properties). The operation returns an argument vector that contains all those options that were not converted (that is, those options that did not match the prefix).
Because parseCommandLineOptions
expects a sequence of strings, but C++ programs are used to dealing with argc
and argv
, Ice provides two utility functions that convert an argc
/argv
vector into a sequence of strings and vice-versa:
namespace Ice { StringSeq argsToStringSeq(int argc, char* argv[]); void stringSeqToArgs(const StringSeq& args, int& argc, char* argv[]); }
You need to use parseCommandLineOptions
(and the utility functions) if you want to permit application-specific properties to be set from the command line. For example, to allow the --Filesystem.MaxFileSize
option to be used on the command line, we need to initialize our program as follows:
int main(int argc, char* argv[]) { // Create an empty property set. // Ice::PropertiesPtr props = Ice::createProperties(); // Convert argc/argv to a string sequence. // Ice::StringSeq args = Ice::argsToStringSeq(argc, argv); // Strip out all options beginning with --Filesystem. // args = props->parseCommandLineOptions("Filesystem", args); // args now contains only those options that were not // stripped. Any options beginning with --Filesystem have // been converted to properties. // Convert remaining arguments back to argc/argv vector. // Ice::stringSeqToArgs(args, argc, argv); // Initialize communicator. // Ice::InitializationData id; id.properties = props; Ice::CommunicatorPtr ic = Ice::initialize(argc, argv, id); // At this point, argc/argv only contain options that // set neither an Ice property nor a Filesystem property, // so we can parse these options as usual. // // ... }
Using this code, any options beginning with --Filesystem
are converted to properties and are available via the property lookup operations as usual. The call to initialize
then removes any Ice-specific command-line options so, once the communicator is created, argc
/argv
only contains options and arguments that are not related to setting either a filesystem or an Ice property.
An easier way to achieve the same thing is to use the overload of Ice::initialize
that accepts a string sequence, instead of an argc
/argv
pair:
int main(int argc, char* argv[]) { // Create an empty property set. // Ice::PropertiesPtr props = Ice::createProperties(); // Convert argc/argv to a string sequence. // Ice::StringSeq args = Ice::argsToStringSeq(argc, argv); // Strip out all options beginning with --Filesystem. // args = props->parseCommandLineOptions("Filesystem", args); // args now contains only those options that were not // stripped. Any options beginning with --Filesystem have // been converted to properties. // Initialize communicator. // Ice::InitializationData id; id.properties = props; Ice::CommunicatorPtr ic = Ice::initialize(args, id); // At this point, args only contains options that // set neither an Ice property nor a Filesystem property, // so we can parse these options as usual. // // ... }
This version of the code avoids having to convert the string sequence back into an argc
/argv
pair before calling Ice::initialize
.
Converting Reserved Command-Line Options to Properties
The parseIceCommandLineOptions
operation behaves like parseCommandLineOptions
, but removes the reserved Ice-specific options from the argument vector:
module Ice { local interface Properties { StringSeq parseIceCommandLineOptions(StringSeq options); // ... }; };
This operation is also used internally by the Ice run time to parse Ice-specific options in initialize
.
See Also
- Properties Overview
- The Properties Interface
- Reading Properties
- Setting Properties
- Command-Line Parsing and Initialization
- Logger Facility