user functions api

8/10/2019 User Functions API

1/36

User Functions API.doc

Flex.Win

User Functions API

Document HistoryRevision Date Author Description1 10-Feb-2002 AT Initial Draft

2 11-Feb-2002 ACH IPC description added

3 14-Feb-2002 AT Updated

4 08-Apr-2002 ACH Translated to English

5 10-Apr-2002 AT Updated

6 30-Apr-2002 AT Updated

7 28-Apr-2002 ACH Additional description for console name field

8 09-May-2002 DC Added description for existing user_func users9 15-Aug-2002 AT Changed SRVIPCGetConsoleList description

10 11-Sep-2002 ACH Description for SRVIPCGetControlInfo() added

11 12-Sep-2002 ACH Fixed description for SRVIPCGetControlInfo()

12 16-Oct-2003 AT Changed SRVIPCInputStrBox() description. $PASS$ added

13 09-Dec-2004 DC Updated description for SRVIPCStartApplication

14 01-Jul-2009 VS Added descriptions for SRVIPCPlaySound(),SRVIPCStopSound(), SRVIPCOpenDisplayEx(),SRVIPCModal() and FlexView API ShowDatabaseEditor()

15 10-Oct-2009 AC RealFlex 6.4.63 compatible functions updated

16 02-Nov-2009 AC Some comment for examples fixed


2/36


3/36

User Functions API.doc Page 3 of 36

Table of contents

RealFlex User functions API...........................................................................................................4Introduction. ................................................................................................................................4API description. ...........................................................................................................................7SRVIPCOpen...............................................................................................................................7SRVIPCClose ..............................................................................................................................8SRVIPCSetTimeout.....................................................................................................................8SRVIPCSetTimeoutMode ...........................................................................................................8SRVIPCGetConsoleList ..............................................................................................................9SRVIPCGetConsoleName.........................................................................................................10SRVIPCGetConsoleType ..........................................................................................................10SRVIPCMessageBox.................................................................................................................11SRVIPCInfoBox........................................................................................................................13SRVIPCCloseInfoBox...............................................................................................................14SRVIPCInputStrBox .................................................................................................................14SRVIPCInputNumBox ..............................................................................................................16

SRVIPCMenu............................................................................................................................18SRVIPCCheckList.....................................................................................................................20SRVIPCOpenDisplay ................................................................................................................22SRVIPCReplaceDisplay............................................................................................................23SRVIPCCloseDisplay................................................................................................................24SRVIPCSendTextMessage........................................................................................................25SRVIPCPrintReport...................................................................................................................26SRVIPCStartApplication...........................................................................................................27SRVIPCGetControlInfo.............................................................................................................28SRVIPCPlaySound....................................................................................................................31SRVIPCStopSound....................................................................................................................32

SRVIPCOpenDisplayEx............................................................................................................32SRVIPCModal...........................................................................................................................34

FlexView User function API .........................................................................................................35ShowDatabaseEditor .................................................................................................................35


4/36


RealFlex User functions API.

Introduction.

This document contains description of application program interface (API) designed to write

QNX applications that can interact with remote FlexView consoles. First of all this API intendedfor QNX applications that use user_func functionality of RealFlex. The following picture

illustrates interaction between QNX application and FlexView console.

The key part of this scheme is FlexServ. User application can be started from FlexView consoleor from CSL or superkey script from RealFlex. In the case, where application is started fromFlexView console using context menu, it will emulate behaviour of RealFlex context userfunction menu. FlexServ always provides connection between QNX application and FlexViewconsole.

API is implemented using POSIX queues (mqueue) and special internal protocol. Using thismethod user application can open special dialogs, messages, information, input or menuwindows at FlexView console.


5/36


User application sends special messages to FlexView. FlexView opens menu window or other

user interface elements, process user input and sends reply to user application queue.

Also FlexView can start user application program using standard piping mechanism. In this case

all application output would be redirected to FlexView console. I.e a FlexView user can start an

application which was compiled and runs on QNX, but have all it output displayed on theFlexView window.

FlexView opens special window for such application. All QNX application output through stdout

and stderr will be redirected to this FlexView window. Any users input in this FlexView

window will be redirected to application. User input can be read by QNX application using

standard input functions such as fgets(),

fgetch() and etc.

For example:

#include

#include

int main( void )

{

char buffer[80];

printf( Hello, world!\n );

while( fgets( buffer, 80, stdin ) != NULL )

fputs( buffer, stdout );

return EXIT_SUCCESS;

}

If user run this application from FlexView console, the the application runs on the QNX PC and

then Hello, world! will appear in FlexView console window.

