6 APPENDIX

6.1 Test Functions

The following routines have been developed to test the functionality of the lqs module. Three test tasks are provided, which use these routines; qsTest1, qsTest2, and qsTest3. They are all equivalent except for the obituary behaviour.

· qsTest1 does neither send nor receive obituary messages.

· qsTest2 sends and receives obituary messages.

· qsTest3 does not send but receives obituary messages.

The task qsTestX, where X is 1, 2 or 3, simply waits forever for a message and returns a reply if required. Messages to these tasks can be send from the local system or from another systems using the RTAP protocol.

The functions described in section 4.5 can be executed as tasks or under VxWorks shell.

A number of test scripts making use of these functions are available in the test directory. These may be adapted to the particular environment and executed under VxWorks shell in a similar way as the boot script.

Note that all the routines used by the test functions, and documented below, do not declare message buffers as local variables. Message buffers are declared in the main function and always passed via pointers to lower level routines. This is necessary to avoid problems of stack overflow. It is recommended to use a similar scheme for the LCU message system.

6.1.1 qsEnter

NAME

qsEnter - enter the LCU Q Server environment

SYNOPSIS

#include "qsLib.h"

int qsEnter (char * local_proc_name_ptr,

int read_comm_size,

int * local_proc_num_ptr,

unsigned int obiFlag)

DESCRIPTION

This operation signals to the LCU Q Server that the application is part of Q Server environment.

· local_proc_name_ptr is the process name of the application. It is used later by other local or remote processes to identify the application.

· read_comm_size is the maximum number of messages of the incoming message queue of the application, i.e. messages from Q Server to applications.

· local_proc_num_ptr is the pointer to an application variable, where the process number of the application is returned.

· obiFlag is the flag describing obituary behaviour.

RETURN VALUES

· OK

· A negative error type:

· qsErrQServerDead_C
If the Q Server task is not present.

· qsErrProcName_C
If the given process name is too long.

· qsErrMsgQ_C
If the given read_comm_size is too large, or the communication from Q Server task to application cannot be opened.

· qsErrPipe_C
If the communication from application to Q Server task cannot be opened.

· qsErrNoRoom_C
If there is no room to store application in the Q Server context.

EXAMPLE

int local_proc_num;

...

if (qsEnter ("qsTest1", 5, &local_proc_num, 0) != OK)

{

/* error process */

...

}

else

/* normal process */

...

CAUTIONS

· Process names shall not be longer than 19 characters.

· The number of processes is currently limited to 254. The first process starts with 2 as 0 is reserved for environment obituary and 1 for the lqs process itself.

· The returned proc num cannot be shared by applications.

· Applications should define a small read_comm_size as each RTAP message size is defined to be more than 8 Kbytes. The maximum size is currently defined to 100.

6.1.2 qsExit

NAME

qsExit - exit the LCU Q Server environment

SYNOPSIS

#include "qsLib.h"

int qsExit (int local_proc_num,

lqsMSGP send_msg)

DESCRIPTION

This operation signals to the LCU Q Server that the application exits of Q Server environment.

· local_proc_num is the process number of the application. It must be obtained previously by an qsEnter operation.

· snd_msg is a pointer to a message buffer. It is required to send an obituary message (if the calling task should generate an obituary message on termination).

RETURN VALUES

· OK

· A negative error type:

· qsErrQServerDead_C
If the Q Server task is not present.

· qsErrProcNum_C
If the local_proc_num is undefined.

· qsErrMsgQ_C
If the Q Server task is aborted and the communication from Q Server task to application cannot be closed.

· qsErrPipe_C
If the Q Server task is aborted and the communication from application to Q Server task cannot be closed.

EXAMPLE

int local_proc_num;

lqsMSG send_msg;

...

if (qsEnter ("qsTest1", 5, &local_proc_num, 0) == OK)

...

...

...

if (qsExit (local_proc_num, &send_msg) != OK)

{

/* error process */

...

}

else

/* normal process */

...

CAUTIONS

Applications should use this function to exit the Q Server environment. If not, when they exit or are aborted, the Q Server automatically detects this and generates an obituary if required.

6.1.3 qsReceive

NAME

qsReceive - Receive a message from another Q Server process.

SYNOPSIS

#include "qsLib.h"

