| |
|
|
|
2 USER'S GUIDE
This chapter provides a functional description of the module: how to use it and what to use it for.
2.1 Overview
The lqs implements the functionalities of the RTAP Q Server [3]. It provides a mechanism to transport data between applications on different hosts:
Assuming application X on host A wants to send a message to application Y on host B, the following transactions take place:
1. Application X asks the message system to deliver the message to application Y. The message system discovers that destination is on a different host and therefore routes the message to the Q-Server.
3. The Q Server on host B routes the message to application Y using the local message system on that host.
4. The Q Server on host B sends back an acknowledgement, which indicates that the message was successfully delivered to application Y.
5. The Q server on host A forwards the acknowledgement to the originator (application X), which was waiting to see whether the message got through.
If case application Y needs to return information it sends response messages in a similar way. Note, however, that there is no acknowledgements for response messages.
1. Application Y asks the message system to deliver the response message to application X. The message system discovers that destination is on a different host and therefore routes the message to the Q-Server.
2. The Q-Server on host B forwards the response message to the Q-Server on host A via the socket connection.
3. The Q-Server on host A routes the response message to application X using the local message system on that host.
Note that socket connections between Q-Servers are kept opened. It means that connection establishment only is required for the first message between two hosts.
2.2 Process Identification
A process is identified by its environment name and its process number in that environment. This information is always used to identify the originator and the destination of a message.
The LCU Q-Server maintains two global tables; the environment table and the local process table.
The environment table is used to define all environments (hosts) in the system which are allowed to communicate with the local host and the status of the tcp socket connections to these environments. An environment normally corresponds to one host, but there could also be more than one environment on one host. The environment table is defined in the boot script and new environments shall only be added after a boot. The environment table contains the following entries ("lqsEnvTbl.h"): 1
The first three items are defined in the boot script, while the last item is dynamically updated when the LCU Q-Server succeed in establishing a tcp connection. In addition the LCU Q-Server updates the VxWorks host table (mapping of host name to IP address), when the environment table is established.
The local process table is dynamically maintained by the LCU Q-Server. Because this table is shared between the LCU Q-Server and applications it is protected by a semaphore. It provides a mapping between local process names and numbers and also contain the file descriptors for local communication. When an application starts it announces its presence to the LCU Q-Server by making an entry in the table. The index in the table is the allocated process number for that application. The application also maintains the entries for file descriptors and obituary behaviour. Note that message queues are used to pass data from the LCU Q-Server to application, and a pipe is used to pass messages from the application to the LCU Q-Server. The local process table contains the following entries ("lqsLocalTbl.h"):
The local process table can also be used by the local message system for local communication.
2.3 Message Format
The format of messages is defined in the include file "rtap.h" and "lqsMain.h". A message contains of a standard header, a message type dependent header and a message body. There are some predefined message types:
The CCS message system also defines other message types.
2.4 Obituaries
An obituary is a special message which contains a notification that a process or environment has terminated. When the LCU Q-Server receives an obituary message it broadcasts it to all local processes, which wants to receive obituary messages, and to all remote environments, which have an open socket connection. An application process may decide it wants or wants not to receive obituary messages. An application process may also decide it wants or wants not to generate obituary messages on termination. This behaviour is specified in the obituary flag in the local process table. The granularity of obituary behaviour may be extended in future releases.
3 REFERENCE
3.1 Introduction
This chapter provides a detailed description of the lqs module interface, namely procedures and include files.
The procedures are described in UNIX man-page format, which are listed on the following pages and are ordered in a functional way:
3.2 lqs Functions
Below is an index of procedures organized in alphabetical order:
The following functions are also available, although they should be private to lqs. Some of them are explicitly used by LCC:
#include "lqs.h"
STATUS lqsInit(int ackTimeout, const char *userName)
void lqs(int lqsProcNum)
void lqsVersion(void)
int lqsCheckDead(void)
The LCU Q-Server 'lqs' performs process communication based on the
same protocol as used by the RTAP database-system of Hewlett-Packard.
lqsInit - Setup the data for the Q-Server Task.
The parameter 'ackTimeout' defines the timeout in seconds
for ping-responses and the behaviour of the Q-Server:
ackTimeout = 0: no timeout, no Ping request generation.
ackTimeout > 0: with timeout and Ping request generation.
The parameter 'userName' defines the value to be used in the
corresponding field in messages. This is important in
connection with RTAP-environments. If the value is NULL
(or if omitted from the shell input), the default is taken,
which is "rtap".
The functions returns either OK or the executing task is
suspended in case of an error.
lqs - The LCU Q-Server Task.
This function must be spawned as a task under VxWorks.
It performs the basic actions for the process communication
between environments on different hosts in a network.
It routes the messages based on the contents of its tables
(Environment-Table and Local-Process-Table) from a source-
process to a destination-process using message-queues and
pipes.
One argument must be passed to the task, which becomes the
process-number of lqs in the Local-Process-Table. The number
must be in the valid range of the table. A value of zero
(or if omitted from the shell input) selects the default,
which is 3 (before v2.3 is was 1). Number 3 was chosen to
match the number of the Q-Server in an RTAP-environment.
lqs must be spawned before any other process is registered
in the Local-Process-Table.
lqsVersion - Prints the installed version of lqs and its behaviour.
lqsCheckDead - Returns FALSE if lqs is present, TRUE if not.
'lqsInit' must be called and the environment table should be set up
with 'lqsAddEnvTbl' before invoking 'lqs'.
The Q-Server task must have the name "tLqs" and cannot be spawned more
than once.
Usually the lqs initialization is done in a VxWorks boot script.
Here lqs is initialized with timeout 10 sec and username "xyz",
and started with the process-number 5.
lqsInit 10,"xyz"
lqsAddEnvTable("wte16","te16","134.171.12.225",2167)
...
prio = 90
options = ...
taskSpawn("tLqs", prio, options, 20000, lqs, 5)
lqsInit, lqsAddEnvTbl, lqsAddLocalTbl, taskSpawn,
LCU Q-Server User Manual (VLT-MAN-ESO-17210-0373),
RTAP documentation
#include "lqs.h"
int lqsAddEnvTbl(char * env,
char * hostName,
char * hostIpAddr,
int tcpPort,
char * netSuffix)
void lqsPrintEnvTbl(void)
The LCU Q-Server Environment-Table contains all environments
to which the Q-Server can connect, i.e. the environment-names and the
corresponding hosts (host-names, IP-addresses, TCP-port-numbers).
'lqsAddEnvTbl' is used to establish the environment table at system
start-up. It adds an entry in the environment-table, consisting of
the environment-name, the host-name, and the TCP-port-number.
It also updates the VxWorks host-table with host-name to IP-address
mapping automatically.
env - the environment name (max. 7 characters)
hostName - the host name where the env. exists (max. 20 chars)
hostIpAddr - the IP address of the host in "dot format"
tcpPort - the allocated TCP port number for this environment
netSuffix - if communication over multiple nets is possible:
this suffix is appended to the local env-name when
communication with host `env'.
NULL means default, no suffix.
'lqsPrintEnvTbl' is used to print the contents of the environment-table
Usually the lqs initialization is done in a VxWorks boot script:
lqsInit(10)
lqsAddEnvTbl "lte21", "te21", "134.171.12.232", 2165
lqsAddEnvTbl "lted", "ted", "134.171.12.214", 2164
lqsAddEnvTbl "wte16", "te16", "134.171.12.225", 2167
lqsPrintEnvTbl
...
lqsAddLocalTbl, lqsDeleteLocalTbl,
lqsGetLocalTblPtr,
lqsGetLocalProcessNames, lqsPrintLocalProcessNames,
lqsPrintLocalTbl -
Add/Delete/Query/Print entries of the LCU Q-Server Local Process Table
#include "lqs.h"
int lqsAddLocalTbl(char *procName,
int readCommId,
int writeCommId,
unsigned int obiFlag)
int lqsDeleteLocalTbl(int procNum)
const lqsPROC * lqsGetLocalTblPtr(int procNum)
int lqsGetLocalProcessNames(
const char (**procNameTbl)[lqsPROC_NAME_LEN], int *nEntries)
int lqsPrintLocalProcessNames(void)
void lqsPrintLocalTbl(void)
The LCU Q-Server Local Process Table contains all local processes
to which the Q-Server can connect, i.e. the process-names and the
corresponding communication IDs for read/write.
It returns the assigned index into the table, which corresponds
to the process-number.
Index 0 is used for obituaries, index 1 is used for lqs itself.
All further processes are assigned to index 2 and so on.
`lqsAddLocalTbl' is called by a local process when it starts up.
It adds an entry in the Local Process Table, consisting of
the process-name, local communication IDs, and an obituary-flag.
The index of the table-entry is used as the process-number.
The table is protected by a semaphore.
procName - the process name to be used in messages (max. 19 chars)
readCommId - the ID process-->Qserver, as returned by `lqsOpenLocal'.
writeCommId - the ID Qserver-->process, as returned by `lqsOpenPipe'.
obiFlag - the behaviour of obitauries, as follows:
0: Process send and receives obituaries
lqsDONT_SEND_OBI: Process does NOT send, but receives obituaries
lqsDONT_RCV_OBI: Process does NOT receive, but sends obituaries
lqsDONT_SEND_OBI+lqsDONT_RCV_OBI: NO send/receive of obituaries
`lqsDeleteLocalTbl' is called by a local process when it terminates.
It deletes (frees) its entry in the Local Process Table.
procNum - the process number, as returned by `lqsAddLocalTbl'
`lqsGetLocalTblPtr' is used to obtain a pointer to a specific entry
in the Local Process Table. Zero as parameter yields a pointer to the
base of the table. Note that any access must be READ-ONLY !
`lqsGetLocalProcessNames' is used to obtain a table with all currently
registered process names. The table consists of as much entries as the
Local Process Table contains, each entry is a null-terminated string
with a fixed length of lqsPROC_NAME_LEN, the remainder is zero-padded.
The index of the table corresponds to the process-ID in `lqs'.
Note that an entry can be empty (all zeros), index 0 is always empty.
Note also that the memory must be free'd by the caller after use!
procNameTbl <OUT> - pointer to the base of the allocated table
A free-statement with this pointer must follow.
nEntries <OUT> - number of valid entries in the table
`lqsPrintLocalTbl' is used to print the contents of the Local Table.
`lqsPrintLocalProcessNames' makes use of `lqsGetLocalProcessNames' and
prints only the currently registered process-names.
lqsLocalTblMin - defines the first entry in the local-table that
shall be used. Default and minimal allowed value is 1.
If the default shall be changed, then it must be set before
any access to the lqs is done.
- Process number (>0) - OK
- lqsERR_INV_PAR - one of the parameters is invalid
- lqsERR_NO_ROOM - the Local Process Table is full,
or the requested memory is not available
- lqsERR_INV_SEM - invalid semaphore operation (internal error)
- lqsERR_NO_COMM_ID - the given table-entry is invalid (not used)
The memory allocated by `lqsGetLocalProcessNames' must explicitly
be free'd by the caller after use.
int localProcNum;
int readCommId, writeCommId;
writeCommId = lqsOpenPipe();
readCommId = lqsOpenLocal(...);
localProcNum = lqsAddLocalTbl("myProgName", readCommId, writeCommId,
lqsDONT_SEND_OBI + lqsDONT_RCV_OBI);
if (localProcNum < 0) ...//error
...
if (lqsDeleteLocalTbl(localProcNum) < 0) ...//error
lqsOpenLocal, lqsCloseLocal, lqsReadLocal, lqsWriteLocal
- Local process communication to receive data from the LCU Q-Server
#include "lqs.h"
int lqsOpenLocal(int maxMsg)
int lqsCloseLocal(int readCommId)
int lqsReadLocal(int readCommId, char ** readMsgPtr, int timeout)
int lqsWriteLocal(int writeCommId,char *wrMsgPtr,int size,int timeout)
lqsOpenLocal - Create the message-queue for receiving data from lqs.
Used by a local process on start-up.
Pended messages are queues in FIFO order.
The maximum message-size if defined by 'rtMSGSIZE'.
Memory is allocated to hold maxMsg of the max. size.
Returns the msg-Queue-ID (as int) or error.
lqsCloseLocal - Delete the message-queue for receiving data from lqs.
Used by a local process on termination.
lqsReadLocal - Read incoming data from the Q-Server.
Used by a local process to read messages from other
processes, which can be local or on another host.
Note that memory to hold the message buffer is
allocated dynamically inside the Q-Server. The
application receiving the message has to release
this memory explicitly by a 'free' instruction!
lqsWriteLocal - Write a message to another process's msg-queue.
A buffer is allocated internally, the provided buffer
is no longer used after return.
NOTE: This function should only be used to BYPASS
the lqs and send a message directly to another local
process. Normally it is only used by lqs itself.
maxMsg - maximum number of messages to be queued.
readCommId - message queue ID as returned from 'lqsOpenLocal'.
readMsgPtr - pointer to the message receive-buffer.
This buffer has to be free'd after the receive!
wrMsgPtr - pointer to the message send-buffer.
size - number of bytes to be written.
timeout - maximum number of ticks to wait on send/receive.
NO_WAIT: do not wait at all
WAIT_FOREVER: no timeout
OK - success
lqsERR_NO_MEMORY_MSGQ - not enough memory to create message(-queue)
lqsERR_INV_MSGQ - the given message queue ID is invalid
lqsERR_TIMEOUT - the call has timed out (not for NO_WAIT, WAIT_FOREVER)
lqsERR_LQS_DEAD - the message-queue has been deleted, lqs terminated
lqsERR_INV_MSG_LENGTH - unexpected amount of bytes were read/written
(internal error)
lqsERR_NO_MSG_AVAILABLE - no messages available (only for read-NO_WAIT)
or queue full (only for write-NO_WAIT)
lqsERR_MSGQ - any other message-queue error from VxWorks indicated
The buffer received by 'lqsReadLocal' has to be released EXPLICITLY
by a 'free' instruction when it is no longer used!
int readCommId;
char *readMsgPtr;
readCommId = lqsOpenLocal(5);
if (readCommId < 0) // error
...
while (! EXIT)
{
if (lqsReadLocal(readCommId, &readMsgPtr, 100) != OK) // error
... // Execute the message
free(readMsgPtr);
}
if (lqsCloseLocal(readCommId) != OK) // error
lqsInit, lqsAddEnvTbl, lqsAddLocalTbl,
lqsOpenPipe, lqsClosePipe, lqsWritePipe,
LCU Q-Server User Manual (VLT-MAN-ESO-17210-0373)
lqsOpenPipe, lqsClosePipe, lqsWritePipe
- Local process communication to send data to the LCU Q-Server
#include "lqs.h"
int lqsOpenPipe(void)
int lqsClosePipe(int writeCommId)
int lqsWritePipe(int writeCommId, char *writeMsgPtr, int bytes)
lqsOpenPipe - Open the pipe for sending data to the Q-Server.
Used by a local process on start-up.
This pipe is used by the application to pass messages
to the Q-Server.
Returns the pipe-ID (a file-descriptor) or error.
lqsClosePipe - Close the pipe for sending data to the Q-Server.
Used by a local process on termination.
lqsWritePipe - Send outgoing data to the Q-Server.
Used by a local process to send messages to other
processes, which can be local or on another host.
Note that memory to hold the message buffer is
allocated dynamically inside the Q-Server. The
application sending the message can therefore
alter the buffer immediately upon return.
writeCommId - file-descriptor ID as returned from 'lqsOpenPipe'.
writeMsgPtr - pointer to the message-buffer.
bytes - number of bytes in the message-buffer.
lqsERR_NO_MEMORY_MSGQ - failed to allocate memory to hold the message
lqsERR_PIPE - VxWorks failed to write to the pipe
lqsERR_CLOSE_PIPE - VxWorks failed to close the pipe
int writeCommId;
char writeMsg[100];
writeCommId = lqsOpenPipe();
if (writeCommId < 0) // error
...
while (! EXIT)
{
if (lqsWritePipe(writeCommId, writeMsg, sizeof(writeMsg)) != OK)
// error
}
if (lqsClosePipe(writeCommId) != OK) // error
lqsInit, lqsAddEnvTbl, lqsAddLocalTbl,
lqsOpenLocal, lqsCloseLocal, lqsReadLocal,
LCU Q-Server User Manual (VLT-MAN-ESO-17210-0373)
#include "lqs.h"
int lqsWatch(int refrTick, int nLines)
void lqsWatchEnable(void)
void lqsWatchDisable(void)
The utility 'lqsWatch' displays the current message activity of all
local processes in the system. The display includes:
- The sequence-number of the last received message
- The number of acknowleges and negative acks received
- The number of messages sent/received
- The amount of KBytes sent/received (excluding net-headers)
- The number of messages that are currently in the read-queue,
a '*' can indicate insufficient queue lenghts (full).
- The system throughput in KBytes/sec (current/max/average)
of all sent and received messages (excluding net-headers).
- The size of the largest available free memory-block
(current/max/min) that can still be allocated.
Parameters are optional from the VxWorks shell:
refrTick - Number of ticks for refresh intervals, defaults to 1 sec.
nLines - Number of processes (lines) the display can show.
By default all processes are displayed.
Internal messages like ack/ping-requests are counted in row 1 (lqs).
Note that 'lqsWatch' can only be stopped by deleting the executing
task, or - if started from the shell - by typing Ctrl-C (Cancel).
'lqsWatchEnable' and 'lqsWatchDisable' are used to enable the
sampling of data in the background. For performance reasons this
feature is 'off' by default. 'lqsWatch' automatically enables
the sampling, but does not disable it on termination.
'lqsWatch' requires terminals that understand basic ANSI sequences.
The average throughput value can be wrong when sampling is out-of-date
or when the sampling has been stopped intermediately.
-> lqsWatch
P# ProcessName SeqNum #ack/nack # messages S/R # KBytes S/R queue
--- ----------- ------- --------- --------------- --------------- -----
1 lqs 0 0/0 0/0 0/0 0
2 perfMsgSlave 15212 0/0 7606/7606 5745/631 0
3 msgServer 0 0/0 0/0 0/0 0
6 lccLogger 0 0/0 0/0 0/0 0
7 lccServer 0 0/0 0/0 0/0 0
8 rdbServer 0 0/0 0/0 0/0 0
-> lqsWatchDisable
3.3 Logging
Logging simply prints messages to the VxWorks shell if available. There are different types of messages:
Debug, trace and ping trace can be switched on/off using the toggle functions lqsDebug, lqsTrace, lqsPing and lqsObi. These functions return a 1 when they are switched on and a 0 when they are switched off. These functions should be issued to the VxWorks shell.
All types of logs can be collectively suppressed by setting the variable `lqsLogFlag' to zero (0). Note that the default of this flag is 1 when lqs is compiled with the macro DEBUG, and 0 otherwise. This means that no logging is produced by the optimized version of lqs. However, in any case the flag is set to 1 when one of the above toggle-functions is invoked to turn a log-type explicitly on.
3.4 Include files
Applications using the lqs interface must include the file "lqs.h" in addition to VxWorks include files. The "lqs.h" include file includes everything required to use the procedures described in previous section.
· "lqsLocalTbl.h". Definition of local process table and prototypes of functions to manage the table.
· "rtap.h", "types.h", "procSched.h", "rtapErrno.h", "cmnErrno.h". Definitions required by the RTAP protocol.
· Dummy include-files for `lcudrvTk'. To use lcudrvTk for lqs include the line "DRIVER lqs" in the file lcudrvTk.config and place it e.g. in your current directory. See [6] for details.
3.5 Tools
The lqs module includes a number of tools, which can be used from the VxWorks shell.
· lqsCloseAllSockets - To explicitly close all connected sockets. This is useful only for test and debug purposes.
This is a sample session using some of the lqs tools:
> lqsVersion
LCU Q-Server (lqs) version 2.3 by Spacebel/ESO (Feb 1995).
This version includes the following features:
1. Message sequence number generation, return and check
2. Local NACK message generation if ACK timeout or
3. received ACK message sequence number mismatch
4. Ping request/response with timeout parameter
5. defined by lqsInit in the bootscript file
> lqsPrintEnvTbl
Environment Host-Name TCP-Port Net Socket pingCtr waitResponse
----------- ---------------- -------- --- ------ ------- ------------
wte16qs te16 2223 - 0 0
lte21 te21 2160 - 0 0
wte1qs te1 2223 - 0 0
wte13qs te13 2223 - 0 0
wte19qs te19 2223 - 0 0
wte13 te13 2155 - 0 0
wte16 te16 2167 - 0 0
lted ted 2160 - 0 0
> lqsPrintLocalTbl
PID Process-Name ReadCId WriteCId ObiFlag TID ackCtr fd
--- ------------------- -------- -------- ------- -------- ------ --
1 perfMsgSlave 3739036 15 3 250308 0 0
2 msgServer 3559128 21 0 353110 0 0
3 lqs 16 0 0 37da34 0 0
4 lccTime 2744356 22 3 2da1dc 0 0
5 lccLogger 2741860 23 2 3580c0 0 0
6 lccEvent 2739364 20 2 2aa76c 0 0
7 lccServer 2692332 24 1 270998 0 0
8 rdbServer 2426008 26 1 25a9c4 0 0
> lqsWatch
PID Process-Name Sequ# #Acks/Nacks # Messages S/R # KBytes S/R Queue
--- ------------------- ----- ----------- --------------- --------------- -----
1 perfMsgSlave 11968 0/0 1000/1 1054/0 0
2 msgServer 0 0/0 0/0 0/0 0
3 lqs 12009 0/0 40/24 1/1 0
4 lccTime 0 0/0 0/0 0/0 0
5 lccLogger 0 0/0 0/0 0/0 0
6 lccEvent 0 0/0 0/0 0/0 0
7 lccServer 11982 0/0 4/4 0/0 0
8 rdbServer 11992 0/0 3/3 1/0 0
-- lqsWatch: 8 processes --- 60 ticks refresh-rate --- Type ^C to exit ---
-- KB/sec now-max-avg: 0 167 6
-- KB free now-max-min: 1672 1672 1295
4 INSTALLATION GUIDE
The installation of the lqs module is done at startup by a script file and shall not be changed at runtime. The script file may compose of the installation of lqs module and the lqs test code qsTest.
This section describes how to build the lqs software, if executables are not already available. It then describes step by step the boot script file to load the software on the target. Finally test procedures to verify the installation are described.
4.1 Installation Requirements
4.1.1 Hardware Requirements
4.1.2 Software Requirements
· qsTest for lqs test programs (these programs make use of the prototype application library, qslib, documented in the appendix)
4.2 Building the software
The lqs module is delivered as a UNIX tar file, either on disk or on tape. The tar file expands in a directory structure as defined in [4]. 2
If it is required to build or rebuild the software makefiles are provided in the subdirectories src/ and test/. To use these makefiles a number of environment variables must be defined. An example of extract from .cshrc is given below.
Before using the make files the user should make sure that GNU make is defined before the make supplied by the vendor in the search path. This can be checked by issuing the UNIX command which make. As defined in [4] VLT software should be built using GNU make is order to avoid discrepancies between different vendors implementation of make. The supplied Makefiles follow VLT standards. They rely on the VLT standard environment, in particular the existence of the files $VLTROOT/include/vltMakefile and $VLTROOT/include/vltMakefile.VxWorks.
To build the software follow the procedure below:
2. Type `make clean'. This will remove everything which can be made, thus enforcing recompilation of the entire code.
3. Type `make' resp. `make OPTIMIZE=on'. This will compile and link everything without resp. with optimization. The result, the executable lqs, will be stored in directory lqs/bin.
5. Type `make install'. This will move the executable, the include files required by external modules, and the man-pages to target directories. If environment variable INTROOT is defined targets will be installed in $INTROOT/vw/bin and $INTROOT/vw/include, otherwise targets will be installed in $VLTROOT/vw/bin and $VLTROOT/vw/include.
4.3 Installation on the target
2. Initialize lqs with time-out value and username. The time-out shall be used for acknowledge and ping polling period. The username shall be a valid username on all machines with Rtap environments that lqs can connect to (max. 8 characters). It can be omitted from the shell, in which case the default ("rtap") is taken.
Note that there must also be an entry for the local environment of the host. The first appropriate entry found defines the name of the local environment. However, there may be more than one entry for the same host.
4. Spawn the lqs task and test programs. Note that lqs has to be spawned with the task name tLqs. This is necessary to avoid multiple copies of lqs. You may assign an explicit process-number (i.e. the index in the local-process-table) to the lqs task by passing it as parameter. It can be omitted from the shell, in which case the default-value (3) is taken.
4.4 Boot script example
The following excerpt of a boot script shall give an example of how to install and start lqs. Note that this example has to be modified for the particular target environment. It is recommended to move the edited script file to the target area, e.g. $VLTROOT/vw/bin.
Below is an example of session how to run this script: In the example it is assumed that the target area for the make install was set to /vltdev/LCUintegration/vw/bin.
4.5 Installation verification
Functions performed during installation phase always log OK or ERROR messages to the console.
The tools described in previous section can be used to test the local system has been installed correctly. From the VxWorks shell issue the following commands:
· lqsPrintEnvTbl - This should print the environment table as defined in the boot script on the console.
· lqsPrintLocalTbl - This should print the local process table as defined in the boot script on the console. Check that lqs is listed with the assigned process-number. If the boot script file given as an example is used the following tasks should be present; lqs, qsTest1, qsTest2.
Providing another lqs environment or other environment communicating with the RTAP protocol is available, it is possible to verify remote communication. The lqs test code contains a number of utilities to perform this test. These tests can also be carried out on the local environment. The following commands can be issued from the VxWorks shell:
· sp(qsTest1GetProcNum, process name , environment name ) where process name and environment name are substituted with real names, e.g. "qsTest1","prolcu1". This should print on the console the process number of qsTest1" running on the environment "prolcu1".
· sp(qsTest1GetProcName, process number , environment name ) where process number and environment name are substituted with real values, e.g. 5, "prolcu1". This should print on the console the process name of process number 5 running on the environment "prolcu2".
· sp(qsTest1Send, process number , environment name , string , it response flag ) where process number, environment name, string, and response flag are substituted, e.g. 5, "prolcu1", "hello",1. The response flag should be set to 0 if no response is required and 1 if response is required. If successful this command should not print any errors on the console.
· sp(qsTest1SendN, process number , env name , number of messages , response flag ) where parameters are substituted as before. This command sends number of messages and calculates the performance. E.g. sp(qsTest1SendN,5,"prolcu1",10000,1). If successful this command should print on the console the number of messages send per second.
If any of the test procedures described above do not work as expected it may be useful to switch on debug and tracing. This can be done by issuing the following commands to the VxWorks shell; lqsDebug, lqsTrace and lqsPing. They should all return the value 1. To switch off just issue the commands again and this time they should return the value 0.
5 ERROR MESSAGES AND RECOVERY
The following is a list of all possible error returned by lqs procedures.
· lqsERR_PIPE (-10)
The communication id for the pipe does not exist or VxWorks returned a driver error when accessing the pipe.
· lqsERR_MSGQ (-20)
Generic message queue error. VxWorks returned an unknown error when accessing the message queue.
· lqsERR_INV_MSG_LENGTH (-23)
Invalid message length given or unexpected amount of bytes was read from the message queue.
· lqsERR_NO_MSG_AVAILABLE (-24)
No message was available after reading the message queue with the NO_WAIT option.
· lqsERR_LQS_DEAD (-26)
The requested message queue is not anymore available. lqs has probably terminated.
· lqsERR_NO_ROOM (-31)
Attempt was made to add a new entry in a table (local process table or environment table), but the table was already full.
· lqsERR_NO_COMM_ID (-32)
The requested process has no defined communication id's. It probably has not entered the environment.
· lqsERR_INV_SEM (-33)
Attempt was made to lock or unlock local process table using an illegal semaphore.
1Additionally there is an option to connect to the same remote environment over different networks using different names for that environment. Currently (version 2.3) this facility is preliminary and therefore not documented in this issue. It may also change completely in future versions of this module. For more information see the man-page of `lqsAddEnvTbl', section 3.2.2.
 Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |
| |
|
|
|