Command line parameters that can be passed to an application when it is started from FlexView

console are:

User can specify any names for this parameters using FlexView menu editor.


6/36


This functionality allows the user to have the same operation as the older style USER

SUPPLIED PROC. that is available in RealFlex/LanFlex. E.g

The user can right-click on any tag on the FlexView console and select USER SUPPLIED PROC

and it will call a QNX application called user_func with a list of parameters passed to user_func-t DatabaseType -i PointIndex c ConsoleName

(Note this is the default setting and the user can change the application name and the list of

parameter that are passed to the application using User Proc Editor)

The QNX application can use the DatabaseType and PointIndex , but must also use the

ConsoleName parameter. The QNX application has to include some of the functions listed in this

document to communicate back to the FlexView console which activated the program.


7/36


API description.

User QNX application must perform following steps.

1) Get FlexView console name from command line parameters

Use FlexView option User Function to create the QNX application name to be

used and list of parameters e.g indicate which console is used. This can be

selected from a list of options within FlexView.

e.g user_func c $(ConsoleName)

2) Open connection with FlexServ (QNX application)

3) Open different dialogs at FlexView console

Use FlexView Options Menu editor to create these.

4) Process user input (QNX application)

5) Close connection with FlexServ (QNX application)

SRVIPCOpen

#include

IPCQUEUE*SRVIPCOpen(intiSize, intiMsgsNum, int nFlags);

This function opens connection with FlexServ. It opens two queues - FlexServ queue andapplication queue.Parameters of application queue specified by iSize and iMsgsNum parameters.1 can be used for iSize and iMsgsNum parameters. In this case SRVIPCOpen will choose theseparameters itself.By default IPC has 20 seconds timeout interval for all user input interface functions. To changetimeout value use SRVIPCSetTimeout() function.

Parameters:

iSizespecifies message size of application input queue (ignored for RF6)iMsgsNum

specifies maximum message size in application input queue (ignored for RF6)nFlags

0 open IPC for read/writeIPCFLAG_WRONLY open IPC for write only (ignored for RF6)

Return value:Returns pointer to IPCQUEUE structure or NULL pointer if operation failed


8/36


SRVIPCClose

#include

voidSRVIPCClose(IPCQUEUE*pQueue);

Close connection with FlexServ. This function closes application and FlexServ queues and frees

memory used by IPCQUEUE structure.

Parameters:pQueue

pointer to an open connection.

SRVIPCSetTimeout

#include

voidSRVIPCSetTimeout(IPCQUEUE*pQueue,unsigned int uTimeOut);

This function sets timeout interval for all user input functions except SRVIPCInfoBox.

Parameters:pQueue

pointer to an open connection.uTimeout

Specifies the duration, in seconds, of the timeout period for all user input interface functionsexcept SRVIPCInfoBox.

Example:

#include

// Open IPC with default queue parameters

IPCQUEUE*pIpc = SRVIPCOpen(-1, -1, 0);

// Set timeout to 5 minutes

if (pIpc != NULL)

SRVIPCSetTimeout(pIpc, 300);

SRVIPCSetTimeoutMode

#include

voidSRVIPCSetTimeoutMode(IPCQUEUE*pQueue,unsigned int uMode);

This function sets timeout mode for user input functions. Default mode is RETURN_DEFAULT user input function returns default value. If uMode set to RETURN_ERROR then user inputfunctions on timeout will return -2 to indicate time out;

Parameters:pQueue

pointer to an open connection.uMode

RETURN_DEFAULT or RETURN_ERROR.


9/36


Example:

#include



// Set timeout return value to RETURN_ERROR

if (pIpc != NULL)

SRVIPCSetTimeoutMode(pIpc, RETURN_ERROR);

SRVIPCGetConsoleList

#include

int SRVIPCGetCosoleList(IPCQUEUE*pQueue, char **pBufferList);

The SRVIPCGetCosoleListfunction fills given buffer with FlexView console names currentlyconnected to RealFlex system. For RF6 the very last name specifies local RF6 host name.

Parameters:pQueue

Pointer to an open connection.pBufferList

An array of pointers which receives list of names of all FlexView console currently connected toRealFlex system. The following example shows the buffer contents with representing theterminating null character.

FW1FW2FW4

Return value:If the function succeeds, the return value is the number of consoles, connected to RF.If the function fails, the return value is -1.

Example:

// open connection and get list of all connected FlexView consoles

#include



char *pBuffer;

// get list of console names

if (SRVIPCGetConsoleList(pQueue, &pBuffer) != -1) {char *pConsole = pBuffer;

while(*pConsole != \0) {

printf(FlexView console name: %s\n, pConsole); // print name

pConsole += strlen(pConsole) + 1; // move to the next name

}

// do to forget to free buffer allocated by SRVIPCGetConsoleList

free(pBuffer);

}


