2.9 COMMAND MANAGEMENT SYSTEM

The Command Management system (cmd) of CCS provides the facility to manage the handling of command definitions of a process.

· simulate commands to nonexistent processes or environments

· assist in formatting and building default reply parameters

The complete functionality of the command management system is fully supported under CCS_LITE.

2.9.2 Basic Concepts

CCS(FULL & LITE) message system introduced the concept of commands that apply to a process delivering a specific service. The commands available to a process are gathered in a Command Definition Table (CDT) .

The Command Management System uses the CDT to check for the correctness of a command and it's parameters and to simulate commands. The CDT syntax is discussed in detail in the message system chapter 2.8.2.7.

The Command Management system also referred to as the cmd module is build on top of chkc which is part of LCC.

2.9.2.1 Command Check

Command definition tables are loaded via calls to the command management system. This could either be from a function call cmdParseCDT (used restricted to the booking system) or by the assisting utility cmdSetup.

When CDT's are loaded the cmd module can perform checks on commands. This is typically done from within the message system as commands are sent with msgSendCommand() when the msgCHECKFLAG is set by the calling process. Normal applications, once debugged, do not request such a check, while UIF via Sequencer should be checked. These checks obviously apply only to formatted messages (ASCII).

The parameter list is assumed to be formatted according to one of the two syntaxes accepted for a user input and described in the LCC User Manual[9] section 6.2 :

The cmd identifies the syntax used, and translates it into the transport format: position dependant parameters with separators between values, comma between parameters and spaces between values for one parameter.

During this translation, the following operations are performed for each parameter :

· Check that mandatory parameters have a value provided in the input buffer.

· When a default value is available for an optional parameter which is not provided, the value is inserted.

· Check that the user provided value is within range when a range or an enumeration is available for that parameter.

Messages with missing values for mandatory parameters, or invalid parameter names, or invalid values for parameters are rejected, and an error message is produced indicating the name of the wrong parameter.

If the translation can be performed without error, the formatted buffer is sent to the destination in place of the input buffer.

Commands which have missing parameters are expanded with default values provided that default values where defined in the CDT. When command check is performed in the message system this has to be explicitly specified with a check flag.

2.9.2.2 Command Simulation

Command simulation in the context of cmd means sending a command to a process which does not exist. The only requirement for simulation is that a CDT describing the commands in the process exists. The simulation is a service provided by the command manager: cmdManager.

The command manager is a system daemon that is started together with the CCS environment. The basic concept is shown on the figure above.

When the CCS environment is set in simulation state the cmd module intercepts the command sent by msgSendCommand. The destination is checked if it accepted as simulation target. If this is the case then the message is redirected to the command manager. The command manager gathers information related to the command from the CDT loaded in the OLDB and assembles a fictitious reply message. If the reply parameter values in the CDT are specified as reference to database points these database values are read and inserted as well. The simulation reply is nested into a reply message of the type msgTYPE_SIMREPLY. At the receiving side this message type is caught when parsing the message (msgParseMsg) where the header is stripped of.

What the originator of the command receives is the reply of the simulated process (as if it where sent by this process).

Command simulation applies to any process and is independent of command checking. The only prerequisite is that the CDT of the simulated process is loaded into the system.

2.9.2.3 CDT Information

Another important task of the cmdManager process is to provide information on the CDT's loaded in the system. The informations can be retrieved via commands send to cmdManager, see also cmdManager.cdt in the CDT directory of VLTROOT.

This information is used extensively by the CCS Engineering User Interface to give user feedback on command. For more information on this subject see chapter on ccsei.

2.9.3 Setting CCS simulation mode

· to allow simulation mode which is controlled by the environment variable CCSSTATE. In normal operation this variable is either unset or set to NORMAL and the message transfer is not intercepted. To set CCSSTATE to SIMULATION, which will allow checking of the destination of every command:

· from CCS Engineering User Interface command window select the "simulation" item in the "options" menu.

· to put individual processes in simulation mode to redirect the commands sent to this process to the cmdManager.:

· use the "simulation setup"item in the "windows" menu of the ccsei

2.9.4 cmdParam , cmdReply - command parameter and command reply support

2.9.4.1 Parsing parameters with cmdParam functions

In order to assist programs providing services via commands e.g. server programs in the process of parsing the parameters which are passed with the command a set of functions is provided by cmd:

