Loading...
 

CXSENDMSG.EXE

CXSENDMSG.EXE

The program cxsendmsg.exe (also called Cxsendmsg) is used to send messages to remote ClassiX® instances via CORBA. The tool attempts to contact a remote ClassiX® instance with the help of the CORBA Naming Service (see also CORBA Installation) and to send an InstantView® message. Only the ClassiX®-Corba interface is used for this. The usual way of working is to send one or more files to a ClassiX® server and write the response to a file. Cxsendmsg sends its own Corba name along with the message. When receiving messages, Cxsendmsg also expects the name of the sender to be sent with the message.

At the same time, the programme serves as an example implementation for using the ClassiX® CORBA interface.

Call example:

The programme can be called up as follows:

cxsendmsg.exe -r <corbaname> -m <message> -- <dateiname>

The name of the remote ClassiX® instance is to be usedfor. As in almost the whole rest of the ClassiX® system, this is not the complete Corba name, but only the last part of the schema "ClassiX//"RemoteMsg"/, so for example for "ClassiX/Information/RemoteMsg/Classix1436" only "Classix1436". For is the name of the Instantview ® message to be sent, and must specify the path to a file. For this call, Cxsendsmg does the following: First, the specified file is read in. The content of the file is marshalled, i.e. encoded in such a way that ClassiX® can recognise that the content should represent an element of the InstantView stack. The entire content of the file is encoded as an element on the stack. Then the file name is also marshalled, the same applies to the Corba name of the sending Cxsendmsg. The filename is transmitted without any directory components (e.g. "d:\data\a1.dat" becomes "a1.dat"). Next, Cxsendmsg tries to contact the Corba naming service to find the specified ClassiX® instance. When this is done, the collected data is sent to the instance, which means a call to the method "SendMsg_CORBA(in string message, in MarshaledStack stack)" or in the asynchronous case "AcceptMsg_CORBA(in string message, in MarshaledStack stack)" of the ClassiX® Corba interface. The first element, with index 0, of "stack" is the file content, followed by the file name and then the Corba name.

After all this has happened, Cxsendmsg waits for an incoming Corba message, which is interpreted as a response from the server (i.e. the contacted ClassiX® instance). When the message arrives, Cxsendmsg extracts the file name chosen by the server and the corresponding data and writes them into the desired file. Caution. Existing files will be overwritten. Cxsendmsg tries to detect if the received filename contains a directory component and removes it if necessary. Thus, when called without further command line arguments, only files in the working directory are written by Cxsendmsg. Nevertheless, it is recommended not to start Cxsendmsg with unnecessary rights and to use the command line option "-s" (see table below) when testing new or changed messages.

The way Cxsendmsg works can be adjusted by arguments on the command line. Among other things, it is possible to swap the order in which elements are placed on the stack and it is possible to create one stack element per line of an input file instead of sending the whole file in one element. The following table lists the most important command line parameters: (identifiers in angle brackets must be replaced by a suitable value when called)

Parameter Meaning
-r The Corba name of a ClassiX® instance as returned by the RemoteClients method. *" can be used as a wildcard at the end of the name to select any entry in the NamingService. The value is optional, if it is omitted "*" is assumed.
-c A file containing the Corba name of a ClassiX® instance. If the first line of the file is "ClassiX" (without quotes), then the second line is interpreted as the Corba name. Otherwise, the first line is the Corba name.
-o The name of the project. This who corresponds to the middle part of the hierarchy "ClassiX"//"RemoteMsg"/. The project name is optional.
-l The Corba name to be used by the sending Cxsendmsg. Is added to "ClassiX/CorbaNameLocal/RemoteMsg". If the selected name is already registered with the naming service, the old binding is overwritten.
-m The name of the InstantView message to be sent.
-p A part of a path that precedes the received file name when saving files. It is recommended to specify an absolute path.
-s A supplementary part of a file name. This addition is appended to the received file name if the received name does not contain a dot ('.'). Otherwise, the complement is prefixed to the last dot of the name.
-i The way file contents and other stack elements are to be marshalled, i.e. encoded for transmission. The default encodes all items as an InstantView string and uses one item for one input file. For MarshalingMode, these specifications can be used:

"singlefile - Use one element per input file (default).
"linewise" - use one element per line
"marshal" - Perform marshaling (default).
"unmarshal" - Consider input data as already marshaled and undo this encoding.

These options can also be combined by specifying several in a row separated by commas. There must be no spaces between these individual options. Example "-i linewise,marshal" is correct. However, "-i linewise, marshal" would be incorrect. The specifications "singlefile" and "linewise" are mutually exclusive. If both "marshal" and "unmarshal" are specified, input data coded as InstantView integers are converted into InstantView strings. It is to be avoided to use other specifications than those listed above.
-d A file into which Cxsendmsg should write debug information.
-R Reverses the order of file name/file content pairs on the stack. The default is to send the content first and then the name. In addition, this option changes the position of the Corba name of the sending Cxsendmsg: By default, the Corba name is sent last, after all file name/file content pairs. With this option, the Corba name comes first.
-O In addition to writing to files, received data is also output on the programme's standard output. All data is written one after the other without further separators.
-P Prevents data from actually being written to files. If this is set by the -d option, data is still written to the debug file. Standard output and standard error output are also unaffected by this option.
-K Without this option, Cxsendmsg exits at the latest after the first Corba message has been received. With this option, Cxsendmsg waits for an unlimited number of messages, unless the option "-S" has determined that no messages are to be received at all.
-S Instructs Cxsendmsg not to wait for incoming messages.
-N With this option, no message is sent, contrary to the usual mode of operation.
-C Checks when messages arrive whether the number of stack elements received is odd. If this is not the case, a message is output.
-t This option must be followed by an argument that is sent on the stack. The argument is sent as received from the command line; it is not marshalled. If the -T option is not used, this element is the second highest on the stack. If the -T option is used, then this element becomes the second or third topmost.
-T This option must be followed by an argument that is sent on the stack. The argument is marshaled as an InstantView string, regardless of the marshaling mode set with the -i option. If the -t option is not used, this element is the second highest on the stack. If the -t option is used, then this element becomes the second or third topmost. 
-- <Datei1> [<Datei2> ...]
 After two middle strokes, only paths to input files may follow. If this command line argument is used, then at least one input file must be specified. Without this argument, an empty stack is sent with the InstantView message. Multiple files can be specified separated by spaces.

