MB_FileRd()

MB_FileRd() is called when a Modbus master sends a Function Code 20 command. MB_FileRd() reads a single integer value from a file. As mentionned in the Modbus specifications, a file is an organization of records. Each file can contain up to 10,000 records (addressed from 0 to 9999). You must 'map' the File/Record/Ix to the actual application's corresponding data. MB_FileRd() should only be called by µC/Modbus.

Prototype

CPU_INT16U MB_FileRd (CPU_INT16U file_nbr,
                      CPU_INT16U record_nbr,
                      CPU_INT16U ix,
                      CPU_INT08U record_len,
                      CPU_INT16U * perr)  

Arguments

file_nbr

Is the number of the desired file.

record_nbr

Is the desired record within the file, a number between 0 and 9999.

ix

Is the desired entry in the specified record.

record_len

Is the total length of the record.

perr

Is a pointer to a variable that will contain an error code based on the outcome of the call. Your code thus needs to return one of the following error codes:

MODBUS_ERR_NONE

the specified file/record/entry is valid and your code is returning its current value.

MODBUS_ERR_FILE

if the specified file_nbr is not a valid file number in your product.

MODBUS_ERR_RECORD

if the specified record_nbr is not a valid record number in the specified file.

MODBUS_ERR_IX

if the specified ix is not a valid index into the specified record. 

Returned Value

MB_FileRd() returns the current value of the element in the file as an unsigned value. Of course, you can also return ‘signed’ values but those need to be cast to CPU_INT16U. You should note that the value will not be changed if you cast a signed variable to CPU_INT16U. The Modbus master will receive the proper value and it’s up to the Modbus master to properly retrieve the signed data . If an error is detected, you should return 0.

Notes / Warnings

Code is enabled when MODBUS_CFG_FC20_EN is set to DEF_ENABLED in your product’s mb_cfg.h file.

Called By:

MBS_FC20_FileRd() in mbs_core.c

Example

In this example, we have two ‘files’ that we implemented as an array of 16-bit integers.

#define     APP_MAX_FILES 2
#define     APP_FILE_MAX_RECORDS   10
#define     APP_FILE_MAX_VALUES   100


CPU_INT16U  AppFile[APP_MAX_FILES][APP_FILE_MAX_RECORDS][APP_FILE_MAX_VALUES];



CPU_INT16U  MB_FileRd (CPU_INT16U   file_nbr, 
                       CPU_INT16U   record_nbr, 
                       CPU_INT16U   ix, 
                       CPU_INT08U   record_len, 
                       CPU_INT16U  *perr)
{
    CPU_INT16U  val;


    *perr = MODBUS_ERR_NONE;
    if (file_nbr >= APP_MAX_FILES) {
        *perr = MODBUS_ERR_FILE;
        return (0);
    }
    if (record_nbr >= APP_FILE_MAX_RECORDS) {
        *perr = MODBUS_ERR_RECORD;
        return (0);
    }
    if (ix >= APP_FILE_MAX_VALUES) {
        *perr = MODBUS_ERR_IX;
        return (0);
    }
    CPU_CRITICAL_ENTER();
    val = AppFile[file_nbr][record_nbr][ix];
    CPU_CRITICAL_EXIT();
    return (val);
}