10/36


SRVIPCGetConsoleName

Available in RealFlex 6.4.63 and higher

#include int SRVIPCGetCosoleName(IPCQUEUE*pQueue, char *pszConsoleName,

size_t nNameLen, IPCTYPE type);

Reads name of RealFlex console on which application is running.

Parameters:pQueue

Pointer to an open connection.pszConsoleName

A buffer where the function can store the console name.

nNameLenThe size of the buffertype

Reserved, must be 0

Return value:0 success

-1 an error occurred

Example:

// open connection and get list of all connected FlexView consoles#include



char name[80];

// get current RealFlex console name

if (SRVIPCGetConsoleName(pQueue, name, sizeof(name), 0) != -1) {

printf(Running on %s\n, buffer);

}

SRVIPCGetConsoleType


#include

IPCTYPESRVIPCGetConsoleType(constIPCQUEUE*pQueue,

constchar*pszConsoleName);

Returns type of console by its name.

Parameters:pQueue


11/36


Pointer to an open connection.pszConsoleName

The name of console that you want to test

Return value:

One of the following constants:

IPCTYPE_ERROR - error, or console not foundIPCTYPE_NONE - console name not foundIPCTYPE_FLEXVIEW this is FlexView console

IPCTYPE_RF_LOCAL this is local RealFlex consoleIPCTYPE_RF_PEER - reserved for future

IPCTYPE_PSEUDO - RealFlex pseudo console - CSL_CONSOLE or ALARMRELAY

Example:

// open connection and get list of all connected FlexView consoles

#include

// Open IPC with default queue parametersIPCQUEUE*pIpc = SRVIPCOpen(-1, -1, 0);

// check console name

if (SRVIPCGetConsoleType(pQueue, argv[1]) == IPCTYPE_RF_LOCAL) {

printf(%s is local RealFlex console\n, argv[1]);

}

SRVIPCMessageBox

#include

intSRVIPCMessageBox(constIPCQUEUE*pQueue,

constchar*pszConsoleName,

constchar*pszTitle,

int iID,

constchar*pszMessage,

unsigned intuStyle,

constchar*pszButtons);

The SRVIPCMessageBoxfunction creates, displays, and operates a message box. The messagebox contains an application-defined message and title, plus up to five push buttons.

If program were started thru a pipe then dialog box would be opened in Main applicationwindow. Dialog box would be titled as defined in pszTitle variable. Message defined bypszMessage would be printed in dialog box. Dialog box would have buttons specified bypszButtons string.

Supported by RealFlex 6 consoles starting with version 6.4.63.


12/36


Parameters:pQueue

Pointer to IPCQUEUE structure (obtained by SRVIPCOpen() call)pszConsoleName

String specifies the name of FlexView console for dialog box. Dialog box would be opened atconsole specified by this parameter

pszTitlePointer to a null-terminated string that contains the dialog box title.iIDDialogs ID in range of 1 to 65535. Must be unique for each dialog box defined in the system.pszMessage

Pointer to a null-terminated string that contains the message to be displayeduStyle

To display an icon in the message box, specify one of the following values.IPCBOX_WARNING - An exclamation-point icon appears in the message box.IPCBOX_INFORMATION - An icon consisting of a lowercase letter iin a circle appears in themessage box.

IPCBOX_QUESTION - A question-mark icon appears in the message box.IPCBOX_ERROR - A stop-sign icon appears in the message box.pszButtons

String with buttons titles. Titles should be separated by colon. Up to five button titles can bedefined. Default button is specified by $. If default button is not specified then first one will beused as default for return value by timeout.

Return value:Function returns the number of selected button starting from 1.Function returns 0 if user press Esc key.If the function fails, the return value is -1. (there is no console with name specified)

Example:

// open MessageBox with Yes and No buttons

#include



if (pIpc != NULL) {

int nButton = SRVIPCMessageBox(pIpc, FW1, Warning, 101,

Are you sure?, IPCBOX_QUESTION , Yes:$No);

if (nButton == 1) // Yes

else if(nButton == 2) // No

else if(nButton == 0) // Esc

else if(nButton == -1)// Error

}


13/36


SRVIPCInfoBox

#include

intSRVIPCInfoBox(constIPCQUEUE*pQueue,


constchar*pszTitle,

int iID,unsigned intuStyle,

constchar*pszMessage);

