Technical Notes on Suprem TCL shell

How to define a new Suprem command
Description of the Files
Description of Data Types
Error Reporting

How to define a new Suprem command

define valid parameters by inserting a Parser_ParameterDef table in syntaxDefinition.c
insert a typedef for command specific data structure used to hold the actual parameter values in commandDefinition.h
insert a Sup_WrapperData structure appropriate for the command into commandHandler.c
insert appropriate declarations for the Parser_ParameterDef and the Sup_WrapperData in commandDefinition.h
registers new command with the Tcl Interpretter by adding in appropriate Tcl_CreateCommand line in tkAppInit.c

Description of the Files

Include Files

parser.h
parser specific constants/data structures
valueGetters.h
routines used by the suprem core for extracting command parameters
tclshell.h
commandDefinition.h
defines command specific data structures to hold the parameter values

C Files

Parser Services
- argvPreprocessor.c
  Preprocesses the command line argv array returned by TCL into parameter name/value pairs that the parser proper could recognize.
- parser.c
  Processes the parameter name/value pairs for each command and stores the parameter values in the appropriate command specific parameter data structure
- syntaxDefinition.c
  Defines and Initialized the Parameter Definition Tables used by the parser
Command Dispatch
- cmdDispatcher.c
  defines Sup_Wrapper function which takes of calling the parser services, and packaging the parsed parameters into a form that can be used by the valueGetter funcations, then dispatches the appropriate routines to execute the command
- commandHandler.c
  defines and initializes the data structures needed by Sup_Wrapper for correct command dispatch
Other Support Services
- tkAppInit.c
  registers the suprem commands with the Tcl Interpreter
- valueGetters.c
  provides the interface between Suprem and the parser: provides the routines that the suprem functions uses to extract the parameter data
- messageLog.c
  provides a means of error reporting/logging. allows fine grain control of the level of reporting.

Calling Sequence

   --------> Tcl_Interpreter
  |                 |command line, 
  |                 |Appropriate Sup_WrapperData
  |                 |
  |                 V         command line
  |            Sup_Wrapper ---------------> Parse_Argv
  |                                              |
  |                                              |Translated command line
  |                                              V
  |                                         Parser_ProcessParameters
  |                                              |
  |                                              |Filled in WidgetRec
  |                                              V
  |                                              *
  |                                              |Packaged Sup_CommandData
  |                                              V
Appropriate Suprem Command <-------------------  *
                            Casted pointer to int

Defined in: include/parser.h
Associated Variable Naming Convention: param<Command>
Located in: tclshell/syntaxDefinition.c
Adapted from the Tk_ConfigSpec datatype, Parser_ParameterDef defines the parameters that are known to a command, and is used by the parser services. The typedef for Parser_ParameterDef is as follows:

  typedef struct Parser_Parameter {
      int type;                   /* Type of option, such as PARSER_TYPE_INT;
                                   * see definitions below.  Last option in
                                   * table must have type PARSER_TABLE_END. */
      char *argvName;             /* Switch used to specify option in argv.
                                   * NULL means this spec is part of a group. */
      char *dbName;               /* Name for option in option database. */
      char *dbClass;              /* Class for option in database. */
      char *defValue;             /* Default value for option if not
                                   * specified in command line or database. */
      int offset;                 /* Where in widget record to store value;
                                   * use Parser_Offset macro to generate values
                                   * for this. */
      int specFlags;              /* Any combination of the values defined
                                   * below;  other bits are used internally. */
      Parser_CustomOption *customPtr;
                                  /* Generic pointer for custom data */
  } Parser_ParameterDef;

Recognized Types include INT, DOUBLE, BOOL, STRING, and 2 special types ACLASS and ALTS. ACLASS defines a class of mutually exclusive options, and ALTS defines the options that belong to a particular ACLASS.

ANSI C compatible Macros are defined in the file syntaxDefinition.c to remove some of the tedium in defining parameters for a command. In general,

  PARAM_<TYPE>     ( <name of command>, 
                     <field in param<Command>Rec corresponding to parameter>,
                     <name of parameter>,
                     <option database entry for parameter>,
                     <default value> )

except for ACLASS and ALTS, which has

  PARAM_ACLASS     ( <name of command>,
                     <name of mutually exclusive option class>,
                     <default value> )
  PARAM_ALTS       ( <name of command>,
                     <name of option>,
                     <name of option class that the option belongs to>,
                     <value corresponding to current option> )

