Technical information

RMS NetLinx Virtual Device API
121
RMS Enterprise - NetLinx Programmer’s Guide
RMS NetLinx Virtual Device API
Overview
The RMS NetLinx virtual device API provides the lowest level API and direct access to the RMS Engine running on the NetLinx
platform. The RMS NetLinx Adapter module must be defined in the user program code to define a NetLinx virtual device and
connect it to the RMS Engine.
This section defines all the channels, levels, and Send Commands exposed by the RMS Engine via the RMS NetLinx Adapter.
API Conventions
The RMS NetLinx Virtual Device API is based on the same conventions used by Duet device modules:
SEND_COMMANDS: are used to send query requests or instructions to RMS.
DATA EVENTS (Commands): are used to listen to query response or notification events from RMS.
CHANNELS: are used to provide simple feedback on RMS client state/status.
LEVELS: are used to provide simple feedback on RMS client state/status.
Send commands that start with the "?" character are queries that interrogate the RMS client subsystem for information.
Both query responses and notification events that are generated from the RMS NetLinx Adapter module are emitted as
COMMAND DATA_EVENTS on the RMS virtual device.
Character & String Escaping
Strings and commands sent and received from the RMS NetLinx adapter virtual device (vdvRMS) have special characters (comma,
single quote and double quote) that must be properly escaped when required in the data string.
The RMS API uses the Duet string escaping convention. More information on the character escaping can be found in the Standard
NetLinx API Help guide in NetLinx Studio under the topic of Command and Escape Characters.
The RmsApi Include File includes convenience function wrappers that will automatically perform the string escaping and un-
escaping:
RmsParseDPSFromString (see page 122)
RmsPackCmdHeader (see page 122)
RmsPackCmdParam (see page 123)
RmsPackCmdParamArray (see page 123)
RmsParseCmdHeader (see page 124)
RmsDuetParseCmdParam (see page 124)
RmsParseCmdParamEx (see page 125)
The RMS SDK includes convenience function wrappers in the RMSAPI.axi Include File that will automatically perform the string
escaping and un-escaping.
The following code snippet provides an example of escaping a command destined for the RMS NetLinx virtual device API:
STACK_VAR CHAR rmsCommand[RMS_MAX_CMD_LEN];
rmsCommand = RmsPackCmdHeader('ASSET.SERIAL');
rmsCommand = RmsPackCmdParam(rmsCommand,'128:1:0');
rmsCommand = RmsPackCmdParam(rmsCommand,'01235X34GS2');
SEND_COMMAND vdvRMS, rmsCommand;
This code snippet provides an example of un-escaping a command received from the RMS NetLinx virtual device API.
STACK_VAR CHAR rmsHeader[RMS_MAX_HDR_LEN];
STACK_VAR CHAR rmsParam1[RMS_MAX_PARAM_LEN];
STACK_VAR CHAR rmsParam2[RMS_MAX_PARAM_LEN];
rmsHeader = RmsParseCmdHeader(DATA.TEXT);
rmsParam1 = RmsParseCmdParam(DATA.TEXT);
rmsParam2 = RmsParseCmdParam(DATA.TEXT);