Function displays information window. This function returns immediately after sending messageto consoles and application can continue. Information box will remain open on FlexViewconsole while user application works. Application can close this box by callingSRVIPCCloseInfoBox(). If application call SRVIPCInfoBox() with the same iID, then thecontent of information box will be updated. If application call SRVIPCInfoBox() with differentiID, then FlexView will open new information box.


Parameters:

pQueue


String specifies the name of FlexView console for info box. Info box would be opened at consolespecified by this parameter.pszConsoleNamecan contain a comma separated list of consolepatterns. Simbols * and ? are used as for file masks in the command line shell.For example: X*, AR*. The Information box would be opened at all consoles match withthese patterns.

pszTitlePointer to a null-terminated string that contains the dialog box title.iID

Unique ID for this info box in range 1 to 65535. This id is used by SRVIPCCloseInfoBox()function to close information box.uStyle

To display an icon in the message box, specify one of the following values.IPCBOX_WARNING - An exclamation-point icon appears in the message box.IPCBOX_INFORMATION - An icon consisting of a lowercase letter iin a circle appears in themessage box.IPCBOX_QUESTION - A question-mark icon appears in the message box.

IPCBOX_ERROR - A stop-sign icon appears in the message box.pszMessage

Pointer to a null-terminated string that contains the message to be displayed

Return values:

0 if successIf the function fails, the return value is -1.


14/36


SRVIPCCloseInfoBox

#include

intSRVIPCCloseInfoBox(constIPCQUEUE*pQueue,


int iID);

This function closes information box opened by SRVIPCInfoBox() function. This functioncloses information box with Id specified by iID at console pszConsoleName.


Return values:0 if successIf the function fails, the return value is -1.

SRVIPCInputStrBox

#include

intSRVIPCInputStrBox(constIPCQUEUE*pQueue,


constchar*pszTitle,

int iID,

constchar*pszMessage,

constchar*pszButtons,

char *pszText,

int iStrlen);

Function displays string input box at FlexView console. User can type text and press one of twobuttons (default buttons are OK and CANCEL).


Parameters:

pQueue


String specifies the name of FlexView console for dialog box. Dialog box would be opened at

console specified by this parameterpszTitle

Dialog box title.Note: Starting from FlexView 3.0.4 opening pszTitle with $PASS$ causes all characters enteredinto the edit box to be displayed as an asterisk (*). $PASS$ is omitted when dialog box titledisplayed. E.g. if pszTitle points to $PASS$Password needed then dialog box with titlePassword needed will be opened.iID

Unique id for this dialog in range 1 to 65535.pszMessage



15/36


pszButtons

Pointer to colon separated string with buttons definitions. If this pointer is NULL the OK andCANCEL buttons would be displayed. $OK:CANCEL is a default value for this parameter.$ sign specifies default button. Up to two buttons can be specified.pszText

The buffer for user input. If pszText contains text when function is called then this text will be

displayed as a default input value for the user.iStrlen

Specifies the size of the text buffer not including terminating null, so buffer must be at leastiStrLen + 1 in size. User will be able to enter only iStrlen characters.

Return values:

Function returns the number of selected button starting from 1. pszText receives stringentered by user.

0 if user press Esc.If the function fails, the return value is -1.

Example:

#include


char szText[80];


if (pIpc != NULL) {

intitem = SRVIPCInputStrBox(pIpc, argv[1], "String box", 1001,

"Enter some text","OK:CANCEL",

szText, sizeof(szText) - 1);

if (item == 1) {

printf(User pressed OK. Text \%s\\n, szText);

}}


16/36


SRVIPCInputNumBox

#include

intSRVIPCInputNumBox(constIPCQUEUE*pQueue,


constchar*pszTitle,

int iID,constchar*pszMessage,


IPCNUMBER *pnInput);

typedef struct _tagIPCINT

{

int iValue; // default value/entered value

int iMin; // minimal value

int iMax; // maximum value

int iStep; // step value for spin control

}IPCINT;

typedef struct _tagIPCDOUBLE{

double dbValue; // default value/entered value

double dbMin; // minimal value

double dbMax; // maximum value

double dbStep; // step value for spin control

}IPCDOUBLE;

typedef struct _tagIPCNUMBER

{

unsigned int cbSize; // structure size

unsigned int nFlags;

union {IPCINT i;

IPCDOUBLE db.

}value;

}IPCNUMBER;

Function displays input box at FlexView console for numbers. User types number and press oneof two buttons (default buttons are OK and CANCEL).


Parameters:

pQueuePointer to IPCQUEUE structure (obtained by SRVIPCOpen() call)pszConsoleName

String specifies the name of FlexView console for dialog box. Dialog box would be opened atconsole specified by this parameterpszTitle

