2 USER's GUIDE

2.1 OVERVIEW

Figure 2.1: The Protocol Converter (PCO).

PCO is a generic communication interface that enables CCS Message System processes to communicate with non CCS processes. In this release only one external process is supported, namely On-Line MIDAS. However, it is designed so it is possible to extend it later on to support communication with other types of external clients.

PCO is executed as an independent task that should run continuously during the normal operation of the VLT SW. It makes an asynchronous wait for messages from all its external connections. When a message is received through one of the communication channels, it is parsed by PCO to determine where to redirect it. PCO tries to open connections to external processes as messages for these are received.

PCO is not intended for exchange of large amounts of data, but is merely a gateway to exchange smaller messages. It is however possible to transfer larger amounts of data with PCO, but the risk is that PCO will be occupied sending messages, which will block the handling of other commands.

PCO does not have to run in the same environment as the source process. In principle it would be possible to have only one PCO in the whole VLT SW system, but to avoid overloading the PCO, it might be desirable to have one PCO running in each environment. PCO does not consume any considerable CPU time when it is waiting for messages.

2.2 PROTOCOL FOR FORWARDING EXTERNAL MESSAGES

The protocol for forwarding messages is shown in figure 2.2. The protocol shown is applied when messages are sent to external processes.

Figure 2.1: Protocol for the communication with PCO.

The Source Process sends off the message containing the information to be forwarded. PCO receives the message, and analyses it. It checks if the specified destination can be reached. If this condition is met, PCO sends the message to the Destination Process which must be ready to receive. The destination might send back one or more replies, or the acknowledge is returned directly from the subroutine used to deliver the message. PCO sends back an immediate reply (within few seconds) to acknowledge whether the message was delivered successfully or not. One or more additional replies might follow. The last reply is signalled by the "lastReply" flag of the CCS Message. PCO can forward Event Messages to external processes. In this case no replies are sent off.

If PCO receives a message it cannot deliver, e.g. a reply from a destination to a source process, this reply is simply discarded.

2.3 FORWARDING OF EVENT MESSAGES TO EXTERNAL PROCESSES

PCO can handle forwarding of event messages sent from the DB Event Manager. For enabling this, it is necessary to send a command to PCO that makes it attach itself on a specific attribute, on behalf of an external process. The command for doing this is ATTACH. When an event is triggered by a change of the attribute, the Event Manager sends an Event Message to PCO. PCO converts the message to a format required for the external process, and forwards this message. It is possible to make the Event Manager send a special text along with the event message.

PCO can detach itself on behalf of an external process if this should no-longer be notified about the event; this is done with the command DETACH.

Forwarding of events will be used e.g. to notify external processes about the availability of new image data.

2.4 ERROR HANDLING

PCO in general, only logs errors that concerns its own/private operations. I.e., if a message is received from a source to a destination process, and PCO cannot open a socket connection to this destination, PCO does not log any error, but sends back an error reply to the source. It is subsequently up to the source process to actually log the error. In other cases, like if PCO fails allocating memory, it logs the error by itself.

2.5 PCO COMMANDS

Messages to PCO are ASCII formatted data; concrete examples of messages are given later in the chapter. PCO recognizes the following commands (only if the buffer of the reply message contains data, this data is described, otherwise the buffer will be empty) :