int qsReceive (int local_proc_num,

lqsMSG ** msg,

int time_out_second,

int remote_proc_num,

char * remote_env_name_ptr)

DESCRIPTION

This function is used to receive a Q Server message from another process. That process may either be running on the same LCU or on another environment.

· local_proc_num is the process number of the application. It must be obtained previously by an qsEnter operation.

· msg is a pointer to the message structure.

· time_out_second allows the application to wait for a number of seconds for an incoming message before timing out. rtNO_TIMEOUT causes an indefinite timeout, rtNO_WAIT causes this function to return immediately if there is no message on the queue.

· remote_proc_num and remote_env_name_ptr are not used in the present version.

· No message filtering is performed at this level.

RETURN VALUES

· OK

· A negative error type:

· qsErrQServerDead_C - If the Q Server task is not present.

· qsErrProcNum_C - If the local_proc_num or remote_proc_num is undefined.

· qsErrEnvironment_C - If the remote environment is undefined.

· qsErrTimeOut_C - If timeout.

· qsErrMsgQ_C - If the communication from Q Server task to application cannot be read.

· qsErrNack_C - If an Nack message is received.

· qsErrObituary_C - If an Obituary message is received from the remote process, of the remote environment.

EXAMPLE

int qs_error;

int local_proc_num;

lqsMSG msg;

...

if (qsEnter ("qsTest1", 5, &local_proc_num, 0) == OK)

...

...

...

qs_error = qsReceive (local_proc_num, &msg, 10, 0, 0);

if (qs_error != OK)

{

/* error process */

...

}

else

{

/* normal process */

free(msg);

...

}

6.1.4 qsSend

NAME

qsSend - Send a message to another Q Server process.

SYNOPSIS

#include "qsLib.h"

int qsSend ( int local_proc_num,

lqsMSG * msg,

lqsMSG * ack_msg,

int time_out_second)

DESCRIPTION

This function is used to send a Q Server message to another process. That process may be either be running under the same LCU or under another environment.

· local_proc_num is the process number of the application. It must be obtained previously by an qsEnter operation.

· msg is the message structure.

· ack_msg is the message structure to receive an acknowledgement.

· time_out_second allows the application to wait for a number of seconds for an Ack message before timing out. rtNO_TIMEOUT causes an indefinite timeout. The option rtNO_WAIT causes this function to return immediately without waiting for Ack. This option should only be used when sending response messages.

RETURN VALUES

· OK

· A negative error type:

· qsErrQServerDead_C - If the Q Server task is not present.

· qsErrProcNum_C - If the local_proc_num is undefined.

· qsErrPipe_C - If the communication to Q Server task cannot be written.

· qsErrTimeOut_C - If timeout.

· qsErrMsgQ_C - If the communication from Q Server task to application cannot be read.

· qsErrNack_C - If an Nack message is received.

· qsErrObituary_C - If an Obituary message is received from the remote process, of the remote environment.

EXAMPLE

int qs_error;

int local_proc_num;

lqsMSG msg;

lqsMSG *ack_msg;

...

if (qsEnter ("qsTest1", 5, &local_proc_num, 0) == OK)

...

...

...

/* Fill msg */

qs_error = qsSend (local_proc_num, &msg, ack_msg, 10);

if (qs_error != OK)

{

/* error process */

...

}

else

{

/* normal process */

...

}

6.1.5 qsGetProcNum

NAME

qsGetProcNum - Get the process number of another Q Server process.

SYNOPSIS

#include "qsLib.h"

int qsGetProcNum (int local_proc_num,

char * remote_proc_name_ptr,

char * remote_env_name_ptr,

int time_out_second,

lqsMSG * receive_msg,

lqsMSG * send_msg,

int * remote_proc_num_ptr)

DESCRIPTION

This function is used to get the process number of another Q Server process. That process may be either be running under the same LCU or under another environment.

· local_proc_num is the process number of the application. It must be obtained previously by an qsEnter operation.

· remote_proc_name_ptr is the remote process name.

· remote_env_name_ptr is the remote environment.

· time_out_second allows the application to wait for a number of seconds for the response message before timing out. rtNO_TIMEOUT causes an indefinite timeout. The option rtNO_WAIT causes this function to return immediately if there is no response on the queue, it shall never to be used then.

· receive_msg is a pointer to a message buffer.

· send_msg is a pointer to a message buffer.