Dialog titleiID

Unique id for this dialog in range 1 to 65535pszMessage



17/36


pszButtons

Pointer to colon separated string with buttons definitions. If this pointer is NULL the OK andCANCEL buttons would be displayed. $OK:CANCEL is a default value for this parameter.$ sign specifies default button. Up to two buttons can be specified.pnInput

Pointer to the buffer structure for user input. pnInput can contain default value to be displayed.

pnInput->nFlagscan be one or more of the following values.IPCN_INT IPCINT member should be used for user inputIPCN_DOUBLE IPCDOUBLE member should be used for user inputIPCN_SIGNED user can input negative numbersIPCN_LIMITS minimum and maximum values are valid and to be used for user input filteringIPCN_SPIN step member is valid and spin control can be used for user input

Return values:Function returns the number of selected button starting from 1. pnInput receives value

entered by user.

0 if user press EscIf the function fails, the return value is -1.

Example:

// input integer number from -100 to 100 range

#include



if (pIpc != NULL) {

IPCNUMBER ipcNum;

memset(&ipcNum, 0, sizeof(IPCNUMBER));

ipcNum.cbSize = sizeof(IPCNUMBER);

ipcNum.nFlags = IPC_INT | IPC_SIGNED | IPC_LIMITS | IPC_SPIN;

ipcNum.i.iValue = 20;

ipcNum.i.iMin = -100;

ipcNum.i.iMax = 100;

ipcNum.i.iStep = 1;

intiItem = SRVIPCInputNumBox(pIpc, FW1, Enter integer, 103,

$OK:Exit, &ipcNum);

if (iItem < 0) {

// error processing

return;

}

if (iItem == 1) {

int iUserValue = ipcNum.i.iValue;

}

}


18/36


SRVIPCMenu

#include

intSRVIPCMenu(constIPCQUEUE*pQueue,


constchar*pszTitle,

int iID,constchar*menuItems);

Function displays menu at FlexView console. Menu items are defined by stringmenuIntems. This string has following format:

ID1,menu item 1:ID2,menu item 2: :IDn,menu item n

ID1 IDn unsigned integer numbers chosen by programmer (must be > 0)

menu item 1 menu item n are text string which will be displayed in menu.

Menu item which begins with $ symbol would be default menu item. Mouse cursor will bepositioned at default menu item.

Double colon specifies menu separator.

Parameters:pQueue


String specifies the name of FlexView console for menu window. Menu window would beopened at console specified by this parameterpszTitle

Menu window titleiID

Unique id for this menu in range of 1 to 65535.menuItems

The string with menu items definitions. See description above.

Return values:the menu item ID selected by user0 if user refused all choices (closed menu without any menu item choose)If the function fails, the return value is -1.


19/36


Example:

// open menu on FlexView console

#include



if (pIpc != NULL) {

// Set timeout to 5 minutesif (pIpc != NULL)

SRVIPCSetTimeout(pIpc, 300);

intiItem = SRVIPCMenu(pIpc, FW1, PRW 8L SIGNAL, 102,

1,$Depart:2,Hold:3,Route Start::4,Cancel all automatics::5,Exit);

if (iItem < 0) {

// error processing

return;

}

switch(iItem) {

case 0: // Selection not made

case 1: // Depart

case 2: // Hold

case 3: // Route Start

case 4: // Cancel

case 5: // exit

}

}


20/36


SRVIPCCheckList

#include

intSRVIPCCheckList(constIPCQUEUE*pQueue,


constchar*pszTitle,

int iID,constchar*checkItems,


char *pszInputItems,

int iInputSize);

Function displays check box list at FlexView console. User choose list of items then press OK orCANCEL button. If user press OK then this function returns list of items picked by user.

The list of items picked by user has following form:

ID1,text 1:ID2,text 2: :IDn,text n

ID1 IDn unsigned integer numbers chosen by programmer (must be > 0)

text 1 text n are text string which will be displayed for check boxes.

If text field started with $ sign then check box will be displayed in check state.

Parameters:pQueue


String specifies the name of FlexView console for check box window. Check box window wouldbe opened at console specified by this parameterpszTitle

Check box window titleiID

Unique id for this check box in range of 1 to 65535.checkItems

The string with check box items definitions. Has the same form as menuItems string forSRVIPCMenu() function.pszButtons

Colon separated string with buttons definitions. If it is NULL the OK and CANCEL buttonswould be displayed. $OK:CANCEL is a default value for this parameter. $ sign specifiesdefault button. Up to two buttons can be specified.pszInputItems

Pointer to a buffer that receives a series of null-terminated strings, one for each check box IDselected by user, that end with a second null character. The following example shows the buffercontents with representing the terminating null character.