PING	This command makes PCO send back one reply. It is used to check if PCO is running, and capable of handling messages. Processes that want to use PCO should make this test before starting to use PCO; a convenience subroutine is provided to ease this (pcoPing()). The message buffer does not contain any data.
FORWMSG	Indicates for the PCO that this is a message to forward to a destination process. PCO unpacks the message buffer and forwards only the part containing the actual message for the destination. PCO returns immediately with one reply indicating whether the message was forwarded successfully or not, and indicating if more replies will follow this. It might be that the destination process needs some time to process the message, in which case the additional reply(ies) may come with some delay. The format of the message is as follows: -protocol <protocol> -procID <process ID> -hostName <host name> \ -message <message> For now, the <protocol> can only be "MIDAS". Later on when Archive is introduced, the identifier will be "ARCHIVE" for this destination. The <process ID> for MIDAS is the Unit ID, which is an integer number in the interval from 0 to 99. Is TBD for Archive. The <host name> is the name of the host where the process is running. The <message> is the actual message to forward to the destination. In case of MIDAS this must be the MIDAS command to execute like "load/image <filename>".
READKEY	Indicates for the PCO that it should read a key from an external process and send back the value(s). PCO returns immediately (within seconds) with one or more replies, if not something went wrong. The handling of the retrieval of MIDAS key values can be done easily using the function pcoReadMidasKey() that takes care of all the packing and unpacking of messages, and returns the value(s) in the correct format to the source application. The format of the message is as follows: -protocol <protocol> -procID <process ID> -hostName <host name> \ -keyName <key name> -keyType <key type> -elSize <element size> \ -firstEl <first element> -noOfEls <number of elements> The first two keys are the same as described above. The <key name>, is the name of the key to read, the <key type> can be either "INTEGER", "REAL", "DOUBLE", or "STRING". The <element size> defines the size in bytes of the individual element to read. This need only to be specified when reading a string variable (i.e. it is the length of the strings). For the numerical types this should just be 0. The <first element> field defines the first element to read if the MIDAS key is an array. In case the key is a scalar, this must be 1. The <number of elements> defines the number of elements to read from the MIDAS key if this is an array. If the key is a scalar, this should just be 1. If PCO succeed in reading the key, it will send back a message with the following format: <elements read>,<element 1>,<element 2>,...,<element n> If all the elements did not fit into one CCS Message additional replies will follow; these will have the format: <element m>,<element o>,...<element <elements read>>
WRITKEY	Indicates for the PCO that a key should be written for an external process. PCO will return immediately with one reply stating if the operation was successful. A convenience function is provided by the PCO module to ease this operation for the source process (pcoWriteMidasKey()). The format of the message is as follows: -protocol <protocol> -procID <process ID> -hostName <host name> \ -keyName <key name> -keyType <key type>, -elSize <element size> -firstEl <first element> \ -noOfEls <number of elements> \ -els <element 1> <element 2> ... <element n> Field 1 to 8 are used to specify the features for the key, and the destination process, and are the same as for the READKEY command. The fields <element x> are the elements to be written into the MIDAS key; note that the individual elements must be separated by blanks. With the present design of the CCS Message System it is only possible to send approximately 8 kB of data in a single CCS Message. This is thus the maximum limit for the amount of data that can be sent. In any case, it will probably not be necessary to send amounts of data larger than 8 kB in this way to MIDAS. If this is needed, it is neessary to send several WRITKEY commands, and then specify the <first element> to write the key appropriately.
ATTACH	Makes PCO attach itself on behalf of an external process. The format of the message is: -protocol <protocol> -procID <process ID> \ -hostName <host name> -attribName <attribute name> [-message <message>] The <attribute name> specifies which attribute should trigger the event. It must be the complete path of the attribute. It is possible to specify a message that should be sent along with the contents of the attribute to the external process. This message is optional. The attribute must be a scalar. When PCO receives the Event Message it will forward a message to the specified destination process of the following format: [<message> ]<new attribute value>
DETACH	Makes PCO detach itself on behalf of an external process. The format of the message is: -protocol <protocol> -procID <process ID> \ -hostName <host name> -attribName <attribute name> See description of ATTACH command
EXIT	Indicates for the PCO that it should stop the execution. PCO enters an `Exit Mode', and does not terminate unless all expected replies have been received. When PCO is in Exit Mode, it does not accept further commands, i.e. error replies will be sent back, stating that the command cannot be handled. The message does not contain any data.
DISCON	Makes PCO close a connection which is currently open to an external process. The format of the message is: -protocol <protocol> -procID <process ID> -hostName <host name>

2.6 EXAMPLES

2.6.1 Issuing MIDAS Commands

A MIDAS command can be executed in the following way:

1. Start up PCO (if not already done):

$ pco [-v] &

2. Start up a MIDAS session¹:

$ inmidas <unit ID> -p

A <unit ID> not already used must be chosen, e.g. "11".

3. Set MIDAS in background mode:

Midas 001> set/back socket,remote

MIDAS now enters background mode, and it is no longer possible to enter commands from the shell to this MIDAS unit (by issuing the MIDAS command "clear/back" via the PCO, it is possible to make MIDAS go back to `shell mode').

4. Issue commands with msgSend:

$ msgSend wte13 pco FORWMSG "MIDAS,11,te13,create/display"

- if the Unit ID was "11" the RTAP Environment for PCO "wte13" and the hostname where the MIDAS session is executed "te13". A new display should now pop up. Try possibly to type the following (requires the availability of BDF images (available in ~pco/test, sombrero.bdf)):

$ msgSend wte13 pco FORWMSG \

"MIDAS,11,te13,load/image <path>/<name>.bdf"

- the image should now be displayed. To delete the display:

$ msgSend wte13 pco FORWMSG "MIDAS,11,te13,del/display"