Parameter Record(s)
Parameter Record Structure Type Naming Convention: Param<Command>Rec
Defined in: include/commandDefinition.h
Structure Member are reserved for specific entries in the Parser_ParameterDef records.
```
  Entry Type      Member Type
  PARAM_INT    -> int
  PARAM_DOUBLE -> double
  PARAM_BOOL   -> boolean
  PARAM_STRING -> char *
  PARAM_ACLASS -> int
  PARAM_ALTS   -> <none>
```

type Sup_WrapperData

Defined in: include/parser.h
Associated Variables Naming Convention: <command>Wrap
Located in: tclshell/commandHandler.c
Data Structure containing the information needed by Sup_Wrapper for dispatch of the appropriate suprem routines. Definition as follows:

  typedef void WrapperInit(void);
  typedef void SupremFcn(char *par, int param);

  typedef struct {
    int widgRecSize;           /* size of associated widgRec */
    Parser_ParameterDef *paramSpecs;
                               /* definition and info of the parameters */
    SupremFcn *supremFcn;      /* suprem C func to carry out the command */
    char *commandName;         /* also widget pathname for option database */
    WrapperInit *initproc;     /* a chance to initialize, eg. SUP_ALT field */
  } Sup_WrapperData;

type Sup_CommandData
Defined in: include/parser.h
Data Structure containing pointers to the current tcl interpreter, the relevant Parser_ParameterDef structure, and the widget rec containing the parameter values. used by Sup_Wrapper to pass the relevant data to the suprem functions. also used by the valueGetters.c routines for the actual parameter extraction.
```
  typedef struct {
    Tcl_Interp *interp;        /* interp of client requestin service */
    Parser_ParameterDef *paramSpecs;
                               /* Tk_ConfigSpec defining the parameters */
    char *widgRec;             /* widgRec specifying value of the parameters */
  } Sup_CommandData;
```

Error Reporting

LogMask and MessageMask
There are two important concepts for the Error Reporting Services:
```
  the LogMask and the MessageMask.
```
They are used to control which messages are logged/displayed respectively.
They are accessed through the access functions GetLogMask, SetLogMask, GetMessageMask, and SetMessageMask.
We specify the log file to use by calling function OpenLogFile. We can choose whether to overwrite or append to the file if it exists. If the file cannot be opened, OpenLogFile returns TCL_ERROR.
LogMessage and LogError
We can log a message/error by calling either LogMessage and LogError. We specify the type of the message by the msgType argument.
Message Types/Flags
- Messages
  There are 3 levels of messages: MESSAGE_TYPE_INFO, MESSAGE_TYPE_DETAIL, & MESSAGE_TYPE_VERBOSE. By Setting MessageMask to MESSAGE_TYPE_DETAIL, messages of both type MESSAGE_TYPE_INFO and MESSAGE_TYPE_DETAIL would be displayed, but not messages of type MESSAGE_TYPE_VERBOSE. Similarly by setting MessageMask to MESSAGE_TYPE_VERBOSE, messages of all 3 types would be displayed. The same would apply to LogMask.
- Errors
  There are 3 levels of errors: MESSAGE_TYPE_ERROR, MESSAGE_TYPE_ALERT, & MESSAGE_TYPE_WARNING. By setting MessageMask to MESSAGE_TYPE_DETAIL, messages of both type MESSAGE_TYPE_INFO and MESSAGE_TYPE_DETAIL would be displayed, but not messages of type MESSAGE_TYPE_VERBOSE. Similarly by setting MessageMask to MESSAGE_TYPE_VERBOSE, messages of all 3 types would be displayed. The same would apply to LogMask.
- Flags
  If flag MESSAGE_TYPE_TCLRESULT is set, LogMessage/LogError would add the message/error to the result field of current TCL interpreter. If MESSAGE_TYPE_TCLRESULT is set in MessageMask, messages with MESSAGE_TYPE_TCLRESULT set for its msgType would also be displayed on terminal. If MESSAGE_TYPE_TCLRESULT is set in LogMask, messages with MESSAGE_TYPE_TCLRESULT set for its msgType will be added to the current log file.
  The flag MESSAGE_TYPE_DEBUG indicates a particular message is a debug message.