ID1ID3ID4

iInputSize

size of string allocated for pszInputItems


21/36


Return value:

0 no selection were made or user press Esc>0 number of button pressed by user. In this case pszInputItems will contain list of IDs

of check boxes picked by user separated by .If the function fails, the return value is -1.

Example:

// open check box list on a FlexView console

#include



if (pIpc != NULL) {

char szOptions[80];

intiItem = SRVIPCCheckList(pIpc, FW1, Select signals, 105,

1,$Left:2,$Right:3,$Stop, Execute, szOptions, 80);

if (iItem < 0) {

// error processing

return;

}

if (iItem == 1) {

// if user selected Left and Stop then szOptions will contain

// 1\02\0\0

char *pParse = szOptions;

while(*pParse != \0) {

int iID = atoi(pParse); // get ID of check box

pParse += strlen(pParse) + 1; // move to the next ID

}

}

}


22/36


SRVIPCOpenDisplay

#include

intSRVIPCOpenDisplay(constIPCQUEUE*pQueue,


constchar*pszDisplayName);

Function opens display with namepszDisplayNameon consolepszConsoleName.


Parameters:pQueue


Null-terminated string specifies the name of FlexView console where display will be open. Thelist of comma separated console patterns can be used. Simbols * and ? are used as for file

masks in the command line shell. For example: X*, AR*. The display would be opened at allconsoles match with these patterns.pszDisplayName

Null-terminated string specifies the name of display to be opened on FlexView console.

Return value:0 if success-1 if error occured

Example:

#include


if (pIpc != NULL) {

if ( SRVIPCOpenDisplay(pIpc, FW1, DISPLAY1) == -1) {

// error is occurred

}

}


23/36


SRVIPCReplaceDisplay

#include

intSRVIPCReplaceDisplay(constIPCQUEUE*pQueue,


constchar*pszOldDisplay,

constchar*pszNewDisplay);

Function tries to open display withpszNewDisplayname instead of pszOldDisplayon consolepszConsoleName.


Parameters:pQueue


Null-terminated string specifies the name of FlexView console where display will be open. Thelist of comma separated console patterns can be used. Simbols * and ? are used as for filemasks in the command line shell. For example: X*, AR*. The command would be issued at allconsoles match with this pattern.

pszOldDisplay

Null-terminated string specifies the name of display to be closed on FlexView console.pszNewDisplay

Null-terminated string specifies the name of display to be opened on FlexView console.

Remark:

If pszOldDisplay is NULL and pszNewDisplay specifies name of existing display then thisdisplay will be opened. If pszOldDisplay specifies name of existing display and this display isopened then this display will be closed.

Return value:

0 if success-1 if error occured

Example:

#include


if (pIpc != NULL) {

// Open display DISPLAY1

SRVIPCReplaceDisplay(pIpc, NULL, DISPLAY1);

// Replace it with display DISPLAY2

SRVIPCReplaceDisplay(pIpc, DISPLAY1, DISPLAY2);

// Close DISPLAY2

SRVIPCReplaceDisplay(pIpc, DISPLAY2, NULL);

}


24/36


SRVIPCCloseDisplay

#include

intSRVIPCCloseDisplay(constIPCQUEUE*pQueue,


constchar*pszDisplayName);

Function closes display with namepszDisplayNameon consolepszConsoleName.


Parameters:pQueue



masks in the command line shell. For example: X*, AR*. The display would be opened at allconsoles match with these patterns.pszDisplayName

Null-terminated string specifies the name of display to be closed on FlexView console.

Return value:0 if success-1 if error occurred

Example:

#include


if (pIpc != NULL) {

if ( SRVIPCOpenDisplay(pIpc, FW1, DISPLAY1) == -1) {

// error is occurred

}

}


25/36


SRVIPCSendTextMessage

#include

intSRVIPCSendTextMessage(constIPCQUEUE*pQueue,

constchar*pszConsole,

constchar*pszSubject,

constchar*pszMessage);

Function sends a text message to FlexView console. The message can contain two parts:message subject and message body. Message subject is displayed in a separate field at FlexViewconsole.

Parameters:pQueue


String specifies the name of FlexView console where message will be send to. The list of comma

separated console patterns can be used. Simbols * and ? are used as for file masks in thecommand line shell. For example: X*, AR*. The message would be sent to all consoles matchwith this pattern.pszSubject

Null-terminated string with a subject of the message. It will be displayed in the special Subjectfield.pszMessage

Null-terminated string with a message body.

Return value:

0 if success

-1 if error occurred


26/36


27/36