5. Terminate the MIDAS session (if desirable):

$ msgSend wte13 pco FORWMSG "MIDAS,11,te13,clear/back;exit"

6. Make PCO exit (if desirable):

$ msgSend wte13 pco EXIT ""

The applications that communicates with PCO must use the commands a specified previously, and pack ASCII formatted messages like the ones shown in this example.

2.6.2 Writing a MIDAS Key

For writing a MIDAS the message must be WRITKEY. An example of a message is as follows:

MIDAS,11,te13,intkey,INTEGER,0,1,5,10 20 30 40 50

This message will make PCO forward a message to MIDAS with the Unit ID "11" on the host "te13". The name of the key to write in (or to create if not existing) is "intkey", which is of the type INTEGER. The element size need only to be specified writing strings. The first element to write is number 1, and a total of 5 elements are written.

It is recommended to use the convenience function pcoWriteMidasKey() to do this operation.

2.6.3 Reading a MIDAS Key

The command must be READKEY. An example of a message is as follows:

MIDAS,11,te13,intkey,INTEGER,0,1,5

- which will read the contents of the key written in the previous example. If PCO succeed to read the key, it will send back a message with the following contents:

5,10,20,30,40,50

It is recommended to use the convenience function pcoReadMidasKey() to do this operation.

2.6.4 Attaching an External Process on an Event

The command is ATTACH and the message must have the following format:

MIDAS,11,te13,@wte13:PARAMS:SCALARS.scalar_string64,load/image

Each time the value of the attribute "@wte13:PARAMS:SCALARS.scalar_string64" changes, the following message is sent to the MIDAS session with the Unit ID 11:

load/image <value of attribute>

The <value of attribute> could thus be the name of an image file.

2.6.5 Detaching an External Process

The command is DETACH and the message must have a format as e.g.:

MIDAS,11,te13,@wte13:PARAMS:SCALARS.scalar_string64

To make PCO detach itself on behalf of the MIDAS session with Unit ID "11". The external process will not receive further Event Messages.

2.6.6 Application Programming with PCO

PCO will normally be used by applications to access various services of external processes, like e.g. MIDAS services. In the following a simple application is shown that receives a message about the availability of new image data, and subsequently sends off a command to MIDAS to display this image. Note that the example is simplified in several ways, e.g. when it comes to handling of CCS replies (should check for error replies etc.). These details are left out to keep the size of the program small.

/************************************************************************

* NAME

* pcoExample - example program for the Protocol Converter - PCO

*

* SYNOPSIS

* pcoExample

*

* DESCRIPTION

* Example program for the PCO module. Creates a MIDAS display and display

* images.

*

* CAUTIONS

* The Protocol Converter (PCO) must be running. Furthermore a background

* MIDAS session with Unit ID 33 must be running.

*

*------------------------------------------------------------------------

*/

#define _POSIX_SOURCE 1

#include "vltPort.h"

/*

* System Headers

*/

#include <stdio.h>

#include <string.h>

/*

* Local Headers

*/

#include "pco.h"

#include "pcoErrors.h"

/*

* Main

*/

int main (int argc, char *argv[])