Passing arguments other than those mentioned in the table should be avoided.

Diagnostic messages

A variety of problems can occur while Cxsendmsg is running, such as failure to find a file intended as input, options not allowed on the command line, failure to contact the Corba naming service, and others. Many of these problems can be detected by Cxsendmsg. In these cases, the programme prints a diagnostic message on the standard error output. Such messages are not written to the standardoutput. Outputs that are made due to the command line option "-O" are only written to the standard output. Only messages originating from external libraries can deviate from this convention. Diagnostic messages are usually introduced by the words Error and Attention in pointed classifiers (&lmt;>, <>). After an error, Cxsendmsg terminates without sending or receiving further messages.

The following table gives some diagnostic messages and their meaning:

Message Meaning Remedy/procedure
Illegal command line: ...Details... ...Instructions for use... An argument on the command line is invalid or the number of arguments is too low. Further hints follow this message. Call Cxsendmsg with a valid command line.
Failed to read from remote Corbaname file. A file name was specified to read from the receiver, but it was not possible to read from this file. Check if the file exists and read permissions are available.
Not sending any input files. This message does not necessarily indicate an error: no files have been designated for sending.
Both -N and -S options were specified. This message does not necessarily indicate an error: Cxsendmsg should neither send nor receive messages. Decide whether an empty call is actually desired.
Failed to initialize ACE. An important library could not be put into operation.
A failure occurred while reading data to transfer from file. The name of the file is: ...filename... ...Other.... A failure occurred while reading from an input file. The name of the file is given. Further information follows, but does not necessarily indicate the exact reason for the error. Check whether the specified file exists and read rights are available.
Failed to register local interface with Naming Service. The Corba servant of Cxsendmsg could not be registered with the Corba Naming Service. Check if the network connection is stable and the naming service is still working.
A received message was invalid. Message waiting was cancelled because the last received message was not correctly established. Check if the format of the message is correct.
Opening an output file failed. The name of the file is: ...Filename... ...Other... A file for outputting received data could not be created. The name of the file is specified. Further information follows, but it does not necessarily indicate the exact reason for the error. Check whether a valid name was sent and whether write permissions are available for the file.
Writing to an output file failed. The name of the file is: ...Filename... ...Other... An error occurred while writing to an open output file. The name of the file is given. Further information follows, but does not necessarily indicate the exact reason for the error. Check whether there is enough free space on the drive.
An unknown error occurred while receiving messages. An error occurred while editing a message.
A memory allocation failed while processing remote messages. A memory request failed while processing a message. Check if there is sufficient memory available. Free memory must exceed the size of the message.
An exception occurred while processing remote messages. ...Details... ...Type of exception... An error occurred while processing a message. Details of the error are available.
The specified ClassiX instance was not found. No remote ClassiX instance could be found under the specified name. Check whether the instance you specified is running and registered.
CORBA exception caught: ...Details... The communication via Corba broke down. Further details about the error follow.

 Check whether the details contain the text "IDL:omg.org/CORBA/TRANSIENT". If so, it is probably not possible to use the Corba naming service. In this case, check whether the naming service is running and accessible via the network. Another probable cause is that a ClassiX instance previously registered with the naming service has terminated without logging off.
Caught exception: ...Details... ...Type of exception... An error occurred. More information follows that can tell you more about the type of error. The error probably occurred during or before transmission, not during reception.
A memory allocation failed. A memory request failed. The error probably occurred when sending, not when receiving. Check whether there is sufficient memory. Free memory must exceed the size of the message.
Unknown exception caught. An error occurred. Details could not be determined.
Stack length is even The receiver replied with a message whose stack contains an even number of arguments. This message is only displayed if the command line option -C was used.

In addition to diagnostic messages beginning with Error or Attention, Cxsendmsg also outputs other information about work steps and received data. The detail of these outputs can change from revision to revision. These messages are considered diagnostic messages and are accordingly written to the standard error output.
If you receive error messages that are notprecededby &lmt;>, you may be using an older version of Cxsendmsg.

Scalability and resilience

By exploiting the naming hierarchy, it is very easy to scale an application and make it fault tolerant:

Several ClassiX servers can be started, all logging in under the same project (in this case, no SetName should be called, as the names must be unique). cxsendmsg is then calledwith "-o -r *" (or completely without -r) and chooses a server at random. From this server the corresponding method SendMsg_CORBA or AcceptMsg_CORBA is called. If an error occurs (e.g. timeout or network termination), it is checked whether the message has been processed (a flag in the exception). If not, the corresponding entry is removed from the name service and a new attempt is started with another server.

To ensure that there are always enough ClassiX servers for a project, the CORBA controller (the program cxcctrl.exe) can be used.

The presence of a correspondingly large number of ClassiX-

See also

Notes on the installation of the Corba NamingService
The Corba interface of ClassiX®.