Value Meaning

IPCP_PRINTER Print report on default FlexView printer

IPCP_FILE Save report to a file. Overwrite existing file.

IPCP_APPEND Save report to a file. Create new file, add time stamp to file name.

Return value:0 if success-1 if error occurred

Example:

// Save System Summary for WATER PCU to file with tagstamp.

#include



if (pIpc != NULL) {

// Create file SYS.WATER.YYYYMMDDHHMMSS

SRVIPCPrintReport(pIpc, Operator1, WATER, IPCR_SYSTEM |

IPCP_SYS | IPCP_APPEND);

}

SRVIPCStartApplication

#include

intSRVIPCStartApplication(constIPCQUEUE*pQueue,

constchar*pszConsoleName,constchar*pszApplicationName,

constchar*pszCommandLine);

The SRVIPCStartApplicationfunction starts user application on FlexView console.

Parameters:

pQueue


String specifies the name of FlexView console. The list of comma separated console patterns can

be used. Simbols * and ? are used as for file masks in the command line shell. For example:X*, AR*. The application would be started at all consoles match with this pattern.pszApplicationName

Pointer to a null-terminated string that specifies the module to execute. The specified module canbe a Windows-based application. It can be some other type of module (for example, MS-DOS orOS/2) if the appropriate subsystem is available on the local FlexView computer.The string can specify the full path and file name of the module to execute or it can specify apartial name. In the case of a partial name, the function uses the current drive and currentdirectory to complete the specification. The function will not use the search path. If the file namedoes not contain an extension, .exe is assumed. Therefore, if the file name extension is .com, thisparameter must include the .com extension.


28/36


pszApplicationName can be NULL.In that case, the module name must be the first white space-delimited token in thepszCommandLinestring.

pszCommandLine

Pointer to a null-terminated string that specifies the command line to execute. ThepszCommandLineparameter can be NULL. In that case, the function uses the string pointed to

bypszApplicationNameas the command line.

IfpszApplicationNameis NULL, the first white-space delimited token of the command linespecifies the module name. If you are using a long file name that contains a space, use quotedstrings to indicate where the file name ends and the arguments begin. If the file name does notcontain an extension, .exe is appended. Therefore, if the file name extension is .com, thisparameter must include the .com extension. If the file name ends in a period (.) with noextension, or if the file name contains a path, .exe is not appended. If the file name does notcontain a directory path, the system searches for the executable file in the following sequence:

1. The directory where FlexView is installed.

2. The Windows system directory.3. The Windows directory.4. The directories that are listed in the PATH environment variable.

Return value:

0 if success-1 if error occurred

SRVIPCGetControlInfo

#include

intSRVIPCGetControlInfo(constIPCQUEUE*pQueue,

structIPCCONTROL*pControl,

intflags);

FlexServ stores special record IPCCONTROL for every tag controlled from FlexViewconsole. SRVIPCGetControlInfo() checks and reads IPCCONTROL structure for specified tag toget information about FlexView console

struct IPCCONTROL

{

int iDbType; // tag database type (ANALOG_DB, STATUS_DB, )

int iDbIndex; // tag index

char szConsoleName[34]; // FlexView console name

time_t time; // time when controlled

union {

char status[2]; // from -> to

float analog[2]; // from -> to

long meter[2]; // from -> to

};

char text[2][21]; // description from -> to

};


29/36


By default FlexServ stores 10 IPCCONTROL structures. To change length of buffer use hcommand line parameter for FlexServ.

Note: This function is not supported by RealFlex 6 server.

Parameters:

pQueue

Pointer to IPCQUEUE structure (obtained by SRVIPCOpen() call)pControl

Pointer to output control structure. pControl->iDbType and pControl->iDbIndex should containdatabase type of the database index of tag which would be checked.flags

CTL_PEEK check if control structure for given tag exists in FlexServ buffer. If structure existsfunction reads it but does not remove from buffer.CTL_READ read control info and remove it from server buffer

CTL_READ should be used to avoid following situation:1. FlexView console "A" sends control to status point2. FlexServ stores control in to buffer3. User defined routine reads it from buffer, but does not remove it frombuffer, so it is still available for reading next time.4. Userss routine uses FlexView "A" console name to open message on5. Operator from RealFlex console sends control6. Users routine reads console name from step 2 and sends message toFlexView "A" console, instead of opening message on RealFlex console.

Return value:

0 success. Control information structure found and copied to pControl.-1 control information structure was not found


30/36


Example:

// check if status point was controlled from FlexView console

#include

IPCCONTROL info;

int iPcuIndex, iTagIndex;