{

ccsERROR error;

ccsERROR errorMsg;

ccsENVNAME pcoEnvName;

char sendMsg[1024];

char midasCommand[512];

char *buffer;

char imageFile[256];

msgCMD commandSend;

msgCMD *command;

msgCMDID commandID;

msgHEADER *msgRecv;

msgLENGTH msgLen;

msgLENGTH bufLen;

msgPROCESSID *orgID;

msgRECEIVEFILTER msgFilter;

msgTIMEOUT timeOut;

vltLOGICAL lastReply;

vltUINT8 msgType;

if (ccsInit("xxxDisplayImage", 0, NULL, NULL, &error) == FAILURE)

{

printf("\nxxxDisplayImage: Error in call to ccsInit()!!\n\n");

exit(1);

}

strcpy((char *)pcoEnvName, "wte13");

/*

* Make a call to "pcoPing()" to see if PCO is alive and kicking.

*/

if (pcoPing(pcoEnvName, msgNO_TIMEOUT, &error) == FAILURE)

{

printf("\n\nError: PCO Could not be reached!\n\n");

ccsExit(&error);

exit(1);

}

printf("\nPCO is alive and kicking!!!\n\n");

/*

* Create a MIDAS display (assuming that a background MIDAS session with

* Unit ID 33 is running); pack a "FORWMSG" and send it to MIDAS

* via the PCO.

*/

timeOut = msgNO_TIMEOUT;

strcpy((char *)commandSend, pcoFORWARD_COM_STR);

if (pcoPackMsg(pcoMIDAS, "33", "te13",

sendMsg, &msgLen, "create/display", NULL) == FAILURE)

{

printf("\nError in packing message!\n\n");

ccsExit(&error);

exit(1);

}

msgFilter.accept = msgANY_MESSAGE;

if (msgSendCommand(commandSend, 0, pcoEnvName, pcoPCO_PROC_NAME,

sendMsg, msgLen, 0, &error) == FAILURE)

{

printf("\nError sending message to PCO!!\n\n");

ccsExit(&error);

exit(1);

}

do

{

if (msgRecvMsg(&msgFilter, timeOut, &msgRecv, &error) == FAILURE)

{

printf("\nError receiving message from PCO!!\n\n");

ccsExit(&error);

exit(1);

}

if (msgRecv != (msgHEADER *)NULL)

{

if (msgParseMsg(msgRecv, &msgType, &command, &commandID,

&orgID, &lastReply, &buffer, &bufLen,

&errorMsg, &error) == FAILURE)

{

printf("\nError parsing message from PCO!!\n\n");

ccsExit(&error);

exit(1);

}

} /* end-if (message != (msgHEADER *)NULL) */

}

while (lastReply == ccsFALSE);

/*

* Main loop: receive message about availability of new image data and

* issue a MIDAS command to display the image.

*/

while (1)

{

/*

* Receive info about new image - get the filename (imageFile)

*/

/* <receive message, process it ...> */

/*

* Display image; pack a "FORWMSG" and send it to MIDAS

* via the PCO.

*/

strcpy((char *)midasCommand, "load/image ");

strcat((char *)midasCommand, imageFile);

if (pcoPackMsg(pcoMIDAS, "33", "te13", sendMsg, &msgLen,

midasCommand, NULL) == FAILURE)

{

printf("\nError in packing message!\n\n");

ccsExit(&error);

exit(1);

}

if (msgSendCommand(commandSend, 0, pcoEnvName, pcoPCO_PROC_NAME,

sendMsg, msgLen, 0, &error) == FAILURE)

{

printf("\nError sending message to PCO!!\n\n");

ccsExit(&error);

exit(1);

}

do

{

if (msgRecvMsg(&msgFilter, timeOut, &msgRecv, &error) == FAILURE)

{

printf("\nError receiving message from PCO!!\n\n");

ccsExit(&error);

exit(1);

}

if (msgRecv != (msgHEADER *)NULL)

{

if (msgParseMsg(msgRecv, &msgType, &command, &commandID,

&orgID, &lastReply, &buffer, &bufLen,

&errorMsg, &error) == FAILURE)

{

printf("\nError parsing message from PCO!!\n\n");

ccsExit(&error);

exit(1);

}

} /* end-if (message != (msgHEADER *)NULL) */

}

while (lastReply == ccsFALSE);

} /* end-while (1) */

}

/* ------ o0o ------- */

2.7 PCO FEATURES

2.7.1 PCO Applications

The following applications are provided by the PCO module:

pco

The actual Protocol Converter program to be executed as a background process during the operation of the VLT SW. At start-up it initializes itself on the CCS Message System. When messages for external processes are received, PCO tries to open socket connections to these.

PCO complies with the standards prescribed by the CCS Message System for exchange of messages.

pcoExit

Program used to make the PCO in a certain environment quit.

2.7.2 PCO Functions

The following convenience functions are provided by the PCO module:

pcoPing

Used to make PCO send back an Acknowledgment Message, stating whether it is operating properly or not.

pcoPackMsg

Function to generate a PCO Message. The various fields of the PCO Message are given in as independent input parameters.

pcoReadMidasKey

The function is used to read a MIDAS key. The name of the key and its features must be given as input parameters. The function returns immediately (within a few seconds) with the key value(s) as requested, or it returns with an error if the operation failed. In case of success, it takes care of filling out the variable or the array in which the data should be stored so the calling application does not have to be concerned with this. It may be that data comes in several packages, but this is handled internally by the function and is thus transparent for the calling application.

pcoWriteMidasKey

The function is used to write a MIDAS key. This can be either a scalar or a vector. The function returns immediately (within few seconds) with a status stating if the operation was successful. The calling application has to provide various information about the key to write, such as the data type, the name of the key and more. In the present implementation, it is only possible to send 8 kB of data with each call of this function.

¹

Note, that this manual is not intended as an introduction to MIDAS. Please consult the proper MIDAS documentation for specific information about MIDAS.

Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com