Cogent SA85 Driver for Modicon Modbus Plus Cards : Version 1.10
	Chapter 4. Communicating with the Administrator

Chapter 4. Communicating with the Administrator

Table of Contents

The Cogent SA85 Driver for Modicon Modbus Plus Cards device administrator is an OS task, mbpadmin, which allows several tasks to communicate with other devices on the Modbus Plus network. Communication between application tasks and mbpadmin is performed with messages according to message formats defined in the file mbpmsgs.h.

A client task may determine the task id of mbpadmin by querying the name server on the node on which mbpadmin is running. By default, the name mbpadmin is registered by the administrator with the name server. (There is a command-line option that can tell mbpadmin to register a different name, if necessary.) In a QNX 4 network, client tasks on any network node may send requests to the administrator because of the virtual circuit capability of QNX. In QNX 4 or Linux, if a task knows on which node mbpadmin is running, it can use the library function name_locate to find it and prepare to send messages to it. In QNX 6, a task can use the library function name_open to find mbpadmin and prepare and send messages to it.

Each message transaction consists of a request message and a response message. In QNX 4 and Linux, the request is sent to mbpadmin using the send function and the response is returned from mbpadmin by the reply function. In QNX 6, the request is sent to mbpadmin using the MsgSend function and the response is returned from mbpadmin by the MsgReply function.

The type of the request is defined by the first byte of the message. It must contain one of the values which are defined in mbpmsgs.h as MBP_GET_STATE, MBP_GET_GLOBAL, etc. The format of the rest of the message is determined by this type. There is a structure defined in mbpmsgs.h for each request type. For example, a request of type MBP_CLOSE_IN has the format of the C structure mbp_close_in.

...
#define MBP_CLOSE_IN 24
...
typedef struct MBPCLOSEIN
 {
  char type; /* MBP_CLOSE_IN */
  char path_num; /* 1 to 8 */
 } mbp_close_in;

For each request type, there is a corresponding response message structure. It has the same name as the request struct, except that the letter 'r' is inserted after the 'mbp' prefix. For example, the response message for an MBP_CLOSE_IN request is a message of type mbp_r_close_in.

typedef struct MBPRCLOSEIN
 {
  char type;        /* MBP_CLOSE_IN */
  char result_code; /* MBP_R_OK or */
                    /* error code */
 } mbp_r_close_in;

Each response begins with two fields: the type of the request to which mbpadmin is responding and the result code. The result code indicates the success or failure of the requested operation and gives a reason for a failed operation. The result code contains one of the values defined as MBP_R_OK, MBP_R_WRITE_FAILED, etc. If the request type field contains a value not defined in mbpmsgs.h, the result code MBP_R_UNKNOWN_REQUEST is returned in the response.

Because all responses begin with the same two fields, the structure mbp_r_common is defined and used as the first element of each response message structure.

typedef struct MBPRCOMMON
 {
   char type;
   char result_code;
 } mbp_r_common;

typedef struct MBPRCLOSEIN
 {
   mbp_r_common common;
 } mbp_r_close_in;

The following sections describe how and when to use each request type and how to interpret the responses. The requests can be categorized into four classes: status information retrieval, global data access, administrator control and Modbus message path access.

4.1. Status Information

There are three messages in this category: MBP_GET_STATE, MBP_GET_STATUS_BUF and MBP_DEBUG_FLAGS.

4.1.1. `MBP_GET_STATE`

The MBP_GET_STATE request is used to get information about the operational status of the device administrator. The request message consists of only the type field.

The response contains six fields: dmaster_tids, dslave_tids, card_down, debug_flags, tick_size and poll_period. The result code is always MBP_R_OK.

The dmaster_tids and dslave_tids are arrays that contain the task id's of the tasks which have opened each master and slave data path. These paths are discussed in Communication Paths

The card_down field is non-zero if the peer processor on the SA85 or PC85 card has crashed. When this happens, an MBP_INIT request should be sent to mbpadmin.

The debug_flags field contains the debug bits that control the output of trace messages from mbpadmin. These bits can be modified by means of the MBP_DEBUG_FLAGS request or a command-line parameter to mbpadmin. See MBP_DEBUG_FLAGS for more information about the meaning of these bits.

The poll_period field contains the minimum time in milliseconds between checks by mbpadmin for activity on the communication paths. The actual time may be longer due to task scheduling and processing of requests. This value is given on the command-line of mbpadmin and has a default of 100.

4.1.2. `MBP_GET_STATUS_BUF`

The MBP_GET_STATUS_BUF request yields the network status information buffer from the SA85 or PC85 peer processor. This buffer is a 54-word array that contains information such as the Modbus Plus node type, node number, processor version, processor status and various error counters and state variables. This information is described in some detail in the Modicon Modbus Plus Network Programming Guide, Appendix B.

The result code in the mbp_r_get_status_buf response is always MBP_R_OK.

4.1.3. `MBP_DEBUG_FLAGS`

The mbpadmin task can optionally generate trace information that is useful in debugging its operation. This option was incorporated to facilitate debugging the mbpadmin task itself and should be of little interest to application programmers. It is documented here for completeness.

For most efficient operation, the debug flags should be zero.

Each bit of the debug flags word corresponds to a class of trace output messages. When a bit is on, trace messages of that type are written (appended) to the trace device or file. These bits are not mutually exclusive; any or all of the bits may be set at once.

The device or file to which the trace output is written is given in the dev_name field. If it is the null string (""), the output is written to the standard output of mbpadmin.

The MBP_D_WATCHDOG bit (bit 0) causes alternating '+' and '-' characters to appear in the upper left corner of the console. The alternation of these characters serves as a "liveness" indicator. It changes each time a "watchdog" message is sent to the peer processor. It should change approximately once per second. If not, the peer processor will likely crash and the card_down flag will be set (see MBP_GET_STATE).

The MBP_D_MSG_RCV bit (bit 1) enables tracing of receipt of messages from tasks. The request type and task id are printed.

The MBP_D_TASK_DEATH bit (bit 2) enables tracing of task death messages received by mbpadmin. Such a message is received whenever a task terminates. The task id of the dead task is printed.

The MBP_D_GEN_ERRS bit (bit 3) enables the output of general error messages from the administrator. These are usually errors in interacting with the peer processor on the SA85 or PC85 card.

The MBP_D_SERV_REQ bit (bit 4) enables the output of information related to host service requests from the peer processor. This is related to the receipt of messages on one of the data master or slave paths.

The MBP_D_PEER_MSG bit (bit 5) controls the printing of messages that describe Modbus messages received on each data master or slave path.

The result code of the mbp_r_debug_flags response is always MBP_R_OK.


Chapter 3. Starting the Administrator - mbpadmin		4.2. Global Data

Chapter 4. Communicating with the Administrator

4.1. Status Information

4.1.1. MBP_GET_STATE

4.1.2. MBP_GET_STATUS_BUF

4.1.3. MBP_DEBUG_FLAGS

4.1.1. `MBP_GET_STATE`

4.1.2. `MBP_GET_STATUS_BUF`

4.1.3. `MBP_DEBUG_FLAGS`