Orbit > OTG > Function Specifications > User Interface

Function Specification: User Interface Design

User Interace provides a command shell to users. User can specify important program arguments in a standard command line format. "—option <arg>".

Design Requirement

The following principles of the design should be respected:

• User only need to give command-line options once to start the program. A step-by-step configuraton tends to be confusing, error-prone and complicates fault-handling.
• Configuration file shall not be used. (difficult to maintain)
• Run-time argument change must be supported whenever possible.
• In the run-time, user comamnd inputs can only change one parameter a time. (multiple changes at the same time might lead mutual conflicting)

Brief introduction abou using POPT

The OTG software uses POPT library to simplify the design of user interface. To use POPT, An "options" structure has to be defined first.

struct poptOption options[] = {
  POPT_AUTOHELP
  { NULL, '\0', POPT_ARG_INCLUDE_TABLE, NULL, 0, "Port" },
  { NULL, '\0', POPT_ARG_INCLUDE_TABLE, NULL, 0, "Generator" },
  { "protocol", '\0', POPT_ARG_STRING, NULL, 0, "Name of protocol"},
  { "generator", '\0', POPT_ARG_STRING, NULL, 0, "Name of generator"},
  { "debuglog", '\0', POPT_ARG_STRING, NULL, 0, "Filename of Measurements Log"},
  { "exit", '\0', POPT_ARG_NONE, NULL, 1, "Stop the generator and exit" },
  { "pause", '\0', POPT_ARG_NONE, NULL, 2, "pause the generator and exit" },
  { "resume", '\0', POPT_ARG_NONE, NULL, 3, "resume the generator" },
  { NULL, 0, 0, NULL, 0 }
};

then, use a while loop to parse all given option arguments. Whenever an option name matches one of the options defined in the options array, the "poptGetNextOpt" fucntion call will return a value. Different options return differnt valuse. This occurs repetitively until the value returns -1. So, In "case" of differnt value, different handling routing should be proceeded.

  int rc;
  while ((rc = poptGetNextOpt(optCon)) > 0) {

        if (rc == 1) {// Stop
	  str->exitStream();
          exit(0);  //exit terminate process and all its threads
        }
        else if (rc == 2)
	{ 
          str->pauseStream();         
	}
	else if (rc==3)
	{
          str->resumeStream();
	}     
  };
  if (rc < -1) {
    cerr << "ERROR: " << poptBadOption(optCon, POPT_BADOPTION_NOALIAS)
	 << " (" << poptStrerror(rc) << ")" << endl;
  }
  poptFreeContext(optCon);
  return rc;	

OTG User Interface

In OTG program, first-tier options are following

• protocol, generator, debuglog

"protocol" and "generator" must be parsed correctly before other arguements related to them can be understood. "debuglog" is used only for turning on the local logging of measurements. Because first-tier options are pivotal and governing 2nd-tier options in the program, run-time changes for them are impossible.

Correspondingly, three fucntions are used in parsing options:

• parseOptionsPhase1
• parseOptionsPhase2
• parseRuntimeOptions

parseOptionsPhase1 is used to set values for variables corresponding to first-tier arguments Because both Port and Generator are vitual base class, a certain type of Port and Generator objects will be created based on those variables. Second-tier options are parsed by parseOptionsPhase2. Certain properties of newly created Port and Generator objects will be set. Finally, parseRuntimeOptions will parse run-time user input to change a certain set of parameters. For initial shell user inputs, argc and argv are automatically provided by standard C. So, we pass them to POPT function directly. But for run-time user inputs, a special char* variable msg is taken as the parameter. The msg contain the setting for only one options and either in "—option <arg>" format or without leading hyphons.

OTR User Interface

In OTR program, first-tier options are following

• protocol, debuglog

"protocol" must be parsed correctly before other arguements relating to receiving functions could be understood. "debuglog" is used only for turning on the local logging of measurements. Because first-tier options are pivotal and governing 2nd-tier options in the program, run-time changes for them are impossible.

Correspondingly, three fucntions are used in parsing options:

• parseOptionsPhase1
• parseOptionsPhase2
• parseRuntimeOptions

parseOptionsPhase1 is used to set values for variable corresponding to first-tier arguments Because Gate is a virtual base class, a certain type of Gate object will be created based on prootcol_name variable. Second-tier options are parsed by parseOptionsPhase2. Certain properties of newly created Gate object will be set. Finally, parseRuntimeOptions will parse run-time user input to change a certain set of parameters. For initial shell user inputs, argc and argv are automatically provided by standard C. So, we pass them to POPT function directly. But for run-time user inputs, a special char* variable msg is taken as the parameter. The msg contain the setting for only one options and either in "—option <arg>" format or without leading hyphons.

Difference between OTG and OTR user interface design

As can be seen, the deisng for OTG and OTR user interfaces are quite similar, but there are two major differnce:

• Gate does not need "generator" related options
• Gate does not support run-time pause and resume options.

Discussion

A major shortcoming of current design is the "—help" option does not disclose the full scale of option structure. Only first-tier options are showed.