| |
|
|
|
3 REFERENCE
3.1 PCO APPLICATIONS
The purpose of the Protocol Converter (PCO) is to interface CCS Message
System Applications with external clients like On-Line MIDAS, to enable
exchange of messages.
The program should be executed at start-up of the VLT SW system, and
should then run as a background process as long as the VLT SW is running.
PCO tries to establish connection to external processes as the messages
for these come in. The PCO always sends a reply within few seconds
(positive or negative). More replies may follow after this, indicated by
the "lastReply" flag of the msgRecvMsg() call.
PCO also handles forwarding of event messages for external processes.
PCO complies with the standards for communication for CCS applications.
I.e. it must always receive a command, to which one or more replies are
send back. The last reply is indicated with the "lastReply" flag.
The first(/last!) reply is always send within few seconds.
-v Will start the PCO up in verbose mode
PING Used to make the PCO generate a reply indicating if it is
running properly.
FORWMSG Used to make PCO forward a message to an external process.
READKEY Makes PCO read a key from an external process. Now only
supported for MIDAS.
WRITKEY Makes PCO write/create a key for an external process. Now
only supported for MIDAS.
ATTACH Makes PCO attach an external process for event notification.
The event is send out by the DB Event Manager, and converted
by PCO. It is possible to specify a special message that should
be forwarded to the external process.
DETACH Detaches an external process from the event notification.
DISCON Make the PCO close a connection to an external process. The
connection will be reopened if a command is forwarded to this
process at a later stage.
EXIT Makes the PCO terminate execution in a clean way. I.e. it waits
till all replies from external processes have been received
before terminating. The command triggers one immediate reply.
When the PCO is in the Exit Mode it will reject further
commands coming in.
This application can only be executed with the RTAP Q-Server. I.e., it is
not possible to execute on an LCU, nor to execute with the Q-Server
Emulator.
If an EXIT command is issued, PCO will not terminate until all external
replies are received. It might be that an external reply failing to
come in, causes PCO to wait forever. In this case the standard CCS KILL
command can be used to force PCO to terminate.
For the time being there is no clean way to terminate a MIDAS session from
PCO, nor to close a connection (but leave MIDAS running, waiting on the
the socket). The only way is to issue a FORWMSG command with the MIDAS
command "clear/back;exit". This will make MIDAS go back to interactive
mode, and terminate it. PCO will generate an error after this, but
continues working without problems. If MIDAS cannot start up with the
same unit ID it may help to delete the files in the $HOME/midwork
directory for that MIDAS session. However, it may be that the unit ID for
a MIDAS session terminated in this way, remains blocked for a while
(operating system management).
The program makes the Protocol Converter - PCO - terminate in a clean
way, i.e. it free's memory occupied, and it exits on the Q-Server.
Before closing down PCO will wait for messages possibly expected from
external processes before actually closing down.
The RTAP Environment where PCO is running should be specified. If the
environment is not specified the program tries with the default
environment (indicated by the "RTAPENV" environment variable).
<environment name> The RTAP Environment where PCO is running.
Optional, otherwise the program will try to use
the default (local) RTAP Environment.
-v Runs the program in verbose mode.
RTAPENV The name of the RTAP Environment for this session. Will be
used if the PCO RTAP Environment is not specified.
Since PCO will wait for missing external replies to come in when an EXIT
command has been issued, it might be that an external reply failing to come
in causes PCO to wait forever. The standard CCS command, KILL, can thus be
used to force PCO to terminate immediately.
3.2 PCO FUNCTIONS
#include "pco.h"
ccsCOMPL_STAT pcoPackMsg(pcoPROTOCOL protocol,
char *processID,
char *hostName,
char *sendBuf,
msgLENGTH *sendBufLen,
..., NULL)
Creates a PCO Message to be sent to the PCO. It is the reponsability of
of the calling application to afterwards send off the message with the
correct CCS call, and afterwards receive the incoming replies.
protocol IN The protocol for the entity to send to. The constants
available for handling this parameter are:
pcoMIDAS To send to a MIDAS destination.
processID IN For a MIDAS Process this is the Unit ID.
hostName IN The name of the host where the destination process is
running.
sendBuf OUT Pointer to buffer in which the generated PCO Message can
be found. The buffer must be provided by the calling
application.
sendBufLen OUT Length of the PCO "FORWMSG" Message generated.
... IN Variable list of _strings_ that will be packed together
to form the message to send to the destination. The
strings will be separated by one comma each. The list
should be terminated with a "NULL".
It the responsability of the calling application to allocate memory for
the buffer to contain the generated CCS Message.
The function sends a PCO Test Message to PCO which will respond if it is
running properly in the specified RTAP Environment.
If the PCO test was successfull "SUCCESS" is returned, otherwise "FAILURE".
pcoEnvName IN Name of the RTAP Environment where the PCO to be used for
distributing messages is running.
timeOut IN Timeout to wait for reply. Can be either msgNO_TIMEOUT,
msgNO_WAIT, or the timeout specified in milliseconds.
error OUT CCS error structure. Indicates the type of error that
possibly occurred.
SUCCESS If PCO received the PCO Test Message, and sent back the correct
reply.
FAILURE If no reply was received from the (possible) PCO in the specified
environment.
#include "pco.h"
ccsCOMPL_STAT pcoReadMidasKey(msgTIMEOUT timeOut,
ccsENVNAME pcoEnvName,
vltUINT8 midasUnitID,
char *hostName,
char *keyName,
pcoMIDAS_KEY_TYPE keyType,
vltUINT16 elSize,
vltUINT16 firstEl,
vltUINT16 numberOfEls,
void *keyArray,
vltUINT16 *elsRead,
ccsERROR *error)
The function sends off a "READKEY" command to MIDAS via the PCO. It packs
the buffer of the message according to the specified format for this
message, and receives the data from PCO (MIDAS) as they come in. It
unpacks the messages and converts and copies the data into the array
pointed to by "keyArray". This array must be provided by the calling
application.
The function should normally return immediately, but it is possible to
specify a timeout in case something went wrong.
timeOut IN The timeout to wait for the replies from PCO (MIDAS).
Can be either msgNO_TIMEOUT, msgNO_WAIT or the timeout
time specified in milliseconds.
pcoEnvName IN Name of the RTAP Environment where the PCO to be used
is executed.
midasUnitID IN The MIDAS Unit ID. This is an integer number
in the interval [0; 99].
hostName IN The name of the host where the MIDAS session is
running.
keyName IN The name of the MIDAS key to read.
keyType IN The type of the MIDAS key. Can be one of the
following:
pcoMIDAS_INTEGER, pcoMIDAS_REAL, pcoMIDAS_DOUBLE,
pcoMIDAS_STRING.
elSize IN The size (in bytes) of the element. Only used when
reading string keys, is otherwise ignored.
firstEl IN The first element to read in case the key is an
array. If the key is scalar (or only the first
element is requested) it must be 1.
numberOfEls IN The number of elements to read. In case the key is
a scalar or only one element is needed it must be 1.
keyArray OUT Array allocated by the calling application in which
the value(s) received will be copied. Must be of the
same type as the key. For integers, reals (floats),
and doubles this is straightforward, for strings an
array must be allocated big enough to store all the
values, i.e. of size (elSize * numberOfEls +
numberOfEls). The strings will be organized in the
following way by the function:
<value 1>,<value 2>, ...,<value <elsRead>>
elsRead OUT The number of elements actually read from MIDAS.
error OUT Indicates the type of an error possibly occurring.
SUCCESS In case the operation was successful.
FAILURE In case the operation failed. The follwing error codes can be
generated by the function:
pcoERR_INPUT_PARS There is something wrong with one of the
input parameters to the function.
pcoERR_SND_TO_PCO The function couldn't send the command to
PCO. Check that environment is correct.
pcoERR_ALLOC_MEM The function couldn't allocate memory for
receiving the data.
pcoERR_RCV_MSG There were problems receiving a message from
the PCO.
pcoERR_PARSE_MSG The message couldn't be parsed.
pcoERR_FORMAT_MSG The format of the message received is wrong.
Furthermore error messages sent from the PCO can be returned.
It would however be too comprehensive to mention all these
errors here. Please refere to the list of errors in the "PCO
User Manual".
#include "pco.h"
ccsCOMPL_STAT pcoWriteMidasKey(msgTIMEOUT timeOut,
ccsENVNAME pcoEnvName,
vltUINT8 midasUnitID,
char *hostName,
char *keyName,
pcoMIDAS_KEY_TYPE keyType,
vltUINT16 elSize,
vltUINT16 firstEl,
vltUINT16 numberOfEls,
void *elArray,
ccsERROR *error)
The function is used to write a MIDAS key. This can either be an integer,
a real, a double or a string. Furthermore it can be either a scalar or
a vector.
The function should return immediately (within seconds) with the status
stating whether the write operation was successful or not. However in
case something went wrong, it is possible to specify a timeout to wait
for the reply.
The messages are sent to MIDAS via the PCO, which consequently must be
running.
timeOut IN Specifies the timeout to wait for a reply from PCO.
pcoEnvName IN The RTAP Environment where the PCO is running.
midasUnitID IN The Unit ID of the MIDAS session to communicate with.
The Unit ID is an integer number in the interval
[0; 99].
hostName IN The name of the host where the MIDAS session is
running.
keyName IN Name of the MIDAS key to write data into.
keyType IN Type of the MIDAS key. The following constants are
defined to handle this parameter:
pcoMIDAS_INTEGER, pcoMIDAS_REAL, pcoMIDAS_DOUBLE and
pcoMIDAS_STRING.
elSize IN Size in bytes of each element to read. Does only need
to be specified when characters/strings are read. Is
otherwise ignored.
firstEl IN Defines the first element to write if the key is a
vector. In case of a scalar it is 1.
numberOfEls IN The number of elements to write.
elArray IN Void pointer to array containing the value(s) to
write. In case of a string this must be a list of
comma separated strings:
"string 1","string 2",...,"string n"
error OUT Indicates the type of error that possibly occurred.
SUCCESS In case the operation was successfull.
FAILURE In case something went wrong. The following error codes can
be returned:
pcoERR_INPUT_PARS There is something wrong with one of the
input parameters to the function.
pcoERR_SND_TO_PCO The function couldn't send the command to
PCO. Check that environment is correct.
pcoERR_RCV_MSG There were problems receiving a message from
the PCO.
pcoERR_PARSE_MSG The message couldn't be parsed.
Furthermore error messages sent from the PCO can be returned.
It would however be too comprehensive to mention all these
errors here. Please refere to the list of errors in the "PCO
User Manual".
 Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |
| |
|
|
|