· remote_proc_num_ptr is the buffer to receive the remote process number. It is valid only of the function returns OK, undefined otherwise.

RETURN VALUES

· OK

· A negative error type:

· qsErrQServerDead_C - If the Q Server task is not present.

· qsErrProcNum_C - If the local_proc_num is undefined.

· qsErrProcName_C - If the remote_proc_name is too long.

· qsErrEnvironment_C - If the remote environment is undefined.

· qsErrTimeOut_C - If timeout.

· qsErrPipe_C - If the communication to Q Server task cannot be written.

· qsErrMsgQ_C - If the communication from Q Server task to application cannot be read.

· qsErrNack_C - If an Nack message is received.

· qsErrObituary_C - If an Obituary message is received from the remote process, of the remote environment.

EXAMPLE

int qs_error;

int local_proc_num;

int remote_proc_num;

lqsMSG send_msg;

lqsMSG receive_msg;

...

if (qsEnter ("qsTest1", 5, &local_proc_num, 0) == OK)

...

...

...

qs_error = qsGetProcNum (local_proc_num,"qsTest2","prolcu2",10,

&receive_msg, &send_msg, &remote_proc_num);

if (qs_error != OK)

{

/* error process */

...

}

else

{

/* normal process */

...

}

6.1.6 qsGetProcName

NAME

qsGetProcName - Get the process name of another Q Server process.

SYNOPSIS

#include "qsLib.h"

int qsGetProcName (int local_proc_num,

int remote_proc_num,

char * remote_env_name_ptr,

int time_out_second,

lqsMSG * receive_msg;

lqsMSG * send_msg;

char ** remote_proc_name_ptr)

DESCRIPTION

This function is used to get the process number of another Q Server process. That process may be either be running under the same LCU or under another environment.

· local_proc_num is the process number of the application. It must be obtained previously by an qsEnter operation.

· remote_proc_num is the remote process number.

· remote_env_name_ptr is the remote environment.

· time_out_second allows the application to wait for a number of seconds for the response message before timing out. rtNO_TIMEOUT causes an indefinite timeout. The option rtNO_WAIT causes this function to return immediately if there is no response on the queue, it shall never to be used then.

· receive_msg is a pointer to a message buffer.

· send_msg is a pointer to a message buffer.

· remote_proc_name_ptr is the pointer to the string to receive the remote process name. It is valid only of the function returns OK, undefined otherwise.

RETURN VALUES

· OK

· A negative error type:

· qsErrQServerDead_C If the Q Server task is not present.

· qsErrProcNum_C If the local_proc_num or remote_proc_num is undefined.

· qsErrEnvironment_C If the remote environment is undefined.

· qsErrTimeOut_C If timeout.

· qsErrPipe_C If the communication to Q Server task cannot be written.

· qsErrMsgQ_C If the communication from Q Server task to application cannot be read.

· qsErrNack_C If an Nack message is received.

· qsErrObituary_C If an Obituary message is received from the remote process, of the remote environment.

EXAMPLE

int qs_error;

int local_proc_num;

char remote_proc_name [10];

lqsMSG receive_msg;

lqsMSG send_msg;

...

if (qsEnter ("qsTest1", 5, &local_proc_num, 0) == OK)

...

...

...

qs_error = qsGetProcName (local_proc_num, 12, "prolcu2", 10,

&receive_msg, &send_msg, &remote_proc_name);

if (qs_error != OK)

{

/* error process */

...

}

else

{

/* normal process */

...

}

6.1.7 qsFillMsg

NAME

qsFillMsg - Fill an Q Server message.

SYNOPSIS

#include "qsLib.h"

int qsFillMsg (lqsMSG * msg,

int msg_priority,

rtProcessId * source_proc_id_ptr,

rtProcessId * dest_proc_id_ptr,

int msg_type,

int msg_id,

int msg_responseFlag,

char * data_ptr,

int data_len)

DESCRIPTION

This function is simply used to fill an Q Server message.

· msg is the message structure.

· source_proc_id_ptr and dest_proc_id_ptr are structures defined in ???.

· msg_type, msg_id and msg_responseFlag literals are defined in ??.

· data_ptr points to user data to be copied into the message.

· data_len is the length of the user data.

RETURN VALUES

· OK

· A negative error type:

· qsErrMsgSize_C If data len is greater than rtMAXMSG.

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