// Open IPC with default queue parametersIPCQUEUE *pIpc = SRVIPCOpen(-1, -1, 0);

if (pIpc != NULL) {

// check if status record CONTROL on PCU SYSTEM

// was controlled from FlexView console

iPcuIndex = db_io(PCU_DB, g, 0, SYSTEM, );

iTagIndex = db_io(STATUS_DB, g, iPcuIndex, CONTROL, );

memset(&info, 0, sizeof(info));

info.iDbType = STATUS_DB;

info.iDbIndex = tagindex;

printf("tag SYSTEM:S:CONTROL );

if (SRVIPCGetControlInfo(pQueue, &info, CTL_READ) == 0) {

printf("was changed from console %s from %d to %d at %s",

info.szConsoleName,

info.status[0],

info.status[1],

ctime(&info.time));

}

else {

printf("was not changed from any of FlexView console\n");

}

}


31/36


32/36


SRVIPCStopSound


#include

intSRVIPCStopSound(constIPCQUEUE*pQueue,

constchar*pszConsoleName);

The SRVIPCStopSoundfunction stops the user sound currently playing on FlexView console.

Parameters:

pQueue


String specifies the name of FlexView console. The list of comma separated console patterns canbe used. Simbols * and ? are used as for file masks in the command line shell. For example:X*, AR*. The application would be started at all consoles match with this pattern.

Return value:

0 if success-1 if error occurred

SRVIPCOpenDisplayEx


#include

intSRVIPCOpenDisplay(constIPCQUEUE*pQueue,


constchar*pszDisplayName,

constchar*pszPcuGroup,

constchar*pszPcu,

unsigneduFlags

);

If uFlags== 0 than this function opens display specified bypszDisplaNameparameter. IfuFlags== 1 than this function works with opened display only.

Function activates specifiedpszPcufor givedpszPcuGroup.

Parameters:pQueue


Null-terminated string specifies the name of FlexView console where display will be open. Thelist of comma separated console patterns can be used. Simbols * and ? are used as for filemasks in the command line shell. For example: X*, AR*. The display would be opened at allconsoles match with these patterns.pszDisplayName


33/36


34/36


SRVIPCModal


#include

INTSRVIPCModal(const IPCQUEUE*pQueue,const char*pszConsoleName, bool bModal);

The SRVIPCModalfunction sets modal mode for dialogs displayed on FlexView

Parameters:pQueue



masks in the command line shell. For example: X*, AR*. The display would be opened at allconsoles match with these patterns.bModalIf this flag is specified then all dialogs on FlexView shown by SRVIPCMessageBox,SRVIPCInfoBox and other FlexServ API functions will be displayed in modal mode. Otherwisethe dialogs wll be shown not modal.

Return value:

0 if success-1 if error occured

Example:

#include

IPCQUEUE *pIpc = SRVIPCOpen(-1, -1, 0);

if (pIpc != NULL)

{

SPVIRCModal(pIpc, FW1, true);

int nButton = SRVIPCMessageBox(pIpc, FW1, Warning, 101,

Are you sure?,

IPCBOX_QUESTION , Yes:$No);

SPVIRCModal(pIpc, FW1, FALSE);

}


35/36


FlexView User function API

This API provides access to FlexView functions.

API is installed in APIfolder in Flex.View install path. FlexView API contents:FlexViewAPI.dll

FlexViewAPI.h

FlexViewAPI.lib

ShowDatabaseEditor

Available in FlexView 3.1.56 and higher

#include FlexViewAPI.h

int ShowDatabaseEditor(LPCTSTR szPcuName, LPCTSTR szDbName, LPCTSTR

szTagName, UINT uFlags = 0);

ShowDatabaseEditor() allows to open database editor for specific database tag on local machinerunning FlexView. FlexView should be started before this function call.

Parameters:

szPcuName

PCU Name

szDbName

Database name (analog, status, meter, tank)

szTagName

Tag name

Return Value:

0 successAny other value means error

Example:

#include "stdafx.h"

#include "FlexViewAPI.h"

int _tmain(int argc, _TCHAR* argv[])

{

ShowDatabaseEditor("RTU_1", "analog", "AI_00_01");

return 0;

}


36/36

RealFlex Technologies,526 Kingwood Drive, Suite 310,Kingwood, Texas, 77339, USA

Tel: +1 281 348 2341, Fax: +1 281 348 2340

Email: [email protected]://www.realflex.com/

or

RealFlex Technologies Ltd,Limerick Business Complex,

Raheen Business Park, Limerick, Ireland.Tel: +353 61 308884, Fax +353 61 308883,

Email: [email protected]://www.realflex.com/

user functions api

Documents