cmdParamList() parses the message body, as it was received by msgParseMsg() and splits the incoming parameters into a list of parameter entries (cmdPARAM_LIST_ITEM). The cmdParamList() uses the CDT information to parse the parameters, thus the CDT of this server process must be present and loaded (either at environment start-up or by cmdSetup). The success of this parsing is of course dependent on a complete and correct (e.g. valid ranges) parameter list.

Once the parameter list is present the individual parameters can be accessed either via index number: cmdParamGetByIndex() or via parameter name cmdParamGetByName().These functions return the direct value of the individual parameter e.g. logical,string, integer or double.

Please note that when using cmdParamList() function call the first time the parameter structure cmdPARAM_LIST must be cleared. See also CAUTION section of man page to cmdParamList(3).

In order to support the forwarding of commands the function cmdParamToMsg() can be used to reassemble a message body from a given parameter list (cmdPARAM_LIST).

2.9.4.2 Parsing replies with cmdReply functions

Command parameters and command replies parameters have a similar structure. The parsing of reply parameters is identical to the parsing of command parameters as explained on the last paragraphs. Only, the function cmdParamList() should be replaced by cmdReplyList().

2.9.4.3 Building command parameters and replies

In some cases a process needs to build a command message to send to another process. The cmdParam functions can assist the user in this task. In order to build a parameter structure from scratch the function cmdParamDefault() can be used. It's result is a cmdPARAM_LIST type structure filled with the parameters of the specified command and with the default values (if any) as specified in the CDT. In the case of replies, the function cmdReplyDefault() will build a default reply structure from scratch. It's result is also a cmdPARAM_LIST type structure.

The values in the parameter structure can be manipulated with the functions cmdParmSetByName() and cmdParamSetByIndex() - or the different convenience functions which are adapted directly to the type of value: LOGICAL, INT, REAL (vltDOUBLE) and STRING.

After the parameter structure is set satisfactorily a new message body is built with the function cmdParamToMsg. This message body can be passed directly to msgSendCommand().

2.9.4.4 Formatting replies

When a reply buffer is received by an application, it is possible to build a formatted string ( to display ) with what is contained on it. For that purpose the function cmfFormatReply() should be used. It works on structured binary reply types and uses the DISPLAY_FORMAT specified on the CDT in order to produce the ascii string. If the reply type is ascii the cmdFormatReply will return the same ascii `reply' it received as input. If the reply type is unformatted binary cmdFormatReply will return an error.

2.9.5 Configuration

The CDT's are managed by the cmdManager that parses and loads the CDT's in the system, thus the cmdManager must be specified in the RtapEnvTable under the list of processes that must be started:

With this relase the cmdManager does not use the CCS shared memory area any longer.

As default the cmdManager loads all CDT's it finds in the VLTROOT environment and if present in the INTROOT environment. In order to customize this the user can optionally specify which CDT directories should be loaded from start-up. This is specified with the option -l - see manual page for details.

CDT's can be loaded (and unloaded) at any time by sending commands to the cmdManager or using the utility cmdSetup. cmdSetup can also be used to list the currently loaded CDT's.

2.9.6 Reference

cmdCheckCmd(). Check command parameters and inserts default values.

cmdParamList(). Parse message body to a list of parameters.

cmdParamDefault() Build a parameter structure filled with defaults from CDT.

cmdParamDelete() Delete parameters from parameter structure.

cmdParamGetByIndex(). Get values of parameter indexed by parameter number.

cmdParamGet<TYPE>ByIndex() For each type of parameter an convenience function exists

cmdParamGetByName(). Get values of parameter indexed by parameter name.

cmdParamGet<TYPE>ByName() For each type of parameter an convenience function exists

cmdParamSetByIndex(). Set values of parameter indexed by parameter number.

cmdParamSet<TYPE>ByIndex() For each type of parameter an convenience function exists

cmdParamSetByName(). Set values of parameter indexed by parameter name.

cmdParamSet<TYPE>ByName() For each type of parameter an convenience function exists

cmdParamFree(). Relase internal memory allocated by cmdParamList.

cmdSimulation(). Responses if a process or environment is in simulation

cmdReplyList(). Parse message body to a list of reply parameters.

cmdFormatReply(). Formats reply buffer to an ascii string.

cmdReplyDefault(). Build a parameter structure filled with defaults from CDT.

cmdCCS.h Contains constants, types and function prototypes of the cmd system

cmdSetup. Lists, checks and/or loads CDT files into the cmd system.

cmdManager Daemon to manage simulation of processes and retrieve CDT information.