PVI base system

The PVI (Process Visualization Interface) base system is the central means to access B&R Automation Net in Windows and Windows CE.

PVI forms a common interface to the world of the B&R industrial PC / Automation PC for all Windows-based software packages.

Each station communicating on the network can exchange and process program objects and data, regardless of the target system, media, and protocol being used.

The PVI base system consists of the following components:

PVI component | Description
PVI Manager | PVI Manager is the central component of PVI. It is responsible for managing all types of process data -- from simple process variables to lists and program/data objects. PVI Manager organizes process data with regard to both timing and direction.
PVI Monitor | PVI Monitor is an auxiliary tool which displays operating states, versions of active PVI components, and PLC operating systems. In addition, PVI Monitor is used to configure PVI Manager and PVI Data Logger properties and to trigger the snapshot function.
PVICOM interface | The PVICOM interface (client interface) establishes access to the PVI at the lowest level. This represents the "tightest" and, regarding performance, the most optimal PVI interface. The PVICOM interface is also used by all other Windows-based components which have PVI access (PVIServices, PVIOPC, PVIDDE, PVI controls, etc.).
PVI lines | The basic task of a PVI line is to connect PVI objects to objects outside of PVI. The line is also responsible for communicating with B&R controllers and determines the communication protocol to be used to do so.

In this section the following topics are discussed:

PVI base system

Overview

Terms

PVI Manager

PVI Monitor

PVICOM interface

PVI lines

Diagnostics

Appendix

FAQ

Start Page

Next Topic >>
Overview


Overview

A considerable part of the effectiveness of a process visualization project is decided by the means by which process data is collected. Since process data in a control system must often be obtained asynchronously over slow serial data lines or other bus systems before being passed on, it is necessary to store the data in a process image.

In PVI, the process image consists of a number of variable objects containing data which is updated either cyclically or at specific time points. Variable objects are special types of process objects. Other process objects are used to handle services such as module downloading/uploading, reading PLC information, or defining the PLC connection, etc.

Process objects are managed in an object structure within PVI Manager. Connecting process objects with external objects (e.g. objects on a PLC) takes place with one or more PVI lines (line servers). They also take over transporting process data to and from the PLC as well as handling PLC services on the protocol level.

The PVICOM interface acts according to the client/server principle. The PVI Manager acts as the server, and the PVICOM applications are the clients. Servers and clients can be on the same machine (local communication type) or on different computers (remote communication type).

Using additional servers, it is also possible to link architectures like DDE (Dynamic Data Exchange), OPC (OLE for process control) or HTML (Web) to PVI. These servers are components of PVI and delivered in the PVI standard package.

The following image gives an overview of the most important PVI components:

<< Previous Topic
PVI base system

Start Page

Next Topic >>
Terms

Start of Chapter


Terms

Term | Description
Connection descriptions | A connection description consists of the connection name and optional connection parameters. This defines the connection between PVI process objects and external objects. External objects can be in a line or outside of PVI.
Connection name | The connection name is part of the connection description and is used as the name for the service object. Depending on the process object type being used, the connection name defines a line, device, station, PLC, or PLC object.
User messages | PVI uses user messages to signal the existence of response or event data in the PVICOM communication instance to the PVI application.
Response data | Response data is received from the application with a PVICOM response. This also includes any error codes and status flags in addition to the actual data.
Request data | Request data is sent from the application with a PVICOM request.
Data format | The data format of the process data in the process object (variable object) or link object.
Data format description | The data format description defines the data format. The description consists of parameters in an ASCII string.
Event types | The event type determines the type of event data.
Event data | Event data is received from the application with a PVICOM event (event or global event). This also includes any error codes and status flags in addition to the actual data.
Communication type | The communication type defines the type of the connection between the PVICOM application and PVI Manager.
Communication instances | The communication between a PVICOM application and PVI Manager is handled via a communication instance.
Line | A PVI line establishes the connection between a subset of process objects and the environment outside of PVI. Depending on the line being used, this "outside world" can consist of PLC objects (INA2000 line) or PC objects (ADI line). A line is also called a line server.
Object attributes | Object attributes control how process data is acquired and handled for a process object (variable object).
Object descriptions | The object description defines the properties of a link object (link object description) or a process object (process object description). The object description also contains properties such as connection description, object attributes and data format. The description consists of parameters in an ASCII string.
Object name | The object name is the name of a process object in PVI Manager.
Object path | The object path consists of one or more object names and determines the position of a process object within the object structure.
Object structure | The process object tree created in PVI Manager is called the object structure.
Process image | The process image is depicted using process objects and represents all the process data necessary to regulate a visualization process.
Process object | Process objects represent the process image in PVI Manager.
Process object state | The process object state describes the actual condition of a process object. The process object can take on undefined, ready, or error states as well as active or idle states.
PVICOM interface | The PVICOM interface represents the access way for the application to PVI Manager.
Refresh time | The refresh time determines how frequently the process data of external variable objects is updated.
Service objects | A service object assigns an external object to a process object. External object can be in the PVI line or outside of PVI (e.g. PLC objects).
Type casting | Type casting transforms the process data from the data format of the process object into the data format of the link object and vice versa.
Link object | A link object establishes a connection from the application to a PVI Manager process object.
Access types | The access type determines the type of read or write request. In this way, object data, object states, different object properties, and various services can be selected.

<< Previous Topic
Overview

Start Page

Next Topic >>
PVI Manager


PVI Manager

PVI Manager (PviMan.exe) is the central component of PVI.

It is responsible for managing all types of process data -- from simple process variables to lists and program/data objects. PVI Manager organizes process data with regard to both timing and direction. That means PVI Manager uses the specifications from the application to determine which data is transferred via which device and medium from or to a certain station.

Special attention has been given to asynchronous task handling in order to e.g. be able to use network delays for other tasks or to fit in coordinated event processing between different tasks.

In Windows (not Windows 9x), PVI Manager can either be operated as a process or as a system service, and under Windows CE the PVI Manager is always started as a process. See also the chapter "Start program".

The operating mode of PVI Manager can be configured with the "Change registry for PVI Manager" function in PVI Monitor.

There is basically no difference when running PVI Manager as a service or a process. The service can be started and ended, just like process. In addition, as a service, the program is shown in the list of local services and can be operated using Windows service functions.

The substantial advantage of service operation, however, is that PVI Manager is not ended automatically by Windows after the user logs off.

If PVI Manager is started as a process (or as a service under Windows NT/2000/XP), then a corresponding icon appears in the system tray in the Start bar. It can be turned off in the PVI Manager properties.

Double-clicking on the PVI Manager icon starts PVI Monitor. It can also be started using the PVI Manager shortcut menu (right mouse button). The shortcut menu also contains a function for exiting PVI Manager. The start function always starts the PVI Monitor that is located in the same directory as the PVI Manager.

The limitations that apply for 64-bit applications are described in the chapter "User messages".

64-bit applications can communicate with both 64-bit and 32-bit versions of PVI Manager. The same applies for all 32-bit applications.

In this section the following topics are discussed:

PVI Manager

Start program

Commands and options

<< Previous Topic
Terms

Start Page

Next Topic >>
Start program


Starting the PVI Manager

Start program

PVI Manager must be started to use PVI (PVICOM interface).

The manager is automatically started when using the local communication type (PVICOM function PviInitialize or PviXInitialize). The manager has to be started by the user when using the remote communication type.

When started, the PVICOM interface searches for PVI Manager in the following order:

  1. The PVI Manager in the directory of the PVICOM library (PviCom.dll or PviCom64.dll) being used by the application is started.
  2. The PVI Manager in the application's directory is started (or more exactly, in the directory of the module assigned to the system process).
  3. The registered PVI Manager is started (Changing the registry for PVI Manager).
  4. The PVI Manager in the application's current working directory is started.
  5. PVI Manager instances in the directories specified with the PATH environment variables are searched for.

PVI Setup installs PVI Manager and the PVICOM library, as well as the other PVI components in a separate PVI directory. The PVICOM library is also stored in the Windows\System (or System32) directory. The registered PVI Manager (item 3) is always started for applications outside the PVI directory. Applications in the PVI directory (e.g. PVI Monitor) always start the local PVI Manager (item 2) regardless of the PVI Manager registry entries.

Only one instance of PVI manager can be active at a time. If a second instance (service or process) is started, it is ended immediately.

If PVI Manager is registered as a system service (see chapter "Changing the registry for PVI Manager"), and if the startup type is set to "Manual", then the started PVI Manager process automatically activates the corresponding service and then closes again. Then the PVI Manager service takes over the rest of PVI communication. This automatic activation only occurs if the started PVI Manager is also the registered PVI Manager. If multiple PVI versions are installed, only one can function as a service.

If the PVI Manager service should be started at startup, then the startup type should be set to "Automatic". The startup type can be modified in the Windows Service manager. Keep in mind, however, that any changes to the registry for the PVI Manager (see "Changing the registry for PVI Manager") returns the startup type to "Manual".

<< Previous Topic
PVI Manager

Start Page

Next Topic >>
Commands and options


Starting the PVI Manager

Commands and options

When the PVI Manager is started, commands or options can be sent as program arguments.

When one or more commands are entered, the PVI Manager is started as a process, the functions are executed, and then it is ended. On the other hand, the options only affect the operation of the PVI Manager.

The following commands can be entered:

Command | Function
/SvReg (or /Install, /Register) | The PVI Manager is registered as a system service in Windows NT/2000/XP/Vista.
/SvUnreg (or /Deinstall, /Unregister) | The registration as system service is deleted (if found).
/FwReg | The PVI Manager is registered with the Windows Firewall in Windows XP/Vista.
/FwUnreg | The registration with the Windows Firewall is deleted (if found).
/Quiet | Errors that have occurred are not displayed in a message box.

If an error occurs while executing a command, it is displayed in a message box. By entering "/Quiet" you can suppress the message box. Either way, the error is reported as exit code, and can, for example, be evaluated using batch processing.

The following options can be entered:

Option | Function
/NoNtService | Independent of its registration as system service, the PVI Manager is operated as a process. Provided that the PVI Manager system service has not been started.
/NoExptFlt | Exception handling in the PVI Manager is not enabled. Exceptions are displayed by the operating system as standard messages.
/NoDispErr | The message box for reporting global PVI errors is disabled. Since global PVI errors also include exceptions, this option also affects exception handling. Error information (exception information) is written to the PVI logger files independent of the setting for how they are displayed.
/NoCheckBuR | The B&R PC check is disabled (standard PC behavior).
/NoCheckKey | The PVI dongle check is disabled (behavior like without dongle).

All options can also be entered in the PVI configuration file (PviConfig.xml). A value not equal to 0 (null) corresponds to an option entered as a program argument.

Default setting in the PVI configuration file:

<PviMan NoDispErr="0" NoCheckBuR="0" NoCheckKey="0" />

<< Previous Topic
Start program

Start Page

Next Topic >>
PVI Monitor


PVI Monitor

The PVI Monitor (PviMon.exe) aids the display of operating information and is used to configure diagnostics functions and global properties for the PVI Manager.

PVI Monitor is started by double-clicking on the PVI Manager icon in the system tray or using the "PVI Monitor" entry in the Start menu.

The PVI Monitor status window is displayed once the program is started.

The following information is output in the status window:

  • Name of the current PVI version
  • Name of the registered PVI version (only if the registered and current version are different).
  • Security mode (operating status) of PVI Manager:
Undefined | The operational status has not been captured yet by PVI Manager.
Runtime | PVI license available for PVI Manager.
Trial | No license availability - The PVI Manager runs for 2 hours after the start.
Locked | No license enabled - the 2 hour "trial" mode has expired
  • Operating mode of the PVI Manager (service or process, 32 or 64-bit Version, administrator rights).
  • The assigned port number if TCP/IP communication is enabled on PVI Manager
  • Time elapsed since PVI Manager was started
  • The number of link objects created in PVI Manager
  • The number of process objects created in PVI Manager, number of active process objects, and number of process objects with errors
  • The number of service objects present in PVI Manager, number of active service objects, and number of service objects with errors
  • The number of currently active data objects (request and response objects)
  • The number of PVICOM communication instances (clients) registered with PVI Manager
  • Counter for received request data (requests)
  • Counter for sent response data (responses)
  • Counter for sent event data (events)

PVI Monitor cyclically generates requests for information from PVI Manager. Since this affects the status counter display, PVI Monitor tracks its own calls and subtracts them from the status counters. Closing the PVI Monitor and then restarting it immediately may therefore cause the status counters to increase erratically. The cyclic PVI Monitor information requests can be turned on and off with the "Options -> Stop Cyclic Refresh" menu item.

The PVI version shown in the PVI Monitor status window always refers to the local computer. This is also true for the Remote communication type in PVI Monitor.

In this section the following topics are discussed:

PVI Monitor

Operation and functions

Communication type

Changing the registry for PVI Manager

PVI Manager properties

Setting up the data logger

Execute snapshot function

Snapshot Viewer

<< Previous Topic
Commands and options

Start Page

Next Topic >>
Operation and functions


Operation and functions

In the PVI monitor, the following functions are available, which can be located using the respective menus or shortcuts:

Menu | Key | Function
File -> Connect | Ctrl+O | Establishes the communication connection to PVI Manager (only in Remote communication mode).
File -> Disconnect | Ctrl+S | Removes the communication connection to PVI Manager (only in Remote communication mode).
File -> Start manager | Ctrl+Alt+O | Starts PVI Manager (only in Local communication mode). The start function always starts the PVI Manager that is located in the same directory as the PVI Monitor.
File -> Stop manager | Ctrl+Alt+S | Ends PVI Manager (only in Local communication mode).
Options -> Manager properties | Alt+F7 | Configures PVI Manager properties.
Options -> PVI diagnostics | Alt+F8 | Configures the PVI Data Logger for generating PVI log files. Triggers the Snapshot function for generating a PVI snapshot file.
Options -> PVI snapshot viewer | Alt+F9 | Snapshot viewer for displaying PVI snapshot files.
Options -> PVI registry changer |  | Changes the registry for PVI Manager (version switching). Configures the service and process mode for PVI Manager.
Options -> Topmost |  | Determines whether PVI Monitor should also be in the foreground on the screen.
Options -> Show toolbar |  | Shows/Hides the toolbar.
Options -> Stop cyclic refresh | Ctrl+F5 | Turns the PVI Manager cyclic information request on/off.
Help -> Documentation | F1 | Opens the PVI base documentation (only if installed).
Help -> Component versions |  | Displays the versions of all currently active PVI Manager PVI components.
Help -> PCC System Versions |  | Shows the operating system versions of all PLCs currently connected to PVI Manager.

<< Previous Topic
PVI Monitor

Start Page

Next Topic >>
Communication type


Communication type

Communication with PVI Manger can be done either locally (Monitor and Manager running on the same computer) or remotely (Monitor and Manager not running on the same computer).

The type of communication used is determined by the "/Remote" program argument when PVI Monitor is started and can no longer be changed at runtime.

The PVI entry in the Start Menu provides both types of communication (menu entries "PVI Monitor" and "PVI Monitor (Remote)"). The remote connection is not supported in the Windows CE version of PVI Monitors. However, a remote connection can be made to the Windows CE version of PVI Manager under Win32.

> PviMon /Remote

When using the remote communication type, PVI Monitor is connected to PVI Manager over TCP/IP. The "File -> Connect" menu item in PVI Monitor opens up the dialog box for configuring TCP/IP connection parameters.

The IP address or host name (e.g. "SystemPC1") of the server needs to be specified in the "IP Address" input field. The "Number of Port" input field needs to contain the port number assigned to PVI Manager (Setting PVI Manager Properties).

<< Previous Topic
Operation and functions

Start Page

Next Topic >>
Changing the registry for PVI Manager


Changing the registry for PVI Manager

The dialog box for changing the PVI Manager registration is done by running Options -> PVI Registry Changer in PVI Monitor.

PVI Manager registry entries can only be modified for the local computer. This function is not available with the Remote communication type in PVI Monitor or in Windows CE.

Selecting the "OK" button closes the currently active PVI Manager. The user must have administrator rights to change registry entries for PVI Manager.

Function | Description
PVI version | The setup version (product version) of the selected PVI Manager instance is displayed in the "PVI version" field.
PVI Manager | The input field is preset with the path of the registered PVI Manager. To switch the PVI version, a PVI Manager instance from another PVI version can be selected by entering the information manually or using the browse function.
Use PVI manager as a system service | This switch configures the operating mode of PVI Manager. If this switch is activated, the registered PVI Manager runs as a system service. If inactive, the registered PVI Manager runs as a process.
The internal process for the function is described in "Appendix C - Registration".

<< Previous Topic
Communication type

Start Page

Next Topic >>
PVI Manager properties


PVI Manager properties

The dialog box for setting PVI Manager properties is done by running Options -> Manager Properties in PVI Monitor.

For the Windows CE version, click on the "Properties" button in PVI Monitor. Regardless of the PVI Monitor communication type being used (remote or local), the PVI Manager properties are always configured on the PVI Manager system. This basically means the remote system when using the remote communication type.

The settings can only be changed if the user has administrator rights, if the PVI monitor is started with administrator rights, or if the PVI manager is started as a service with administrator rights. Otherwise system error 5 (Access is denied) or PVI error 12106 appears.

Dialog box for configuring PVI Manager properties:

Function | Win CE support | Description
Use TCP/IP Communication Yes If this field is selected, them PVI Manager is started as a TCP/IP server (remote communication type).

A unique port number has to be assigned in the "Number of Port" field. Any value between 1024 and 65535 can be defined as a port number. The default setting for PVI is 20000.

The port number has to be unique within the local computer, i.e. no other TCP/IP server on the computer may use the same port number.

If TCP/IP communication is not needed, then this field should not be enabled. Otherwise, unnecessary resources are expended.

Display trial mode messages No If this field is enabled, then PVI Manager displays warning messages on the screen if a valid security key has not been found and the "trial time" (2 hours) has expired.

The current operating status can be viewed in the PVI Monitor status window.
Display symbol on system tray | Yes | If this function is enabled, then PVI Manager is displayed as an icon in the system tray on the taskbar. PVI Manager can be closed or PVI Monitor can be opened using the icon's shortcut menu (right mouse click).
Stop the PVI manager automatically Yes If this field is enabled, then PVI Manager exits automatically as soon as the last PVICOM communication instance (client) is deregistered.

However, there can be no static process objects which were created earlier still available (except for the PVI base object).

This function cannot be used together with TCP/IP network communication (remote communication type).

This function is basically intended as help when developing or testing PVI applications.
Execution Priority No Setting the process priority of the PVI Manager.
  • Default (priority is inherited)
  • Normal (normal priority)
  • Idle (low priority)
  • High (high priority)
  • RealTime (highest priority)

The PVI Manager sets its process priority to the value specified here after every restart. Except for the "Default" setting, which doesn't change the process priority. As a result, when the PVI Manager is started by a PVI application (e.g. the function PviInitialize or PviXInitialize), the process priority of the PVI application is inherited by the PVI Manager.

The settings in the PVI Manager properties are saved in the Windows Registry. The corresponding keys are found in "Appendix C - Registration".

The default values are defined in the PVI configuration file (PviConfig.xml):

<Pvi>
  ...
  <PviBase>
    ...
    <PviMan ...
      ManDispTrial="1" ManSysTray="0" ManAutoExit="0" ManPriority="normal" />
    ...
  <PviBase/>
  ...
</Pvi>

Clicking the "Default" button in the dialog box applies the default values. These values are also shown by default when reading the Windows Registry.

<< Previous Topic
Changing the registry for PVI Manager

Start Page

Next Topic >>
Setting up the data logger


Data logger for PVI components

Setting up the data logger

The data logger only be turned on/off globally with the Windows CE version of PVI Monitor. However, a Data Logger included with a standard version of PVI Monitor can be set for Windows CE over a remote connection.

The dialog box for configuring the data logger is opened using the PVI Monitor menu Options -> PVI Diagnostics.

The settings can only be changed if the user has administrator rights, if the PVI monitor is started with administrator rights, or if the PVI manager is started as a service with administrator rights. Otherwise system error 5 (Access is denied) or PVI error 12106 appears.

Global settings

Main dialog box for defining global logger properties and managing the components list:

The "Details" button can be used to show or hide the list of components.

To enable the Data Logger for a certain PVI component, the respective entry must first be created in the component list.

The names of all components set up are displayed when the dialog box is expanded. To set up a new component, double-click on the first available line or mark any line and press "Insert" on the keyboard. This opens a second dialog for defining the component and setting its logger properties. To modify the logger properties of a component which has already been set up, double-click on the respective entry in the component list.

To delete a component from the list, first select it and then press the "Delete" key on the keyboard. All of these functions can also be executed via the component list's shortcut menu (right mouse click).

Any changes made to logger settings in this dialog box only take effect after "Apply" is clicked. From that point on, any settings made become effective. Restarting the components is not necessary.

The settings made for logging mode and verbose in the main dialog box limit all component settings. In global logging mode, the "Off" setting disables the data logger for all components.

When the PVI data logger is enabled, the PVI monitor's cyclic information requirements from the PVI manager are automatically turned off ("Stop Cyclic Refresh" function).

Component settings

Component dialog box for defining components and setting logger properties:

Defining components

The name of the desired PVI component is defined in the "Component" input field. This name consists of a maximum of three segments. Each of these segments is separated using a forward-slash ('/') character. Component names are not case sensitive.

<Program>[/<Module>][/<Section>]

Section | Description
<Program> | File name for the program where the component is being used in a process context. This program name needs to be specified completely.
<Module> | If the desired component is a module (e.g. DLL), then the complete module file name needs to be specified here. If the desired component is a program, then this segment does not need to be specified.
<Section> | Some PVI components divide logger output into several sections. The desired section is selected by specifying a section name.

An overview of the most important PVI components with logger output has been put together in the PVI Components with Logger Output section.

Setting the logging mode and verbose

Setting the logging mode is crucial for logger output.

Logging mode | Description
"Off" | Logger output is turned off
"Log Errors" | Logger output at Level 1 (PVILOG_ERROR): Only errors are logged.
"Log Mains" | Logger output at Level 2 (PVILOG_MAIN): Errors as well as sequences at the interfaces (from externally controlled program flow) are logged.
"Log Details" | Logger output at Level 3 (PVILOG_DETAIL): In addition to "Log Mains", internal function processes are output (internal program flow).

The logging mode can be defined for each component in the "Mode" selection box. This selection is also displayed in the "Mode" column in the main dialog box's component list. In addition, the logging mode can be set in the "Global Mode" field in the main dialog box. This setting works globally and limits the logging mode of all components. If "Global Mode" is switched "Off", then logger output is turned off for all components. If "Global Mode" is set to "Log Details", then logger information is output according to the logging mode of the individual components.

Additional logger output is enabled by switching on Verbose mode. Some PVI components carry out a hexdump output of data in Verbose mode. Verbose mode can be set in the component's dialog box with the "Verbose" check box. If Verbose mode is selected for a component, then a plus character "+" will appear in the "Mode" column in the component list in the main dialog box. Like the logging mode, Verbose mode can be switched on for all components with the "Global Verbose" checkbox in the main dialog box.

The maximum amount of log information is output using the "Log Details" setting for the logging mode along with Verbose mode. Note, however, that logger output consumes a relatively large amount of computing time. In practice, all logger information is not usually necessary. In addition, changes in timing should be kept to a minimum as much as possible. Setting the logging mode and Verbose mode should therefore always be adapted to the problem at hand.

Set timestamp

Each logger entry begins with one or several ">" characters as well as a timestamp. The format of this timestamp can be set.

Format | Description
"No" | Instead of a timestamp, values in increasing order are output.
"Time" | Outputs the current time
"Time+Date" | Outputs the current data and time

The format of the timestamp can be defined for each component in the "Timestamp" field. The timestamp format can also be set in the "Global Timestamp" field in the main dialog box. This setting takes effect globally and limits the timestamp format for all components. The default setting for the format is "Time". If logging should take place over a period of several days, then the "Time+Date" setting may be more appropriate.

Setting the logger file

Logger information is written as text (ASCII) to the logger file. The path name of this logger file is defined in the "File Name" field. Note that all directories specified in the path name have to already exist when logger output starts. Path specifications always refer to the component itself. If the component and PVI Monitor are not on the same computer (remote connection), this needs to be taken into consideration. Each component is assigned a separate file. Writing to one logger file with several components is not possible.

The Data Logger handles the file like a ring buffer. The size of the ring buffer corresponds to the file size defined in the "File Size" field. The file size is specified in KB. The default value for the file size if 1024 KB (1 MB). If a larger time frame is needed, then this file size needs to be increased accordingly.

Backup logger files

If a PVI component is started while the Data Logger is enabled (e.g. program) or initialized (e.g. DLL), then a logger file with the defined name is automatically created. If a file already exists with the same name, then it deleted beforehand. By specifying a value greater than 0 (zero) in the "Backup Level" field in the component's dialog box, this can be prevented. This value defines the maximum number of levels for backup files (maximum 20). To prevent an existing logger file from being overwritten, the old logger file is renamed as a backup file each time it is opened. This new file name is also listed with a number. If the maximum number of backup file levels is reached, then the oldest file is erased (date of the last write access).

Setting the output parameters

The "Dump Length" input field defines the maximum length of hex dump output in bytes. Hex dumps are normally used to output log data or interface data. Any value between 64 and 1048576 can be defined as the maximum length. Large hex dump outputs can be very time-intensive and have a negative effect on the timing behavior of PVI components The logger file also gets filled up quickly and must be expanded accordingly. On the other hand, setting the maximum length to low could result in important information being lost. The default value for the maximum dump length is 65536 bytes. Normally, values between 256 and 16384 are sufficient for PVI components. It is not possible to turn off hex dump output using this parameter.

The "Line Length" input field defines the maximum length of a text line in characters. Basically, each logger entry begins on a new line. However, if the maximum line length is reached when writing, then output continues on a new line. The maximum line length is not meant to limit logger information; instead, it serves for better logger file readability. The default value for the maximum line length is 512 characters.

Break function

In the logger file, old entries are always overwritten by newer entries (ring buffer). If a certain piece of information (e.g. error situation or a program's initialization phase) should remain in the file, then the logger output needs to stopped in time. This can be done manually by ending the program or setting the logging mode to "Off". This can also be done automatically using the break function.

The break function works on the text level. With the break function, conditions for breaking off the logging can be defined using one or more text expressions. These text expressions may not contain blank characters. Individual text expressions are linked together using the logical operators "&" (AND), "|" (OR), and "!" (NOT). At least one space needs to be entered between the text expression and the operator. If an operator is not defined between two text expressions, then the "&" (AND) operator is used. A maximum of 32 text expressions can be specified for the break function. Hexdump output cannot be monitored with the break function.

Each individual text expression in the break function is compared with the text positions in the logger entry. If at least one expression matches, then the result becomes 1 (TRUE). Otherwise, the result is 0 (FALSE). Case is not taken into account when comparing text expressions (not case-sensitive). Then all section results are linked with the specified operators. The following is the order in which the operations are carried out: NOT, AND, OR. If the entire result is 1 (TRUE), then the break condition is met.

The "Use Break Function" check box has to be selected to enable the break function in addition to a break expression in the "Expression" field. A certain time can optionally be defined between the break detection (break condition is met) and carrying out the break (stopping logger output). This break time is specified in the "Break Time" field in milliseconds.

What happens when the break occurs can be selected in the component's dialog box:

Selection | Description
"Break component logging" | Logger output is only stopped for this component. If the component is restarted (e.g. program) or reinitialized (e.g. DLL), then logger output is reactivated.
"Turn-off global logging mode" | Logger output is stopped for all components. This automatically switches the global logging mode to "Off". To turn logger output back on again, the logging mode has to be set to the desired level in the main dialog box and "Apply" needs to be clicked.

Examples of break expressions:

Comm.WriteRequ & Ty=11 | Comm.ReadRequ & Ty=11

This break condition is met if the "Ty=11" text expression is output in a logger entry with either "Comm.WriteRequ" or "Comm.ReadRequ".

E=4808 & ! Comm.Event

This break condition is met if the "E=4808" text expression is output in a logger entry without the "Comm.Event" text expression.

Standard procedure

Standard procedure for switching on the Data Logger:

  1. Select the PVI Monitor menu "Options -> PVI Diagnostics" to open the main dialog box
  2. Set the "Global Mode" to "Log Details"
  3. Enable the "Global Verbose" checkbox and set the "Global Timestamp" to "Time+Date"
  4. Click on "Details" to enlarge the dialog box
  5. Create and define all necessary components if they are not already in the component list
  6. Remove any unnecessary components from the component list or change their "Mode" to "Off" in the component dialog box
  7. Make desired logger settings in the component dialog box for all required components
  8. Click on "Apply"
  9. Click on "Exit" to exit from the main dialog box

Standard procedure for switching off the Data Logger:

  1. Select the PVI Monitor menu "Options -> PVI Diagnostics" to open the main dialog box
  2. Set the "Global Mode" to "Off"
  3. Click on "Apply"
  4. Click on "Exit" to exit from the main dialog box

<< Previous Topic
PVI Manager properties

Start Page

Next Topic >>
Execute snapshot function


Snapshot Function

Execute snapshot function

The Snapshot function cannot be used with the Windows CE version of PVI Monitor. However, a standard version of PVI Monitor is able to use the PVI Manager Snapshot function on Windows CE computers over a remote connection.

The dialog box for triggering the PVI Snapshot function is opened using the PVI Monitor menu Options -> PVI Diagnostics.

Clicking on the "Snapshot" button triggers a snapshot function. The Snapshot information is written to the file specified in the "Path" input field. The path specification for the Snapshot file refers to PVI Manager. If PVI Manager and PVI Monitor are not on the same computer (remote communication type), this needs to be taken into consideration.

<< Previous Topic
Setting up the data logger

Start Page

Next Topic >>
Snapshot Viewer


Snapshot Function

Snapshot Viewer

The Snapshot Viewer display the object information of a snapshot file in a structured tree view and in two lists. However, it is also possible to generate and display a temporary snapshot file.

It can be opened using the PVI Snapshot Viewer menu item in PVI Monitor.

The tree view shows the registered communication instances as well as the object structure for process objects and service objects. Selecting an entry in the tree view shows all of the sub-level objects in the main list view (upper list). The extended list view (lower list) is enabled when an entry in the main list is selected and shows all of the objects assigned.

In addition to the object name, the list view also displays the object ID, object status, and the object description for the PVI object. The object type is indicated by its icon.

Operation and functions

Menu | Key | Function
File -> Open Snapshot File | Ctrl+O | Opens and displays a snapshot file.
File -> Make Topical Snapshot | F5 | Triggers a temporary snapshot to PVI Manager and displays it is the Snapshot Viewer (only with the local communication type).
File -> Close Snapshot |  | Closes the snapshot.
View -> Global Information | Ctrl+F10 | Displays global snapshot information like the timestamp for the snapshot function, current PVI settings, and the version of PVI and the operating system platform.
View -> Object Details | F10 | Displays complete information about an object.
View -> Up One Level |  | Selects the next highest level of the object structure.
Options -> Filter Objects | Ctrl+E | Opens the dialog box for object filters.
Options -> Search Objects | Ctrl+F | Opens the dialog box for object searching.
Options -> Search Next Object | F3 | Finds the next object (according to the search criteria in the Search Object dialog box).
Options -> Show toolbar |  | Shows/Hides the toolbar.
Options -> Show Extended List |  | Shows/Hides the extended list.
Options -> Adapt Column Width |  | Turns the automatic configuration of the column width in the list view on/off.
Options -> Display Colored Objects |  | Turns the colored object display for highlighting the object status on/off.
Help -> Documentation | F1 | Opens the PVI base documentation (only if installed).

Object status

The object status is output in the "State" column in the list view and shows the status of the PVI objects at the point the snapshot is taken.

Status indicators | Meaning
Act | Link, process, or service object is active.
Idl | Link, process, or service object is in an inactive state (idle).
NotRdy | Link, process, or service object is in an undefined state.
Rdy | Link, process, or service object is in a ready state.
Err | Link, process, or service object is in an error state.
External | External process object.
Internal | Internal process object.
Temp | Process object set up as a temporary process object.
Static | Process object set up as a static process object.
Local | Communication instance with a local communication type.
Remote | Communication instance with a remote communication type.

Displaying the object status can be highlighted using a colored object display (Options -> Display Colored Objects):

Color | Object status
Green | Object is active.
Blue | Object is inactive.
Red | Object is active and in an error state.
Magenta | Object is inactive and in an error state.

Object descriptions

The object description is output in the "Description" column and shows (depending on the object type) the current object description at the point the snapshot was taken. Communication instances show the parameters specified when calling the PviInitialize or PviXInitialize function (TC - communication timeout in seconds, TR - retry time for PVICOM user messages in seconds).

Object filter

The object filter is used to suppress the display of individual objects. The dialog box for filtering object is opened using the Options -> Filter Objects menu item. This window allows objects to be displayed or not displayed, depending on the object status.

If every field in the dialog box is selected, then all objects are displayed ("Show All Objects" button). This is also the default after the Snapshot Viewer is run. The settings made in the image above would only display active objects. Higher-level and inactive objects will be grayed out in the list view.

Search Objects

The object search can be used to find object names or a certain entry in object descriptions. The dialog box for searching for objects is opened with the Options -> Search Objects menu item.

Pressing the "Search" button starts the search process. Searching always begins at the start of the object list, regardless of which object is selected in the tree or list view. If an object is found, it is displayed and highlighted in the main list view. If you want to continue the search, you can either reopen the search dialog box and click on the "Search Next" button or open the Options -> Search Next Object menu item.

Running the Snapshot Viewer without a PVI connection

If the program argument "/Snapshot" or the name of snapshot file (must have ".snp" or ".pvisnp" extension) is specified when PVI Monitor is started, then only the Snapshot Viewer is opened. The snapshot file provided is read and displayed immediately.

> c:\BrAutomation\Bin\PviMon /Snapshot
> c:\BrAutomation\Bin\PviMon "c:\BrAutomation\Log\Facility.pvisnp"

In this mode, a connection to PVI Manager is not established. The Snapshot Viewer can therefore be used as a stand-alone tool, independent of PVI Manager, for displaying snapshot files.

<< Previous Topic
Execute snapshot function

Start Page

Next Topic >>
PVICOM interface


PVICOM interface

The PVICOM interface (client interface) establishes access to the PVI at the lowest level.

This represents the "tightest" and, regarding performance, the most optimal PVI interface. The PVICOM interface is also used by all other Windows-based components which have PVI access (PVI OPC, PVI DDE, PVI services, etc.).

Communication via the PVICOM interface is handled with the functions in the PVI communication library, "PviCom.dll" (32-bit version) or "PviCom64.dll" (64-bit version). The PVI communication library is a DLL (Dynamic Link Library) based on the Windows standard. If applications use functions of a DLL, then the DLL has to be loaded explicitly with functions being declared, or the static library "PviCom.lib" or "PviCom64.dll" has to be bundled to the program (loaded implicitly). The procedure can be found in the respective programming manual.

The limitations for the 64-bit version of the PVICOM interface are described in the chapter "User messages".

The following development environments are supported:

  • Visual C++ (Version 6.0 and up)
  • Visual Basic (Version 6.0 and up)
  • Borland C++ Builder (Version 3 and up)
  • Borland Delphi (Version 4 and up)

Files in the PVICOM interface:

PviCom.dll | PVI communication library for 32-bit applications.
PviCom.lib | Static library for Visual C/C++ for 32-bit applications.
PviCom64.dll | PVI communication library for 64-bit applications.
PviCom64.lib | Static library for Visual C/C++ for 64-bit applications.
PviCom.h | Definition file (include file) for Visual C/C++ (32-bit and 64-bit).
PviCom.bas | Definition file (include file) for Visual Basic (32-bit).
PviCom.pas | Definition file (include file) for DELPHI (32-bit).

The PVICOM definition file contains definitions and/or declaration for all PVICOM interface functions, types, structures used, and PVI constants.

If the file "PviCom.h" is linked in a 64-bit application, the symbol "_WIN64" must be defined.

"Tools" has to be selected in PVI Setup to install the necessary files.

In this section the following topics are discussed:

PVICOM interface

Client/Server communication

Objects

User messages

Requests and responses

Event

Process data

PVICOM functions

PVICOM structures

<< Previous Topic
Snapshot Viewer

Start Page

Next Topic >>
Client/Server communication


Client/Server communication

This section deals with the communication between a PVICOM application and the PVI Manager. The communication between PVI and the PLC is described in the PVI Lines section.

The PVICOM interface acts according to the client/server principle. The PVI Manager acts as the server, and the PVICOM applications are the clients. Servers and clients can be on the same machine (local) or on different computers (remote). When local communication is used, data is exchanged using a shared memory area. Remote communication exchanges data over a TCP/IP network. The communication type determines the type of client/server connection. Each PVICOM client/server connection is handled using one communication instance.

The PVICOM interface allows an application to set up several communication instances. In this way, an application can exchange data with several PVI Managers at the same time. Theoretically, up to 65,534 communication instances can be registered on one PVI Manager.

In this section the following topics are discussed:

Client/Server communication

Communication instance

Communication type

Global events

<< Previous Topic
PVICOM interface

Start Page

Next Topic >>
Communication instance


Client/Server communication

Communication instances

To set up a PVICOM communication instance, an application must first call the PVICOM function PviInitialize or PviXInitialize.

This will also determine the communication type (local or remote) and the timeout for the life sign monitoring (communication timeout). Setting up also initiates the communication instance (client) registration for the PVI Manager (server).

If a communication instance is set up, PVICOM functions can send requests to the PVI Manager in addition to the definition of a user message. After the PVI Manager sends back an appropriate response, the user message defined with the request is carried out (Request and Respond). Using this method, the application is able to set up PVI link and process objects, access dates, conditions, or properties, and free up PVI objects. When setting up a link object, a user message can also be defined to signal events.

If a PVICOM communication instance is no longer needed, then it has to be freed up with either the PviDeinitialize or PviXDeinitialize PVICOM function. This also de-registers the communication instance (client) for the PVI Manager (server).

Each PVI link object created is assigned to a certain communication instance (client). If a communication instance is de-registered from the PVI Manager, then all assigned link objects as well as temporary process objects are automatically freed up.

Each PVICOM communication connection has life sign monitoring. This checks the function of the connection by way of cyclic data exchange. If communication cannot take place within the defined communication timeout (e.g. network connection is interrupted), then the PVI Manager automatically de-registers the communication instance. The same thing happens when the PVI Manager is ended. However, the communication instance continues to exist on the side of the application (client). It keeps trying (cyclically) to register with the PVI Manager (server). If the registration is successful (e.g. network connection could be reestablished or PVI Manager is restarted), then client/server communication can begin again immediately. It is important to note, however, that all link objects which were assigned, as well as all temporary process objects in the PVI Manager, were released when the communication instance was de-registered. These objects therefore have to be set up again by the PVICOM application after the communication connection is reestablished. The PVICOM interface uses global events (see also the PviSetGlobEventMsg or PviXSetGlobEventMsg function) to signal the application as to the state of the communication connection.

<< Previous Topic
Client/Server communication

Start Page

Next Topic >>
Communication type


Client/Server communication

Communication type

The communication type defines the type of connection between a PVICOM application communication instance (client) and the PVI Manager (server). This communication type only refers to PVICOM client/server communication and has nothing to do with the data being exchanged between the PVI Manager and a controller (PLC).

The following communication types can be used:

Local | The PVI Manager and the PVICOM application are located on the same computer. Data is exchanged using a shared memory area.
Remote | The PVI Manager and the PVICOM application can be located on separate computers. Data is exchanged over a TCP/IP network.

The type of communication is defined by specifying the IP initialization parameter when the PviInitialize function is called.

If the IP parameter is not specified, then the "local" communication type is used. The PVI Manager is also started automatically when the function is called using local communication (can be turned off with the AS initialization parameter).

If the IP initialization parameter is specified, then the communication type is set to "remote" and client/server communication is handled over a TCP/IP network. The IP parameter specifies the IP address or the host name of the server computer (PVI Manager). The TCP/IP port number can be specified with the PN initialization parameter.

If the host name of the server computer is specified, then the system must determine the corresponding IP address. The procedure is as follows:

  1. Host name of the local computer
  2. Name entries in the HOSTS file
  3. The DNS server is queried (if present)
  4. NetBIOS

With the local IP address "IP=127.0.0.1", communication can take place with a local PVI Manager even when the remote communication type is being used. However, since a local connection works faster than a remote connection, communication type "local" should always be used on a local PVI Manager.

The following prerequisites are necessary for this communication type "remote":

  1. Network connection between both controllers
  2. TCP/IP protocol must be installed as network components on both controllers
  3. A unique IP address must be specified on both computers
  4. The Windows socket DLL wsock32.dll with a version >= 1.1 must be present on both computers
  5. PVI must be installed on both computers, the same version if possible. On the client computer (PVICOM application), PVI really only needs the communication libraries PviCom.dll and PviLog.dll (for 32-bit) or PviCom64.dll and PviLog64.dll (for 64-bit).
  6. TCP/IP communication has to be enabled and an available port number assigned on the server computer (PVI Manager) using PVI Manager properties. No other TCP/IP server can use the same port number. The port number used here must also be set in the application with the PN initialization parameter.
    PVI Manager has to be restarted to apply any changes.

A basic function check of the TCP/IP communication can be performed using the DOS utility ”ping.exe”.

<< Previous Topic
Communication instance

Start Page

Next Topic >>
Global events


Global events

Global events are formed in the PVICOM communication instance and are used to signal the state of the connection between the instance and the PVI Manager (client/server). In order to receive a certain global event, the application has to assign it a user message. This assignment is done with the PVICOM function PviSetGlobEventMsg or PviXSetGlobEventMsg. The following picture shows the basic sequence for global events.

A PVICOM communication instance can trigger the following global events:

Event types | No. | Description
POBJ_EVENT_PVI_CONNECT | #240 | The communication instance (client) established the connection to the PVI Manager (server).
POBJ_EVENT_PVI_DISCONN | #241 | The connection between the communication instance (client) to the PVI Manager was interrupted (server). The corresponding error code is reported with the event data. The communication timeout plays the main role in recognizing the disruption in the client/server connection. The communication timeout is defined with the PviInitialize or PviXInitialize function.
POBJ_EVENT_PVI_ARRANGE | #242 | This event signals that the communication instance has been newly registered with the PVI Manager. This event can only be triggered if there is a valid client/server connection.

The global events POBJ_EVENT_PVI_CONNECT and POBJ_EVENT_PVI_DISCONN only signal the state of the client/server connection. In contrast, the POBJ_EVENT_PVI_ARRANGE event signals the application when connection objects and temporary process objects have to be set up again. If there is a longer interruption in the client/server connection (doubled communication timeout), then the PVI Manager automatically de-registers the communication instance and releases all assigned connection objects. If the connection is established later, then the PVICOM application has to set up all objects again. The POBJ_EVENT_PVI_ARRANGE event can be used to automatically control this procedure.

As for events, the PVICOM function PviReadResponse or PviXReadResponse has to be called to read event data and confirm when responses are received. Information about the event can be read beforehand with the PVICOM function PviGetResponseInfo or PviXGetResponseInfo. An exception is using the callback function of type PVICALLBACK_DATA as a user message. Since response data is passed along directly to the callback function, it does not have to be read using a PVICOM function.

<< Previous Topic
Communication type

Start Page

Next Topic >>
Objects


Objects

In PVI Manager, the process image is managed using process objects.

When creating a process object, the PVICOM application also has to assign an object name. Applications can then create link objects using the object name to establish one or more connections to a process object.

The service object assigns an external object to a process object. Objects which reside outside of PVI are called external objects (e.g. PLC objects). A connection name is assigned to each service object. The connection name is a component of a process object's connection description.

The uniqueness of the name makes sure that all process objects with the same connection name use the same service object and all link objects with the same object name use the same process object. In this way, several process objects can be assigned to one service object, and several link objects can be assigned to one process object.

In this section the following topics are discussed:

Objects

Link objects

Process Objects

Service objects

Object names and connection descriptions

Object descriptions

<< Previous Topic
Global events

Start Page

Next Topic >>
Link objects


Objects

Link objects

Link objects are set up with the PVICOM function PviLinkRequest or PviXLinkRequest or with PviCreateRequest or PviXCreateRequest.

Releasing link objects takes place using the PVICOM function PviUnlinkRequest or PviXUnlinkRequest or with the PviUnlinkAll function. If the PVICOM communication instance is released (PviDeinitialize or PviXDeinitialize), then all links objects for this communication instance are also released.

A link object established the connection for the PVICOM application to a PVI Manager process object. The application then uses this link object to access process data, process object properties or states, or to carry out special services (Request and Respond). The enable mask for events is also managed in the link object.

If the POBJ_EVENT_ERROR or POBJ_EVENT_DATA event is enabled in the enable mask of the link object, then the process object receives an Active state. If there is no link object with an enabled POBJ_EVENT_ERROR or POBJ_EVENT_DATA event, then the process object receives the Inactive state.

The PVICOM interface provides 2 methods of modifying the active or inactive state of a process object at runtime:

  1. The existence of at least one link object sets the state to active:
    If event data is needed, then a link object with the required enabled mask needs to be created (e.g. "EV=ed"). If this event data is not longer needed, then link object is released once more. However, it is required that all process objects remain in use during runtime. Because of this, this method is primarily intended for static process objects.
  2. The active or inactive state is set using the enable mask, aided by access type POBJ_ACC_EVMASK:
    The link object always remains in use here. If event data is needed, then the enable mask needs to be activated (e.g. "EV=ed"). If the event data is no longer needed, then the enable mask needs to be deactivated "EV=". Since the link object remains in use, this method is especially suitable for temporary process objects. However, it can also be used for static process objects.

<< Previous Topic
Objects

Start Page

Next Topic >>
Process Objects


Objects

Process Objects

Process objects are created with the PVICOM function PviCreateRequest or PviXCreateRequest. They are the central part of managing the process image in PVI Manager.

Object structure

Process objects are divided into different object types. Each object type either represents a certain logical or physical part of the communication connection or an object within the line or on the PLC.

Object type |  |  | Name | Usage
Binary |  | String
POBJ_PVI | #0 | Pvi | Base object | PVI Manager base object
POBJ_LINE | #1 | Line | Line object | Represents the PVI line being used (line server)
POBJ_DEVICE | #2 | Device | Device object | Represents the physics of the network communication or a communication device
POBJ_STATION | #3 | Station | Station object | Represents a station in a network
POBJ_CPU | #4 | CPU | CPU object | Represents a PLC in a network
POBJ_MODULE | #5 | Module | Module object | Represents a module in a station or a CPU (PLC object)
POBJ_TASK | #6 | Task | Task object | Represents a task or process in a station, CPU, or module (PLC object)
POBJ_PVAR | #7 | Pvar | Variable object | Represents a variable in a station, CPU, module, or task (PLC task), or a PVI-internal variable

The order in which the object types are listed in the table corresponds to the object hierarchy. Starting from the PVI base object, each process object is assigned to another process object. However according to the object hierarchy, only objects with a higher-level object type can be assigned. This means that a variable object can be assigned to all other process objects except a variable object. A line object can only be assigned to the PVI base object. These assignments lead to a tree structure with the PVI base object as the root. This process object tree is also called the object structure.

An object name is assigned to each process object. The object path defines a process object contained within the object structure. The object name and names of the subordinate process objects are specified in the object path. Individual names are separated by a "/" character. Optionally, a process object type can also be specified to each name. The object path makes it possible to determine each process object within an object structure.

Example of an object structure (process object tree):

The PVI base object is managed automatically by PVI Manager. It is always present during the PVI Manager runtime. Applications don't need to set up or delete this object. The name of the base object is "Pvi".

The line object assigns a PVI line to a subset of the object structure. This automatically assigns all process objects to the line which are assigned to the line object. The object structure underneath the line object depends on the line being used.

External and internal process objects

External process objects have a line connection. i.e. They are assigned to a certain PVI line with the line object and represent a component of the communication connection or an object in the line or on the PLC. A connection description (CD parameter) and therefore a service object are assigned to external process objects.

Internal process objects do not have a line connection and are therefore not assigned to a PVI line. They have to be directly assigned to the PVI base object and have either no or an empty (null string) connection description. Because of this, a service object is also not assigned to an internal process object. All process objects in the object structure underneath an internal process object are also internal process objects automatically regardless of their connection description.

Basically, process objects from each object type can be set as internal process objects. However, not all access types supported by the line can be used for internal process objects (e.g. upload, download, reading CPU status, etc.). In this case, Error 12058 (Access type not supported) is reported.

Internal variable objects can use the functionalities of the process image though. In this way, they can be used as PVI constants or to exchange data between PVICOM applications. The DV parameter in the process object description can be used to assign process data when creating an internal variable object.

Undefined, ready, or error process object states

After being created, external process objects are Undefined. After being identified by the PVI line being used, the state becomes Ready or Error and the corresponding event POBJ_EVENT_ERROR or POBJ_EVENT_DATA (if enabled) is carried out.

Depending on the object type, if the state is Ready, then an existing PLC communication connection or a valid object identification is signaled by the PVI line. In the same way, an Error state signals a faulty PLC communication connection or an invalid object identification. The type of error is given by the error code. A process object's error state is passed down. i.e. All process objects in the object structure underneath the erroneous process object receive the same error condition. The RESP_STATUS_INHERIT_ERR flag is set with the POBJ_EVENT_ERROR event in the status of the event data (RESPONSE_INFO structure).

Active or inactive process object states

Each process object can be in either an active or inactive state. If at least one link object is assigned to the process object with an enabled POBJ_EVENT_ERROR or POBJ_EVENT_DATA event, then the process object takes on an active state. Otherwise, it is inactive. Process objects with an active state are given priority when being identified by the PVI line. Active or inactive states control process data acquisition for variable objects. For inactive process objects, process data is not read and PLC communication is not burdened. PVICOM applications should therefore only keep the process objects which are needed at the time in an active state.

Static and temporary process objects

A process object can be created either as a temporary or static process object. Both types of objects work the same way. There is only a difference when creating and enabling the process object.

A static process object is created with the PVICOM function PviCreateRequest or PviXCreateRequest. To establish a connection to a static process object, the PVICOM function PviLinkRequest or PviXLinkRequest has to be used. Static process objects remain throughout the entire runtime of PVI Manager. They also remain if the PVICOM application is ended. Error 12002 (Object name already exists) is reported if you try to create a process object which is already present. PVICOM applications can query this error and react accordingly. Process objects can be deleted using the PVICOM function PviDeleteRequest or PviXDeleteRequest. However, this isn't how static process objects should be used. The delete function is only intended for the configuration program.

A temporary process object is always created together with a link object. The PVICOM function PviCreateRequest or PviXCreateRequest are used to do this. Unlike static process objects, calling the PviLinkRequest function is not necessary. An error is not reported if you try to create a process object which already exists. Instead, a link object to the already existing process object is created. The process object description specified in the PviCreateRequest function is not applied in this case. Temporary process objects remain as long as one link object or one other process object is assigned to this process object. Releasing the last link objects automatically deletes the process object.

A newly set up link object with a line connection triggers a process for either establishing a connection (station objects, CPU objects) or for PLC object identification (module objects, task objects, variable objects). Depending on the line being used, this process can take some time to complete. If the process object is disconnected and then freshly set up again, then this process has to be repeated. It is therefore an advantage if PVICOM applications only have to set up process objects once.

<< Previous Topic
Link objects

Start Page

Next Topic >>
Service objects


Objects

Service objects

A service object assigns a PVI line or an object in a line (communication object or PLC object) to a process object.

Service objects are automatically managed by PVI Manager depending on the definition of the process object's connection description and the line being used.

<< Previous Topic
Process Objects

Start Page

Next Topic >>
Object names and connection descriptions


Object names and connection descriptions

The object name is the name of a process object in PVI Manager.

The connection description consists of the connection name as well as (usually) optional connection parameters. The connection name is the name of the service object being used in PVI Manager. The connection description is defined with the CD parameter in the process object description when creating the process object or with the POBJ_ACC_CONNECT access type.

For line objects (process objects of type POBJ_LINE), the connection name is defined as the name of the PVI line. PVI Setup stores the names of all installed lines (line servers) in the Windows registry. As an alternative, the path name of the line DLL's can be specified as the connection name.

Evaluating the connection description is carried out by the specified PVI line for all process objects assigned to a line object. The syntax of the connection description therefore depends on the line being used. Internal process objects either have no connection description or an empty connection description (null string) and are assigned directly to the PVI base object (process objects of type POBJ_PVI).

All ASCII characters except for the control characters (< code 32), the "/" character (slash), spaces, and the DEL character (code 127) can be used. If one of these prohibited characters is used in a name, then the name has to be surrounded by quotation marks ("...."). PVI then interprets all the characters between the quotation marks as the process object name. When specifying path names, note that syntactical characters ("/" or "@") and name parameters (OT parameter) are not a part of the actual process object name and therefore must remain outside of the quotation marks.

Process object names can be defined as unique object names or as object names with a path specification. The "@" character at the beginning of an object name determines the type of name assignment.

In this section the following topics are discussed:

Object names and connection descriptions

Object Names with Path Specification

Unique Object Names

<< Previous Topic
Service objects

Start Page

Next Topic >>
Object Names with Path Specification


Object names and connection descriptions

Object Names with Path Specification

An object path is specified together with the object name.

The object path defines the position of the process object within the object structure. The object path must always start from an object with a unique object name. The PVI base object is automatically created when PVI Manager is started and has a unique object name. If additional process objects with unique object names have not been created, then the object path must always be defined starting from the PVI base object. Object names specified with a path must begin with the "@" character. The names of the individual objects within the path must be separated by a "/" character.

In contrast to the method with unique object names, several objects with the same name can be created here. These objects have to be different in either the object assignments or in the object types. For example, a variable object can be created under the "Task1" task object and a second variable object can be created with the same name under the "Task2" task object. A task object and a module object can also be created with the name name under the same CPU object.

In addition, an object type can be specified for all object names in the object path (OT parameter). This can differentiate between process objects which have the same name.

The following object types can be specified:

Object type | Name
Pvi | PVI base object
Line | Line object
Device | Device object
Station | Station object
CPU | CPU object
Module | Module object
Task | Task object
Pvar | Variable object

Object name syntax:

@[/]Pvi/ ... /<ObjectName - 1> [OT=<ObjectType>]/<ObjectName> [OT=<ObjectType>]

Connection description syntax:

CD=<Connection>

Examples:

A device object with the name "DEVICE 1" should be created under the existing line object "LNINA2":

Object Name:
@Pvi/LNINA2/"DEVICE 1"
Connection description:
CD="/IF=com1 /BD=57600 /PA=2"

The PLC variable "Temperature" should be read. To do so, a variable object named "HeaterTemp" should be created under the existing task object "Heater":

Object Name:
@Pvi/LNINA2 OT=Line/"DEVICE 1" OT=Device/CPU OT=Cpu/Heater OT=Task/HeaterTemp OT=Pvar
Connection description:
CD=Temperature

<< Previous Topic
Object names and connection descriptions

Start Page

Next Topic >>
Unique Object Names


Object names and connection descriptions

Unique Object Names

All process objects are defined with a object name unique within PVI Manager. This name must not be the same even for process objects with varying object types.

Unique object names may not begin with the "@".

The object hierarchy in PVI Manager is defined with the first part of the connection description. Either the whole path to the PVI base object can be specified or just the name of the process object at the next highest level.

The connection is outwardly defined with the second part of the connection description.

Object name syntax:

<ObjectName>

Connection description syntax:

CD=[[[/]Pvi/ ... /]<ObjectName - 1>/]<Connection>

Examples:

A device object with the name "DEVICE 1" should be created under the existing line object "LNINA2":

Object Name:
DEVICE 1
Connection description:
CD=LNINA2/"/IF=com1 /BD=57600 /PA=2"

The PLC variable "Temperature" should be read. To do so, a variable object named "HeaterTemp" should be created under the existing task object "Heater":

Object Name:
HeaterTemp
Connection description:
CD=/Pvi/LNINA2/"DEVICE 1"/CPU/Heater/Temperature
The specification is identical to: CD=Heater/Temperature

<< Previous Topic
Object Names with Path Specification

Start Page

Next Topic >>
Object descriptions


Object descriptions

Object properties are set with the object description when a process or link object is set up. The object description is specified as an ASCII string and terminated with a binary 0 (null).

The individual parameters are differentiated in the string using parameter codes:

<ParameterCode> = ["]<ParameterValue>["]

All alphanumeric characters, special characters "[" (open bracket), "]" (closed bracket), "$" (dollar sign), "*" (asterisk), "+" (plus sign), "-" (minus sign), "," (comma), "." (period), ";" (semicolon), "_" (underscore), as well as ASCII characters above 127 can be used as parameter values. If other characters are used (e.g. spaces or the "/" character), then the parameter value has to be specified inside quotation marks ("..."). At least one blank space needs to be between individual parameter entries.

The following table shows all parameters which can be defined in an object description. The "Obj." column indicates where (in which object description) the parameter can be specified. The letter "L" stands for the link object description and "P" stands for the process object description. Only the CD and EV parameters can be used for all process object types. All other parameters can only be defined in connection with link objects. The corresponding access type is indicated in the "Access type" column. Object properties can be set or modified at a later time using this access type.

Par. | Obj. | Access types | Description
CD | P | POBJ_ACC_CONNECT | Connection description This parameter can be specified for all process object types (except for PVI base objects).
EV | C | POBJ_ACC_EVMASK | Definition of the enable mask for events. Default: "EV=ed". "e": Change in error state "d": Change in data "f": Change in data format "c": Change in the connection description "p": Progress information about active requests "s": Status changes 'u': Change in the user tag string 'l': Special line events Example: "EV=edfc" If no events should be enabled, then specify "EV=".
LT | C |  | Link type (see "Process Data Functions" section). Default: "LT=raw". "raw": Raw value "prc": Process value
AT | P | POBJ_ACC_TYPE | Object attributes. Default: "AT=rw" "r": Allows read access "w": Allows write access "e": PLC event operation "h": Immediate write echo if access type POBJ_ACC_DATA "d": Direct event trigger for the POBJ_EVENT_DATA event
RF | P | POBJ_ACC_REFRESH | Refresh rate in ms. Default: "RF=1000". =-1: Cyclic data refresh is turned off = 0: Data refresh is only carried out once > 0: Cyclic data refresh is carried out with the specified refresh rate
VT | P+L | POBJ_ACC_TYPE | Variable type (Data format description). Default in the process object: "VT=i32" "i8", "i16", "i32", "i64": 8 to 64-bit signed integer "u8", "u16", "u32", "u64": 8 to 64-bit unsigned integer "f32", "f64": 32/64-bit floating point "boolean": Flag with element length of 1 byte "string": String with 8-bit character size "wstring": String with 16-bit character size "struct": Structure "time": 32-bit time in ms since midnight "dt": 32-bit date and time in seconds since 1/1/1968 "date": 32-bit date, "tod". 32-bit time of day, "date": General variable type with 1 byte element length
VL | P+L | POBJ_ACC_TYPE | Variable length in bytes (data format description). This parameter can only be specified together with the VT parameter. For single variables, the variable length corresponds to the process data length. For array variables, the variable length is defined as the element length. This parameter does not need to be specified when used in conjunction with variable types which have a fixed variable length (e.g. VT=i32 always has a variable length of 4 bytes).
VN | P+L | POBJ_ACC_TYPE | Number of elements in array variables (data format description). Default: VN=1. This parameter can only be specified together with the VT parameter.
VS | P+L | POBJ_ACC_TYPE | Optional additional specification of variable type (Data format description). This parameter can only be specified together with the VT parameter.
{...} | P+L | POBJ_ACC_TYPE | Definition of structure elements(data format description) The definition of the structure element must be specified at the end of the object description. First the nesting depth is defined by a number of "."'s (periods) within each expression in parentheses. Then element variables are defined.
AL | P+L | POBJ_ACC_TYPE | Structure alignment (data format description). Default: "AL=1". This parameter only takes effect in connection with variable type "VT=struct". Alignment values 1, 2, 4, 8, or 16 can be defined.
CM | P+L | POBJ_ACC_TYPE | Mode for type casting (cast mode). Default: "CM=0". The mode is defined as a bit list and controls type casting between link and process objects. Bit 0: String variable for PG2000 or AS 1.3 Bit 1: String contents are interpreted as a decimal number Bit 2: Value range is monitored Bit 3: Rounding takes place when type casting from a float to an integer Bit 4: Strings are always terminated with 0 (null).
VA | L |  | Variable addressing. Default: No variable addressing Using variable addressing, link objects can address subsets from the process data of a variable object.
DV | P | POBJ_ACC_DEFAULT | Default value for single variables (process data). This parameter can be used to assign a default data value to process variable objects of type Integer, Floating Point, Boolean, or String. If this parameter is specified, then a data format also has to be defined in the object description. This default value is only written to the process image but is not transferred to the PLC. Examples: DV=123, DV=2.561e10, DV="string format"
HY | P+L | POBJ_ACC_HYSTERESE | Assigned event hysteresis. Default: No hysteresis Definition of event hysteresis for single variables or array variables of type Integer or Floating Point. Event hysteresis is specified as a hysteresis value. Examples: HY=10, HY=2.5
FS | P+L | POBJ_ACC_FUNCTION | Assigned data function. Default: No function Definition of a data function for single variables or array variables of type Integer or Floating Point. The data function is specified as a function description.
UT | P | POBJ_ACC_USERTAG | With user tags, PVI applications can assign a private user code or specific user data to a process object (module, task, or variable object) in the form of a string. User tags are only managed by PVI, not evaluated.

<< Previous Topic
Unique Object Names

Start Page

Next Topic >>
User messages


User messages

PVI uses user messages to signal the existence of response or event data in the PVICOM communication instance to the PVI application.

A user message is defined using three parameters:

  1. Message pointer/handle
  2. Message number
  3. Message parameter

The size of the parameters "Message Pointer/Handle" and "Message Parameter" in the 32-bit PVI version (PviCom.dll) is 4 bytes and in the 64-bit PVI version (PviCom64.dll) 8 bytes.

User messages with 8-byte (64-bit) parameters are only supported by the PVI Manager with Version 3.50 (PviMan.exe file version) or higher. This applies for the 32-bit and for the 64-bit versions of the PVI Manager. With Version 3.50 and higher, 64-bit applications (PviCom64.dll used) can therefore also communicate with a 32-bit PVI Manager (local or remote). However, it is not possible to communicate with older versions of the PVI Manager. For 32-bit applications (PviCom.dll used) there are no limitations.

User messages can be sent as a Windows message or as a callback function, or by a cyclic function call from the PVICOM application. A reference (wParam) to the response or event data of the PVICOM application is sent (except for user messages as callback with data). To read the response or event data, the corresponding response function must be called and the reference must be sent as an argument.

User messages | Type | Description
Windows message | - | Signals using a Windows message. Response or event data is read using the response function.
Message function | PVIFUNCTION | Cyclic call of the PVI function PviGetNextResponse. A system event can be used as a signal. Response or event data is read using the response function.
Callback with data | PVICALLBACK_DATA | Signals using a callback function. Response or event data is transferred using the callback function.
Callback without data | PVICALLBACK | Signals using a callback function. Response or event data is read using the response function.
Asynchronous callback | PVICALLBACK_ASYNC | Signals using an asynchronous callback function. Response or event data is read using the response function.

A PVICOM application can also mix Window messages and callbacks (with or without data) within a communication instance. For example, event data can register to the application as a Windows message and response data as callback. Keep in mind that when they are mixed, the order of processing can change drastically. Message function and asynchronous callback should not be mixed with other types within a communication instance.

User message type | Usage
Windows message | Applications with open (accessible) windows. Optimized for Visual C/C++ applications with dialog or view windows.
PVIFUNCTION | Applications with or without windows. Optimized for console applications, driver applications, server applications, and for applications where PVI communication takes place in its own thread (multi-thread applications).
PVICALLBACK_DATA | Applications with or without open windows. Optimized for Visual Basic applications.
PVICALLBACK | Such as PVICALLBACK_DATA.
PVICALLBACK_ASYNC | Applications with or without windows. This variant is obsolete and has been replaced by the user message type PVIFUNCTION.

In practice, a user message as message function provides the best performance. Window message and callback with data are also acceptable options. The worst performance is generally associated with asynchronous callback and callback without data. However, the differences are relatively small, and only occur with larger applications (500-1000 active variables or more) combined with a large amount of data. The settings of initialization parameters LM and RETR can also affect performance, depending on the user message type used. For the best performance, use the setting "LM=0 RETR=0" (see section "User message operation").

In this section the following topics are discussed:

User messages

Operation

Windows message

Message function

Callback with data

Callback without data

Asynchronous callback

<< Previous Topic
Object descriptions

Start Page

Next Topic >>
Operation


User messages

Operation

If PVI Manager (server) sends response or event data to the PVICOM communication instance (client), then the data is stored in the client temporarily and the application is notified with a user message.

The application must then react to the user message and call the corresponding PVICOM response function (except for user message as callback with data). Once that happens, the data is read and the data memory area in the client is freed up. If the application "forgets" to call the response function, then the data remains and occupies memory in the communication instance.

The initialization parameters LM and RETR of the PviInitialize or PviXInitialize functions can affect the control of certain user messages.

User message type | LM parameter | RETR parameter
Windows message | Limits number of window messages. | Repeats the window message.
PVIFUNCTION | No meaning. | No meaning.
PVICALLBACK_DATA | No meaning. | Repeats the callback.
PVICALLBACK | Limits number of callbacks. | Repeats the callback.
PVICALLBACK_ASYNC | No meaning. | No meaning.

The initialization parameter LM can be used to limit the number of user messages per communication instance. If limiting is enabled (limit value > 0), then it doesn't mean user messages are lost. Instead, it refers to how they are distributed in time. A setting of "LM=100" means that the PVICOM sends a maximum of 100 user messages to the application. An additional user message is then only sent once the application has reacted to a user message which has already been sent and has called the corresponding PVICOM response function. With the setting "LM=1", each new user message is sent only when the previous user message has been processed. If the application "forgets" to call the response function, then the application does not receive any more user messages. The setting "LM=1" is therefore well suited for testing the application. For this reason, this is the setting used by default by the PVI interface. The disadvantage, however, is that user messages are delayed.

It is only necessary to limit the "Windows Message" and "PVICALLBACK" user messages. A Windows message is sent for each occurrence of these types of user messages. However, the Windows message buffer is limited. Once it is full, user messages are lost. Limiting user messages effectively prevents the Windows message buffer from overflowing. In practice, values between 100 ("LM=100" for Windows CE / Windows 95) and 500 ("LM=500" for Windows XP) have proven effective. This limit can be turned off if an application works with a small enough number of user messages (e.g. Number of active PVI objects < 100). The setting "LM=0" turns off the limit.

The RETR initialization parameter (specified in seconds) can be used to set user message repeats. If a user message is not confirmed by calling the corresponding "Response" function, then the same user message is re-sent after the time expires. This procedure is repeated until the application acknowledges the user message. For the chronological order of request and response data to be maintained, the LM parameter must be set to 1 ("LM=1").

In principle, retrying user messages is only necessary when debugging Visual Basic 5.0 applications. If the application's execution is stopped by a breakpoint, then the callback function (user message) is not carried out. When using newer versions of Visual Basic or other programming languages, repetition of user messages should be turned off ("RETR=0").

<< Previous Topic
User messages

Start Page

Next Topic >>
Windows message


User messages

Windows message

The message handle is defined as the handle for the allocated window (type HWND) for this user message.

The message number is defined as the window message number. A user parameter can be specified as a message parameter. This message parameter is not evaluated by the PVICOM interface but is passed through with the user message. Signaling the user message is done as a "post message".

In the application's window procedure assigned by the message handle, user message data is transferred as follows:

WinProc (HWND hWnd, UINT nMsg, WPARAM wParam, LPARAM lParam)

Window procedure arguments:

Argument | Description
nMsg | Message number
wParam | Reference to response or event data (for PVI response functions)
lParam | Message parameter The size of the message parameter (user parameter) in the 32-bit PVI version (PviCom.dll) is 4 bytes and in the 64-bit PVI version (PviCom64.dll) 8 bytes.

After the user message is received, the application can use the PviGetResponseInfo or PviXGetResponseInfo function to read information about the data assigned to the user message. The application receives the response or event data by calling the corresponding PVI response function (Pvi...Response or PviX...Response). The response function has to be called with each user message. Otherwise, the data buffer for the response or event data is not released.

Example for Visual C++

#include <PviCom.h>
class CPviDlg : public CDialog
{
    ...
    DWORD m_hPv;
    DWORD m_PvData;
    DWORD m_PvStatus;

    void MakePviReadRequ ();
    LRESULT OnPviReadResp (WPARAM, LPARAM);
    ...
    DECLARE_MESSAGE_MAP()
};
BEGIN_MESSAGE_MAP(CPviDlg, CDialog)
    ...
    ON_MESSAGE (WM_USER+1, OnPviReadResp)
END_MESSAGE_MAP()
LRESULT CPviDlg::OnPviReadResp (WPARAM wParam, LPARAM lParam)
{
    T_RESPONSE_INFO Info;
    long ErrCode;

    // read response status:
    ErrCode = PviGetResponseInfo (wParam, NULL, NULL, &Info, sizeof(Info));
    if (ErrCode == 0)
        m_PvStatus = Info.Status;
    ...

    // read response data:
    ErrCode = PviReadResponse (wParam, &m_PvData, sizeof(m_PvData));
    ...

    return (0);
}
void CPviDlg::MakePviReadRequ ()
{
    long ErrCode;

    // make read request:
    ErrCode = PviReadRequest (m_hPv, POBJ_ACC_DATA,
                              CWnd::m_hWnd, WM_USER+1, 0);
    ...
}

<< Previous Topic
Operation

Start Page

Next Topic >>
Message function


User messages

Message function

As the message number for the user message, SET_PVIFUNCTION (binary 0xfffffffc) must be entered. The message handle and the message parameter can be used freely by the PVICOM application. Keep in mind, however, that entering the value zero for the message handle (argument "hResMsg" of the PVI functions) suppresses the response (see section "Requests and responses") For a message handle that is not needed, the constant PVI_HMSG_NIL can be entered.

To read the user message, the PVICOM application needs to call the PviGetNextResponse or PviXGetNextResponse function. After that, the procedure is the same as for the user message as window message.

Within the PVICOM application, the function PviGetNextResponse should be called cyclically in a central program loop. This allows you to control the entire program process via the user messages. If the evaluation of the PVI response or event data takes place in a separate thread, the function PviGetNextRespons can be easily integrated in the thread program loop. All asynchronous PVICOM functions (asynchronous and synchronous functions) and the function PviGetNextResponse (or PviXGetNextResponse) can be called from different threads.

Example for Visual C++

#include <PviCom.h>
typedef bool (*T_RESPONSE_FUNC) (WPARAM, LPARAM, T_RESPONSE_INFO*, DWORD);
#define PVIOBJ_CNT 40
static DWORD PviObjLinkID[PVIOBJ_CNT];
static bool bExitProg;
static HANDLE hRespEvent;
void ExitProg ()
{
    bExitProg = TRUE;
    SetEvent (hRespEvent);
}
...
static void ObjectEvent (WPARAM wParam, LPARAM lParam, T_RESPONSE_INFO* pInfo, DWORD DataLen)
{
    INT   ErrCode;

    switch (pInfo->nType)
    {
        case POBJ_EVENT_DATA:
            // confirm object event and read data:
            ErrCode = PviReadResponse (wParam, pDataBf, DataLen);
            ...

        case POBJ_EVENT_ERROR:
            ...

        case POBJ_EVENT_DATAFORM:
            ...

    }
}
static void CreateResp (WPARAM wParam, LPARAM lParam, T_RESPONSE_INFO* pInfo, DWORD DataLen)
{
    DWORD LinkID
    INT   ErrCode;

    // confirm create response:
    ÉrrCode = PviCreateResponse (wParam, &LinkID)
    if (ErrCode != 0)
    {
        printf ("Object creation failed (Error=%d)\n", ErrCode);
        LinkID = 0;
    }

    PviObjLinkID[lParam] = LinkID;
}
static void GlobalEvent (WPARAM wParam, LPARAM lParam, T_RESPONSE_INFO* pInfo, DWORD DataLen)
{
    // confirm global event:
    PviReadResponse (wParam, NULL, 0);

    switch (pInfo->nType)
    {
        case POBJ_EVENT_PVI_CONNECT:
            printf ("PVI connection established\n");
        break;
        case POBJ_EVENT_PVI_DISCONN:
            printf ("PVI connection failed (Error=%d)\n", pInfo->ErrCode);
        break;
        case POBJ_EVENT_PVI_ARRANGE:
            // create all required PVI objects:
            ErrCode = PviCreateRequest ("@Pvi/LNINA2", POBJ_LINE, "CD=LnIna2",
                ObjectEvent, SET_PVIFUNCTION, 0, "EV=e", CreateResp, SET_PVIFUNCTION, 0);
            ...

            ErrCode = PviCreateRequest ("@Pvi/LNINA2/COM2/CPU/PVar1", POBJ_PVAR, "CD=PVar1",
                ObjectEvent, SET_PVIFUNCTION, 24, "EV=edf", CreateResp, SET_PVIFUNCTION, 24);
            ...

        break;
    }
}
int main ()
{
    INT   ErrCode;
    WPARAM wParam;
    LPARAM lParam;
    LPVOID hMsg;
    DWORD  DataLen;
    T_RESPONSE_INFO Info;
    T_RESPONSE_FUNC RespFunc;

    bExitProg = FALSE;
    hRespEvent = CreateEvent (NULL, FALSE, FALSE, NULL);
    if (hRespEvent == NULL)
    {
        printf ("Can't create system event\n");
        return (1);
    }

    ErrCode = PviInitialize (0, 0, "", NULL);
    if (ErrCode != 0)
    {
        printf ("Initialize failed (Error=%d)\n", ErrCode);
        return (1);
    }

    // define global events:
    ErrCode = PviSetGlobEventMsg (POBJ_EVENT_PVI_ARRANGE, GlobalEvent, SET_PVIFUNCTION, 0);
    ...

    // loop to control all response/event data:
    while (! bExitProg)
    {
        // get response/event data identification:
        ErrCode = PviGetNextResponse (&wParam, &lParam, &hMsg, hRespEvent);
        if (ErrCode != 0)
        {
            printf ("NextResponse failed (Error=%d)\n", ErrCode);
            break; // -> exit loop
        }

        if (wParam == 0)
           // wait for response/event data:
           WaitForSingleObject (hRespEvent, INFINITE);
        else
        {
            // read response/event data information:
            ErrCode = PviGetResponseInfo (wParam, NULL, &DataLen, &Info, sizeof (Info));
            if (ErrCode != 0)
            {
                if (ErrCode == 12055)
                    continue; // -> no response (skip error 12055)

                printf ("GetResponseInfo failed (Error=%d)\n", ErrCode);
                break; // -> exit loop
            }

            // call response/event function:
            RespFunc = (T_RESPONSE_FUNC) hMsg;
            RespFunc (wParam, lParam, &Info, DataLen);
        }
    }

    PviDeinitialize ();
    CloseHandle (hRespEvent);
    return (0);
}

<< Previous Topic
Windows message

Start Page

Next Topic >>
Callback with data


User messages

Callback with data

The pointer to a callback function provided by the application needs to be specified for the user message's message handle.

SET_PVICALLBACK_DATA (binary 0xfffffffe) must be specified as the message number. The message parameter is passed through to the callback function.

Syntax of the callback function of type PVICALLBACK_DATA:

void WINAPI PviProc (WPARAM wParam, LPARAM lParam, LPVOID pData, DWORD DataLen, T_RESPONSE_INFO* pInfo)

Arguments of the callback function of type PVICALLBACK_DATA:

Argument | Description
wParam | Always 0 (reserved for future expansions)
lParam | Message parameter The size of the message parameter (user parameter) in the 32-bit PVI version (PviCom.dll) is 4 bytes and in the 64-bit PVI version (PviCom64.dll) 8 bytes.
pData | Pointer to the response or event data. If NULL is transferred as a pointer, then no data exists.
DataLen | Length of response or event data in bytes
pInfo | Pointer to the RESPONSE_INFO structure for additional information

Response or event data is transferred directly to the callback function. Calling the corresponding response function is not necessary or even possible.

Calling the callback function is handled within the PVICOM interface using the window procedure for an internal window. This allows the callback function to always be called in the context of the user thread. If an application is using asynchronous windows in different threads and the PVICOM functions in more than one of them, it can be determined where (in which thread context) the callback function is currently running. Asynchronous PVICOM functions are multithread-capable. Calling these function is therefore not the problem; instead, it's accessing the internal application data buffer. In this case, the application has to be equipped with the appropriate mechanisms for access synchronization (e.g. critical sections).

Within the callback function, unrestricted asynchronous PVICOM functions can be used, but synchronous PVICOM functions may not. In general, the callback function should be kept brief. Actions which may take longer times (such as accessing databases, etc.) should not be carried out here.

Example for Visual C++

#include <PviCom.h>
class CPviDlg : public CDialog
{
    ...
    DWORD m_hPv;
    DWORD m_PvData;
    DWORD m_PvStatus;

    void MakePviReadRequ ();
    void MakePviReadResp (DWORD, DWORD*);
    ...
};
static void WINAPI PviProc (WPARAM wParam, LPARAM lParam,
                            LPVOID pData, DWORD DataLen,
                            T_RESPONSE_INFO* pInfo)
{
    CPviDlg* pPviDlg = (CPviDlg*) lParam;

    if (pInfo->ErrCode == 0) && (DataLen == sizeof(DWORD))
        pPviDlg->MakePviReadResp (pInfo->Status, (DWORD*) pData);
}
void CPviDlg::MakePviReadResp (DWORD Status, DWORD* pData)
{
    m_PvStatus = Status;
    m_PvData = *pData;
}
void CPviDlg::MakePviReadRequ ()
{
    long ErrCode;

    // make read request:
    ErrCode = PviReadRequest (m_hPv, POBJ_ACC_DATA,
                              PviProc, SET_PVICALLBACK_DATA, (LPARAM) this);
    ...
}

<< Previous Topic
Message function

Start Page

Next Topic >>
Callback without data


User messages

Callback without data

The pointer to a callback function provided by the application needs to be specified for the user message's message handle.

SET_PVICALLBACK (binary 0xffffffff) must be specified as the message number. The message parameter is passed through to the callback function.

Syntax of the callback function of type PVICALLBACK:

void WINAPI PviProc (WPARAM wParam, LPARAM lParam)

Arguments of the callback function of type PVICALLBACK:

Argument | Description
wParam | Reference to response or event data (for PVI response functions)
lParam | Message parameter The size of the message parameter (user parameter) in the 32-bit PVI version (PviCom.dll) is 4 bytes and in the 64-bit PVI version (PviCom64.dll) 8 bytes.

The same rules apply as with user messages as callback functions with data, but response or event data has to be read with PVICOM function, as with user messages as window messages.

Example for Visual C++

#include <PviCom.h>
#define PV_CNT	40
DWORD  PvLinkID[PV_CNT];
long   PvData[PV_CNT];
long   PvDataError[PV_CNT];
long   PvWriteError[PV_CNT];
HANDLE hRespEvent;
static void WINAPI PviCallback (WPARAM wParam, LPARAM lParam)
{
    T_RESPONSE_INFO Info;
    long  ErrCode;
    long  Data;
    DWORD LinkID;

    // get response informations:
    ErrCode = PviGetResponseInfo (wParam, NULL, NULL, &Info, sizeof(Info));
    if (ErrCode != 0)
        return;  // -> no response (skip error 12055)

    switch (Info.nMode)
    {
        case POBJ_MODE_LINK:
            // get link response:
            ErrCode = PviLinkResponse (wParam, &LinkID);
            if ((DWORD) lParam < PV_CNT)
            {
                PvDataError[lParam] = ErrCode;
                if (ErrCode == 0)
                    PvLinkID[lParam] = LinkID;
            }
            break;

        case POBJ_MODE_UNLINK:
            // get unlink response:
            ErrCode = PviUnlinkResponse (wParam);
            if ((DWORD) lParam < PV_CNT)
                PvLinkID[lParam] = 0;
            break;

        case POBJ_MODE_EVENT:
        case POBJ_MODE_READ:
            // get read or event response (PV data):
            ErrCode = PviReadResponse (wParam, &Data, sizeof (Data));
            if ((DWORD) lParam < PV_CNT)
            {
                PvData[lParam] = Data;
                PvDataError[lParam] = ErrCode;
                SetEvent (hRespEvent);
            }
            break;

        case POBJ_MODE_WRITE:
            // get write response (PV data):
            ErrCode = PviWriteResponse (wParam);
            if ((DWORD) lParam < PV_CNT)
            {
                PvWriteError[lParam] = ErrCode;
                SetEvent (hRespEvent);
            }
            break;
    }
}

<< Previous Topic
Callback with data

Start Page

Next Topic >>
Asynchronous callback


User messages

Asynchronous callback

This user message variant is obsolete and has been replaced by the user message type PVIFUNCTION.

The pointer to a callback function provided by the application needs to be specified for the user message's message handle.

SET_PVICALLBACK_ASYNC (binary 0xfffffffd) must be specified as the message number. The message parameter is passed through to the callback function.

The syntax of asynchronous callback functions of type PVICALLBACK_ASYNC correspond to callback functions of type PVICALLBACK (User messages as callback functions without data).

Unlike the other callback function variations, this variant is not called from an internal window procedure but directly from the PVICOM thread of the communication instance. This means that the callback function call always takes place asynchronously to the user thread. The application itself must therefore provide the corresponding synchronization mechanisms. The callback function must be kept extremely short since data transfer (and therefore the life-sign monitoring of the PVICOM communication instance) is completely blocked during execution. Only the corresponding PVICOM response function may be called within the callback function. However, it is better to save the callback parameters (the wParam and IParam arguments) in a separate list and evaluate the user message in a separate thread. Under no circumstances may the PviInitialize, PviDeinitialize or any other synchronous PVICOM function be called within the callback function.

This callback function variant is not suitable for Visual Basic applications.

Example for Visual C++

#include <PviCom.h>
HANDLE hPviEvent;
bool   bPviExit;
static void WINAPI PviCallback (WPARAM wParam, LPARAM lParam)
{
    Container.AddMsg (wParam, lParam);
    SetEvent (hPviEvent);
}
void CPviThread::PviExit ()
{
    bPviExit = TRUE;
    SetEvent (hPviEvent);
}
void CPviThread::PviProc (WPARAM wParam, LPARAM lParam)
{
    T_RESPONSE_INFO Info;
    long ErrCode;

    ErrCode = PviGetResponseInfo (wParam, NULL, NULL, &Info, sizeof(Info));
    if (ErrCode != 0)
        return;  // -> no response (skip error 12055)

    switch (Info.nMode)
    {
        case POBJ_MODE_WRITE:
            ErrCode = PviWriteResponse (wParam);

        ...
    }
}
void CPviThread::ThreadFunc ()
{
    ...

    hPviEvent = CreateEvent (NULL, FALSE, FALSE, NULL);
    bPviExit = FALSE;
    ErrCode = PviInitialize (6, 0, NULL, NULL);

    ...

    while (! bPviExit)
    {
        LPARAM lParam;
        WPARAM wParam;

        WaitForSingleObject (hPviEvent, INFINITE);
        while (Container.RemoveMsg (&wParam, &lParam))
            CPviThread::PviProc (wParam, lParam);
    }

    ...

    PviDeinitialize ();
    CloseHandle (hPviEvent);
}

This example shows the recommended procedure for using the callback function of type PVICALLBACK_ASYNC. The PVICOM function calls are carried out in the context of the user thread. Only the message parameters (wParam, IParam) are stored in a container in the asynchronous PVI callback function.

<< Previous Topic
Callback without data

Start Page

Next Topic >>
Requests and responses


Requests and responses

Using PVICOM functions, requests can be sent to the PVI Manager via a communication instance together with the definition of a user message.

After being processed by PVI Manager or the PVI line, the response is sent back and the assigned user message is executed. The response data is then read. The following picture shows the basic sequence.

This procedure accomplishes several things: PVI objects are set up in the manager and then released again; data, states, and properties of PVI objects are read and written; and special PVI Manager functions are carried out. The sequence in the picture assigns a PVI object to the request. This also applies in most cases. The only exceptions are requests for setting up and deleting PVI objects. In this case, the PVI object in the picture would be dropped since these requests would be executed by the manager outside of the object level.

In this section the following topics are discussed:

Requests and responses

Sending requests and receiving responses

Order of request execution

Access types

<< Previous Topic
Asynchronous callback

Start Page

Next Topic >>
Sending requests and receiving responses


Requests and responses

Sending requests and receiving responses

PVICOM functions with the word "Request" in their name are used to send requests (e.g. PviLinkRequest, PviReadRequest, PviWriteRequest, etc.).

PVICOM functions with the word "Response" in their name are used to read response data (e.g. PviLinkResponse, PviReadResponse, PviWriteResponse, etc.). An exception is using the callback function of type PVICALLBACK_DATA as a user message. Since response data is passed along directly to the callback function, it does not have to be read using a PVICOM function.

The response to a request is a request acknowledgement at the same time. If an error occurs when executing a request in PVI Manager or in the PVI line, then the response data includes the corresponding error code. If no errors occur with the response data, then the response signals that the request was executed correctly.

For each request, the user can choose whether the PVICOM application should receive a response. If a user message is specified when calling a request function ("hResMsg" argument not equal to zero), then a response is always sent to the application. If no user message is specified ("hResMsg" argument is zero), then a response is not sent to the application. Without a response, however, the application cannot determine whether the request has been carried out correctly or if an error occurred.

A request to cancel one or more active requests can be sent using the POBJ_ACC_CANCEL access type. This cancel function can refer to either certain requests or all requests of a link object. For example, a time-intensive request (e.g. uploading or downloading modules) can be cancelled before it is completed. Error 12043 is reported in the response data of every cancelled request. The response data for a cancel request is always sent to the PVICOM application after the response data of the requests which were cancelled.

If the application has defined a valid user message when sending the request, then normally response data is always send to the application. There are only two situations where response data is not sent back for active requests:

  1. When releasing a link object (PVICOM function PviUnlinkRequest / PviXUnlinkRequest or PviUnlinkAll), all requests assigned to it are cancelled and response data deleted.
  2. When releasing a communication instance (PVICOM function PviDeinitialize or PviXDeinitialize), all requests assigned to it are cancelled and response data deleted.

However, it is not certain whether a request has been cancelled before being executed or just the response data after the execution has been deleted. For example, a variable should be set back to 0 before the object is released. If the PviWriteRequest function is called directly before the PviUnlinkRequest function, then there is no guarantee that the write request is carried out. To ensure that the write request is executed, the PviUnlinkRequest function may only be called after the response to the write request is received.

With an interruption of the client/server communication connection, the procedure depends on the length of the interruption. If the interruption falls within the communication timeout period, then data transfer simply continues after the connection is reestablished. Unless there is a delay in processing the request, the PVICOM application doesn't notice the interruption. But if the interruption is longer than the communication timeout allows, then all outstanding requests trigger a user message and a corresponding error is recorded in the response data.

<< Previous Topic
Requests and responses

Start Page

Next Topic >>
Order of request execution


Requests and responses

Order of request execution

With asynchronous PVICOM functions, several requests can also be sent directly after one another.

All of these requests are stored in the PVICOM communication instance, sent in blocks to PVI Manager and processed at the same time if possible.

The maximum number of requests is limited only by the amount of memory available.

Practically, requests should be limited to approx. 500 to 5,000 requests. This way of handling requests is very efficient since PVI components such as the PVICOM interface, PVI Manager, and the PVI line are used optimally and several requests can be executed at the same time.

For example, all variables should be initialized when a PVI application is started. The most time-efficient way to do so would be to call the PVICOM function PviWriteRequest or PviXWriteRequest for all variable objects in a program loop. However, it should be noted that the order of calls does not have to match the order of the actual execution in PVI Manager and the response data being sent back. This also means that the order of PviWriteRequest calls and the order used to write data to PLC variables also do not have to match. This basically applies to all types of requests. Requests can be rearranged by PVI Manager of the PVI line to use time the most optimally when processing all outstanding requests.

If several requests are directed to one process object, then the likely order of execution is also determined by the priority level of the request. Write requests to process data have the highest priority. Read requests to process data have an average priority. All other requests have the lowest priority. After a certain number of requests, a request with lower priority is executed to prevent many requests with high priority from stopping the execution of a request with lower priority. This is the reason why we can only mention the 'likely' order. Priority levels cannot be changed by the user.

Requests within one process object and within one priority level are not rearranged though. Here, the order of calls corresponds to that of the execution. For example, a PVICOM application can assign the value 4 to a variable object's data before then assigning it 2 directly afterwards. At the end, the variable will hold the value 2.

If a certain order should be kept when executing requests over several process objects or over different priority levels of a process object, then the application may only send the next request once the response of the previous request has been received.

<< Previous Topic
Sending requests and receiving responses

Start Page

Next Topic >>
Access types


Access types

The access type is specified whenever a read or write request is specified for a PVI object. This allows process data, properties, states of process objects, and various services to be selected.

Read requests are implemented with the PviReadRequest or PviXReadRequest function. The PviReadResponse or PviXReadResponse function is used to read response data. Write requests are implemented with the PviWriteRequest or PviXWriteRequest function. The PviWriteResponse or PviXWriteResponse function is used to write response data.

Some access types are directly executed by PVI Manager. Other access types are passed along to the line and processed there. Therefore, which access types can be used depends on the PVI line being used.

All standardized access types are listed in the following table. Suitable parameter codes for the object description are displayed in the "Par." column. The corresponding process object type is listed in the "Type" column.

Access types | No. | Par. | Type | Description
POBJ_ACC_OBJECT | #1 | All | Read access: Reads object type of the process object. The object type is returned in 4-byte binary format (integer).
POBJ_ACC_VERSION #2 Pvi
Line
Device
Station
Cpu
Module
Task 		Read access: Either the version of the PVI component or the version of the PLC object is read depending on the object type. This version information is returned in string format. Each version entry is terminated with a LF ("\n").

Syntax for PVI components version (object type: Pvi, Line, Device):
<Title> (<FileName>) <FileVersion> [<Date>] \n

Syntax for PLC object version (object type: Station, Cpu, Module, Task):
[<Title>] <Version> [<Date>] \n
POBJ_ACC_ERROR | #3 | All | Read access: Reads error code of the most recent error
POBJ_ACC_EVMASK #5 EV All Write access: Definition of the enabling mask for the event type for enabling events.
"e": Change in error state
"d": Data changes
"f": Change to the data format
"c": Change to the connection description
"p": Progress information about active requests
"s": Status changes
"u": Change in the user tag string
'l' -> Special line event.
Specifications here take place using string format. The sequence of letters doesn't really matter. If no events should be enabled, then specify an empty string.

Read access: Reads the current setting

POBJ_ACC_LIST #6 Pvi
Line
Device
Station
Cpu
Module
Task 		Read access: List of all process objects which have been created in PVI Manager under this process object. This list is returned as a string. The list includes the PVI name and the type of process objects.

Syntax of the process object list:
<ObjectName> OT=<ObjectType> \t
Object entries are separated by the \t character (tabulator).
POBJ_ACC_LIST_EXTERN #7 Pvi
Line
Device
Station
Cpu
Module
Task 		Read access: List of all process objects which can be created in PVI Manager under this process object. This list is returned as a string. The list includes the connection name and the type of process objects.

Syntax of the process object list:
<ConnectionName> OT=<ObjectType> \t
Object entries are separated by the \t character (tabulator).

Unlike POBJ_ACC_LIST, all process objects which can be created are shown in this list. This list is created by PVI Manager for process object types "Pvi" and "Line" and includes all lines or devices which were installed with PVI Setup. For all other process object types, this list is put together by the line being used. Which line for which process object type this access type supports can be found in the respective line description.

POBJ_ACC_CONNECT #10 CD Line
Device
Station
Cpu
Module
Task
Pvar 		Write access: Sets or modifies the connection description property of the process object. The connection description is specified as a string. Changing this connection description triggers the POBJ_EVENT_CONNECT event. If an empty string is specified as the connection description for a line object, then it and all subordinate process objects are handled as internal process objects.

Read access: Reads the currently set connection description (string format). The object hierarchy is not listed when using unique object names.

POBJ_ACC_DATA | #11 | Pvar | Write access / read access: Access to a variable object's data
POBJ_ACC_STATUS #12 Cpu
Module
Task
Pvar 		Write access / read access: Access to the status of a PLC object
To delete a PLC module, carry out a write access with the string "LD=Delete".
To delete PLC module payload (only possible for BR log data modules), write access must be performed using the string "LD=Clear".
POBJ_ACC_TYPE *) #13 AT
VT
CM 		Pvar Write access / read access: Reads and writes the object attributes property, the mode for type casting (cast mode) and/or data format of a variable object.
POBJ_ACC_TYPE_EXTERN #14 AT
VT 		Pvar Read access: Reads object attributes and data format description as well as the name of the structure definition and elements of a PLC variable.
POBJ_ACC_REFRESH #15 RF Pvar Refresh rate in ms.
= -1: Cyclic data refresh is disabled.
= 0: Data refresh is only performed once.
> 0: Cyclic data refresh takes place using the specified refresh time.

Write access: Sets or modifies the refresh rate of the process object. The refresh rate is specified as a 4-byte binary value (integer).

Read access: Reads the currently set refresh time (4-byte binary value)
POBJ_ACC_HYSTERESE *) #16 HY Pvar As with the HY parameter, event hysteresis is defined by a hysteresis value in string format. Unlike the object description however, the "HY=" parameter is left out here.

Write access: Sets or modifies event hysteresis of the variable object (string format)

Read access: Reads the currently set event hysteresis (string format)
POBJ_ACC_DEFAULT | #17 | DV | Pvar | Read access: Reads the set default value (DV parameter) of the variable object. The value is returned in string format.
POBJ_ACC_FUNCTION *) #18 FS Pvar As with the FS parameter, the data function is defined by a function description in string format. Unlike the object description however, the "FS=" parameter is left out here.

Write access: Sets or modifies the data function of the variable object (string format)

Read access: Reads the currently set data function (string format)
POBJ_ACC_TYPE_INTERN #19 AT
VT
CM 		Pvar Read access: Read the object attribute, data format description and the mode for type conversion (cast mode) of a PVI process variable object.
POBJ_ACC_UPLOAD | #20 | Modules | Read access: Reads BR module from PLC and saves it to a file The PVICOM function PviReadArgumentRequest or PviXReadArgumentRequest must be used for this access type.
POBJ_ACC_DOWNLOAD | #21 | CPU | Write access: Reads BR module from file and transfers it to PLC
POBJ_ACC_DATE_TIME #22 Pvi
Cpu
Module 		Reads and writes date and time. The data is transferred in binary form in the format of the "tm" structure. Date and time is defined as local time.

Definition of the "tm" structure in C/C++ (32-bit integer):

struct tm
{
int tm_sec; // seconds after the minute - [0,59]
int tm_min; // minutes after the hour - [0,59]
int tm_hour; // hours since midnight - [0,23]
int tm_mday; // day of the month - [1,31]
int tm_mon; // months since January - [0,11]
int tm_year; // years since 1900
int tm_wday; // days since Sunday - [0,6]
int tm_yday; // days since January 1 - [0,365]
int tm_isdst; // daylight savings time flag
};

Write access: Can only be used for process objects of type CPU. This sets the data and time of the PLC. The last three structure elements are not evaluated.

Read access: The mode of operation of the access depends on the process object type being used. With process object types Pvi or Cpu, current information about the date and time (local time zone) is read from the PC or PLC. With access via a process object of type Module, the date and time of creation or the last set date and time are read.
POBJ_ACC_MEM_DELETE #23 CPU Write access: Deletes specified data memory on the PLC. The memory type is defined by the LD parameter in the description string.

Syntax of the description string:
LD=<MemoryType>
<MemoryType>: Ram, SysRom, Rom, MemCard, FixRam, PerMem, RemMem, Trsf or the memory type as a numerical value
POBJ_ACC_MEM_INFO #24 CPU Read access: Reads information in string format about all existing PLC data memory.

Syntax of the description string:
{ < Entry1> } { <Entry2> } ... { <EntryN> }
Each <Entry> expression contains information for a certain memory type.
<Entry>: LD=<MemoryType> SL=<Length> SF=<LengthFree> SB=<Block>
<MemoryType>: Memory type (RAM, MemCard, etc.)
<Length>: Size of memory (total, in bytes)
<LengthFree>: Size of free memory (in bytes)
<Block>: Size of the largest free memory area (in bytes)

Example:
"{ LD=Ram SL=65535 SF=16384 SB=4096 } { LD=FixRam ... }"
POBJ_ACC_MOD_TYPE #25 Modules Read access: Reads information about a module in string format.

Syntax of the description string:
MT=<ModuleType> ML=<ModuleLength> [DL=<DataLength>] [VI=<Version>]
<ModuleType>: Module type as a numeric expression
<ModuleLength>: Length of the module in bytes
<DataLength>: Length of the payload in bytes.
<Version>: Version of the payload format.
The parameters DL and VI are only listed for BR log data modules.

POBJ_ACC_UPLOAD_STM | #26 | Modules | Read access: Reads a BR module from the PLC and transfers it to the application in the form of binary data. The PVICOM function PviReadArgumentRequest or PviXReadArgumentRequest must be used for this access type.
POBJ_ACC_DOWNLOAD_STM | #27 | CPU | Write access: Transfers BR module from binary user data to PLC
POBJ_ACC_MOD_DATA #28 Modules Read access: Reads payload data from a module.

Write access: Writes payload data from a module.

This access type can only be used in connection with BR log data modules.

POBJ_ACC_MOD_DELETE #29 CPU Write access: Deletes the BR module on AR.

Syntax of the description string:
MN=<ModuleName>
<ModuleName>: Name of the BR module:

The access type POBJ_ACC_MOD_DELETE is only supported by PVI Manager Version 3.50 (PviMan.exe file version) or higher, and by INA2000 Version 3.44 (LnIna2.dll file version).

POBJ_ACC_LIST_LINE #30 Pvi Read access: List of all list objects which can be created in PVI Manager under the PVI base object. This list is created by PVI Manager and includes all lines installed with PVI Setup in string format.

Syntax of the line object list:
<LineName1> \t <LineName2> ...
All object entries are separated with the character \t (tabulator).
<LineName>: Connection name for the line object.
POBJ_ACC_LIST_DEVICE #31 Line Read access: List of all device objects which can be created in PVI Manager under the line object. This list is created by PVI Manager and includes all device installed with PVI Setup for this line in string format.

Syntax of the device object list:
<DeviceName 1> \t <DeviceName 2> ...
All object entries are separated with the character \t (tabulator).
<DeviceName>: Connection name for the device object.
POBJ_ACC_LIST_STATION #32 Line
Device 		Read access: List of all station objects which can be created in PVI Manager under the corresponding process object. This list is created by the line being used. Which line for which process object type this access type supports can be found in the respective line description.

Syntax of the station object list with station names specification:
<StationName1> \t <StationName2> ...
All object entries are separated with the character \t (tabulator).
<StationName>: Connection name for the station object.

Syntax of the station object list with station number specification:
<MinNumber> <MaxNumber>
POBJ_ACC_LIST_CPU #33 Line
Device
Station 		Read access: List of all CPU objects which can be created in PVI Manager under the corresponding process object. This list is created by the line being used. Which line for which process object type this access type supports can be found in the respective line description.

Syntax of the CPU object list:
<CPUName1> \t <CPUName2> ...
All object entries are separated with the character \t (tabulator).
<CPUName>: Connection name for the CPU object.
POBJ_ACC_LIST_MODULE #34 Line
Device
Station
Cpu 		Read access: List of all module objects which can be created in PVI Manager under the corresponding process object. This list is created by the line being used. Which line for which process object type this access type supports can be found in the respective line description.

Syntax of the module object list:
<ModuleName1> \t <ModuleName2> ...
All object entries are separated with the character \t (tabulator).
<ModuleName>: Connection name for the module object.
POBJ_ACC_LIST_TASK #35 Line
Device
Station
Cpu
Module 		Read access: List of all task objects which can be created in PVI Manager under the corresponding process object. This list is created by the line being used. Which line for which process object type this access type supports can be found in the respective line description.

Syntax of the task object list:
<TaskName1> \t <TaskName2> ...
All object entries are separated with the character \t (tabulator).
<TaskName>: Connection name for the task object.
POBJ_ACC_LIST_PVAR #36 Line
Device
Station
Cpu
Module
Task 		Read access: List of all variable objects which can be created in PVI Manager under the corresponding process object. This list is created by the line being used. Which line for which process object type this access type supports can be found in the respective line description.

Syntax of the variable object list:
<VariableName1> [<Info>] \t <VariableName2> [<Info>] ...
All object entries are separated by the \t character (tab).
<VariableName>: Connection name for the task object.
<Info>: Description string for additional information

Syntax of the additional information:
[SC=<Scope>] [VT=<VariableType> ... ]
<Scope>: Scope of a variable on the PLC:
'g': global, 'l': local, 'd': dynamic object (also always local)
<VariableType>: Specification of the data format of a variable on the PLC. See also the POBJ_ACC_TYPE_EXTERN access type.
POBJ_ACC_CPU_INFO #50 CPU Read access: Reads CPU information in string format.

Syntax of the description string:
[CN=<CPUName>] [CT=<CPUType>] [AW=<ASWType>]
<CPUName>: Logical name of the CPU
<CPUType>: PLC type
<APMType>: Application memory type
POBJ_ACC_CANCEL #128 All Write access: Cancels sent PVI request. Request data is made up of a 4-byte integer value. A certain request or all requests can be canceled depending on this integer value.
=0: Cancels all requests
>0: Only cancels requests with the specified access type

The POBJ_ACC_CANCEL write access and the request to be canceled must be led via the same link object.
See also the Request and Response section.
POBJ_ACC_USERTAG #129 UT Module
Task Pvar 		With user tags, PVI applications can assign a private user code or specific user data to a process object (module, task, or variable object) in the form of a string (string terminated with 0) (see also event typePOBJ_EVENT_USERTAG). User tags are only managed by PVI, not evaluated.

Write access / read access: Access to the user tag string
POBJ_ACC_INFO_LICENCE | #200 | Pvi | Read access: Reads PVI Manager license information. License information is read in the format of the T_PVI_INFO_LICENCE structure.
POBJ_ACC_LIST_CLIENTS #210 Pvi Read access: List of all clients logged onto the PVI Manager (module names of PVICOM applications).

Syntax of the client list:
<ClientModule1> \t <ClientModule2> ...
All client entries are separated with the character \t (Tabulator).
POBJ_ACC_PVI_VERSION | #211 | Pvi | Read access: Read PVI version. Reads the PVI product version string saved in the PVI Manager.
POBJ_ACC_SNAPSHOT #240 All Write access: Executes Snapshot function. When calling, the name of the snapshot file needs to be specified as a string. A path can also be specified.

Only the process object for which the Snapshot function was activated and all subordinate process objects (object hierarchy) are written to the Snapshot file. For example, if the Snapshot function was triggered for a task object, then only this task object and the variable objects created underneath it are written to the Snapshot file. If information about all established objects in the PVI Manager should be written, then activation must take place using the global PVI object (base object "/Pvi").

All other functions in PVI Manager are blocked while the Snapshot function is carried out. This secures the consistency of the Snapshot data, but can also lead to immense timing variations when there are large quantities of data being handled by PVI Manager. Therefore, the Snapshot function should only be used sparingly.

Read access: Path name of the last specified Snapshot file (string format).

POBJ_ACC_PVIMAN_EXIT | #243 | Pvi | Write access: Close the PVI Manager. Keep in mind that for this type of access the response data is not defined.
Access type > 255 | Line access types for special line services
*) The POBJ_ACC_TYPE, POBJ_ACC_HYSTERESE and POBJ_ACC_FUNCTION can only be used to access the properties of the process object. They cannot be used to access the corresponding properties of the link object.

Line access types

Line access types are all access types with a number greater than 255. These access types are exclusively executed in the line being used. The request and response data is only passed on by PVI Manager.

Line access types are principally intended for internal communication between Automation Studio and Automation Runtime. Some of these line access types can also be used by PVI customer applications, however.

The following table lists all of the line access types permitted for use in PVI customer applications. The corresponding process object type is listed in the "Type" column.

Access types | No. | Type | Description
POBJ_ACC_LN_COMM_DST | #291 | CPU | Read access: Reads the communication parameters as a parameter string
POBJ_ACC_LN_LKN_LIST #296 CPU Read access: Reads list of link nodes

Syntax of optional parameters:
[QU=<Type>] [QP=<Name>]
All link nodes are read with "QU=All" (default). "QU=Pv" only reads the link node assigned
to a process variable. The variable name is defined by the QP parameter.
The following syntax applies to <Name> :
Global process variable: [<ApplicationModuleName>::]<PVName>
Local process variable: [<ApplicationModuleName>::]<TaskName>:<PVName>

Syntax of the link node list:
<LinkNode1> \t <LinkNode2> \t ...
Link node entries are separated by the \t character (tab).

POBJ_ACC_LN_XML_LIC_STATUS #351 CPU Read access: Reads the license status of the PLC as an XML string

Structure of the response data:

<?xml version="1.0" encoding="utf-8" ?>
<License>
  <Status Error="..." />
</License>
Error ... License status of the PLC
= 0 ... License status is valid.
>0 ... License status is invalid. Error returns the AR error status.
POBJ_ACC_LN_XML_CPU_INFO #400 CPU Read access: Reads CPU information as an XML string. This XML string contains more information than the one for the POBJ_ACC_CPU_INFO access type.

Structure of the response data:

<?xml version="1.0" encoding="utf-8" ?>
<CpuInfo>
  <SoftwareVers AutomationRuntime="..." AnslRtrVers="..." AnslServVers="..." ... />
  <CpuConfiguration Type="..." ShortName="..." Node="..."/>
  <OperationalValues CurrentCpuMode="..." CurrentCpuState="..." CurrentCpuUsage="..."
                     CpuBootMode="..." BatteryStatus="..." BatteryStatusBackplane="..." ... />
  <NetworkDevices>
    <Host Host="..."/>
    <Interface IF="..." IP="..." ... />
    ...
  </NetworkDevices>
  ...
</CpuInfo>
AutomationRuntime ... Current operating system (Runtime) version
AnslRtrVers ... Current version of the ANSL base system as a hexadecimal value
AnslServVers ... Current version of the ANSL online server as a hexadecimal value
Type ... Type of PLC (e.g. X20CP3568, APC910, etc.)
ShortName ... Short name of the PLC
Node ... Current node number of the PLC
CurrentCpuMode ... Current status of the PLC as a decimal value
= 1 ... Boot
= 2 ... Diagnose
= 3 ... Service
= 4 ... Run.
CurrentCpuState ... Current status of the PLC in INA2000 format
CurrentCpuUsage ... Current CPU load in % as a decimal value
CpuBootMode ... Last boot reason of the PLC as a decimal value
= 1 ... Warm restart
= 2 ... Cold restart
= 4 ... Watchdog
= 32 ... Diagnose
= 64 ... Error
BatteryStatus ... Status of the backup battery (1 = OK)
BatteryStatusBackplane ... Status of the backplane battery (1 = OK)
Host ... Hostname of the controller
IF ... Name of the network interface
IP ... IP address of the network interface
POBJ_ACC_LN_XML_MOD_INFO #401 Module
Task 		Read access: Reads PLC module information as an XML string.

Structure of the response data:

<?xml version="1.0" encoding="utf-8" ?>
<ModInfo Name="..." Size="..." MemType="..." Version="..." Revision="..."
         ModulType="..." Time="..." RawTimeErzT5="..." RawTimeAenT5="..." ... />
Name ... Name of the module
Size ... Size of the module in bytes as a decimal value
MemType ... Memory type as a decimal value
Version ... Version as a decimal value
Revision ... Revision as a decimal value
ModulType ... Module type as a decimal value
Time ... Timestamp when created in the format Year-Month-Day-Hour-Minute-Second. Seconds are specified with a decimal point (e.g. 2013-12-28-17-34-53.000000)
RawTimeErzT5 ... Timestamp when created in T5 format (e.g. e3-31-70-ec-38)
RawTimeAenT5 ... Timestamp when modified in T5 format (e.g. e3-31-70-ed-2f)
POBJ_ACC_LN_XML_TASK_INFO #402 Task Read access: Reads PLC task information as an XML string

Structure of the response data:

<?xml version="1.0" encoding="utf-8" ?>
<TaskInfo Name="..." Size="..." MemType="..." Version="..." Revision="..."
          ModulType="..." Time="..." RawTimeErzT5="..." RawTimeAenT5="..."
          TaskClass="..." InstallNo="..." ModulState="..." DiagIndex="..." ... />
The attributes for module information are the same as those for the POBJ_ACC_LN_XML_MOD_INFO access type.
TaskClass ... Assigned task class (task class number) as a decimal value
InstallNo ... Task installation number
ModulState ... Current task status as a decimal value
= 1 ... Not executable
= 2 ... Idle state
= 3 ... Run state
= 4 ... Stopped state
DiagIndex ... Module index as a decimal value (only if PLC is in diagnostics mode)
POBJ_ACC_LN_XML_MOD_LIST #403 CPU Read access: Reads the PLC module list as an XML string

Structure of the response data:

<?xml version="1.0" encoding="utf-8" ?>
<ModList>
  <TaskInfo Name="..." ... />
  <ModInfo Name="..." ... />
  ...
</ModList>
TaskInfo ... This element is specified for all modules of type Task. Its attributes are the same as those for the POBJ_ACC_LN_XML_TASK_INFO access type.
ModInfo ... This element is specified for modules not of type Task. Its attributes are the same as those for the POBJ_ACC_LN_XML_MOD_INFO access type.
POBJ_ACC_LN_XML_MEM_INFO #404 CPU Read access: Reads CPU memory information as an XML string

Structure of the response data:

<?xml version="1.0" encoding="utf-8" ?>
<StoreInfo>
  <Drive>
    <Drive0 ID="..." Name="..." Size="..." UsedSize="..." ... />
    ...
  </Drive>
  <Memory>>
    <xxx Type="..." Size="..." UsedSize="..." MaxBlockSize="..." ... />
    ...
  </Memory>
</StoreInfo>
xxx ... The type of memory should be specified in place of "xxx" (e.g. <SystemFlash>, <UserFlash>, <UserRam>, etc.).
ID ... Partition ID
Name ... Name of the partition
Type ... Memory type as a decimal value
Size ... Total size of the memory in bytes as a decimal value
UsedSize ... Size of currently used memory in bytes as a decimal value
MaxBlockSize ... The largest available memory block in bytes as a decimal value
POBJ_ACC_LN_XML_HW_INFO #405 CPU Read access: Reads PLC hardware information as an XML string

Structure of the response data:

<?xml version="1.0" encoding="utf-8" ?>
<<Hardware>
  <Node Name="..." Path="..." State="..." ... />
  ...
</<Hardware>
Name ... Name of the hardware node
Path ... Path of the hardware node
State ... Status of the hardware node
POBJ_ACC_LN_XML_RED_INFO #406 CPU Read access: Reads PLC redundancy information as an XML string

Structure of the response data:

<?xml version="1.0" encoding="utf-8" ?>
<CpuRedInfo rIfModeSwitch="..." LongPushTimeStamp="..." ShortPushTimeStamp="..."
            CpuModeSwitch="..." ProcessCtrlState="..." SwitchState="..." LinkState="..."
            ProjectName="..." ... >
  <PriIpConfig>
    <Device0 Name="..." Addr="..." SubNetMask="..." Hostname="..." BaudRate="..." ... />
    <Device1 Name="..." ... />
    ...
  </PriIpConfig>
  <SecIpConfig>
    <Device0 Name="..." Addr="..." SubNetMask="..." Hostname="..." BaudRate="..." ... />
    <Device1 Name="..." ... />
    ...
  </SecIpConfig>
  <CluIpConfig Addr="..." SubNetMask="..." />
  <ActIpConfig Addr="..." Hostname="..." AnslPort="..." ... />
  <InactIpConfig Addr="..." Hostname="..." AnslPort="..." ... />
</CpuRedInfo>
rIfModeSwitch ... The current position of the mode switch on the rIF
= 0 ... Illegal
= 1 ... Primary
= 2 ... Secondary
LongPushTimeStamp ... Timestamp of the last long button push on the rIF
ShortPushTimeStamp ... Timestamp of the last short button push on the rIF
CpuModeSwitch ... Priority of the rCPU (primary / secondary)
= 0 ... Illegal
= 1 ... Primary
= 2 ... Secondary
ProzessCtrlState ... State of the process control
= 0 ... Error
= 1 ... Active
= 2 ... Passive
= 3 ... Standby
SwitchState ... Redundancy mode (Hot / Warm / Cold / Cannot failover).
= 0x00 ... Cannot failover
= 0x10 ... Cold
= 0x20 ... Warm
= 0xff ... Hot
LinkState ... Status of the redundancy connection
= 0 ... None
= 1 ... Synchronous
= 2 ... Asynchronous
ProjectName ... Name of the redundancy project
PriIpConfig ... Section of the IP configuration for the primary CPU
SecIpConfig ... Section of the IP configuration for the secondary CPU
CluIpConfig ... Section of the IP configuration for the cluster interface (virtual address)
ActIpConfig ... Section of the IP configuration for the currently active CPU
InactIpConfig ... Section of the IP configuration for the currently inactive CPU
Addr ... IP address of the network interface
SubNetMask ... Subnet mask of the network interface
HostName ... Hostname of the network interface
BaudRate ... Baud rate of the network interface
AnslPort ... Port number for ANSL online communication

This access type can only be used on a redundant PLC system.

POBJ_ACC_LN_XML_TC_INFO #408 CPU Read access: Reads PLC task class information as an XML string

Structure of the response data:

<?xml version="1.0" encoding="utf-8" ?>
<TimingInfo>
  <TimerInfo>
    <System Tick="..." Device="..." ... />
    ...
  </TimerInfo>
  <TaskclassInfo>
    <Tc1 Name="..." Num="..." Cycle="..." Tolerance="..." State="..." ... />
    <Tc2 ... />
    ...
  </TaskclassInfo>
  ...
</TimingInfo>
TimerInfo ... Section for general timer information
Tick ... Configured system tick in µs as a decimal value
Device ... Configured device
TaskclassInfo ... Section for task class information
Name ... Name of the task class
Num ... Number of the task class as a decimal value
Cycle ... Configured cycle time of the task class in µs as a decimal value
Tolerance ... Configured tolerance of the task class in µs as a decimal value
State ... Current status of the task class as a decimal value
= 1 ... Run status
= 2 ... Suspended status

XML string

XML (Extensible Markup Language) is a standardized markup language for depicting hierarchically structured data in text form. Some PVI access types return the response data as a string in XML format. Parameter groups (e.g. an entry in a list ) are then structured in XML elements. The individual parameters within these elements are usually specified as XML attributes.

The following must be taken into consideration when evaluating XML response data in PVI applications:

  • A suitable parser must be used for the evaluation.
  • XML data from newer AR versions may contain new XML elements or attributes.
    In order to ensure compatibility, PVI applications must always ignore unknown XML elements and attributes.
  • Existing XML elements and attributes may also be made obsolete if they no longer have relevance in a newer AR version.
    PVI applications must take these cases into consideration through the implementation of suitable measures (e.g. assigning default values).
  • Numerical values in XML attributes can be specified in either decimal (Param="123") or hexadecimal format (Param="0x7b").

POBJ_ACC_DATA access type

Write access: Write process data. The data is first written to the PVI process image. Transferring to the PLC then takes place when external variables are used. Termination of the write procedure is reported along with the response data. This also guarantees that the data has been transferred to the PLC. If the "h" object attribute is specified however, then the response data is sent to the application right after writing to the PVI process image. The application therefore receives a quicker write response. When the response data is received however, it cannot be guaranteed that the data has actually been written to the PLC.

Read access: Activates a read request for process data. Data is read from the PLC and sent with the response data to the application. If the process data changes, then a POBJ_EVENT_DATA event is triggered along with the response data.

POBJ_ACC_STATUS access type

This access type is used to read or set a process object's status. This status is defined using a status description in string format. Processing this status description is done in the line being used. Which line this access type supports can be found in the respective line description.

Write access:

Object type | Syntax
CPU | ST=<Status> <Status>: WarmStart, ColdStart, Reset, Diagnose
Modules | LD=Delete Deletes module object on the PLC
Task | ST=<Status> <Status>: Start, Stop, Resume, Cycle, Cycle(<Number>).

Read access:

Object type | Syntax
CPU | ST=<Status> <Status>: WarmStart, ColdStart, Reset, Reconfiguration, NMI, Diagnose, Error
Modules | ST=<Status> [LD=<LoadType>] [ID=<Identification>] <Status>: NonExisting, Exists, Loading, Incomplete, Complete, Ready, InUse. <LoadType>: SysRam, Ram, SysRom, Rom, MemCard, FixRam, DRam, PerMem, RemMem, Trsf. <Identification>: Identification number for the most current logbook entry for BR log data modules
Task | ST=<Status> <Status>: NonExisting, Unrunnable, Idle, Running, Stopped, Starting, Stopping, Resuming, Resetting
Pvar | ST=<Status> [FC=<Force>] [IO=<Attribute>] [SC=<Scope>] <Force>: Force state 1 or 0 <Attribute>: "r" .. input, "w" .. output <Status>: "Const" for constants, "Var" for variables, or "Lkn" for link node <Scope>: Scope of the variables on the PLC: 'g': .. global, 'l': .. local, 'd': .. dynamic object (also always local).

POBJ_ACC_TYPE access type

This access type is used to read or set process object object attributes, data formats and modes for type casting. This access type works with a description in string format. Like the object description, individual parameters are differentiated in a string with parameter codes.

The description can include the following parameters:
AT, VT, VL, VN, VS, AL, CM.

To ensure compatibility with older versions of PVI (earlier than V3.0.0), the parameter VS is not specified for "simple" array variables (one-dimensional array with more than one array element, array index starts at 0, not a derived data type). To identify a variable as an array variable, the parameter VN must also be evaluated in addition to the additional specification 'a'. The following condition applies: Array variable if VS=...a... or VN > 1.

Write access: Properties for object attributes, data format and/or type casting mode are set for the process object depending on the specifications in the description string. These properties can either be set individually or together with one another. For example, the "AT=r" string only sets the object attribute. Other properties remain unchanged.
A POBJ_EVENT_DATAFORM event is triggered when the data format changes.
If the data format for the process object is specified by the line, then the application cannot change it. Any attempt will be rejected with Error 12039.

Read access: Reads the properties for object attribute, data format, and type casting mode set in the process object.

POBJ_ACC_TYPE_INTERN access type

The POBJ_ACC_TYPE_INTERN access type reads the properties for the object attributes and data format of a PVI variable. Unlike the access type POBJ_ACC_TYPE_EXTERN, the properties of the variable are read from the PVI process image.

The description can include the following parameters:
AT, VT, VL, VN, VS, AL, CM, VO.

In the read direction, the access type POBJ_ACC_TYPE_INTERN is an extension of the access type POBJ_ACC_TYPE. The access type POBJ_ACC_TYPE_INTERN can be used to read the following information.

Par. | Description
VO | Relative offset of the structure element. The offset specified here refers to the PVI process image in the process variable object. If no cast function has been defined, the data format of the process image is the same as the data coming from PVI.

For structure variables, the name of the structure element can be specified when specifying the data format of the structure elements.

{.<ElementName1>[.<ElementName2>] ... }

Read access: Reads the properties for object attribute, data format, and type casting mode set in the process object.

POBJ_ACC_TYPE_EXTERN access type

The POBJ_ACC_TYPE_EXTERN access type reads the properties for the object attributes and data format of a PLC variable. Unlike the access types POBJ_ACC_TYPE and POBJ_ACC_TYPE_INTERN, the properties of the variable are read from the PLC. These may deviate from the properties of the variable in the PVI image. Processing the read request is done in the PVI line being used. Which line this access type supports can be found in the respective line description.

The description can include the following parameters:
AT, SC, VT, VL, VN, VS, AL, SN, TN, VO, VE.

The data format parameters VT, VL, VN, VS and AL are the parameters from the object description. All other parameters are optional, and can differ from the object description.

Unlike the object attributes for variable objects, AT is defined as follows:

AT | Description
r | Read access to the data in the variable is allowed
w | Write access to the data in the variable is allowed
e | PLC event control is possible for this variable

The SC parameter (scope) is used to display the scope of a variable on the PLC:

SC | Description
g | Global PLC variable.
l | Local PLC variable (task variable).
d | Dynamic PLC variable.

Still more information can be specified with the data format of the variable:

Par. | Description
VS | Additional specifications for the data type.
SN | Name of the superior type for enumeration or structure variables.
TN | Name of the derived data type. If a data type is derived multiple times, the name of each data type is listed. Individual names are separated by a "," (comma).
VO | Variable offset or relative structure element offset The offset specified here refers to the PLC variable and not to the process image in the PVI.
VE | Element information used internally by the line.

The parameters SN, TN, VO and VE are optional additions to the data format. The entry depends on the line and access type.

The VS parameter is only given if additional specifications are present. An additional specification consists of a specification ID and optional specification parameters. The VS parameter can also contain several additional specifications (<Spec>). These specifications are always separated by the ';' (semicolon) character. The specification parameters are separated from each other and from the specification ID by "," (commas).

General syntax:

VS=<Spec1>[,<Para1>[,<Para2>[, ... ]]][;<Spec2>[, ... ]]

The following additional specifications can be specified:

VS | Description
a[,<Inx1>,<Inx2>] | Identifies a one dimensional array variable or an array dimension of a multidimensional variable. The specification parameters <Inx1> and <Inx2> define the permissible array index (lower index, upper index). The number of array elements (array dimension) can be determined by <Inx2> - <Inx1> + 1. The array index can also take on negative values.
v[,<Val1>,<Val2>] | Identifies a derived data type. <Val1> and <Val2> can be used to specify a valid range for variable data in integer format (lower bound, upper bound).
e[,<Val>,<Name>] | Identifies an enumeration type or an enumerator. Every enumerator consists of a value <Val> and a name <Name>.
b | Identifies a bit string (bit list). The data type (VT parameter) can be u8, u16, u32 or u64.

The additional specifications "a", "v" and "e" can be entered multiple times. Each entry of additional specification "a" describes an array dimension. The first entry describes the outermost array dimension; the last entry describes the innermost array dimension (Example: var[0..9][0..4] or var[10][5], two-dimensional variable with 50 elements => "VS=a,0,9;a,0,4"). Each entry of additional specification "v" describes a derived data type. The name of the derived data type is also listed in the same order in the parameter TN. The order can also be used to assign the derived data type to array dimensions (example: Typ1[0..9], Typ2[0..4], variable is derived from Typ2, Typ2 is derived from Typ1 => "TN=Typ1,Typ2 VS=a,0,9;v;a,0,4;v").

To ensure compatibility with older versions of PVI (earlier than V3.0.0), the parameter VS is not specified for "simple" array variables (one-dimensional array with more than one array element, array index starts at 0, not a derived data type). To identify a variable as an array variable, the parameter VN must also be evaluated in addition to the additional specification 'a'. The following condition applies: Array variable if VS=...a... or VN > 1.

With structure variables, the names of structure elements can be specified with the description of their data format.

{.<ElementName1>[.<ElementName2>] ... }

Read access: Properties of the object can be read, such as object attributes, data format, name of derived data types, name of the structure definition, and all elements of structures.

Access types POBJ_ACC_TYPE_INTERN (or POBJ_ACC_TYPE) and POBJ_ACC_TYPE_EXTERN can also return different data formats. Note that only the POBJ_ACC_TYPE_INTERN access type (or POBJ_ACC_TYPE or a POBJ_EVENT_DATAFORM event) can describe the format of process data in the PVI process image.

POBJ_ACC_UPLOAD and POBJ_ACC_UPLOAD_STM access types

These access types are used to read BR modules from the PLC. The PVICOM function PviReadArgumentRequest or PviXReadArgumentRequest must be used since the application also has to define filenames and module parameters with the read request. The application receives either a confirmation of the upload or an error with the response data (PviReadResponse or PviXReadResponse). An upload is always regulated via a PVI module object. The name of the module on the PLC is defined with the connection description of the process object.

The module data is stored in the specified file with the POBJ_ACC_UPLOAD access type. Note that all directories specified in the path name have to already exist when the function is called. The path is always based on the working directory of the PVI manager. In order to transfer the module data via a PVI remote connection, access type POBJ_ACC_UPLOAD_STM must be used.

Module data is transferred to the application with the response data as binary data with POBJ_ACC_UPLOAD_STM. In this case, the length of the module data corresponds to the length of the response data.

If the module type is not defined in the calling string (MT parameter not specified), then the module data being read corresponds to the finished BR module on the PLC. If the module type is defined in the calling string (MT parameter specified), then the payload is extracted from the specified BR module. The module data being read then includes only the payload of the BR module.

Syntax of the calling string for POBJ_ACC_UPLOAD:

["]<Filename>["] [MT=<ModuleType> ...]

or

FN=["]<Filename>["] [MT=<ModuleType> ...]

The variant with the FN parameter entries cannot be used with the INA2000 line.

Syntax of the calling string for POBJ_ACC_UPLOAD_STM:

[MT=<ModuleType> ...]

Upload parameters in the calling string:

Par. | Description
MT | Module type for module compilation. Additional parameters can be specified in the calling string depending on the compilation library being used (INA2000 or ANSL).

Example of access type POBJ_ACC_UPLOAD in C:

#include <PviCom.h>

static void WINAPI PviUploadResp (WPARAM wParam, LPARAM lParam)
{
    int ErrCode;

    ErrCode = PviReadResponse (wParam, NULL, 0);
    if (ErrCode != 0)
        printf ("Problem uploading module (PVI Error %d)", ErrCode);
}

void UploadRequ (DWORD hModule, char* szFileName)
{
    int  ErrCode;

    // start PVI upload service:
    ErrCode = PviReadArgumentRequest (hModule, POBJ_ACC_UPLOAD,
                                      szFileName, strlen (szFileName) + 1,
                                      PviUploadResp, SET_PVICALLBACK, 0);
    if (ErrCode != 0)
        printf ("Can't start upload service (PVI Error %d)", ErrCode);
}

Example of access type POBJ_ACC_UPLOAD_STM in C:

#include <PviCom.h>

static void WINAPI PviUploadResp (WPARAM wParam, LPARAM lParam)
{
    DWORD DataLen = 0;
    void* pData = NULL;
    int   ErrCode;
    char  szFilename[256];
    FILE* stream;

    PviGetResponseInfo (wParam, NULL, &DataLen, NULL, 0);
    if (DataLen != 0)
    {
        // create data buffer:
        pData = malloc (DataLen);
        if (pData == NULL)
        {
            printf ("Can't allocate memory");
            DataLen = 0;
        }
    }

    // read module data:
    ErrCode = PviReadResponse (wParam, pData, DataLen);
    if (ErrCode != 0)
        printf ("Problem uploading module (PVI Error %d)", ErrCode);
    else
    {
        // write module data to file:
        sprintf (szFilename, "C:\\List\\Module%u.bin", lParam);
        if ((stream = fopen (szFilename, "wb")) != NULL)
        {
            fwrite (pData, 1, DataLen, stream);
            fclose (stream);
        }
        else
            printf ("Can't create file %s", szFilename);
    }

    if (pData != NULL)
        free (pData);
}

void UploadRequ (DWORD hModule, DWORD ModuleNum)
{
    char* szParam;
    int   ErrCode;

    szParam = "";
    ErrCode = PviReadArgumentRequest (hModule, POBJ_ACC_UPLOAD_STM,
                                      szParam, strlen (szParam) + 1,
                                      PviUploadResp, SET_PVICALLBACK, ModuleNum);
    if (ErrCode != 0)
        printf ("Can't start upload service (PVI Error %d)", ErrCode);
}

POBJ_ACC_DOWNLOAD and POBJ_ACC_DOWNLOAD_STM access types

These access types are used to write BR modules to the PLC. To carry out a download procedure, the PVICOM function PviWriteRequest or PviXWriteRequest must be used. The application receives either a confirmation of the download or an error with the response data (PviWriteResponse or PviXWriteResponse). A download is always regulated via a PVI CPU object.

Module data is read from the specified file with the POBJ_ACC_DOWNLOAD access type. The path is always based on the working directory of the PVI manager. In order to transfer the module data via a PVI remote connection, access type POBJ_ACC_UPLOAD_STM must be used.

The application must transfer the module data with the request data using POBJ_ACC_DOWNLOAD_STM. A data block must be created for this. This data block needs to include the calling string and the binary module data, and the request function (PviWriteRequest or PviXWriteRequest) must be transferred. The size of the data block in bytes is calculated from the length of the calling string + the size of the binary module data + 1. The calling string in ASCII format (character length is 1 byte) must always be at the beginning of the data block and terminated with a binary 0 (null). The binary module data must begin right after the null byte. If a calling string is not needed, then an empty string should be specified in the data block.

If the module type is not defined in the calling string (MT parameter not specified), then the module data needs to include a finished BR module. If the module type is defined in the calling string (MT parameter specified), then the module data is regarded as payload from a BR module. PVI then generates a finished BR module from this payload and module type information and transfers it to the PLC.

Syntax of the calling string for POBJ_ACC_DOWNLOAD:

["]<Filename>["] [LD=<MemoryType>] [IM=<InstallationMode>] [MT=<ModuleType> MN=<ModuleName> ...]

or

FN=["]<Filename>["] [LD=<MemoryType>] [IM=<InstallationMode>] [MT=<ModuleType> MN=<ModuleName> ...]

The variant with the FN parameter entries cannot be used with the INA2000 line.

Syntax of the calling string for POBJ_ACC_DOWNLOAD_STM:

[LD=<MemoryType>] [IM=<InstallationMode>] [MT=<ModuleType> MN=<ModuleName> ...]

Download parameters in the calling string:

Par. | Description
MT | Module type for module compilation. Additional parameters can be specified in the calling string depending on the compilation library being used (INA2000 or ANSL).
MN | Name of the BR module on the PLC This parameter only takes effect in connection with the module compilation (parameter MT). With a standard download, the module name entered in the BR module is used.
LD | Load type (memory type). Default "LD=Ram". The load type selects the target memory on the PLC for the download. The following memory types can be specified: SysRam, Ram, SysRom, Rom, MemCard, FixRam, DRam, Trsf or the load type (memory type) as a numerical value.
IM | Installation mode Default "IM=Overload". The installation mode determines how a task module is transferred. Overload: Standard mechanism. Copy: Exchange is several cycles. OneCycle: Exchange in one cycle.

Example of access type POBJ_ACC_DOWNLOAD in C:

#include <PviCom.h>

static void WINAPI PviDownloadResp (WPARAM wParam, LPARAM lParam)
{
    int ErrCode;

    ErrCode = PviWriteResponse (wParam);
    if (ErrCode != 0)
        printf ("Problem downloading module (PVI Error %d)", ErrCode);
}

void DownloadRequ (DWORD hCpu, char* szFileName)
{
    char szParam[256];
    int  ErrCode;

    // start PVI download service:
    sprintf (szParam, "%s LD=Rom", szFileName);
    ErrCode = PviWriteRequest (hCpu, POBJ_ACC_DOWNLOAD,
                               szParam, strlen (szParam) + 1,
                               PviDownloadResp , SET_PVICALLBACK, 0);
    if (ErrCode != 0)
        printf ("Can't start download service (PVI Error %d)", ErrCode);
}

Example of access type POBJ_ACC_DOWNLOAD_STM in C:

#include <PviCom.h>

static void WINAPI PviDownloadResp (WPARAM wParam, LPARAM lParam)
{
    int ErrCode;

    ErrCode = PviWriteResponse (wParam);
    if (ErrCode != 0)
        printf ("Problem downloading module (PVI Error %d)", ErrCode);
}

void DownloadRequ (DWORD hCpu, char* szModuleName)
{
    char  szFilename[256];
    FILE* stream;
    long  FileLen;
    char  szParam[256];
    long  ParamLen;
    void* pRequData;
    int   ErrCode;

    // open file:
    sprintf (szFilename, "C:\\List\\%s.bin", szModuleName);
    if ((stream = fopen (szFilename, "rb")) != NULL)
    {
        // get file length:
        fseek (stream, 0, SEEK_END);
        FileLen = ftell (stream);

        // PVI download parameter:
        sprintf (szParam, "MT=BRT MN=%s LD=DRam", szModuleName);
        ParamLen = strlen (szParam) + 1;

        // create request data buffer:
        pRequData = malloc (ParamLen + FileLen);
        if (pRequData != NULL)
        {
            // prepare request data buffer:
            memcpy (pRequData, szParam, ParamLen);
            fseek (stream, 0, SEEK_SET);
            FileLen = fread ((BYTE*) pRequData + ParamLen, 1, FileLen, stream);

            // start PVI download service:
            ErrCode = PviWriteRequest (hCpu, POBJ_ACC_DOWNLOAD_STM,
                                       pRequData, ParamLen + FileLen,
                                       PviDownloadResp , SET_PVICALLBACK, 0);
            if (ErrCode != 0)
                printf ("Can't start download service (PVI Error %d)", ErrCode);

            free (pRequData);
        }
        else
           printf ("Can't allocate memory");

        fclose (stream);
    }
    else
        printf ("Can't open file %s", szFilename);
}

POBJ_ACC_MOD_DATA access type

This access type can be used to read payload data from BR log data modules or to write an entry to the BR log data module.

Read access:

The read access is initiated with the PVICOM function PviReadArgumentRequest or PviXReadArgumentRequest. The argument parameters specified in the calling string define the log data to be read. If the read access should only be done with the default argument parameters, the PVICOM function PviReadRequest can also be used. The application receives either the requested log data or an error with the response data (PviReadResponse or PviXReadResponse).

Each logbook entry in a BR log data module has a unique identification number (ID). The identification number is increased by one with each new log entry. Once the number counter is overrun, the identification numbers begin at zero again. If the identification number is used to find out a difference, this condition needs to be taken into consideration.

Log entries can be read starting from a certain identification number or from the last (most current) logbook entry. The identification number of the most current log entry for a BR log data module can also be determined using the POBJ_ACC_STATUS access type or the POBJ_EVENT_STATUS event type.

Syntax of the calling string:

[DN=<Number>] [ID=<Identification>]

Argument parameters in the calling string:

Par. | Description
DN | Number of log entries to be read. Default: DN=1
ID | Identification number of the first entry to be read. If the parameter ID is not specified, then reading takes place from the last (most current) entry.

Syntax of the response string:

Response data consists of individual ASCII strings. Each of these strings is terminated with a null character ("\0" character). The next string begins directly after the null character.

<AccessInformation> \0 <LogEntry1> \0 <LogEntry2> \0 ... \0 <LogEntryN> \0

The first string contains general access information:

Par. | Description
DN | Number of log entries read. The number of subsequent strings is calculated from DN * 3.

Three strings are listed for each read logbook entry (<LogEntry>). The (<Information>) string contains general information about the logbook entry. Next comes the string with the message text (<ASCIILogData>) followed by a string with binary log data (<BinaryLogData>) in hex format. If there is no ASCII or binary log data, then an empty string (only the null character) is listed.

In the response data, the first log entry (<LogEntry1>) is always the newest of the logbook entries read.

<Information> \0 <ASCIILogData> \0 <BinaryLogData>

Parameters in the information string:

Par. | Description
TLEN | Number of characters in the string for the message text (ASCII log data) without the null character.
BLEN | Number of characters in the string for the binary log datas without the null character.
TIME | Timestamp in seconds as a decimal number with decimal places. The number of positions after the decimal defines the resolution of the timestamp.
ID | Log entry identification number.
E | Error number assigned to the log entry as a decimal number.
INFO | Additional information as a decimal number.
LEV | Level of the log entry as a decimal number.
TN | Task name (specified in quotes: TN="<Name>").

Write access:

The write access is initiated with the PVICOM function PviWriteRequest or PviXWriteRequest. An entry is written to the BR log data module on the PLC for each write access.

Syntax of the calling string:

TXT=["]<Text>["] [LEV=<Level>] [E=<ErrorCode>]

Argument parameters in the calling string:

Par. | Description
TXT | Log text. If the text contains spaces or special characters, then the text must be placed inside quotation marks.
LEV | Optional level of the log entry as a decimal value (default: "LEV=1")
E | Optional specification of an error code as a decimal value (default : "E=0")

It is not possible to write binary data.

Example for reading with access type POBJ_ACC_MOD_DATA in C:

#include <PviCom.h>

//////////////////////////
// Parse PVI Parameter: //
//////////////////////////

static bool GetNextParam (const char** pszDesc,
                          char* szKeywordBf, int KeywordBfLen,
                          char* szParamBf,   int ParamBfLen)
{
    const char* szDesc = *pszDesc;
    char  EndChr = ' ';

    // skip space characters:
    while (*szDesc == ' ')
        szDesc++;

    // copy keyword:
    while (isalpha (*szDesc))
        if (--KeywordBfLen > 0)
            *(szKeywordBf++) = (char) toupper (*(szDesc++));
        else
            szDesc++;
    *szKeywordBf = '\0';

    if (*szDesc == PVICHR_ASSIGN)
    {
        // skip space characters:
        while (*(++szDesc) == ' ');

        // test parameter spezification:
        if (*szDesc == PVICHR_PARAM)
        {
            szDesc++;
            EndChr = PVICHR_PARAM;
        }

        // copy parameter:
        while ((*szDesc != '\0') && (*szDesc != EndChr))
            if (--ParamBfLen > 0)
                *(szParamBf++) = *(szDesc++);
            else
                szDesc++;
        *szParamBf = '\0';

        if (*szDesc == PVICHR_PARAM)
            szDesc++;
        *pszDesc = szDesc;
        return (TRUE);
    }
    *pszDesc = szDesc;
    return (FALSE);
}

bool FindParam (const char* szDesc,
                const char* szKeyword,
                char* szParamBf, int ParamBfLen)
{
    char szKeywordBf[16];

    while (GetNextParam (&szDesc, szKeywordBf, 16, szParamBf, ParamBfLen))
        if (strcmp (szKeywordBf, szKeyword) == 0)
            return (TRUE);
    return (FALSE);
}

////////////////////////////////
// Read logging informations: //
////////////////////////////////

typedef struct
{
    bool  bValid;
    DWORD Level;
    DWORD Error;
    char  Task[32+1];
    char  Text[80+1];
} T_LOGDATA;

static HANDLE hReadLogEvent;

// PVI callback function:
static void WINAPI ReadLogProc (WPARAM wParam, LPARAM lParam,
                                LPVOID pData, DWORD DataLen,
                                T_RESPONSE_INFO* pInfo)
{
    const char* szDesc = (const char*) pData;
    T_LOGDATA* pLogData = (T_LOGDATA*) lParam;
    char szParamBf[256];
    int Entries = 0;

    if (DataLen > 0)
        if (FindParam (szDesc, KWDESC_DATACNT, szParamBf, sizeof (szParamBf)))
            Entries = strtol (szParamBf, NULL, 10);

    while (Entries-- > 0)
    {
        // parse informations (string 1):
        szDesc += (strlen (szDesc) + 1);
        if (! FindParam (szDesc, "LEV", szParamBf, sizeof (szParamBf)))
            pLogData->Level = 0;
        else
            pLogData->Level = strtoul (szParamBf, NULL, 10);
        if (! FindParam (szDesc, "E", szParamBf, sizeof (szParamBf)))
            pLogData->Error = 0;
        else
            pLogData->Error = strtoul (szParamBf, NULL, 10);
        if (! FindParam (szDesc, "TN", pLogData->Task, sizeof (pLogData->Task)))
            strcpy (pLogData->Task, "???");

        // copy ASCII data (string 2):
        szDesc += (strlen (szDesc) + 1);
        strncpy (pLogData->Text, szDesc, (sizeof (pLogData->Text)-1));
        pLogData->Text[sizeof (pLogData->Text)-1] = '\0';

        // skip binary data (string 3):
        szDesc += (strlen (szDesc) + 1);

        pLogData->bValid = TRUE;
        pLogData++;
    }
    SetEvent (hReadLogEvent);
}

// Read logging informations from module object:
void ReadLog (DWORD LinkId,        // PVI module object handle
              T_LOGDATA* pLogData, // pointer to data buffer
              DWORD ReadCnt)       // entries to read
{
    char szArgParam[32];
    int i;

    // reset data buffer:
    for (i = 0; (i < ReadCnt); i++)
        pLogData[i].bValid = FALSE;

    hReadLogEvent = CreateEvent (NULL, FALSE, FALSE, NULL);
    sprintf (szArgParam, "%s=%u", KWDESC_DATACNT, ReadCnt);

    // request read service:
    if (PviReadArgumentRequest (LinkId, POBJ_ACC_MOD_DATA,
                                szArgParam, strlen (szArgParam), ReadLogProc,
                                SET_PVICALLBACK_DATA, (LPARAM) pLogData) == 0)
        WaitForSingleObject (hReadLogEvent, INFINITE);

    CloseHandle (hReadLogEvent);
}

<< Previous Topic
Order of request execution

Start Page

Next Topic >>
Event


Event

Events are used to send data, status, or property changes in process objects from PVI Manager to the PVI application.

To receive events, a PVI application must define a user message when creating the link object. Link objects are set up with the PVICOM functions PviCreateRequest / PviXCreateRequest or PviLinkRequest / PviXLinkRequest. The following picture shows the basic sequence for events.

All events are guided with link objects. In addition to the user message, the link object also manages a release mask for events. The event mask is used to release or suppress certain event types. As with the user message, the release mask can be defined when setting up a link object. This is done with the EV parameter in the link object description. The release mask can also be modified at a later time with the POBJ_ACC_EVMASK access type. The enable mask is specified as a string. Individual event types are defined with code letters.

In this section the following topics are discussed:

Event

Receive event

Event types

<< Previous Topic
Access types

Start Page

Next Topic >>
Receive event


Receive event

The PviReadResponse or PviXReadResponse has to be called in order to read event data or confirm when responses are received.

Event information such as its type, length of the event data, and the RESPONSE_INFO structure can be read beforehand with the PviGetResponseInfo or PviXGetResponseInfo. One exception is using the callback function of type PVICALLBACK_DATA as a user message. Since response data is passed along directly to the callback function, it does not have to be read using a PVICOM function.

Unlike response data, event data can be overwritten when being transported to the PVI application. If event data is not transported and read by the PVI application with at least the same speed as which they occur, then event data piles up in memory until there is no more system memory available. Overwriting prevents ever-increasing system memory needs. Only events from the same link object and event type are overwritten. The RESP_STATUS_OVERWRITE flag in the status of the event data (RESPONSE_INFO structure) is set if event data has been overwritten by newer data.

<< Previous Topic
Event

Start Page

Next Topic >>
Event types


Event types

To receive events, a PVI application needs to define a user message when a link object is created.

Some event types are generated by PVI Manager, others are generated by the line. Therefore, which event types can be used depends on the PVI line being used.

All event types are listed in the following table. The "EV" columns lists the corresponding code letters for enabling the event type (EV parameter).

Event types | No. | EV | Description
POBJ_EVENT_ERROR | #3 | e | Signals a change in the error state or error code of a process object
POBJ_EVENT_CONNECT | #10 | c | Signals a change in the connection description of a process object. The event data contains the connection description in the format of the POBJ_ACC_CONNECT access type.
POBJ_EVENT_DATA | #11 | d | Signals a change in a variable object's process data or an end to a process object's error state
POBJ_EVENT_STATUS | #12 | s | Signals a status change in the process object. The event data contains the status in the format of the POBJ_ACC_STATUS access type. This event is generated by the line being used and formatted accordingly by PVI Manager. Which line this status event supports can be found in the respective line description.
POBJ_EVENT_DATAFORM | #13 | f | Signals a change in a variable object's data format
POBJ_EVENT_PROCEEDING | #128 | p | This event informs a PVICOM application about the progress of active requests. The POBJ_EVENT_PROCEEDING event is only sent to the application which made the request. This progress information is sent as a PROCEEDING_INFO structure. This event is generated by the line being used and formatted accordingly by PVI Manager. Which line this progress event supports can be found in the respective line description.
POBJ_EVENT_USERTAG | #129 | u | Signals a change in the user tag. The event data contains the user tag in string format (see also access type POBJ_ACC_USERTAG).
Event type > 255 |  | l | Indicates special line events.

Line event types

Line events are all event types with a number greater than 255. These events are generated by the line being used and are only forwarded by PVI Manager. Which PVI line these line events supports can be found in the respective line description.

Line events are principally intended for internal communication between Automation Studio and Automation Runtime. Some of these event types can also be used by PVI customer applications, however.

The EV parameter can be used to enable all line events of an object. Enabling event types individually is not possible. For this reason, a PVI application must acknowledge all received line events by calling the PVICOM function PviReadResponse or PviXReadResponse. Line events that are not needed by the PVI application or those that cannot be interpreted can then be ignored.

The following table lists all of the line event types permitted for use in PVI customer applications. The corresponding process object type is listed in the "Type" column.

Event types No. Type Description
POBJ_EVENT_LN_XML_MOD_LIST #403 CPU Indicates a change to a PLC module list
All new, modified or deleted modules are listed in an XML string in the event data. The POBJ_ACC_LN_XML_MOD_LIST access type can be used to read the complete module list.

Structure of the list of modifications:

<?xml version="1.0" encoding="utf-8"?>
<ModList>
  <Deleted>
    <TaskInfo Name="..." />
    <ModInfo Name="..." />
    ...
  </Deleted>
  <New>
    <TaskInfo Name="..." ... />
    <ModInfo Name="..." ... />
    ...
  </New>
  <Changed>
    <TaskInfo Name="..." ... />
    <ModInfo Name="..." ... />
    ...
  </Changed>
</ModList>
Delete ... Section for deleted modules / task modules
New ... Section for new modules / task modules
Changed ... Section for changed modules / task modules

The section for new and modified modules and task modules contains the complete module or task information of the POBJ_ACC_LN_XML_MOD_INFO and POBJ_ACC_LN_XML_TASK_INFO access types.

POBJ_EVENT_LN_XML_RED_CTRL #440 CPU Indicates a redundancy failover and other events on redundant PLC systems
The type of the event is listed in an XML string in the event data.

Structure of the event data:

<?xml version="1.0" encoding="utf-8"?>
<CpuRedCtrl Cmd="..." ... />
Cmd ... Specifies the type of the redundancy event
Cmd="1" ... Indicates that a redundancy failover has taken place
Cmd="2" ... Application synchronization is active or has ended
In principle, the "Cmd" attribute can also contain other values. For this reason, PVI applications must ignore all events with unknown values in Cmd.

The POBJ_ACC_LN_XML_RED_INFO access type can be used to specify the active and standby CPU.

XML string

XML (Extensible Markup Language) is a standardized markup language for depicting hierarchically structured data in text form. Some PVI event types return the event data as a string in XML format. Parameter groups (e.g. an entry in a list ) are then structured in XML elements. The individual parameters within these elements are usually specified as XML attributes.

The following must be taken into consideration when evaluating XML event data in PVI applications:

  • A suitable parser must be used for the evaluation.
  • XML data from newer AR versions may contain new XML elements or attributes.
    In order to ensure compatibility, PVI applications must always ignore unknown XML elements and attributes.
  • Existing XML elements and attributes may also be made obsolete if they no longer have relevance in a newer AR version.
    PVI applications must take these cases into consideration through the implementation of suitable measures (e.g. assigning default values).
  • Numerical values in XML attributes can be specified in either decimal (Param="123") or hexadecimal format (Param="0x7b").

POBJ_EVENT_ERROR Event Type

This event is sent each time the error state or error code of a process object changes. The error code is given as a return value from the PviReadResponse or PviXReadResponse function. The end of the error state is signaled by error code 0 (null). However, if the POBJ_EVENT_DATA event type is enabled, then the end of the error state is only signaled by a POBJ_EVENT_DATA event.

A POBJ_EVENT_ERROR event is only triggered if the process object is in an error state. Errors which occur in connection with other events or requests are reported with the corresponding event or response data and not by a POBJ_EVENT_ERROR event.

POBJ_EVENT_DATA Event Type

This event is sent each time a variable object's data is changed. The variable data (process data) is transferred as event data. The format of the data corresponds to the data format set in the process object. If a data format is defined in the link object, then data is transferred in the format of the link object (type casting).

Process objects without process data (e.g. line objects, module objects, etc.) always send event data with a data length of 0 (null). This signals the end of the error state.

The "d" object attribute (AT parameter) can be used to suppress the monitoring of changes in process data in the variable object as well as overwriting POBJ_EVENT_DATA events. In this case, each individual POBJ_EVENT_DATA event is sent to the PVI application.

If event data cannot be transported quickly and read from the PVI application at the same time, then the memory needs constantly increase. Therefore, the "d" attribute should be used with extreme care and only when absolutely necessary.

The "d" attribute is intended e.g. for variables on the Direct CAN or MTC line if short-lived data changes in the PVI application need to be signaled (e.g. value changes from 0 to 1 and then back to 0 right away). Using the "d" attribute in connection with normal PLC variables doesn't make much sense since the short-lived data changes cannot be detected within the refresh time anyway.

POBJ_EVENT_DATAFORM Event Type

This event is sent each time a variable object's data format is changed. Process objects without process data cannot trigger this event. This event data contains a description of the data format in string format. Like the object description, individual parameters are differentiated in a string with parameter codes. The data format is defined with the VT, VL, VN, VS and AL parameters.

To ensure compatibility with older versions of PVI (earlier than V3.0.0), the parameter VS is not specified for "simple" array variables (one-dimensional array with more than one array element, array index starts at 0, not a derived data type). To identify a variable as an array variable, the parameter VN must also be evaluated in addition to the additional specification 'a'. The following condition applies: Array variable if VS=...a... or VN > 1.

If an application doesn't have a data format defined in the link object, the data is sent in the format of the process object with the POBJ_EVENT_DATA event. The POBJ_EVENT_DATAFORM event makes sure that the application always sends the current data format of the process object. If a change in the data format occurs, both events are controlled in such a way that the application always receives a POBJ_EVENT_DATAFORM event first. The POBJ_EVENT_DATA event only occurs afterwards with the data in the new format.

<< Previous Topic
Receive event

Start Page

Next Topic >>
Process data


Process data

The process image represents all the process data required for handling a visualization process.

Process data (variable data) is contained in individual variable objects (process objects of type POBJ_PVAR. To access this data, the application needs to set up a link object.

Process data is assigned a data format. Process data is mapped in the variable object according to the data format property. The data format can be specified by the PVI application in the process object description when setting up the variable object. The POBJ_ACC_TYPE access type can be used to read or write the current setting for the data format property at runtime. You should be aware that the data format can be defined by the line being used for external variable objects. Which line defines the data formats of variables objects can be found in the corresponding section of PVI lines. A data format defined by the line can no longer be changed by the application.

If a new process variable object is set up, then there is no process data present at first. Internal process objects do not contain any valid process data after being setup and have to be provided with data from the application. External process objects are identified by the line being used and then supplied with data. This procedure can take a bit of time. The DV parameter can be used to provide variable objects with process data right when they are setup. However, this is only possible for single variables and Integer, Floating Point, Boolean, or String data formats.

If the data format of variable objects is determined by the line, then the user does not have to specify a data format when creating the variable object. However, if the DV parameter is used, then a data format has to be defined in the process object description in this case. This data format is then overwritten later by the data format from the line.

The application uses the link object to read and write data in the format of the variable object. However, a data format can also be defined in the link object. In this case, data is read/written using the format of the link object. If the data format of the variable object and the link object are not the same, then type conversion is carried out.

Data acquisition (supplying variable objects with current data) of external objects (e.g. PLC variables) can be done by either reading cyclically or using event variables. The 'event variable' operating mode is selected with the object attribute 'e'.

When reading cyclically, read requests are passed from the PVI Manager to the PVI line being used (line server). The line packs these instructions into a data frame and sends them to the connected PLC. It then sends the requested data back to the line in the form of a data frame. The line unpacks the data frame and passes the process data to the PVI Manager. The process data is then compared with the process image data of the respective variable object. When data changes, the process data is applied and a POBJ_EVENT_DATA event is triggered. This event is then sent to the appropriate PVICOM application via all assigned link objects with an enabled POBJ_EVENT_DATA event.

For event variables, monitoring changes to the process data is carried out on the PLC (or in the line). Process data is only sent from the PLC to PVI if there are changes. Cyclic reading is omitted. When using this operating mode, data coming over the PLC communication connection can be considerably reduced. However, note that both the line server and PLC event variables must be supported.

Basically, process data is only acquired from the line being used for process objects in an active state. In an inactive state, the process image is not updated for the affected variable. This also reduces data traffic with the PLC.

Regardless of the type of data acquisition and the state (active or inactive), the application can also request data from external objects with a read instruction (access type POBJ_ACC_DATA). Data is read from the PLC and sent with the response data to the application. If process data is changed in the process image, then a POBJ_EVENT_DATA event (if enabled) is also triggered along with the response data via all existing link objects.

When writing process data to an external variable object with access type POBJ_ACC_DATA, data is first written to the PLC. Once the write has been confirmed by the PLC, response data is sent to the application. If the 'r' object attribute is specified, then a read request is triggered for the affected object in connection with the write instruction. Further processing occurs as with cyclic reading.

In this section the following topics are discussed:

Process data

Type conversion

Variable addressing

Process data properties

Process data functions

<< Previous Topic
Event types

Start Page

Next Topic >>
Type conversion


Process data

Type conversion

To be able to handle process data, PVICOM application have to know the data format of the process data.

Although a PVICOM application and a PLC application can "agree" to use a certain data format, any change to the data format has to always be carried out in both applications. In practice, this frequently leads to hidden errors. However, the application has the possibility to read the data format of a variable object (POBJ_EVENT_DATAFORM event or POBJ_ACC_TYPE or POBJ_ACC_TYPE_INTERN access type). The application can either check the data format and output an error message if the format is not permitted, or it can manage the process data dynamically. Type conversion is another solution.

During type conversion (cast function), a data format is predetermined by the PVICOM application. Process data in variable objects is then converted into the given data format when reading and writing, and vice versa. To be able to use type conversion, an application must define a data format when setting up a link object. Process data will then always be written and read in this format, regardless of the data format of the variable object.

This image shows the formats of the process data from the PLC to the PVICOM application:

When converting types, Integer (signed or unsigned), Float, Boolean, and String variable types can be combined as array variables or single variables. All other variable types cannot be combined. Error 12036 is reported when attempting to combine variable types not mentioned above.

If a structure with structure elements is defined in the link object, then the number of structure elements must be identical with that of the process variable. The data in the individual structure elements is converted according to their data format. The same rules apply here as for single variables. In addition, structure data is oriented according to the specified structure alignment.

Example of type converting a structure and specifying the structure elements:

Data format of the variable object:
    "VT=struct AL=2 {. VT=i8 } {. VT=i32 }"
Definition of structure in C for the PLC (SG3):
    struct
    {
        SINT a;
        DINT b;
    }
Specification for the link object data format:
    "VT=struct {. VT=string VL=16 } {. VT=string VL=16 }"
Definition of the structure in C for the application:
    struct
    {
        char strA[16];
        char strB[16];
    }

In this example, the type will be converted to string. Of course, strings integer or floating point formats can be used as well.

If only the structure alignment should be set (AL parameter), but the format of the structure elements should be applied, then a structure without structure elements and variable length 0 (zero) need to be defined as the data format for the link object (data format "VT=struct VL=0"). This particular specification applies the structure elements from the data format of the variable objects. Together with a definition of the structure alignment (AL parameter) in the link object, any structure can be oriented according to the specified structure alignment.

Example of type converting a structure without specifying the structure elements:

Data format of the variable object:
    "VT=struct AL=2 {. VT=i8 } {. VT=i32 }"
Definition of structure in C for the PLC (SG3):
    struct
    {
        SINT a;
        DINT b;
    }
Specification for the link object data format:
    "VT=struct VL=0 AL=4"
Definition of the structure in C for the application:
    struct
    {
        char A;
        long B;
    }

The format of the individual structure elements corresponds to that of the PLC. However, the application works with structure alignment 4. Therefore, the size of the structure is 8 bytes in the application and 6 bytes in the PLC (SG3).

In arrays, all elements are converted (type cast) individually. The same rules apply here as for single variables. If the array variables possess a different number of elements, then type conversion will be terminated at the end of the smaller array. If the target array is larger, than the rest is filled with binary zeroes.

Example of type converting an array:

Data format of the variable object:
    "VT=u16 VN=10"
Definition of the variable in C for the PLC:
    INT Array[10];
Specification for the link object data format:
    "VT=i32 VN=10"
Definition of the variable in C for the application:
    long Array[10];

All values not equal to 0 (zero) receive the value TRUE when type converting to variable type Boolean. If a String ("VT=string" or "VT=wstring") is type converted to type Boolean, than it will first be converted to an Integer before the value is checked as being unequal to zero.

Data in floating point variables (f32, f64) can contain invalid values (infinity, not-a-number) as per the IEEE. Valid values are formed during the type conversion (largest or smallest displayable value or 0).

When the type is changed from a 2 byte ("VT=wstring") to a 1 byte ("VT=string") string, all characters < 256 are applied without any changes. Characters >= 256 are represented by the '~' character.

In general, note that loss of value information is possible during type conversion. For example, data in an i16 variable (2-byte integer) should be type converted to an i8 (1-byte integer). i8 variables can represent values from -128 to +127. The value "130" in the i16 variable is outside of the i8 value range and can therefore not be represented with the i8 variable. This causes a value range violation. Value range monitoring can be activated with Bit 2 of the CM parameter.

What happens when value range monitoring is deactivated during type conversion:

  • Variable type Integer to a variable type Integer with a smaller value range:
    The number is truncated in its binary form.
  • Floating point variable type to a variable type with a smaller value range:
    If the number cannot be represented in the value range, then the result is undefined.
  • String variable type to a floating point of integer variable type:
    If the number cannot be represented in the value range, then the result is undefined.
  • Floating point or integer variable type to a string variable type:
    If the converted string is longer than the length of the string variable ("VL" parameter), then the string is truncated.

What happens when value range monitoring is activated during type conversion ("CM=4"):

  • If the value range is violated when writing process data (access type POBJ_ACC_DATA), then the write instruction is not executed. Error 12014 is reported with the response data. The RESP_STATUS_CAST_OVERFLOW or RESP_STATUS_CAST_UNDERFLOW flag is set in the status of the response data (RESPONSE_INFO structure). In addition, the response data contains the exceeded limit value in the link object's data format. This limit value can be read with the PVICOM function PviWriteResultResponse or PviXWriteResultResponse.
  • If the value range is violated in the read direction (access type POBJ_ACC_DATA or event POBJ_EVENT_DATA), then the limit value is supplied with the response or event data. The limit value is the largest or smallest value which can be represented. The RESP_STATUS_CAST_OVERFLOW or RESP_STATUS_CAST_UNDERFLOW flag is set in the status of the response or event data (RESPONSE_INFO structure).
  • Monitoring of limits is also carried out for String variable types ("VT=string" or "VT=wstring"). A limit violation occurs when the string data is longer then the buffer size of the string variables. For example, a string "abcdefg" + terminating null cannot be put completely into a variable with the data format "VT=string VL=4".

Type conversion modes of operation can be affected by the CM parameter. The parameter can be defined in the object description for a process object and for a link object. For type conversion, settings from both objects are always evaluated (OR function). The setting in the process object defines the mode of operation for all connections, while the specification in the link object only applies for that one connection. CM is assigned 0 (zero) by default.

The CM parameter is structured as a bit list. The adjustable conversion modes are represented by several bits within the bit list. If a bit is set, then the corresponding function is activated:

Bit Value Description
#0 1 PG2000 or AS 1.3 - String variable:
If the variable object data format defines a i8 or u8 array (1 byte array), then the process data is regarded as a single variable of type String (VT=string) during type conversion. When reading the data format (access type POBJ_ACC_TYPE or event POBJ_EVENT_DATAFORM), "String" is returned as the variable type (e.g. actual data format = "VT=i8 VL=1 VN=24" -> returned data format "VT=string VL=24 VN=1"). Setting CM=1 should take place in the process object. If CM=1 is only specified in the link object, the corresponding type conversion is carried out, but the actual data format is returned when the data format is read.

This conversion mode is intended for "old" PG2000 or AS 1.3 applications. New applications should not use this mode. Instead, a string variable should also be defined as a string variable in the PLC.

#1 2 Decimal mode:
Defines how the string contents are interpreted when type converting from the String variable type ("VT=string") to variable type Integer.

Without decimal mode, string contents are interpreted like this:
A string with leading 0's is interpreted as an octal number (e.g. -077, 0012).
If the string begins with "0x" or "0X", then the following positions are interpreted in hexadecimal (e.g. 0x1f, -0x56a9, 0xA3).
In all other cases, the string contents are interpreted as decimal.

If decimal mode is activated (CM=2), then contents of the string are always interpreted as decimal.

#2 4 Value range monitoring:
If value range monitoring is enabled (CM=4), process data is checked whether it can be represented during type conversion. Value range violations are monitored. If one occurs, Error 12014 is reported when writing and the largest or smallest value that can be represented is returned when reading.
#3 8 4/5 rounding mode:
Determines how a Floating Point variable type should be converted to an Integer variable type.

Without rounding mode, the positions to the right of the decimal point are simply truncated. (Examples: 1.3 -> 1, -15.5 -> -15, 0.9999 -> 0)

If rounding mode is switched on (CM=8), then the positions to the right of the decimal point are rounded. (Examples: 1.3 -> 1, -15.5 -> -16, 0.9999 -> 1)

#4 16 Always terminating string variables with a binary 0 (zero):
A string variable with a data format of "VT=string VL=4" can contain a maximum of 4 characters. If string data "abcd" is assigned, then there is no more room for zero-termination. If "zero-termination" mode is enabled, then the string variable will always be terminated with a binary 0 during type conversion. In the example above, the string variable would contain "abc" and a binary 0 would hold the fourth position.

Individual conversion modes for the CM parameter can be combined. Example: Value range monitoring + rounding mode result in CM=12 (4 + 8 = 12).

<< Previous Topic
Process data

Start Page

Next Topic >>
Variable addressing


Process data

Variable addressing

Using variable addressing, link objects can address subsets from the process data of a variable object.

All read and write accesses carried out through the link object therefore only address one subset of the process data. The subset is defined by specifying the variable address (VA parameter).

When writing, only the subset in the variable object's process data image is transferred. Then all the process data from the image is written to the PLC. When reading, this process is executed in reverse. The POBJ_EVENT_DATA event is only triggered when a change occurs in the subset.

When writing to a subset, all of the process data is always transferred to the PLC. If the process data is changed by the PLC from the time of the last read cycle up to the carrying out of the write instruction, then the data will be placed back to their old values by the write procedure. Therefore, variable addressing should be used either only in the read direction or the PLC accesses the process data only when reading.

Variable addressing is enabled by specifying the VA parameter in the link object description. Since variable addressing works via type conversion, a data format must be defined for the link object. Any application can set up several link objects to a variable object and divide process data into subsections using different variable addresses.

Possible addressing types:

Addressing | Description
Bit number | Bit addressing: With bit addressing, an individual bit is defined an integer variable. In the link object, the data format of the single variable or array must be defined with variable type Boolean (VT=boolean) or to a type which can be converted to Boolean. The variable object must have variable type Integer (signed or unsigned). The bit number is specified with the VA parameter. The bit number begins with 0 at the lowest valued bit. Example: "VT=boolean VA=2" - addresses Bit 2. If the variable object is an array of Integers, then a Boolean array can also be defined in the link object. Bit addressing is then carried out for each individual array.
Array index | Array addressing: With array addressing, an individual element is defined an array variable. The element of the array variable may not be a structure. A data format for a single variable must be defined in the link object. The array index is specified in brackets with the VA parameter. The array index begins with 0 at the first array element. Example: "VT=u32 VA=[3]" - addresses the fourth array element.

Example of variable addressing:

Data format of the variable object:
    "VT=u16 VN=10"
Definition of the variable for C on the PLC:
    INT Array[10];
Specification for the link object data format and variable addressing:
    "VT=u32 VA=[3]"
Definition of the variable for C in the application:
    unsigned long Array4;

<< Previous Topic
Type conversion

Start Page

Next Topic >>
Process data properties


Process data properties

The following properties can be set for process data:

Data format | Data format of the process data in the variable object and link object.
Object attributes | Object attributes control the approach when acquiring and handling process data of external variable objects.
Refresh time | The refresh time determines how frequently the process data of external variable objects is updated.

<< Previous Topic
Variable addressing

Start Page

Next Topic >>
Data format


Process data properties

Data format

A data format has to be assigned to be able to access the process data in a variable object (process object of type POBJ_PVAR).

The format of the process data is defined in the data format description. When the variable object is created, the data format description can be specified as part of the process object description. The POBJ_ACC_TYPE access type can be used to read or write the current setting for the data format property at runtime. The user must always assign a data format to internal variable objects. For external variable objects, this depends on the PVI line being used. Some lines (e.g. INA2000, NET2000 lines) set the data format for the variable object automatically. In this case, entry of a data format is optional, and is only valid until the data format is defined (overwritten) by the line.

The user can assign a data format to each link object regardless of the data format in the variable object. This corresponding data format description is defined in the link object description when creating a link object. If the data format is different for the variable object and the link object, then type casting is carried out when reading and writing process data.

Variable objects are divided into 3 types depending on the data format being used:

Single variable | Variables with any variable type except for structures. The number of array elements (VN parameter) is always 1.
Structure variable | Variable with variable type Structure. The number of array elements (VN parameter) is always 1. The elements in the structure can consist of single variables, additional structure variables, or array variables.
Array variable | Single variable or structure variable with more than one array element (VN parameter > 1 or VS=a).

In this section the following topics are discussed:

Data format

Data format description

Single variable

Structure variable

<< Previous Topic
Process data properties

Start Page

Next Topic >>
Data format description


Process data properties

Data format description

The data format is described using the following parameters:

Par. | Description
VT | Variable type. Default in the variable object: VT=i32, the link object is not assigned a default data format. See the following table for an overview of all variable types.
VL | Variable length in bytes. For single variables, the variable length corresponds to the process data length. For array variables, the variable length is defined as the element length.
VN | Number of elements in array variables. Default: VN=1. For multi-dimensional array variables, the number of elements for all array dimensions (example: var[10][5] => VN=50). To differentiate between array variables with only one element with a single variable, the VS parameter can be used (example: var[1] => VN=1 VS=a).
VS | Optional additional specification of variable type. The VS parameter provides additional information about the variable type (VT parameter), and does not affect how data is handled (data functions, type changes, etc.) in PVI. Each additional specification consists of one or more specification IDs ('a' - 'z'). The individual specification IDs are separated by semicolons (';'). The following additional specifications are currently defined: 'a' ... array variable, 'b' ... bit string, 'e' ... enumeration, 'v' ... derived data type. If the data format of the line used is not defined (not overwritten), the specification IDs entered in the process object description can be read using access type POBJ_ACC_TYPE or POBJ_ACC_TYPE_INTERN or the event POBJ_EVENT_DATAFORM. The complete additional specification of a PLC variable can be only be read with POBJ_ACC_TYPE_EXTERN access.
{...} | Definition of structure elements. The definition of the structure element must be specified at the end of the object description. First the nesting depth is defined by a number of "."'s (periods) within each expression in parentheses. Optionally, an element name can be specified after each '.' character (e.g. ".cpu.temp" or "..temp"). For PVI, the name after the final '.' character is significant. After the specification of the nesting depth and the element name (optional), the data format of the element variable is defined. Defined element names can only be read using access type POBJ_ACC_TYPE_INTERN, and element names of PLC variables using POBJ_ACC_TYPE_INTERN or POBJ_ACC_TYPE_EXTERN.
AL | Structure alignment. Default: AL=1. This parameter only takes effect in connection with variable type "VT=struct". Alignment values 1, 2, 4, 8, or 16 can be defined.

Variable length does not have to be specified for variable types with a fixed variable length (e.g. VT=i32 always has a length of 4 bytes). If the variable length is specified however, it has to match with the length of the variable type. The length of the process data is calculated from the variable length multiplied with the number of elements (VL * VN). The process data length is the total length of the data of a variable object in the process image. This includes all filler bytes in structures.

The following variable types can be specified with the VT parameter:

Type | Description
i8 | 8-bit signed integer. Variable length: VL=1. Value range: -128 ... 127.
i16 | 16-bit signed integer. Variable length: VL=2. Value range: -32768 ... 32767.
i32 | 32-bit signed integer. Variable length: VL=4. Value range: -2147483648 ... 2147483647.
i64 | 64-bit signed integer. Variable length: VL=8. Value range: -9223372036854775808 ... 9223372036854775807.
u8 | 8-bit unsigned integer. Variable length: VL=1. Value range: 0 ... 255.
u16 | 16-bit unsigned integer. Variable length: VL=2. Value range: 0 ... 65535.
u32 | 32-bit unsigned integer. Variable length: VL=4. Value range: 0 ... 4294967295.
u64 | 64-bit unsigned integer. Variable length: VL=8. Value range: 0 ... 18446744073709551615.
f32 | 32-bit floating point (IEEE Float). Variable length: VL=4. Value range: -3.402823466e+38 ... -1.175494351e-38 / +1.175494351e-38 ... +3.402823466e+38.
f64 | 64-bit floating point (IEEE Float). Variable length: VL=8. Value range: -1.7976931348623158e+308 ... -2.2250738585072014e-308 / +2.2250738585072014e-308 ... +1.7976931348623158e+308.
boolean | Bit variable (flag) mapped to 1 byte. Variable length: VL=1. TRUE = value other than 0, FALSE = value 0.
string | String with 1-byte character size and binary 0 termination (null-terminated). The length of the string buffer is defined with the variable length (VL parameter). The length of the string buffer is also the maximum string length. The actual string length is determined by the binary null character. When reading and writing process data with variable type String, note that data is only transferred up to and including the null character. All characters after the null character are undefined.
wstring | Wide string with 2-byte character size (wide character) and binary 0 termination (null-terminated). The behavior corresponds to that of the String data type. Keep in mind, however, that the number of bytes and not the number of characters must be entered for the variable length (parameter VL). For example, "VT=wstring VL=160" defines a wide string buffer with 80 characters. PVI does not allow you to enter an odd number length (error).
struct | Structure. The length of the structure can be defined either by specifying the structure elements or with the variable length (VL parameter).
time | 32-bit time difference in milliseconds. For clocks, this time difference refers to midnight. Variable length: VL=4.
dt | 32-bit time and data in seconds since 1/1/1970. Variable length: VL=4.
date | 32-bit date. Variable length: VL=4.
tod | 32-bit time of day. Variable length: VL=4.
data | General data type. The length (bytes) is defined with the variable length (VL parameter).

<< Previous Topic
Data format

Start Page

Next Topic >>
Single variable


Process data properties

Single variable

The basis of a single variable is a defined data type.

Syntax:

VT=<VariableType> [VL=<VariableLength>] [VN=<NumberOfArrayElements>] [VS=<AdditionalSpecification>]

Example of a single variable as a 16-bit signed integer:

"VT=i16"

Example of an array variable with 8 elements and type 32-bit floating point:

"VT=f32 VN=8"

Example of a single variable of type String with 24 characters:

"VT=string VL=24"

Example of an array variable with 5 elements of type String, each with 24 characters:

"VT=string VL=24 VN=5"

Example of a single variable of type Wide String with 24 characters:

"VT=wstring VL=48"

Example of an array variable with only one element and type Bit List with a length of 1 byte:

"VT=u8 VS=a;b"

Entering the parameter VS has no effect on the way PVI handles data. The entry is only an ID for the PVI application. If the PVI application doesn't evaluate the VS parameter (access type POBJ_ACC_TYPE or event POBJ_EVENT_DATAFORM), the entry has no effect.

<< Previous Topic
Data format description

Start Page

Next Topic >>
Structure variable


Process data properties

Structure variable

In principle, structures can be specified with or without defining the structure elements. If structure elements are not defined, then the variable length (VL parameter) has to be specified. If structure elements are defined, then the variable length is automatically calculated taking the set alignment (AL parameter) into consideration.

Syntax for structure without structure elements:

VT=struct VL=<VariableLength> [VN=<NumberOfArrayElements>] [VS=<AdditionalSpecifications>]

Syntax for structure with structure elements:

VT=struct [VN=<NumberOfArrayElements>] [VS=<AdditionalSpecifications>] [AL=<Alignment>] { <Element1> } { <Element2> } ...

<Element>: { <Nesting> VT=<VariableType> [VL=<VariableLength>] [VN=<NumberOfArrayElements>] [VS=<AdditionalSpecifications>] }

Each structure element (<Element>) is specified inside of braces (curved brackets " {...}"). The <nesting depth> is defined by a number of "."'s (periods) at the beginning of each expression in parentheses. The definition of the structure element also begins with a period. If a second structure is defined inside a structure, then the nesting depth is increased by one. Therefore, two periods have to specified when defining the elements of the second structure. Nesting depth can be increased to a maximum of 64. Optionally, an element name can be specified after each "." (period) character. For PVI, only the name after the final '.' character is significant. The element names are stored in the process variable object and can be read using access type POBJ_ACC_TYPE_INTERN. Entering the element name has no effect on how the variable data is handled.

Example of a structure variable:

"VT=struct AL=4 {. VT=i16} {. VT=struct VN=2}
  {.. VT=string VL=24} {.. VT=i32} {. VT=u32}"
Same data format, however specified with element names:
"VT=struct AL=4 {.Level VT=i16} {.Msg VT=struct VN=2}
  {.Msg.Text VT=string VL=24} {.Msg.Number VT=i32} {.Temp VT=u32}"
or
"VT=struct AL=4 {.Level VT=i16} {.Msg VT=struct VN=2}
  {..Text VT=string VL=24} {..Number VT=i32} {.Temp VT=u32}"
All variants correspond to the following C structure with Alignment 4:
struct
{
    short Level;
    struct
    {
        char Text[24];
        long Number;
    } Msg[2];
    unsigned long Temp;
}

Structure alignment:

If structure elements larger than one byte are addressed in a program, memory access by the processor can be accelerated by setting the structure elements to a data word limit. To do this, "filler bytes" are added to the respective structure elements. However, the filler bytes require more memory to be used.

The structure alignment then defines the size of the data word limit where structure elements are mapped.

Alignment = 1 ....minimum memory requirements and maximum processor access time
Alignment = 8 ....maximum memory requirements and minimum processor access time

In VC++, alignment can be defined globally in the project settings or locally using the Pragma statement "#pragma pack". Alignment is fixed at 4 for VB 6.0.

The alignment requirements for a structure element are determined by the size of the structure element and the alignment specifications. The following rules apply:

<AlignmentRequirement> = min (<AlignmentSpecification>, sizeof (<StructureElement>))

Rules for structures within a structure:

sizeof (<LargestStructureElement>)

The offset of a structure element is determined using the following formula:

<Offset> % <AlignmentRequirement> == 0

The alignment can be specified (AL parameter) when defining the data format of a structure. The process data for this variable object is then aligned according to this setting.

<< Previous Topic
Single variable

Start Page

Next Topic >>
Object attributes


Process data properties

Object attributes

Object attributes control the approach when acquiring and handling process data of external variable objects.

For internal variable objects, only the "r" and "w" attributes have any significance.

The user can can define object attributes in the process object description with the AT parameter when creating a variable object. The POBJ_ACC_TYPE access type can be used to read or write the current setting for the object attribute property at runtime.

AT | Description
r | Allows read access to the process data of a variable object. If this attribute is not specified, a read access attempt (POBJ_ACC_DATA access type) is rejected with Error 12035. In addition, PVI Manager doesn't carry out any cyclic read requests.
w | Allows write access to the process data of a variable object. If this attribute is not specified, a write access attempt (POBJ_ACC_DATA access type) is rejected with Error 12034.
e | Operating mode as a line or PLC event variable. Monitoring for changes in the process data is carried out in the line or on the PLC. For this reason, PVI Manager doesn't need to carry out any cyclic read requests. To find out which lines support event variables, refer to the descriptions for each line.
h | Fast echo after write access. With the "h" object attribute, the time between a write request and a resulting "Data Change" event can be reduced (POBJ_EVENT_DATA event type). However, the write request itself cannot be accelerated with this (time between write request and write response). The write data is compared with the process image before the transfer to the PLC and, if there is a change, a POBJ_EVENT_DATA event is triggered via all existing link objects.
d | Direct event trigger for the POBJ_EVENT_DATA event. The "d" attribute is only effective in connection with the "e" attribute. A direct event trigger means that all process data returned by the line or PLC is sent directly to the application. For more information, see the POBJ_EVENT_DATA Event section.

<< Previous Topic
Structure variable

Start Page

Next Topic >>
Refresh time


Process data properties

Refresh time

The refresh time determines how frequently the process data of external variable objects is updated.

PVI attempts to acquire process data either through cyclic read accesses ("polling") or by using event variables (PLC event variables) within this time. The user can define the refresh time in the process object description (RF parameter) when creating a variable object. The POBJ_ACC_REFRESH access type can be used to read or write the current refresh time setting at runtime.

Refresh time | Description
-1 | The behavior corresponds to that of an internal process variable. The data is not read automatically. However, the application can control data acquisition using targeted read tasks.
0 | Process data is only read once. Reading takes place after the line has initialized the variable object. As with RF = -1, the application can control further data acquisitioning using targeted read tasks. This setting can be used for constants for example.
Greater than 0 | Behavior as with RF = 0, though the variable object is supplied with current process data in the specified refresh time (specified in ms). The refresh time should be set to correspond with the requirements of the process data (how current). Basic principle: the highest possible refresh rate.

<< Previous Topic
Object attributes

Start Page

Next Topic >>
Process data functions


Process data functions

The following functions can be used for process data:

Event hysteresis | Event hysteresis can be used to reduce the number of POBJ_EVENT_DATA events. The hysteresis filter only allows process values through which have value changes greater than or equal to the specified hysteresis.
Data functions | The data function can be used to scale process values of monitor limit values.

Event hysteresis and the data function can be defined for link objects, process objects (variable objects), or for both. Defining for a link object is only possible however if a corresponding data format has also already been specified for the link object.

Process data is divided into a raw value and a process value in the variable object (process object of type POBJ_PVAR). The raw value corresponds to the data of the external object (e.g. PLC variable). The process value refers to the data which is manipulated using the data function and event hysteresis. If no data function or event hysteresis is defined, then the raw value and process value in the process object are the same.

When creating a link object, you can select between a raw value and process value link. To do so, the link type in the link object description needs to be set with the LT parameter.

The LT parameter is preset to the raw value link ("LT=raw"). However, the data function and event hysteresis defined in the process object is only effective for a process value link ("LT=prc").

This graphic indicates the path of process data in a link and process object in both read and write directions:

The event hysteresis and data function defined in the process object is effective for all connected link objects with a process value link. The event hysteresis and data function defined in the link object is only effective for this link object. An application can also use both connection types. In this case, only two link objects with different connection types need to be created.

<< Previous Topic
Refresh time

Start Page

Next Topic >>
Event hysteresis


Process data functions

Event hysteresis

Event hysteresis (hysteresis filter) can be defined for variable objects (process objects of type POBJ_PVAR) and for link objects with the parameter HY in the object description.

For process objects, the event hysteresis property can also be read or modified using the POBJ_ACC_HYSTERESE access type. Event hysteresis can only be applied for single variables or array variables and the data formats Integer (i8 ..., u8 ...) and Floating Point (f32 ...).

The event hysteresis defined in the process object is only effective if the parameter "LT=prc" has been specified in the link object description when creating the link object.

Syntax:

HY=<HysteresisValue>

The hysteresis value can be specified as an integer (specify without commas, valid value range: 2 - 2147483647) or as a 64-bit floating point number (specify with decimal, valid value range: greater than 0.0). A value outside of the valid ranges deactivates the hysteresis function for the object (e.g. "HY=0.0" or "HY=1").

If event hysteresis is defined, then a POBJ_EVENT_DATA event is only triggered if the value change is greater than or equal to the specified hysteresis value. For array variables, the hysteresis filter is used for all array elements. The event hysteresis is only active in the read direction and always refers to the process value.

The hysteresis filter in variable objects is intended to suppress system-specific value fluctuations (e.g. measurement value fluctuations on temperature sensors). The hysteresis filter in the link object can be used for user-specific demands.

<< Previous Topic
Process data functions

Start Page

Next Topic >>
Data functions


Process data functions

Data functions

Each data function has been developed as a Windows DLL and is loaded by PVI Manager as needed.

PVI Setup generates a key entry in the Windows registry with the function name for each installed data function. All entries are located under the registry key "HKEY_LOCAL_MACHINE\SOFTWARE\BR_Automation\Pvi\PviFunc". Each function key includes entries for the name and path of the DLL as well as function-specific parameters.

A data function can be defined for variable objects (process objects of type POBJ_PVAR) and for link objects with the parameter FS in the object description. For process objects, the data function property can also be read or modified using the POBJ_ACC_FUNCTION access type. The data function can only be applied for single variables or array variables and the data formats Integer (i8 ..., u8 ...) and Floating Point (f32 ...).

The definition of a data function in the variable object is intended to convert system-specific values into a standardized unit, whereas the data function in the link object can be used to further convert values to application-specific units. For example, the temperature value of a non-linear temperature sensor is scaled in the variable object to the unit "degrees Celsius" and then converted to "degrees Fahrenheit" in the link object for display on the screen.

The data function defined in the process object is only effective if the parameter "LT=prc" has been specified in the link object description when creating the link object.

Syntax:

FS=[<FunctionName>;]<FunctionDescription>

A data function is selected with the function name. If a function name is not specified, then the default data function "LIN" is used. The syntax of the function description depends on the data function being used. Alternatively, the path name of the function DLL can be specified in place of the function name. However, PVICOM application should only work with one registered function name. Function names are not case sensitive.

Function name | Short description
LIN | Scaling function and limit monitoring
Only one function DLL is included in PVI at this time

LIN Data Function

Data function for scaling and limit monitoring. Scaling can be defined using 2 (linear function y=kx+d) or more points. The first and last points specified are used for limit monitoring. Limit monitoring can also be defined without a scaling function.

What happens when a limit is exceeded depends on the transfer direction:

  • If the limit value is exceeded when writing process data (access type POBJ_ACC_DATA), then the write instruction is not executed. Error 12014 is reported with the response data. The RESP_STATUS_OVERFLOW or RESP_STATUS_UNDERFLOW flag and the RESP_STATUS_LINK or RESP_STATUS_POBJ flag are set in the status of the response data (RESPONSE_INFO structure). In addition, the response data contains the exceeded limit value in the link object's or process object's data format. This limit value can be read with the PVICOM function PviWriteResultResponse or PviXWriteResultResponse.
  • If the limit value is exceeded in the read direction (access type POBJ_ACC_DATA or event POBJ_EVENT_DATA), then the limit value is returned with the response or event data. The RESP_STATUS_OVERFLOW or RESP_STATUS_UNDERFLOW flag and the RESP_STATUS_LINK or RESP_STATUS_POBJ flag are set in the status of the response or event data (RESPONSE_INFO structure).

Values can be defined as integers (no commas specified) or as floating point (decimal point specified). Depending on this specification, the scaling function and limit monitoring are calculated either in integer or floating point format.

Limit monitoring without scaling:

Syntax:

FS=[LIN;]<Limit1>,<Limit2>

The specified limits (<Limit 1> and <Limit 2>) define a valid value range for the process data. The valid range is tested in the write and read direction.

Example:

"FS=0,100"

valid value range 0 to 100 (identical to specification "FS=100,0" or "FS=0,0;100,100").

Linear function with limit value monitoring:

Syntax:

FS=[LIN;]<XValue1>,<YValue1>;<XValue2>,<YValue2>

Scaling according to a linear function (y=kx+d) within a valid value range. The linear function is defined using 2 coordinates. The function calculation and monitoring of the valid value range takes place in the write and read directions (read process data: X -> Y, write process data: Y -> X).

Example:

FS=40,30;150,110

valid value range for raw value is 40 to 150. For process value, 30 to 110.

Scaling with several coordinates and limit value monitoring:

Syntax:

FS=[LIN;]<XValue1>,<YValue1>;<XValue2>,<YValue2>; ... ;<XValue n>,<YValue n>

Scaling using coordinates. Theoretically, a maximum of 32,766 coordinates can be specified. Scaling between 2 coordinates takes place using linear interpolation (linear function). The valid value range for limit monitoring is defined using the first (X1,Y1) and the last (Xn,Yn) coordinates. The function calculation and monitoring of the valid value range takes place in the write and read directions (read process data: X -> Y, write process data: Y -> X).

Example:

FS=40,30;100,50;140,80;160,110

valid value range for raw value is 40 to 160. For process value, 30 to 110.

The specified function has to be able to be reversed, i.e. "strictly monotonic increasing" or "strictly monotonic decreasing" within the valid value range.

<< Previous Topic
Event hysteresis

Start Page

Next Topic >>
PVICOM functions


PVICOM functions

Function | Description
PviInitialize | Initializes the PVICOM interface and sets up the PVICOM communication instance
PviDeinitialize | Ends the communication connection to the PVI Manager and releases the PVICOM communication instance
PviSetGlobEventMsg | Assigns a user message to a global event of the PVICOM communication instance
PviCreateRequest | Request to set up a static process object or a temporary process object with a link object
PviCreateResponse | Reads a response from a PviCreateRequest instruction. With this response, an ID is passed on to the link object in the application.
PviCreate | Synchronous variant of PviCreateRequest / PviCreateResponse functionality
PviDeleteRequest | Request for deleting a (static) process object
PviDeleteResponse | Reads a PviDeleteRequest response
PviDelete | Synchronous variant of PviDeleteRequest / PviDeleteResponse functionality
PviLinkRequest | Request to set up a link object
PviLinkResponse | Reads a PviDeleteRequest response. With this response, an ID is passed on to the link object in the application.
PviLink | Synchronous variant of PviLinkRequest / PviLinkResponse functionality
PviUnlinkRequest | Request to release a link object
PviUnlinkResponse | Reads a PviUnlinkRequest response
PviUnlink | Synchronous variant of PviUnlinkRequest / PviUnlinkResponse functionality
PviChgLinkRequest | Request to change the user message for event data
PviChgLinkResponse | Reads a PviChgLinkRequest response
PviChgLink | Synchronous variant of PviChgLinkRequest / PviChgLinkResponse functionality
PviUnlinkAll | Releases all link objects to which a certain Windows handle or callback pointer is assigned as a user message
PviReadRequest | Request for read access to an existing PVI object. The type of read access is determined with the access type.
PviReadArgumentRequest | Request for read access with argument data to an existing PVI object. The type of read access is determined with the access type.
PviReadResponse | Reads a PviReadRequest or PviReadArgumentRequest response or event data from a PVICOM event
PviRead | Synchronous variant of PviReadArgumentRequest / PviReadResponse functionality
PviWriteRequest | Request for write access to an existing PVI object. The type of write access is determined with the access type.
PviWriteResponse | Reads a PviWriteRequest response
PviWriteResultResponse | Reads a PviWriteRequest response with result data
PviWrite | Synchronous variant of PviWriteRequest / PviWriteResponse functionality
PviGetResponseInfo | Reads information about response or event data
PviGetNextResponse | User message for reading the next response or event data (only for PVIFUNCTION user message).
PviGetVersion | Reads the version string of PVICOM

Functions with or without an instance handle

Two function groups are implemented in the PVICOM interface:

  1. Functions with an instance handle ("PviX..."):
    The PVICOM interface must be initialized with the PviXInitialize function. Then only functions which begin with "PviX..." can be used.
  2. Functions without an instance handle ("Pvi..."):
    The PVICOM interface must be initialized with the PviInitialize function. Then functions which begin with "PviX..." cannot be used.

Functions which use instance handles allow several communication instances to be operated at one time. Each instance handle defines a communication instance which controls the client/server communication connection to the PVI Manager. This means that an application can communicate with several PVI Managers at the same time (remote communication type). If functions which do not use instance handles are called, then only one communication instance is present. Applications can then only communicate with one PVI Manager. Generally, an application can also set up several communication instances to the same PVI Manager. However, it should be noted that data transfer takes longer over several instances than it does over just one.

Asynchronous and synchronous functions

The PVICOM functions with the word "Request" or "Response" in their name (e.g. PviReadRequest, PviXWriteRequest, PviReadResponse, PviXWriteResponse, etc.) allow requests to be handled asynchronously and can therefore also be called asynchronous PVICOM functions. While a PVI request is being executed, the application can send another PVI request or handle other tasks.

Synchronous PVICOM functions handle sending request data, waiting for the response, and reading the response data within a function. Since synchronous functions use asynchronous functions internally, they don't save any runtime. However, their use is substantially easier within a PVICOM application since the program doesn't have to worry about user messages and assigning requests and responses. In general, asynchronous and synchronous functions can also be mixed together.

Note the following when using synchronous PVICOM functions:

  1. Synchronous PVICOM functions are not multithread-capable. That means that two synchronous functions or one synchronous and one asynchronous function may not be called from different threads at the same time. This also applies if the requests were given over different communication instances.
  2. When the client/server connection is broken, the application stays in the PVICOM function until the communication timeout expires (see Communication instances). If the application is only using one thread, then the entire application cannot be operated during this time.
  3. If a synchronous function is being run right then, then neither the assigned link object of the assigned communication instance can be freed up.
  4. The RESPONSE_INFO structure cannot be read with synchronous functions.

Synchronous functions should only be used in test programs, simple visualization applications, or small PVICOM applications like demo programs. If PVICOM functions need to be called from several threads, then you should only use asynchronous PVICOM functions. Using asynchronous PVICOM functions is recommended with the "remote" communication type or for high-speed applications.

Handling exceptions (e.g. try/catch combination) in connection with PVICOM functions is not allowed. PVICOM functions come equipped with internal mechanisms for communication control and synchronizing access. If the sequence of these mechanisms is interrupted, then it can lead to undefined PVICOM behavior. An exception in a PVICOM function may also be caused by specifying faulty function arguments (e.g. incorrect buffer pointer). For this reason, critical pointer arguments should be checked before PVICOM functions are called in order for operation to go smoothly.

<< Previous Topic
Data functions

Start Page

Next Topic >>
PviInitialize, PviXInitialize functions


PviInitialize, PviXInitialize functions

Definition for C/C++

int PviInitialize (INT Timeout, INT RetryTime, LPCSTR pInitParam, LPVOID pRes)

int PviXInitialize (LPDWORD phPvi, INT Timeout, INT RetryTime, LPCSTR pInitParam, LPVOID pRes)

Definition for Basic

PviInitialize (ByVal Timeout As Long, ByVal RetryTime As Long, ByVal pInitParam As String, ByVal pRes As Long) As Long

PviXInitialize (ByRef phPvi As Long, ByVal Timeout As Long, ByVal RetryTime As Long, ByVal pInitParam As String, ByVal pRes As Long) As Long

Arguments

Argument | I/O | Description
phPvi | Out | Pointer to a variable used for the instance handle. To avoid problems with undefined instance handles, the instance handle should be preinitialized with 0 (zero) in the application. If the value is 0, PVICOM recognizes the instance handle as invalid and returns an appropriate error.
Timeout | In | Communication timeout for the client/server communication in seconds The value specified with this function argument serves as the default setting of the initialization parameter COMT. If no particular presetting is desired, the default value 0 (null) should be entered.
RetryTime | In | Retry time for PVICOM user messages is seconds. The value specified with this function argument serves as the default setting of the initialization parameter RETR. If no particular presetting is desired, the default value 0 (null) should be entered.
pInitParam | In | Pointer to a NULL-terminated initialization parameter string. If no initialization parameters are needed, then NULL can be specified as the pointer.
pRes |  | Reserved for expansions. NULL should always be specified for this parameter.

Return value

The value 0 (null) signals that the initialization was carried out correctly. A value other than 0 (null) indicates an error, and the return value corresponds to the error code of the error which actually occurred.

Description

The PviInitialize or PviXInitialize function initializes the PVICOM interface, establishes a PVICOM communication instance, and initiates the registration of the communication instance (client) with PVI Manager (server). Once registered, a communication connection between the communication instance (client) and PVI Manager (server) is opened. It should be noted, that client registration is only initiated. Therefore, returning from the function does not guarantee stable client/server communication. The PVICOM communication instance can signal the current status of the communication connection with the help of global events from the application. To do so however, the desired global event must be activated with the PviSetGlobEventMsg or PviXSetGlobEventMsg function after the PviInitialize or PviXInitialize function is called.

Unlike the function "PviInitialize", "PviXInitialize" can be called more than once. Each call sets up a new communication instance. This allows a PVICOM application to be able to communicate with several PVI Managers on different computers. If a communication instance is set up with PviXInitialize, then PVICOM functions must subsequently be called with an instance handle (PviX...). See also the Functions With or Without an Instance Handle section.

If the initialization function PviInitialize (or PviXInitialize) doesn't report an error, then sending requests can basically begin immediately (Request and Response). If the communication connection is not active at this point, then all requests are buffered in the communication instance.

Initialization parameters:

The individual initialization parameters are differentiated in the string using parameter codes:

<ParameterName> = ["]<ParameterValue>["]

If a parameter value has characters that are not alpha numeric, they must be entered in ("...") quotation marks. At least one blank space needs to be between individual parameter entries.

Par. | Description
COMT | Communication timeout for the client/server (application/PVI Manager) communication in seconds The timeout also defines the time for the life sign monitor. An additional period is needed to detect a disruption in the client/server connection. To determine the total time where a communication disruption would be detected (at the latest), the timeout value specified here has to be doubled. If the timeout is 5, then an interruption in the connection can be detected in as early as 5 seconds and as late as 10 seconds. Connection interrupts are not recognized as such by the PVICOM interface if they occur within the timeout period. Data transfer simply continues once the connection is reestablished. Often used values are 3 - 10 seconds for local communication and 5 - 30 seconds for remote communication. Value: 1 - 3600, = 0 ... Default value of 30 s used. The value specified in the function argument "Timeout" serves as a presetting for this parameter.
RETR | Retry time for PVICOM user messages is seconds. The default setting ("RetryTime=0") should normally be used for this parameter. See the User Message Operations section for more information about this parameter. Value: 1 - 3600, <= 0 ... no repetition. The value specified in the function argument "RetryTime" serves as a presetting for this parameter.
LM | Limit on user messages. Default: "LM=1". PVICOM applications basically do not need to change the default setting of this parameter. However, if an application is able to respond quickly to PVICOM user messages, then a higher limit value ("LM=100", "LM=500") can speed up user message execution. See the User Message Operations section for more information about this parameter. Value: 1 - 65535, <= 0 -> No limiting.
PT | Process timeout in seconds. Default: "PT=0". This timeout can be used to monitor the time between requests and responses. This parameter is only intended for PVICOM applications which carry out particular tasks. Standard application do not need to be monitored and should use the default setting (no timeout monitoring). Value: 1 - 3600, <=0 -> No timeout monitoring
IP | TCP/IP address or host name. If the IP initialization parameter is specified, then the Remote communication type is used for PVICOM communication. Either the TCP/IP address (e.g. "IP=10.43.50.62") or the host name ("IP=SystemPC1") of the server (PVI Manager) is specified with this parameter. If the host name is given, then the IP address assigned to the name is determined by the system.
PN | TCP/IP port number. Default: "PN=20000". This parameter is only required in conjunction with the IP parameter. The port number assigned to PVI Manager needs to be specified here (PVI Manager Properties). Value: 1024 - 32767.
AS | Auto-Start (only for the local communication type). 1 ... PVI Manager is started (default). 0 ... PVI Manager is not started automatically and must be started already when the function is called. More information about the startup procedure can be found in the PVI Manager section.

Example for Visual C++

Application and PVI Manager are on the same computer:

#include <PviCom.h>

int Initialize (HWND hWnd)
{
    int Error;

    // Create and initialize communication instance:
    Error = PviInitialize (0, 0, "COMT=4 LM=1000", NULL);
    if (Error != 0)
        return (Error);

    // Set global Event ARRANGE to generate PVI objects:
    Error = PviSetGlobEventMsg (POBJ_EVENT_PVI_ARRANGE, hWnd, WM_USER+1, 0);
    if (Error != 0)
        return (Error);
    return (0);
}

int Deinitialize ()
{
    int Error;

    // Free communication instance:
    Error = PviDeinitialize ();
    return (Error);
}

Here, the application should communicate with two PVI Managers where the first PVI Manager is on the same computer and the second PVI Manager is on a different computer:

#include <PviCom.h>

DWORD hPvi1 = 0;
DWORD hPvi2 = 0;

int Initialize (HWND hWnd)
{
    int Error;

    // Create and initialize communication instance 1:
    Error = PviXInitialize (&hPvi1, 6, 0, "", NULL);
    if (Error != 0)
        return (Error);

    // Set global Event ARRANGE to generate PVI objects for manager 1:
    Error = PviXSetGlobEventMsg (hPvi1, POBJ_EVENT_PVI_ARRANGE, hWnd, WM_USER+1, 0);
    if (Error != 0)
        return (Error);

    // Create and initialize communication instance 2:
    Error = PviXInitialize (&hPvi2, 8, 0, "IP=10.43.50.62 PN=20001", NULL);
    if (Error != 0)
        return (Error);

    // Set global Event ARRANGE to generate PVI objects for manager 2:
    Error = PviXSetGlobEventMsg (hPvi2, POBJ_EVENT_PVI_ARRANGE, hWnd, WM_USER+2, 0);
    if (Error != 0)
        return (Error);
    return (0);
}

int Deinitialize ()
{
    int Error;
    int LastError = 0;

    if (hPvi1 != 0)
    {
        // Free communication instance 1:
        Error = PviXDeinitialize (hPvi1);
        if (Error != 0)
            LastError = Error;
        else
            hPvi1 = 0;
    }

    if (hPvi2 != 0)
    {
        // Free communication instance 2:
        Error = PviXDeinitialize (hPvi2);
        if (Error != 0)
            LastError = Error;
        else
            hPvi2 = 0;
    }

    return (LastError);
}

<< Previous Topic
PVICOM functions

Start Page

Next Topic >>
PviDeinitialize, PviXDeinitialize functions


PviDeinitialize, PviXDeinitialize Functions

Definition for C/C++

int PviDeinitialize ()

int PviXDeinitialize (DWORD hPvi)

Definition for Basic

PviDeinitialize () As Long

PviXDeinitialize (ByVal hPvi As Long) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function

Return value

A value other than 0 signals an error. The error code is returned as a value.

Description

This function is used to end the communication connection to PVI Manager and release the PVICOM communication instance.

After the function is called, no user messages are sent to the application. Note, however, that window post-messages may still be in the window message queue. They should be ignored after calling the "PviDeinitialize" function.

<< Previous Topic
PviInitialize, PviXInitialize functions

Start Page

Next Topic >>
PviSetGlobEventMsg, PviXSetGlobEventMsg functions


PviSetGlobEventMsg, PviXSetGlobEventMsg functions

Definition for C/C++

int PviSetGlobEventMsg (DWORD nGlobEvent, LPVOID hEventMsg, DWORD EventMsgNo, LPARAM EventParam)

int PviXSetGlobEventMsg (DWORD hPvi, DWORD nGlobEvent, LPVOID hEventMsg, DWORD EventMsgNo, LPARAM EventParam)

Definition for Basic

PviSetGlobEventMsg (ByVal nGlobEvent As Long, ByVal hEventMsg As Long, ByVal EventMsgNo As Long,ByVal EventParam As Long) As Long

PviXSetGlobEventMsg (ByVal hPvi As Long, ByVal nGlobEvent As Long, ByVal hEventMsg As Long, ByVal EventMsgNo As Long, ByVal EventParam As Long) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
nGlobEvent | In | Selects the global event type where the user message should be assigned POBJ_EVENT_PVI_CONNECT, POBJ_EVENT_PVI_DISCONN, or POBJ_EVENT_PVI_ARRANGE can be specified as an event.
hEventMsg | In | Definition of a user message which is executed when the global event occurs. If hEventMsg = 0 (zero) is specified, then the user message for this event is deleted.
EventMsgNo | In | Message number of the user message
EventParam | In | message parameter of the user message The size of the message parameter (user parameter) in the 32-bit PVI version (PviCom.dll) is 4 bytes and in the 64-bit PVI version (PviCom64.dll) 8 bytes.

Return value

A value other than 0 signals an error. The error code is returned as a value.

Description

This function assigns a user message to a global event from the communication instance. The PviDeinitialize or PviXDeinitialize function is used to release all communication instance assignments.

A different user message can be specified for each global event type. If the same user message is defined for all events, then the event type can be read from the RESPONSE_INFO structure (PviGetResponseInfo function).

After receiving the corresponding user message for a global event, the PVI application has to call the PVICOM function PviReadResponse.

Example for Visual C++

#include <PviCom.h>
class CPviDlg : public CDialog
{
    ...
    int Initialize ();
    void CreatePviObjects ();
    LRESULT OnPviGlobalEvent (WPARAM, LPARAM);
   ...
    DECLARE_MESSAGE_MAP ()
};
BEGIN_MESSAGE_MAP (CPviDlg, CDialog)
    ...
    ON_MESSAGE (WM_USER+1, OnPviGlobalEvent)
END_MESSAGE_MAP()
LRESULT CPviDlg::OnPviGlobalEvent(WPARAM wParam, LPARAM lParam)
{
    T_RESPONSE_INFO Info;
    int Error;

    Error = PviGetResponseInfo (wParam, NULL, NULL, &Info, sizeof (Info));
    if (Error != 0)
        // no event data:
        return (0);

    // execute this function on every valid event:
    Error = PviReadResponse (wParam, NULL, 0);

    switch (Info.nType)
    {
        case POBJ_EVENT_PVI_CONNECT:
            ViewText ("State: CONNECT");
        break;

        case POBJ_EVENT_PVI_DISCONN:
            ViewText ("State: DISCONNECT - Error #%d", Error);
        break;

        case POBJ_EVENT_PVI_ARRANGE:
            CreatePviObjects ();
        break;
    }
    return (0);
}
void CPviDlg::CreatePviObjects()
{
    int ErrCode;

    ...
}
int CPviDlg::Initialize ()
{
    int Error;

    // create and initialize communication instance:
    Error = PviInitialize (8, 0, "IP=10.43.50.62 PN=23840", NULL);
    if (Error != 0)
        return (Error);

    // set global events:
    PviSetGlobEventMsg (POBJ_EVENT_PVI_CONNECT, CWnd::m_hWnd, WM_USER+1, 0);
    PviSetGlobEventMsg (POBJ_EVENT_PVI_DISCONN, CWnd::m_hWnd, WM_USER+1, 0);
    PviSetGlobEventMsg (POBJ_EVENT_PVI_ARRANGE, CWnd::m_hWnd, WM_USER+1, 0);

    return (0);
}

<< Previous Topic
PviDeinitialize, PviXDeinitialize functions

Start Page

Next Topic >>
PviCreateRequest, PviXCreateRequest functions


PviCreateRequest, PviXCreateRequest functions

Definition for C/C++

int PviCreateRequest (LPCSTR pObjectName, DWORD ObjectTyp, LPCSTR pObjektDescriptor, LPVOID hEventMsg, DWORD EventMsgNo, LPARAM EventParam, LPCSTR pLinkDescriptor, LPVOID hResMsg, DWORD ResMsgNo, LPARAM ResParam)

int PviXCreateRequest (DWORD hPvi, LPCSTR pObjectName, DWORD ObjectTyp, LPCSTR pObjektDescriptor, LPVOID hEventMsg, DWORD EventMsgNo, LPARAM EventParam, LPCSTR pLinkDescriptor, LPVOID hResMsg, DWORD ResMsgNo, LPARAM ResParam)

Definition for Basic

PviCreateRequest (ByVal pObjectName As String, ByVal ObjectType As Long, ByVal pObjectDescriptor As String, ByVal hEventMsg As Long, ByVal EventMsgNo As Long, ByVal EventParam As Long, ByVal pLinkDescriptor As String, ByVal hResMsg As Long, ByVal ResMsgNo As Long, ByVal ResParam As Long) As Long

PviXCreateRequest (ByVal hPvi As Long, ByVal pObjectName As String, ByVal ObjectType As Long, ByVal pObjectDescriptor As String, ByVal hEventMsg As Long, ByVal EventMsgNo As Long, ByVal EventParam As Long, ByVal pLinkDescriptor As String, ByVal hResMsg As Long, ByVal ResMsgNo As Long, ByVal ResParam As Long) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
pObjectName | In | Pointer to the object name or object path name. Given as a null-terminated string.
ObjectType | In | Object type entry. POBJ_LINE, POBJ_DEVICE, POBJ_STATION, POBJ_CPU, POBJ_MODUL, POBJ_TASK, POBJ_PVAR. If the object type is specified with the object name in pObjectName ("OT" parameter", then the object type given here is irrelevant.
pObjectDescriptor | In | Pointer to the process object description. Given as a null-terminated string.
hEventMsg | In | Definition of the user message which is assigned to the link object for signaling event data (events). If hEventMsg doesn't equal 0 (zero), then a temporary process object and a link object are set up. If hEventMsg equals 0 (zero), then a static process object without a link object is set up.
EventMsgNo | In | Message number of the user message = 0 (Null): No user message for event data is assigned to the link object In this case, either 0 (zero) or any value not equal to 0 can be specified for hEventMsg (e.g. PVI_HMSG_NIL).
EventParam | In | message parameter of the user message The size of the message parameter (user parameter) in the 32-bit PVI version (PviCom.dll) is 4 bytes and in the 64-bit PVI version (PviCom64.dll) 8 bytes.
pLinkDescriptor | In | Pointer to the link object description. Given as a null-terminated string.
hResMsg | In | Definition of the user message which signals the response for this function call (Requests and Responses) = 0 (Null): No response is sent by PVI Manager
ResMsgNo | In | Message number of the user message = 0 (Null): Same meaning as hResMsg=0.
ResParam | In | message parameter of the user message The size of the message parameter (user parameter) in the 32-bit PVI version (PviCom.dll) is 4 bytes and in the 64-bit PVI version (PviCom64.dll) 8 bytes.

Return value

A value other than 0 signals an error. The error code is returned as a value. In principle, this function only reports Windows resource errors (e.g. not enough memory available) or user errors (e.g. illegal function parameters, incorrect function use, etc.). In this case, a request is not sent to PVI Manager and the defined response message is not executed. If an error occurs during data transfer or when handling the request, then it is reported only with the response data.

Description

This function sends a request to PVI Manager to set up a process object. Either a static process object or a temporary process object can be set up with a link object. The hEventMsg function parameter is used to select the type of the process object. Response data must be read with either the PviCreateResponse or PviXCreateResponse function unless using a callback function of type PVICALLBACK_DATA.

Specifying "hEventMsg=0" (zero) sets up a static process object without a link object. If a process object already exists in PVI Manager which has the same name and same object type, Error 12002 (Object name already exists) is reported with the response. If there isn't such a process object, it will be set up as a static process object and set using the object parameters defined with pObjectDescriptor. The EventMsgNo, EventParam, and pLinkDescriptor parameters are not evaluated in this case and are therefore irrelevant.

If the hEventMsg function parameter defines a user message (value other than zero), then a process object and a link object are set up. If there is already a process object (temporary or static) in PVI Manager with the same name and object type, then only a link object is set up for this process object and the pObjectDescriptor parameter becomes irrelevant. This corresponds to the way the PviLinkRequest function works. However, if no corresponding process object is present, then a temporary process object is set up and set using the object parameters defined with pObjectDescriptor.

The object parameters defined with pLinkDescriptor are used when setting up the link object. The application receives a Link ID with the response data for identifying the set up link object.

Example for Visual C++

#include <PviCom.h>
class CPviDlg : public CDialog
{
    ...
    int m_CreateRequestCnt;
    DWORD m_LinkID[1024];
    long m_ErrCode[1024];

    void CreatePviObjects ();
    LRESULT OnPviCreateResp (WPARAM, LPARAM);
    LRESULT OnPviObjEvent (WPARAM, LPARAM);
    ...
    DECLARE_MESSAGE_MAP ()
};
BEGIN_MESSAGE_MAP (CPviDlg, CDialog)
    ...
    ON_MESSAGE (WM_USER+2, OnPviCreateResp)
    ON_MESSAGE (WM_USER+3, OnPviObjEvent)
END_MESSAGE_MAP()
LRESULT CPviDlg::OnPviObjEvent (WPARAM wParam, LPARAM lParam)
{
    ...
    return (0);
}
LRESULT CPviDlg::OnPviCreateResp (WPARAM wParam, LPARAM lParam)
{
    int ErrCode;
    DWORD LinkID;

    ErrCode = PviCreateResponse (wParam, &LinkID);
    if (ErrCode != 0)
        m_ErrCode[lParam] = ErrCode;
    else
        m_LinkID[lParam] = LinkID;

    if (--m_CreateRequestCnt <= 0)
    {
        // last create response was received:
        ...
    }
    return (0);
}
void CPviDlg::CreatePviObjects()
{
    int ErrCode;

    // Initialize members:
    m_CreateRequestCnt = 0;
    memset (m_LinkID, 0, sizeof (m_LinkID));
    memset (m_ErrCode, 0, sizeof (m_ErrCode));

    // Create line object:
    ErrCode = PviCreateRequest ("@Pvi/LNINA2", POBJ_LINE, "CD=LnIna2",
                                CWnd::m_hWnd, WM_USER+3, 1, "EV=e",
                                CWnd::m_hWnd, WM_USER+2, 1);
    if (ErrCode != 0)
        m_ErrCode[1] = ErrCode;
    else
        m_CreateRequestCnt++;

    // Create device object:
    ErrCode = PviCreateRequest ("@Pvi/LNINA2/COM2", POBJ_DEVICE, "CD=\"/IF=com2\"",
                                CWnd::m_hWnd, WM_USER+3, 2, "EV=e",
                                CWnd::m_hWnd, WM_USER+2, 2);
    if (ErrCode != 0)
        m_ErrCode[2] = ErrCode;
    else
        m_CreateRequestCnt++;

    // Create CPU object:
    ErrCode = PviCreateRequest ("@Pvi/LNINA2/COM2/CPU", POBJ_CPU, "CD=\"\"",
                                CWnd::m_hWnd, WM_USER+3, 3, "EV=e",
                                CWnd::m_hWnd, WM_USER+2, 3);
    if (ErrCode != 0)
        m_ErrCode[3] = ErrCode;
    else
        m_CreateRequestCnt++;

    ...
    // Create variable object for global CPU variable PVar1:
    ErrCode = PviCreateRequest ("@Pvi/LNINA2/COM2/CPU/PVar1", POBJ_PVAR, "CD=PVar1",
                                CWnd::m_hWnd, WM_USER+3, 10, "VT=i32 LT=prc",
                                CWnd::m_hWnd, WM_USER+2, 10);
    if (ErrCode != 0)
        m_ErrCode[10] = ErrCode;
    else
        m_CreateRequestCnt++;
    ...
}

<< Previous Topic
PviSetGlobEventMsg, PviXSetGlobEventMsg functions

Start Page

Next Topic >>
PviCreateResponse, PviXCreateResponse functions


PviCreateResponse, PviXCreateResponse functions

Definition for C/C++

int PviCreateResponse (WPARAM wParam, LPDWORD pLinkID)

int PviXCreateResponse (DWORD hPvi, WPARAM wParam, LPDWORD pLinkID)

Definition for Basic

PviCreateResponse (ByVal wParam As Long, ByRef pLinkID As Long) As Long

PviXCreateResponse (ByVal hPvi As Long, ByVal wParam As Long, ByRef pLinkID As Long) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
wParam | In | Reference to the response data. The "wParam" parameter from the user message must be specified.
pLinkID | Out | Pointer to the variable used to record the Link ID (only required if a link object was set up)

Return value

A value other than 0 signals an error. The error code is returned as a value. An error is reported if an error occurs while carrying out the request or if the connection between the communication instance and PVI Manager is disrupted (communication timeout). If the reference specified in "wParam" is not valid when the function is called (e.g. response data had been previously deleted), then Error 12055 (no response data present) is reported.

Description

This function is used to read the response from a request made by PviCreateRequest or PviXCreateRequest.

If a request has been made to set up a link object, then the Link ID is written to the variable specified by pLinkID. The link object can be clearly identified later with the Link ID. If a static process object has been set up, then a valid Link ID is not returned with the response. The pLinkID parameter may also be specified as a null pointer.

If a user message has been defined with the PviCreateRequest or PviXCreateRequest function call, then the PviCreateResponse or PviXCreateResponse function must be called once the user message is received. However, this does not apply when using a callback function of type PVICALLBACK_DATA.

<< Previous Topic
PviCreateRequest, PviXCreateRequest functions

Start Page

Next Topic >>
PviCreate, PviXCreate functions


PviCreate, PviXCreate functions

Definition for C/C++

int PviCreate (LPDWORD pLinkID, LPCSTR pObjectName, DWORD ObjectTyp, LPCSTR pObjektDescriptor, LPVOID hEventMsg, DWORD EventMsgNo, LPARAM EventParam, LPCSTR pLinkDescriptor)

int PviXCreate (DWORD hPvi, LPDWORD pLinkID, LPCSTR pObjectName, DWORD ObjectTyp, LPCSTR pObjektDescriptor, LPVOID hEventMsg, DWORD EventMsgNo, LPARAM EventParam, LPCSTR pLinkDescriptor)

Definition for Basic

PviCreate (ByRef pLinkID As Long, ByVal pObjectName As String, ByVal ObjectType As Long, ByVal pObjectDescriptor As String, ByVal hEventMsg As Long, ByVal EventMsgNo As Long, ByVal EventParam As Long, ByVal pLinkDescriptor As String) As Long

PviXCreate (ByVal hPvi As Long, ByRef pLinkID As Long, ByVal pObjectName As String, ByVal ObjectType As Long, ByVal pObjectDescriptor As String, ByVal hEventMsg As Long, ByVal EventMsgNo As Long, ByVal EventParam As Long, ByVal pLinkDescriptor As String) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
pLinkID | Out | Pointer to the variable used to record the Link ID (only required if a link object was set up)
pObjectName | In | Pointer to the object name or object path name. Given as a null-terminated string.
ObjectType | In | Object type entry. POBJ_LINE, POBJ_DEVICE, POBJ_STATION, POBJ_CPU, POBJ_MODUL, POBJ_TASK, POBJ_PVAR. If the object type is specified with the object name in pObjectName ("OT" parameter", then the object type given here is irrelevant.
pObjectDescriptor | In | Pointer to the process object description. Given as a null-terminated string.
hEventMsg | In | Definition of the user message which is assigned to the link object for signaling event data (events). If hEventMsg doesn't equal 0 (null), then a temporary process object and a link object are set up. If hEventMsg equals 0 (zero), then a static process object without a link object is set up.
EventMsgNo | In | Message number of the user message = 0 (Null): No user message for event data is assigned to the link object In this case, either 0 (zero) or any value not equal to 0 can be specified for hEventMsg (e.g. PVI_HMSG_NIL).
EventParam | In | message parameter of the user message The size of the message parameter (user parameter) in the 32-bit PVI version (PviCom.dll) is 4 bytes and in the 64-bit PVI version (PviCom64.dll) 8 bytes.
pLinkDescriptor | In | Pointer to the link object description. Given as a null-terminated string.

Return value

A value other than 0 signals an error. The error code is returned as a value. An error is reported if an error occurs while carrying out the request or if the connection between the communication instance and PVI Manager is interrupted (communication timeout).

Description

This function is the synchronous variant of PviCreateRequest / PviCreateResponse or PviXCreateRequest / PviXCreateResponse functionality. See the Asynchronous and synchronous functions section.

<< Previous Topic
PviCreateResponse, PviXCreateResponse functions

Start Page

Next Topic >>
PviDeleteRequest, PviXDeleteRequest functions


PviDeleteRequest, PviXDeleteRequest functions

Definition for C/C++

int PviDeleteRequest (LPCSTR pObjectName, LPVOID hResMsg, DWORD ResMsgNo, LPARAM ResParam)

int PviXDeleteRequest (DWORD hPvi, LPCSTR pObjectName, LPVOID hResMsg, DWORD ResMsgNo, LPARAM ResParam)

Definition for Basic

PviDeleteRequest (ByVal pObjectName As String, ByVal hResMsg As Long, ByVal ResMsgNo As Long, ByVal ResParam As Long) As Long

PviXDeleteRequest (ByVal hPvi As Long, ByVal pObjectName As String, ByVal hResMsg As Long, ByVal ResMsgNo As Long, ByVal ResParam As Long) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
pObjectName | In | Pointer to the object name or object path name. Given as a null-terminated string.
hResMsg | In | Definition of the user message which signals the response for this function call (Requests and Responses) = 0 (Null): No response is sent by PVI Manager
ResMsgNo | In | Message number of the user message = 0 (Null): Same meaning as hResMsg=0.
ResParam | In | message parameter of the user message The size of the message parameter (user parameter) in the 32-bit PVI version (PviCom.dll) is 4 bytes and in the 64-bit PVI version (PviCom64.dll) 8 bytes.

Return value

A value other than 0 signals an error. The error code is returned as a value. In principle, this function only reports Windows resource errors (e.g. not enough memory available) or user errors (e.g. illegal function parameters, incorrect function use, etc.). In this case, a request is not sent to PVI Manager and the defined response message is not executed. If an error occurs during data transfer or when handling the request, then it is reported only with the response data.

Description

This function sends a request to PVI Manager to delete a process object. Response data must be read with the PviDeleteResponse or PviXDeleteResponse function unless using a callback function of type PVICALLBACK_DATA.

This function is intended to delete static process objects. In principle, it is also possible to delete temporary process objects, but this is not necessary since deleting process objects takes place automatically when link objects are released.

When a process object is deleted, all subordinate process objects (object hierarchy) are also deleted and all connected link objects are released.

<< Previous Topic
PviCreate, PviXCreate functions

Start Page

Next Topic >>
PviDeleteResponse, PviXDeleteResponse functions


PviDeleteResponse, PviXDeleteResponse functions

Definition for C/C++

int PviDeleteResponse (WPARAM wParam)

int PviXDeleteResponse (DWORD hPvi, WPARAM wParam)

Definition for Basic

PviDeleteResponse (ByVal wParam As Long) As Long

PviXDeleteResponse (ByVal hPvi As Long, ByVal wParam As Long) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
wParam | In | Reference to the response data. The "wParam" parameter from the user message must be specified.

Return value

A value other than 0 signals an error. The error code is returned as a value. An error is reported if an error occurs while carrying out the request or if the connection between the communication instance and PVI Manager is disrupted (communication timeout). If the reference specified in "wParam" is not valid when the function is called (e.g. response data had been previously deleted), then Error 12055 (no response data present) is reported.

Description

This function is used to read the response from a request made by PviDeleteRequest or PviXDeleteRequest.

If a user message has been defined with the PviDeleteRequest or PviXDeleteRequest function call, then the PviDeleteResponse or PviXDeleteResponse function must be called once the user message is received. However, this does not apply when using a callback function of type PVICALLBACK_DATA.

<< Previous Topic
PviDeleteRequest, PviXDeleteRequest functions

Start Page

Next Topic >>
PviDelete, PviXDelete functions


PviDelete, PviXDelete functions

Definition for C/C++

int PviDelete (LPCSTR pObjectName)

int PviXDelete (DWORD hPvi, LPCSTR pObjectName)

Definition for Basic

PviDelete (ByVal pObjectName As String) As Long

PviXDelete (ByVal hPvi As Long, ByVal pObjectName As String) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
pObjectName | In | Pointer to the object name or object path name. Given as a null-terminated string.

Return value

A value other than 0 signals an error. The error code is returned as a value. An error is reported if an error occurs while carrying out the request or if the connection between the communication instance and PVI Manager is disrupted (communication timeout).

Description

This function is the synchronous variant of the PviDeleteRequest / PviDeleteResponse or PviXDeleteRequest / PviXDeleteResponse functionality. See the Asynchronous and synchronous functions section.

<< Previous Topic
PviDeleteResponse, PviXDeleteResponse functions

Start Page

Next Topic >>
PviLinkRequest, PviXLinkRequest functions


PviLinkRequest, PviXLinkRequest functions

Definition for C/C++

int PviLinkRequest (LPCSTR pObjectName, LPVOID hEventMsg, DWORD EventMsgNo, LPARAM EventParam, LPCSTR pLinkDescriptor, LPVOID hResMsg, DWORD ResMsgNo, LPARAM ResParam)

int PviXLinkRequest (DWORD hPvi, LPCSTR pObjectName, LPVOID hEventMsg, DWORD EventMsgNo, LPARAM EventParam, LPCSTR pLinkDescriptor, LPVOID hResMsg, DWORD ResMsgNo, LPARAM ResParam)

Definition for Basic

PviLinkRequest (ByVal pObjectName As String, ByVal hEventMsg As Long, ByVal EventMsgNo As Long, ByVal EventParam As Long, ByVal pLinkDescriptor As String, ByVal hResMsg As Long, ByVal ResMsgNo As Long, ByVal ResParam As Long) As Long

PviXLinkRequest (ByVal hPvi As Long, ByVal pObjectName As String, ByVal hEventMsg As Long, ByVal EventMsgNo As Long, ByVal EventParam As Long, ByVal pLinkDescriptor As String, ByVal hResMsg As Long, ByVal ResMsgNo As Long, ByVal ResParam As Long) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
pObjectName | In | Pointer to the object name or object path name. Given as a null-terminated string.
hEventMsg | In | Definition of the user message which is assigned to the link object for signaling event data (events). 0 (zero) cannot be specified for this parameter.
EventMsgNo | In | Message number of the user message = 0 (Null): No user message for event data is assigned to the link object In this case, any value other than zero can be specified for hEventMsg (e.g. PVI_HMSG_NIL).
EventParam | In | message parameter of the user message The size of the message parameter (user parameter) in the 32-bit PVI version (PviCom.dll) is 4 bytes and in the 64-bit PVI version (PviCom64.dll) 8 bytes.
pLinkDescriptor | In | Pointer to the link object description. Given as a null-terminated string.
hResMsg | In | Definition of the user message which signals the response for this function call (Requests and Responses) = 0 (Null): No response is sent by PVI Manager
ResMsgNo | In | Message number of the user message = 0 (Null): Same meaning as hResMsg=0.
ResParam | In | message parameter of the user message The size of the message parameter (user parameter) in the 32-bit PVI version (PviCom.dll) is 4 bytes and in the 64-bit PVI version (PviCom64.dll) 8 bytes.

Return value

A value other than 0 signals an error. The error code is returned as a value. In principle, this function only reports Windows resource errors (e.g. not enough memory available) or user errors (e.g. illegal function parameters, incorrect function use, etc.). In this case, a request is not sent to PVI Manager and the defined response message is not executed. If an error occurs during data transfer or when handling the request, then it is reported only with the response data.

Description

This function sends a request to PVI Manager to set up a link object. Response data must be read with the PviLinkResponse or PviXLinkResponse function unless using a callback function of type PVICALLBACK_DATA.

The object parameters defined with pLinkDescriptor are used when setting up the link object. The application receives a Link ID with the response data for identifying the set up link object.

Example for Visual C++

#include <PviCom.h>
class CPviDlg : public CDialog
{
    ...
    int m_LinkRequestCnt;
    DWORD m_LinkID[256];
    long m_ErrCode[256];

    void LinkPviObjects ();
    LRESULT OnPviLinkResp (WPARAM, LPARAM);
    LRESULT OnPviObjEvent (WPARAM, LPARAM);
    ...
    DECLARE_MESSAGE_MAP ()
};
BEGIN_MESSAGE_MAP (CPviDlg, CDialog)
    ...
    ON_MESSAGE (WM_USER+3, OnPviObjEvent)
    ON_MESSAGE (WM_USER+4, OnPviLinkResp)
END_MESSAGE_MAP()
LRESULT CPviDlg::OnPviObjEvent (WPARAM wParam, LPARAM lParam)
{
    ...
    return (0);
}
LRESULT CPviDlg::OnPviCreateResp (WPARAM wParam, LPARAM lParam)
{
    int ErrCode;
    DWORD LinkID;

    ErrCode = PviCreateResponse (wParam, &LinkID);
    if (ErrCode != 0)
        m_ErrCode[lParam] = ErrCode;
    else
        m_LinkID[lParam] = LinkID;

    if (--m_CreateRequestCnt <= 0)
    {
        // last create response was received:
        ...
    }
    return (0);
}
void CPviDlg::LinkPviObjects()
{
    int ErrCode;

    // Initialize members:
    m_LinkRequestCnt = 0;
    memset (m_LinkID, 0, sizeof (m_LinkID));
    memset (m_ErrCode, 0, sizeof (m_ErrCode));

    // Link to variable object PVar1 (process value):
    ErrCode = PviLinkRequest ("@Pvi/LNINA2/COM2/CPU/PVar1",
                              CWnd::m_hWnd, WM_USER+3, 0, "VT=i32 LT=prc",
                              CWnd::m_hWnd, WM_USER+4, 0);
    if (ErrCode != 0)
        m_ErrCode[0] = ErrCode;
    else
        m_LinkRequestCnt++;

    // First link to variable object PVar2 (raw value):
    ErrCode = PviLinkRequest ("@Pvi/LNINA2/COM2/CPU/PVar2",
                              CWnd::m_hWnd, WM_USER+3, 1, "VT=i32 LT=raw",
                              CWnd::m_hWnd, WM_USER+4, 1);
    if (ErrCode != 0)
        m_ErrCode[1] = ErrCode;
    else
        m_LinkRequestCnt++;

    // Second link to variable object PVar2 (process value):
    ErrCode = PviLinkRequest ("@Pvi/LNINA2/COM2/CPU/PVar2",
                              CWnd::m_hWnd, WM_USER+3, 101, "VT=i32 LT=prc",
                              CWnd::m_hWnd, WM_USER+4, 101);
    if (ErrCode != 0)
        m_ErrCode[101] = ErrCode;
    else
        m_LinkRequestCnt++;
    ...
}

<< Previous Topic
PviDelete, PviXDelete functions

Start Page

Next Topic >>
PviLinkResponse, PviXLinkResponse functions


PviLinkResponse, PviXLinkResponse functions

Definition for C/C++

int PviLinkResponse (WPARAM wParam, LPDWORD pLinkID)

int PviXLinkResponse (DWORD hPvi, WPARAM wParam, LPDWORD pLinkID)

Definition for Basic

PviLinkResponse (ByVal wParam As Long, ByRef pLinkID As Long) As Long

PviXLinkResponse (ByVal hPvi As Long, ByVal wParam As Long, ByRef pLinkID As Long) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
wParam | In | Reference to the response data. The "wParam" parameter from the user message must be specified.
pLinkID | Out | Pointer to variables used for recording the Link ID

Return value

A value other than 0 signals an error. The error code is returned as a value. An error is reported if an error occurs while carrying out the request or if the connection between the communication instance and PVI Manager is disrupted (communication timeout). If the reference specified in "wParam" is not valid when the function is called (e.g. response data had been previously deleted), then Error 12055 (no response data present) is reported.

Description

This function is used to read the response from a request made by PviLinkRequest or PviXLinkRequest.

The Link ID is written to the variable specified by pLinkID. The link object can be clearly identified later with the Link ID. The pLinkID parameter may also be specified as a null pointer.

If a user message has been defined with the PviLinkRequest or PviXLinkRequest function call, then the PviLinkResponse or PviXLinkResponse function must be called once the user message is received. However, this does not apply when using a callback function of type PVICALLBACK_DATA.

<< Previous Topic
PviLinkRequest, PviXLinkRequest functions

Start Page

Next Topic >>
PviLink, PviXLink functions


PviLink, PviXLink functions

Definition for C/C++

int PviLink (LPDWORD pLinkID, LPCSTR pObjectName, LPVOID hEventMsg, DWORD EventMsgNo, LPARAM EventParam, LPCSTR pLinkDescriptor)

int PviXLink (DWORD hPvi, LPDWORD pLinkID, LPCSTR pObjectName, LPVOID hEventMsg, DWORD EventMsgNo, LPARAM EventParam, LPCSTR pLinkDescriptor)

Definition for Basic

PviLink (ByRef pLinkID As Long, ByVal pObjectName As String, ByVal hEventMsg As Long, ByVal EventMsgNo As Long, ByVal EventParam As Long, ByVal pLinkDescriptor As String) As Long

PviXLink (ByVal hPvi As Long, ByRef pLinkID As Long, ByVal pObjectName As String, ByVal hEventMsg As Long, ByVal EventMsgNo As Long, ByVal EventParam As Long, ByVal pLinkDescriptor As String) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
pLinkID | Out | Pointer to variables used for recording the Link ID
pObjectName | In | Pointer to the object name or object path name. Given as a null-terminated string.
hEventMsg | In | Definition of the user message which is assigned to the link object for signaling event data (events). 0 (zero) cannot be specified for this parameter.
EventMsgNo | In | Message number of the user message = 0 (Null): No user message for event data is assigned to the link object In this case, any value other than zero can be specified for hEventMsg (e.g. PVI_HMSG_NIL).
EventParam | In | message parameter of the user message The size of the message parameter (user parameter) in the 32-bit PVI version (PviCom.dll) is 4 bytes and in the 64-bit PVI version (PviCom64.dll) 8 bytes.
pLinkDescriptor | In | Pointer to the link object description. Given as a null-terminated string.

Return value

A value other than 0 signals an error. The error code is returned as a value. An error is reported if an error occurs while carrying out the request or if the connection between the communication instance and PVI Manager is interrupted (communication timeout).

Description

This function is the synchronous variant of PviLinkRequest / PviLinkResponse or PviXLinkRequest / PviXLinkResponse functionality. See the Asynchronous and synchronous functions section.

<< Previous Topic
PviLinkResponse, PviXLinkResponse functions

Start Page

Next Topic >>
PviUnlinkRequest, PviXUnlinkRequest functions


PviUnlinkRequest, PviXUnlinkRequest functions

Definition for C/C++

int PviUnlinkRequest (DWORD LinkID, LPVOID hResMsg, DWORD ResMsgNo, LPARAM ResParam)

int PviXUnlinkRequest (DWORD hPvi, DWORD LinkID, LPVOID hResMsg, DWORD ResMsgNo, LPARAM ResParam)

Definition for Basic

PviUnlinkRequest (ByVal LinkID As Long, ByVal hResMsg As Long, ByVal ResMsgNo As Long, ByVal ResParam As Long) As Long

PviXUnlinkRequest (ByVal hPvi As Long, ByVal LinkID As Long, ByVal hResMsg As Long, ByVal ResMsgNo As Long, ByVal ResParam As Long) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
LinkID | In | Link ID from the PviCreateResponse, PviLinkResponse or PviXCreateResponse, PviXLinkResponse functions
hResMsg | In | Definition of the user message which signals the response for this function call (Requests and Responses) = 0 (Null): No response is sent by PVI Manager
ResMsgNo | In | Message number of the user message = 0 (Null): Same meaning as hResMsg=0.
ResParam | In | message parameter of the user message The size of the message parameter (user parameter) in the 32-bit PVI version (PviCom.dll) is 4 bytes and in the 64-bit PVI version (PviCom64.dll) 8 bytes.

Return value

A value other than 0 signals an error. The error code is returned as a value. In principle, this function only reports Windows resource errors (e.g. not enough memory available) or user errors (e.g. illegal function parameters, incorrect function use, etc.). In this case, a request is not sent to PVI Manager and the defined response message is not executed. If an error occurs during data transfer or when handling the request, then it is reported only with the response data.

Description

This function sends a request to PVI Manager to release a link object. Response data must be read with the PviUnlinkResponse or PviXUnlinkResponse function unless using a callback function of type PVICALLBACK_DATA.

If no additional link or process objects are assigned to a temporary process object, then the process object is also released.

Once a link object is released, no more events are via this object. In addition, all requests and response data assigned to the link object are deleted. The corresponding user message are no longer executed.

The application can still receive user messages for response or event data until the response of the unlink request is received.

If the PVICOM application should still receive the response data for all active requests when the link object is released, then the release procedure needs to be carried out in two steps:

  1. Send write request with access type POBJ_ACC_CANCEL and value '0' (zero) to the link object. This cancels all active requests and carries out the user messages from them. Error 12043 is reported with the response data.
  2. After receiving the response to the cancel request, send the request for releasing the link object.

<< Previous Topic
PviLink, PviXLink functions

Start Page

Next Topic >>
PviUnlinkResponse, PviXUnlinkResponse functions


PviUnlinkResponse, PviXUnlinkResponse functions

Definition for C/C++

int PviUnlinkResponse (WPARAM wParam)

int PviXUnlinkResponse (DWORD hPvi, WPARAM wParam)

Definition for Basic

PviUnlinkResponse (ByVal wParam As Long) As Long

PviXUnlinkResponse (ByVal hPvi As Long, ByVal wParam As Long) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
wParam | In | Reference to the response data. The "wParam" parameter from the user message must be specified.

Return value

A value other than 0 signals an error. The error code is returned as a value. An error is reported if an error occurs while carrying out the request or if the connection between the communication instance and PVI Manager is disrupted (communication timeout). If the reference specified in "wParam" is not valid when the function is called (e.g. response data had been previously deleted), then Error 12055 (no response data present) is reported.

Description

This function is used to read the response from a request made by PviUnlinkRequest or PviXUnlinkRequest.

If a user message has been defined with the PviUnlinkRequest or PviXUnlinkRequest function call, then the PviUnlinkResponse or PviXUnlinkResponse function must be called once the user message is received. However, this does not apply when using a callback function of type PVICALLBACK_DATA.

<< Previous Topic
PviUnlinkRequest, PviXUnlinkRequest functions

Start Page

Next Topic >>
PviUnlink, PviXUnlink functions


PviUnlink, PviXUnlink functions

Definition for C/C++

int PviUnlink (DWORD LinkID)

int PviXUnlink (DWORD hPvi, DWORD LinkID)

Definition for Basic

PviUnlink (ByVal LinkID As Long) As Long

PviXUnlink (ByVal hPvi As Long, ByVal LinkID As Long) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
LinkID | In | Link ID from the PviCreateResponse, PviLinkResponse or PviXCreateResponse, PviXLinkResponse functions

Return value

A value other than 0 signals an error. The error code is returned as a value. An error is reported if an error occurs while carrying out the request or if the connection between the communication instance and PVI Manager is disrupted (communication timeout).

Description

This function is the synchronous variant of PviUnlinkRequest / PviUnlinkResponse or PviXUnlinkRequest / PviXUnlinkResponse functionality. See the Asynchronous and synchronous functions section.

All response and event data for an object is deleted after the PviUnlink or PviXUnlink function is carried out. When using the window message as a user message, however, those user messages already sent can no longer be deleted (message queue). Error 12055 is returned if a PVICOM application responds to one of these user messages by calling a PVI response function (Pvi...Response or PviX...Response) or the PviGetResponseInfo or PviXGetResponseInfo function. The PVICOM application must therefore query for error 12055 and handle it accordingly. A better option is using the asynchronous functions PviUnlinkRequest / PviUnlinkResponse or PviXUnlinkRequest / PviXUnlinkResponse. This prevents the situation from happening since no additional user message exist for an object once the user message for the unlink response data has been received.

<< Previous Topic
PviUnlinkResponse, PviXUnlinkResponse functions

Start Page

Next Topic >>
PviChgLinkRequest, PviXChgLinkRequest functions


PviChgLinkRequest, PviXChgLinkRequest functions

Definition for C/C++

int PviChgLinkRequest (DWORD LinkID, DWORD EventMsgNo, LPARAM EventParam, LPVOID hResMsg, DWORD ResMsgNo, LPARAM ResParam)

int PviXChgLinkRequest (DWORD hPvi, DWORD LinkID, DWORD EventMsgNo, LPARAM EventParam, LPVOID hResMsg, DWORD ResMsgNo, LPARAM ResParam)

Definition for Basic

PviChgLinkRequest (ByVal LinkID As Long, ByVal EventMsgNo As Long, ByVal EventParam As Long, ByVal hResMsg As Long, ByVal ResMsgNo As Long, ByVal ResParam As Long) As Long

PviXChgLinkRequest (ByVal hPvi As Long, ByVal LinkID As Long, ByVal EventMsgNo As Long, ByVal EventParam As Long, ByVal hResMsg As Long, ByVal ResMsgNo As Long, ByVal ResParam As Long) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
LinkID | In | Link ID from the PviCreateResponse, PviLinkResponse or PviXCreateResponse, PviXLinkResponse functions
EventMsgNo | In | New message number of the user message. = 0 (Null): No user message for event data is assigned to the link object
EventParam | In | New message parameter of the user message The size of the message parameter (user parameter) in the 32-bit PVI version (PviCom.dll) is 4 bytes and in the 64-bit PVI version (PviCom64.dll) 8 bytes.
hResMsg | In | Definition of the user message which signals the response for this function call (Requests and Responses) = 0 (Null): No response is sent by PVI Manager
ResMsgNo | In | Message number of the user message = 0 (Null): Same meaning as hResMsg=0.
ResParam | In | message parameter of the user message The size of the message parameter (user parameter) in the 32-bit PVI version (PviCom.dll) is 4 bytes and in the 64-bit PVI version (PviCom64.dll) 8 bytes.

Return value

A value other than 0 signals an error. The error code is returned as a value. In principle, this function only reports Windows resource errors (e.g. not enough memory available) or user errors (e.g. illegal function parameters, incorrect function use, etc.). In this case, a request is not sent to PVI Manager and the defined response message is not executed. If an error occurs during data transfer or when handling the request, then it is reported only with the response data.

Description

This function sends a request to change the user message for event data. Response data must be read with the PviChgLinkResponse or PviXChgLinkResponse function unless using a callback function of type PVICALLBACK_DATA.

If a window message is used as a user message, then the message number (EventMsgNo) and the message parameter (EventParam) can be changed with PviChgLinkRequest. If using a callback function as a user message, only the message parameter can be changed (EventParam). Specifying the message number is irrelevant in this case.

The POBJ_ACC_EVMASK access type is intended to enable or disable events. The PviChgLinkRequest should not be used for this purpose.

<< Previous Topic
PviUnlink, PviXUnlink functions

Start Page

Next Topic >>
PviChgLinkResponse, PviXChgLinkResponse functions


PviChgLinkResponse, PviXChgLinkResponse functions

Definition for C/C++

int PviChgLinkResponse (WPARAM wParam)

int PviXChgLinkResponse (DWORD hPvi, WPARAM wParam)

Definition for Basic

PviChgLinkResponse (ByVal wParam As Long) As Long

PviXChgLinkResponse (ByVal hPvi As Long, ByVal wParam As Long) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
wParam | In | Reference to the response data. The "wParam" parameter from the user message must be specified.

Return value

A value other than 0 signals an error. The error code is returned as a value. An error is reported if an error occurs while carrying out the request or if the connection between the communication instance and PVI Manager is disrupted (communication timeout). If the reference specified in "wParam" is not valid when the function is called (e.g. response data had been previously deleted), then Error 12055 (no response data present) is reported.

Description

This function is used to read the response from a request made by PviChgLinkRequest or PviXChgLinkRequest.

If a user message has been defined with the PviChgLinkRequest or PviXChgLinkRequest function call, then the PviChgLinkResponse or PviXChgLinkResponse function must be called once the user message is received. However, this does not apply when using a callback function of type PVICALLBACK_DATA.

<< Previous Topic
PviChgLinkRequest, PviXChgLinkRequest functions

Start Page

Next Topic >>
PviChgLink, PviXChgLink functions


PviChgLink, PviXChgLink functions

Definition for C/C++

int PviChgLink (DWORD LinkID, DWORD EventMsgNo, LPARAM EventParam)

int PviXChgLink (DWORD hPvi, DWORD LinkID, DWORD EventMsgNo, LPARAM EventParam)

Definition for Basic

PviChgLink (ByVal LinkID As Long, ByVal EventMsgNo As Long, ByVal EventParam As Long) As Long

PviXChgLink (ByVal hPvi As Long, ByVal LinkID As Long, ByVal EventMsgNo As Long, ByVal EventParam As Long) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
LinkID | In | Link ID from the PviCreateResponse, PviLinkResponse or PviXCreateResponse, PviXLinkResponse functions
pLinkID | In | Pointer to variables used for recording the Link ID
EventMsgNo | In | New message number of the user message = 0 (Null): No user message for event data is assigned to the link object In this case, any value other than zero can be specified for hEventMsg (e.g. PVI_HMSG_NIL).
EventParam | In | New message parameter of the user message The size of the message parameter (user parameter) in the 32-bit PVI version (PviCom.dll) is 4 bytes and in the 64-bit PVI version (PviCom64.dll) 8 bytes.

Return value

A value other than 0 signals an error. The error code is returned as a value. An error is reported if an error occurs while carrying out the request or if the connection between the communication instance and PVI Manager is interrupted (communication timeout).

Description

This function is the synchronous variant of the PviChgLinkRequest / PviChgLinkResponse or PviXChgLinkRequest / PviXChgLinkResponse functionality. See the Asynchronous and synchronous functions section.

<< Previous Topic
PviChgLinkResponse, PviXChgLinkResponse functions

Start Page

Next Topic >>
PviUnlinkAll, PviXUnlinkAll functions


PviUnlinkAll, PviXUnlinkAll functions

Definition for C/C++

int PviUnlinkAll (LPVOID hEventMsg)

int PviXUnlinkAll (DWORD hPvi, LPVOID hEventMsg)

Definition for Basic

PviUnlinkAll (ByVal hEventMsgAs Long) As Long

PviXUnlinkAll (ByVal hPvi As Long, ByVal hEventMsgAs Long) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
hEventMsg | In | Window handle or pointer to callback function.

Return value

A value other than 0 signals an error. The error code is returned as a value. An error is reported if an error occurs while carrying out the request or if the connection between the communication instance and PVI Manager is interrupted (communication timeout).

Description

This function can be used to release several connection objects with one function call. The window handle or callback pointer specified in "hEventMsg" are compared with user messages to signal event data from all link objects in a communication instance. If they match, then the corresponding link object is released. In this way, all link objects assigned to a certain window or callback function can be released.

Once the link objects are released, no more events are sent for this object. In addition, all requests assigned to the link objects are cancelled and response data is deleted. The corresponding user message are no longer executed.

The PviUnlinkAll and PviXUnlinkAll functions work synchronously. There is no asynchronous variant. See the Asynchronous and synchronous functions section.

<< Previous Topic
PviChgLink, PviXChgLink functions

Start Page

Next Topic >>
PviReadRequest, PviXReadRequest functions


PviReadRequest, PviXReadRequest functions

Definition for C/C++

int PviReadRequest (DWORD LinkID, DWORD nAccess, LPVOID hResMsg, DWORD ResMsgNo, LPARAM ResParam)

int PviXReadRequest (DWORD hPvi, DWORD LinkID, DWORD nAccess, LPVOID hResMsg, DWORD ResMsgNo, LPARAM ResParam)

Definition for Basic

PviReadRequest (ByVal LinkID As Long, ByVal nAccess As Long, ByVal hResMsg As Long, ByVal ResMsgNo As Long, ByVal ResParam As Long) As Long

PviXReadRequest (ByVal hPvi As Long, ByVal LinkID As Long, ByVal nAccess As Long, ByVal hResMsg As Long, ByVal ResMsgNo As Long, ByVal ResParam As Long) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
LinkID | In | Link ID from the PviCreateResponse, PviLinkResponse or PviXCreateResponse, PviXLinkResponse functions
nAccess | In | Access type
hResMsg | In | Definition of the user message which signals the response for this function call (Requests and Responses) = 0 (Null): No response is sent by PVI Manager
ResMsgNo | In | Message number of the user message = 0 (Null): Same meaning as hResMsg=0.
ResParam | In | message parameter of the user message The size of the message parameter (user parameter) in the 32-bit PVI version (PviCom.dll) is 4 bytes and in the 64-bit PVI version (PviCom64.dll) 8 bytes.

Return value

A value other than 0 signals an error. The error code is returned as a value. In principle, this function only reports Windows resource errors (e.g. not enough memory available) or user errors (e.g. illegal function parameters, incorrect function use, etc.). In this case, a request is not sent to PVI Manager and the defined response message is not executed. If an error occurs during data transfer or when handling the request, then it is reported only with the response data.

Description

This function sends a read request to a link object. This link object then passes the request on to the assigned process object. The link object is set using the LinkID function parameter. If a user message has been defined with the read request, it will be executed as soon as the PVICOM communication instance receives the response from PVI Manager. To read the response data, the application needs to call the PviReadResponse or PviXReadResponse function. This does not apply when using a callback function of type PVICALLBACK_DATA.

An access type is assigned to select how read access takes place. The PviReadArgumentRequest or PviXReadArgumentRequest function needs to be used for read accesses with argument data.

<< Previous Topic
PviUnlinkAll, PviXUnlinkAll functions

Start Page

Next Topic >>
*PviReadArgumentRequest, PviXReadArgumentRequest functions


*PviReadArgumentRequest, PviXReadArgumentRequest functions

Definition for C/C++

int PviReadArgumentRequest (DWORD LinkID, DWORD nAccess, LPVOID pArgData, LONG ArgDataLen, LPVOID hResMsg, DWORD ResMsgNo, LPARAM ResParam)

int PviXReadArgumentRequest (DWORD hPvi, DWORD LinkID, DWORD nAccess, LPVOID pArgData, LONG ArgDataLen, LPVOID hResMsg, DWORD ResMsgNo, LPARAM ResParam)

Definition for Basic

PviReadArgumentRequest (ByVal LinkID As Long, ByVal nAccess As Long, ByRef pArgData As Any, ByVal ArgDataLen As Long, ByVal hResMsg As Long, ByVal ResMsgNo As Long, ByVal ResParam As Long) As Long

PviXReadArgumentRequest (ByVal hPvi As Long, ByVal LinkID As Long, ByVal nAccess As Long, ByRef pArgData As Any, ByVal ArgDataLen As Long, ByVal hResMsg As Long, ByVal ResMsgNo As Long, ByVal ResParam As Long) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
LinkID | In | Link ID from the PviCreateResponse, PviLinkResponse or PviXCreateResponse, PviXLinkResponse functions
nAccess | In | Access type
pArgData | In | Pointer to argument data for write access
ArgDataLen | In | Length of argument data = 0: No argument data present. 0 (zero) may be specified for pArgData.
hResMsg | In | Definition of the user message which signals the response for this function call (Requests and Responses) = 0 (Null): No response is sent by PVI Manager
ResMsgNo | In | Message number of the user message = 0 (Null): Same meaning as hResMsg=0.
ResParam | In | message parameter of the user message The size of the message parameter (user parameter) in the 32-bit PVI version (PviCom.dll) is 4 bytes and in the 64-bit PVI version (PviCom64.dll) 8 bytes.

Return value

A value other than 0 signals an error. The error code is returned as a value. In principle, this function only reports Windows resource errors (e.g. not enough memory available) or user errors (e.g. illegal function parameters, incorrect function use, etc.). In this case, a request is not sent to PVI Manager and the defined response message is not executed. If an error occurs during data transfer or when handling the request, then it is reported only with the response data.

Description

This function works similarly to the PviReadRequest or PviXReadRequest function. The only difference is that argument data for read access can be specified with PviReadArgumentRequest or PviXReadArgumentRequest. Access types which require argument data for read requests (e.g. OBJ_ACC_UPLOAD)therefore need to use this function.

<< Previous Topic
PviReadRequest, PviXReadRequest functions

Start Page

Next Topic >>
PviReadResponse, PviXReadResponse functions


PviReadResponse, PviXReadResponse functions

Definition for C/C++

int PviReadResponse (WPARAM wParam, LPVOID pData, LONG DataLen)

int PviXReadResponse (DWORD hPvi, WPARAM wParam, LPVOID pData, LONG DataLen)

Definition for Basic

PviReadResponse (ByVal wParam As Long, ByRef pData As Any, ByVal DataLen As Long) As Long

PviXReadResponse (ByVal hPvi As Long, ByVal wParam As Long, ByRef pData As Any, ByVal DataLen As Long) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
wParam | In | Reference to the response data. The "wParam" parameter from the user message must be specified.
pData | Out | Pointer to the user data buffer used for recording the response or event data
DataLen | In | Length of the user data buffer in bytes = 0: Response or event data is not copied. 0 (zero) may be specified for pData.

Return value

A value other than 0 signals an error. The error code is returned as a value. An error can be reported when reading the response data to a read request if an error occurs when the request is executed, if the communication instance connection to PVI Manager is interrupted (communication timeout), or if there is an application error. The value '0' signals that the read request has been carried out and the response data in the user data buffer is valid. Unless there is an application error, an error can only be reported in connection with the POBJ_EVENT_ERROR when reading event data.

If the reference specified in "wParam" is not valid when the function is called (e.g. response data had been previously deleted), then Error 12055 (no response or event data present) is reported.

Description

This function is used to read event data or response data from a previously made request by PviReadRequest / PviXReadRequest or PviReadArgumentRequest / PviXReadArgumentRequest.

This response or event data is copied to the user data buffer. If the length of the user data buffer is larger than the length actual data, then whatever space remains in the buffer will be filled with binary 0's (zero). If the length of user data buffer is smaller than the length of the data, then copying is stopped when the end of the buffer is reached. Any remaining response or event data is lost. To prevent this from happening, the PVI application has to set the dimensions of the user data buffer accordingly. To achieve this, the application can ask for the length of the response/event data with the PviGetResponseInfo or PviXGetResponseInfo function before this function is called.

After receiving the user message in connection with a read request or an event, the PviReadResponse or PviXReadResponse must be called. However, this does not apply when using a callback function of type PVICALLBACK_DATA.

<< Previous Topic
*PviReadArgumentRequest, PviXReadArgumentRequest functions

Start Page

Next Topic >>
PviRead, PviXRead functions


PviRead, PviXRead functions

Definition for C/C++

int PviRead (DWORD LinkID, DWORD nAccess, LPVOID pArgData, LONG ArgDataLen, LPVOID pData, LONG DataLen)

int PviXRead (DWORD hPvi, DWORD LinkID, DWORD nAccess, LPVOID pArgData, LONG ArgDataLen, LPVOID pData, LONG DataLen)

Definition for Basic

PviRead (ByVal LinkID As Long, ByVal nAccess As Long, ByRef pArgData As Any, ByVal ArgDataLen As Long, ByRef pData As Any, ByVal DataLen As Long) As Long

PviXRead (ByVal hPvi As Long, ByVal LinkID As Long, ByVal nAccess As Long, ByRef pArgData As Any, ByVal ArgDataLen As Long, ByRef pData As Any, ByVal DataLen As Long) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
LinkID | In | Link ID from the PviCreateResponse, PviLinkResponse or PviXCreateResponse, PviXLinkResponse functions
nAccess | In | Access type
pArgData | In | Pointer to argument data for write access
ArgDataLen | In | Length of argument data = 0: No argument data present. 0 (zero) may be specified for pArgData.
pData | Out | Pointer to the user data buffer used for recording the response data
DataLen | In | Length of the user data buffer in bytes = 0: No response data is copied. 0 (zero) may be specified for pData.

Return value

A value other than 0 signals an error. The error code is returned as a value. An error is reported if an error occurs while carrying out the read request or if the connection between the communication instance and PVI Manager is disrupted (communication timeout) or if an application error occurs. The value '0' signals that the read request has been carried out and the response data in the user data buffer is valid.

Description

This function is the synchronous variant of PviReadArgumentRequest / PviReadResponse or PviXReadArgumentRequest / PviXReadResponse functionality. See the Asynchronous and synchronous functions section.

<< Previous Topic
PviReadResponse, PviXReadResponse functions

Start Page

Next Topic >>
PviWriteRequest, PviXWriteRequest functions


PviWriteRequest, PviXWriteRequest functions

Definition for C/C++

int PviWriteRequest (DWORD LinkID, DWORD nAccess, LPVOID pData, LONG DataLen, LPVOID hResMsg, DWORD ResMsgNo, LPARAM ResParam)

int PviXWriteRequest (DWORD hPvi, DWORD LinkID, DWORD nAccess, LPVOID pData, LONG DataLen, LPVOID hResMsg, DWORD ResMsgNo, LPARAM ResParam)

Definition for Basic

PviWriteRequest (ByVal LinkID As Long, ByVal nAccess As Long, ByRef pData As Any, ByVal DataLen As Long, ByVal hResMsg As Long, ByVal ResMsgNo As Long, ByVal ResParam As Long) As Long

PviXWriteRequest (ByVal hPvi As Long, ByVal LinkID As Long, ByVal nAccess As Long, ByRef pData As Any, ByVal DataLen As Long, ByVal hResMsg As Long, ByVal ResMsgNo As Long, ByVal ResParam As Long) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
LinkID | In | Link ID from the PviCreateResponse, PviLinkResponse, or PviXCreateResponse, PviXLinkResponse functions.
nAccess | In | Access type
pData | In | Pointer to write data
DataLen | In | Length of the write data in bytes = 0: No write data present. 0 (zero) may be specified for pData.
hResMsg | In | Definition of the user message which signals the response for this function call (Requests and Responses) = 0 (Null): No response is sent by PVI Manager
ResMsgNo | In | Message number of the user message = 0 (Null): Same meaning as hResMsg=0.
ResParam | In | message parameter of the user message The size of the message parameter (user parameter) in the 32-bit PVI version (PviCom.dll) is 4 bytes and in the 64-bit PVI version (PviCom64.dll) 8 bytes.

Return value

A value other than 0 signals an error. The error code is returned as a value. In principle, this function only reports Windows resource errors (e.g. not enough memory available) or user errors (e.g. illegal function parameters, incorrect function use, etc.). In this case, a request is not sent to PVI Manager and the defined response message is not executed. If an error occurs during data transfer or when handling the request, then it is reported only with the response data.

Description

This function sends a write request to a link object. This link object then passes the request on to the assigned process object. The link object is set using the LinkID function parameter. If a user message has been defined with the write request, it will be executed as soon as the PVICOM communication instance receives the response from PVI Manager. To read the response data, the application needs to call the PviWriteResponse or PviXWriteResponse function. This does not apply when using a callback function of type PVICALLBACK_DATA.

An access type is assigned to each write request to select how write access takes place.

<< Previous Topic
PviRead, PviXRead functions

Start Page

Next Topic >>
PviWriteResponse, PviXWriteResponse functions


PviWriteResponse, PviXWriteResponse functions

Definition for C/C++

int PviWriteResponse (WPARAM wParam)

int PviXWriteResponse (DWORD hPvi, WPARAM wParam)

Definition for Basic

PviWriteResponse (ByVal wParam As Long) As Long

PviXWriteResponse (ByVal hPvi As Long, ByVal wParam As Long) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
wParam | In | Reference to the response data. The "wParam" parameter from the user message must be specified.

Return value

A value other than 0 signals an error. The error code is returned as a value. An error can be reported when reading the response data to a write request if an error occurs when the request is executed, if the communication instance connection to PVI Manager is interrupted (communication timeout), or if there is an application error. The value '0' signals that the write request has been carried out.

If the reference specified in "wParam" is not valid when the function is called (e.g. response data had been previously deleted), then Error 12055 (no response present) is reported.

Description

This function is used to read the response data from a request made by PviWriteRequest or PviXWriteRequest.

After receiving the user message in connection with a write request, the PviWriteResponse/PviXWriteResponse or PviWriteResultResponse/PviXWriteResultResponse function needs to be called. However, this does not apply when using a callback function of type PVICALLBACK_DATA.

<< Previous Topic
PviWriteRequest, PviXWriteRequest functions

Start Page

Next Topic >>
PviWriteResultResponse, PviXWriteResultResponse functions


PviWriteResultResponse, PviXWriteResultResponse functions

Definition for C/C++

int PviWriteResultResponse (WPARAM wParam, LPVOID pRstData, LONG RstDataLen)

int PviXWriteResultResponse (DWORD hPvi, WPARAM wParam, LPVOID pRstData, LONG RstDataLen)

Definition for Basic

PviWriteResultResponse (ByVal wParam As Long, ByRef pRstData As Any, ByVal RstDataLen As Long) As Long

PviXWriteResultResponse (ByVal hPvi As Long, ByVal wParam As Long, ByRef pRstData As Any, ByVal RstDataLen As Long) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
wParam | In | Reference to the response data. The "wParam" parameter from the user message must be specified.
pRstData | Out | Pointer to the user data buffer used for recording the result data
RstDataLen | In | Length of the user data buffer in bytes = 0: No result data is copied. 0 (zero) may be specified for pRstData.

Return value

A value other than 0 signals an error. The error code is returned as a value. An error can be reported when reading the response data to a write request if an error occurs when the request is executed, if the communication instance connection to PVI Manager is interrupted (communication timeout), or if there is an application error. The value '0' signals that the write request has been carried out.

If the reference specified in "wParam" is not valid when the function is called (e.g. response data had been previously deleted), then Error 12055 (no response present) is reported.

Description

This function works similarly to the PviWriteResponse or PviXWriteResponse function. The only difference is that the PviWriteResultResponse or PviXWriteResultResponse function can be used to read result data of a write access.

After receiving the user message in connection with a write request, the PviWriteResponse/PviXWriteResponse or PviWriteResultResponse/PviXWriteResultResponse function needs to be called. However, this does not apply when using a callback function of type PVICALLBACK_DATA.

<< Previous Topic
PviWriteResponse, PviXWriteResponse functions

Start Page

Next Topic >>
PviWrite, PviXWrite functions


PviWrite, PviXWrite functions

Definition for C/C++

int PviWrite (DWORD LinkID, DWORD nAccess, LPVOID pData, LONG DataLen, LPVOID pRstData, LONG RstDataLen)

int PviXWrite (DWORD hPvi, DWORD LinkID, DWORD nAccess, LPVOID pData, LONG DataLen, LPVOID pRstData, LONG RstDataLen)

Definition for Basic

PviWrite (ByVal LinkID As Long, ByVal n Access As Long, ByRef pData As Any, ByVal DataLen As Long, ByRef pRstData As Any, ByVal RstDataLen As Long) As Long

PviXWrite (ByVal hPvi As Long, ByVal LinkID As Long, ByVal n Access As Long, ByRef pData As Any, ByVal DataLen As Long, ByRef pRstData As Any, ByVal RstDataLen As Long) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
LinkID | In | Link ID from the PviCreateResponse, PviLinkResponse or PviXCreateResponse, PviXLinkResponse functions
nAccess | In | Access type
pData | In | Pointer to write data
DataLen | In | Length of the write data in bytes = 0: No write data present. 0 (zero) may be specified for pData.
pRstData | Out | Pointer to the user data buffer used for recording the result data
RstDataLen | In | Length of the user data buffer in bytes = 0: No result data is copied. 0 (zero) may be specified for pRstData.

Return value

A value other than 0 signals an error. The error code is returned as a value. An error is reported if an error occurs while carrying out the write request or if the connection between the communication instance and PVI Manager is disrupted (communication timeout) or if an application error occurs. The value '0' signals that the write request has been carried out and the result data (if present) in the user data buffer is valid.

Description

This function is the synchronous variant of PviWriteRequest / PviWriteResultResponse or PviXWriteRequest / PviXWriteResultResponse functionality. See the Asynchronous and synchronous functions section.

<< Previous Topic
PviWriteResultResponse, PviXWriteResultResponse functions

Start Page

Next Topic >>
PviGetResponseInfo, PviXGetResponseInfo functions


PviGetResponseInfo, PviXGetResponseInfo functions

Definition for C/C++

int PviGetResponseInfo (WPARAM wParam, LPARAM* pParam, LPDWORD pDataLen, T_RESPONSE_INFO* pInfo, DWORD InfoLen)

int PviGetXResponseInfo (DWORD hPvi, WPARAM wParam, LPARAM* pParam, LPDWORD pDataLen, T_RESPONSE_INFO* pInfo, DWORD InfoLen)

Definition for Basic

PviGetResponseInfo (ByVal wParam As Long, ByRef pParam As Long, ByRef pDataLen As Long, ByRef pInfo As T_RESPONSE_INFO, ByVal InfoLen As Long) As Long

PviXGetResponseInfo (ByVal hPvi As Long, ByVal wParam As Long, ByRef pParam As Long, ByRef pDataLen As Long, ByRef pInfo As T_RESPONSE_INFO, ByVal InfoLen As Long) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
wParam | In | Pointer to response or event data. The "wParam" parameter from the user message must be specified.
pParam | Out | Pointer to the variable for recording the user parameter. The size of the user parameter in the 32-bit PVI version (PviCom.dll) is 4 bytes and in the 64-bit PVI version (PviCom64.dll) 8 bytes. If the user parameter is not needed, then a null pointer can be specified.
pDataLen | Out | Pointer to a variable (4 bytes) for recording the length of the response or event data. If the length is not needed, then a null pointer can be specified. The value 0 (zero) as a response data length means that there is no response data present.
pInfo | Out | Pointer to a user buffer (T_RESPONSE_INFO structure) where additional information is copied. If additional information is not needed, then a null pointer can be specified.
InfoLen | In | Size of the user buffer "pInfo" in bytes

Return value

A value other than 0 signals an error. The error code is returned as a value. This function only returns errors which occur when it is called, such as user errors (e.g. illegal function parameters) or Error 12055 (no response data present). Errors which affect the request itself can only be read with the appropriate response function or from the RESPONSE_INFO structure.

If the response or event data is deleted (e.g. PviUnlink) between when the user message is received and when the function PviGetResponseInfo or PviXGetResponseInfo is called, the function returns error 12055. It is therefore recommended to poll error 12055, and in this case skip further handling of the user message (response function call).

Description

The application can use the PviGetResponseInfo or PviXGetResponseInfo function to read information about the response or event data after a user message is received. The function can only be executed before the corresponding response function is called. This function cannot be used in connection with synchronous functions. Calling this function is also not necessary when using a callback function of type PVICALLBACK_DATA as a user message.

<< Previous Topic
PviWrite, PviXWrite functions

Start Page

Next Topic >>
PviGetNextResponse, PviXGetNextResponse functions


PviGetResponseInfo, PviXGetResponseInfo functions

PviGetNextResponse, PviXGetNextResponse functions

Definition for C/C++

int PviGetNextResponse (WPARAM* pwParam, LPARAM* plParam, LPVOID* phMsg, HANDLE hEvent)

int PviGetXNextResponse (DWORD hPvi, WPARAM* pwParam, LPARAM* plParam, LPVOID* phMsg, HANDLE hEvent)

Definition for Basic

PviGetNextResponse (ByRef pwParam As Long, ByRef plParam As Long, ByRef phMsg As Long, ByVal hEvent As Long) As Long

PviGetXNextResponse (ByVal hPvi As Long, ByRef pwParam As Long, ByRef plParam As Long, ByRef phMsg As Long, ByVal hEvent As Long) As Long

Arguments

Argument | I/O | Description
hPvi | In | Instance handle from the PviXInitialize function
pwParam | Out | Pointer to the variable used to link to response or event data
plParam | Out | Pointer to the variable for recording the user parameter. The size of the user parameter in the 32-bit PVI version (PviCom.dll) is 4 bytes and in the 64-bit PVI version (PviCom64.dll) 8 bytes. If the user parameter is not needed, then a null pointer can be specified.
phMsg | Out | Pointer to variable (pointer) used for recording the user message (second user parameter). If the user message is not needed, then a null pointer can be specified.
hEvent | In | Handle for a system event. If no system event is needed, then a null pointer can be specified.

Return value

A value other than 0 signals an error. The error code is returned as a value. This function only returns errors which occur when it is called (e.g. illegal function parameters or internal errors). Errors in the response data are not reported here.

Description

This function can only be used together with a user message of type PVIFUNCTION (see message function).

The functions PviGetNextResponse and PviXGetNextResponse provide the user message for the next response or event data of the respective communication instance. The user message consists of a link (parameter "wParam") to the response or event data, and the user parameter. A valid link is always a value not equal to 0 (zero). If the value 0 (zero) is returned, no response or event data was available at the time of the function call.

The program does not wait within the function for the next user message. The PVICOM application must therefore do the waiting (pause the system thread) itself (e.g. call the system function WaitForSingleObject).

Optionally a handle can be applied to the function of a defined system event. The handle is stored in the communication instance. As soon as response or event data are available, the system event is set.

Example for polling operation (Visual C++):

bool   bExit = FALSE;
WPARAM wParam;
while (! bExit)
{
    ErrCode = PviGetNextResponse (&wParam, NULL, NULL, NULL);
    if (ErrCode != 0)
        bExit = TRUE;
    else
        if (wParam == 0)
            Sleep (20);
        else
        {
            // read response/event data

            ...
        }
}

Example for event-controlled operation (Visual C++):

bool   bExit = FALSE;
HANDLE hEvent
WPARAM wParam;
hEvent = CreateEvent (NULL, FALSE, FALSE, NULL);
while (! bExit)
{
    ErrCode = PviGetNextResponse (&wParam, NULL, NULL, hEvent);
    if (ErrCode != 0)
        bExit = TRUE;
    else
        if (wParam == 0)
            WaitForSingleObject (hEvent, INFINITE);
        else
        {
            // read response/event data

            ...
        }
}
CloseHandle (hEvent);

<< Previous Topic
PviGetResponseInfo, PviXGetResponseInfo functions

Start Page

Next Topic >>
PviGetVersion function


PviGetVersion function

Definition for C/C++

void PviGetVersion (LPSTR pVersionBf, DWORD VersionBfLen)

Definition for Basic

PviGetVersion (ByVal pVersionBf As String, ByVal VersionBfLen As Long)

Arguments

Argument | I/O | Description
pVersionBf | Out | Pointer to the user buffer for recording the version string
VersionBfLen | In | Length of the user buffer in bytes

Description

This function copies the current version string of PVICOM.DLL to the user buffer.

Versions of other PVI components (manager, lines, devices, etc.) can be determined with access type POBJ_ACC_VERSION.

<< Previous Topic
PviGetNextResponse, PviXGetNextResponse functions

Start Page

Next Topic >>
PVICOM structures


PVICOM functions

PVICOM structures

Structure | Description
PROCEEDING_INFO | Events of event type POBJ_EVENT_PROCEEDING transfer event data using the format of the PROCEEDING_INFO structure.
RESPONSE_INFO | Information about event or response data is transferred using the format of the RESPONSE_INFO structure. (see User messages of type PVICALLBACK_DATA and PVICOM function PviGetResponseInfo)

<< Previous Topic
PviGetVersion function

Start Page

Next Topic >>
PROCEEDING_INFO structure


PROCEEDING_INFO structure

Structure for C/C++

 typedef struct
{
    DWORD nAccess;
    DWORD Percent;
    char Info[32];
} T_PROCEEDING_INFO;

Structure for Basic

Public Type T_PROCEEDING_INFO
    nAccess As Long
    Percent As Long
    Info As String * 32
End Type

Elements

Element | Description
nAccess | Access type of the running request
Percent | Progress given in % (0 - 100)
Info | Additional information text for display

<< Previous Topic
PVICOM structures

Start Page

Next Topic >>
RESPONSE_INFO structure


RESPONSE_INFO structure

Structure for C/C++

 typedef struct
{
DWORD LinkID;
    DWORD nMode;
    DWORD nType;
    DWORD ErrCode;
    DWORD Status;
}  T_RESPONSE_INFO;

Structure for Basic

Public Type T_RESPONSE_INFO
    LinkID As Long
    nMode As Long
    nType As Long
    ErrCode As Long
    Status As Long
End Type

Elements

Element | Description
LinkID | Link ID
nMode | User message mode See following table
nType | Access type or event type If an event (nMode = POBJ_MODE_EVENT), then nType contains the type of event. If a response to a read or write request (nMode = POBJ_MODE_READ or nMode = POBJ_MODE_WRITE), then nType contains the access type of the request.
ErrCode | If ErrCode is not equal to 0 (zero=, then an error is reported with the response or event data. The same error is reported as a return value when reading the response or event data with the corresponding "Response" function. However, if a different error is passed on as the return value, then this error occurred right when the function was called.
Status | Status contains the status flags (bits) of the response or event data See following table

Definition of status flags (bits) in the "Status" element:

Status flag | Bit | Description
RESP_STATUS_CAST_OVERFLOW | #0 | Upper range exceeded during type casting
RESP_STATUS_CAST_UNDERFLOW | #1 | Lower range exceeded during type casting
RESP_STATUS_OVERFLOW | #2 | Upper limit value exceeded with the data function
RESP_STATUS_UNDERFLOW | #3 | Lower limit value exceeded with the data function
RESP_STATUS_POBJ | #4 | The limit value transgression (RESP_STATUS_OVERFLOW or RESP_STATUS_UNDERFLOW) occurred in the data function of the process object.
RESP_STATUS_LINK | #5 | A limit value transgression (RESP_STATUS_OVERFLOW or RESP_STATUS_UNDERFLOW) occurred in the data function of the link object.
RESP_STATUS_INHERIT_ERR | #8 | Error state was received from a higher-level process object
RESP_STATUS_OVERWRITE | #9 | Event data overwritten by more current data at least once. See section "Event".

Definition for the mode of the user message in the "nMode" element:

Mode | No. | Description
POBJ_MODE_NULL | #0 | Undefined
POBJ_MODE_EVENT | #1 | Global event or event
POBJ_MODE_READ | #2 | Response to a PviReadRequest or PviReadArgumentRequest request
POBJ_MODE_WRITE | #3 | Response to a PviWriteRequest request
POBJ_MODE_CREATE | #4 | Response to a PviCreateRequest request
POBJ_MODE_DELETE | #5 | Response to a PviDeleteRequest request
POBJ_MODE_LINK | #6 | Response to a PviLinkRequest request
POBJ_MODE_CHGLINK | #7 | Response to a PviChgLinkRequest request
POBJ_MODE_UNLINK | #8 | Response to a PviUnlinkRequest request

<< Previous Topic
PROCEEDING_INFO structure

Start Page

Next Topic >>
PVI lines


PVI lines

The basic task of a PVI line is to connect PVI objects (service objects) with objects outside of PVI. The line is also responsible for communicating with B&R controllers (PLCs) and determines the communication protocol to be used to do so.

PVI contains the following lines (line servers):

Line name | Name and usage
LNANSL | ANSL line: Communication with the ANSL protocol (SG4).
LNINA2 | INA2000 line: Communication with the INA2000 protocol (SG3, SGC, SG4).
LNNET2 | NET2000 line: Communication with the NET2000 protocol (SG3, SGC, SG4).
LNMINI | MININET line: Communication with the MININET protocol (SG2)
LNDCAN | Direct CAN line: Sending and receiving CAN messages
LNSNMP | SNMP line: Access to the SNMP variables of a B&R PLC.
LNADI | ADI line: Access to B&R Automation Device Interface (ADI) functions.
LNMTC | MTC line: Access to Maintenance Controller (MTC) functions
LNMODBUS | MODBUS line: Communication with MODBUS TCP controller.

Line servers are Windows DLLs which are loaded by PVI Manager as needed. The path name of the line servers (lines) are entered in the PVI configuration file (PviConfig.xml) along with their line-specific parameters (Pvi->PviBase->PviLine->).

Line object

To assign a line server to a line object (process object of type POBJ_LINE), the line name needs to be specified in the line object's connection description. This loads the line DLL configured under the line name (PVI configuration file). Alternatively, the name of the line DLL can be specified in the connection description. However, PVI applications should only use the configured line name for the connection description. Line names are not case sensitive.

Connection description syntax:

/LN=<LineName>

or

<LineName>

If the line name is defined as the /LN parameter, the connection description must always be specified in quotation marks ("...") in the object description.

Connection description example:

CD="/LN=LnIna2"

or

CD=LnIna2

<< Previous Topic
RESPONSE_INFO structure

Start Page

Next Topic >>
ANSL line


ANSL line

The ANSL line is used to communicate with B&R SG4 controllers using the ANSL (Automation Network Service Link) protocol.

The following topics are covered in this section:

  • Compatibility with INA2000
  • ANSL process objects
  • ANSL access types
  • ANSL line access types
  • ANSL event types
  • ANSL line event types
  • ANSL communication

Compatibility with INA2000

All services and objects from the INA2000 line are also supported by the ANSL line. The only differences are in the connection description for line, device and CPU objects.

In contrast to INA2000, ANSL only supports Ethernet TCP/IP communication. Establishing a connection using the node number (/DA and /SA parameters with INA2000) is not possible with ANSL.

Like all PVI lines, the ANSL line also provides an error range (error codes 11000 to 11999).

Checklist for switching from INA to ANSL:

  • The PLC Automation Runtime version must be at 4.08 or higher.
  • There must be sufficient memory available on the PLC. The memory requirements for ANSL are specified in the Functionality section.
  • The connection description for line objects must be changed from "LnIna2" to "LnAnsl".
  • "/IF=TcpIp" must be specified in the connection description for the device object.
  • The /DAIP parameter from INA2000 must be specified in the connection description for the CPU object, or the ANSL /IP parameter must (additionally) be specified. The /REPO parameter must not be specified or, if so, changed to "/REPO=11169". Alternatively, the /PT parameter can also (additionally) be used.
    Example for a CPU valid connection description for INA2000 and ANSL: "/DAIP=10.43.50.244 /REPO=11159 /IP=10.43.50.244 /PT=11169"

The most important expansions in the ANSL line:

  • Structure variables can also be used as PLC event variables.
  • Data consistency can be selected when writing and reading variable data larger than 4 bytes.
  • "Hot" reading of variable data during a redundancy event on redundant PLCs.
  • Information services in XML format.

These expansions in the ANSL line are not supported by the INA2000 line.

ANSL process objects

A line object, a device object, and a CPU object are all needed to establish a communication connection to a PLC.

Process objects in the ANSL line:

Name | Type | Connection | Usage
Line object | Line | "LNANSL" | ANSL line
Device object | Device | Device parameter | Represents the communication device being used
Station object | Station |  | Can be specified, but not required.
CPU object | CPU | ANSL communication parameter | Represents a PLC in a network
Module object | Modules | PLC module name and optional application module name | Represents a module on the PLC
Task object | Task | PLC task name and optional application module name | Represents a task on the PLC
Variable object | Pvar | PLC variable name and optional application module name | Represents a variable on the PLC

Allowed object structure for ANSL process objects:

There is no limit to the number of process objects. Theoretically, any number of device objects can be assigned to a line object, any number of CPU objects can be assigned to a device object, etc.

ANSL access types

The following table shows an overview of all access types which are regulated via a line. All access types not listed here as well as access types to the PVI base object are executed by PVI Manager and therefore work independently of the line being used. The corresponding process object type is listed in the "Type" column.

Access types | Type | Special features
POBJ_ACC_VERSION Line
CPU
Module
Task 		Line object: Version of the line DLL.
CPU object: PLC operating system is read ("Vxxx").
Modules and task object: Module version is read ("x.xx").
POBJ_ACC_LIST_EXTERN | Line | List of all installed (PVI Setup) ANSL devices
POBJ_ACC_DATA | Pvar
POBJ_ACC_STATUS Cpu
Module
Task
Pvar
POBJ_ACC_TYPE_EXTERN | Pvar
POBJ_ACC_UPLOAD | Modules | POBJ_EVENT_PROCEEDING is supported. Optionally, the function "Translate BR modules" can be performed.
POBJ_ACC_DOWNLOAD | CPU | POBJ_EVENT_PROCEEDING is supported. Optionally, the function "Translate BR modules" can be performed.
POBJ_ACC_DATE_TIME Cpu
Module
POBJ_ACC_MEM_DELETE | CPU
POBJ_ACC_MEM_INFO | CPU
POBJ_ACC_MOD_TYPE | Modules
POBJ_ACC_UPLOAD_STM | Modules | POBJ_EVENT_PROCEEDING is supported. Optionally, the function "Translate BR modules" can be performed.
POBJ_ACC_DOWNLOAD_STM | CPU | POBJ_EVENT_PROCEEDING is supported. Optionally, the function "Translate BR modules" can be performed.
POBJ_ACC_MOD_DATA | Modules | Reads and writes payload data from B&R log data modules
POBJ_ACC_MOD_DELETE | CPU
POBJ_ACC_LIST_STATION | Not supported
POBJ_ACC_LIST_CPU | Not supported
POBJ_ACC_LIST_MODULE CPU List of a PLC's module objects

Syntax of the module object list:
[<ApplicationModuleName1>::]<ModuleName1> \t [<ApplicationModuleName2>::]<ModuleName2> ...
All object entries are separated with the character \t (tabulator).
<ApplicationModuleName>: Name of the application module
<ModuleName>: Name of the module object

If the module object is within the scope of an application module, then the application module name is specified as well. An application module name is not specified for module objects within the default scope. The visibility of objects within the scope of application modules must be enabled in the connection description of the CPU object using the /AM parameter.

An optional filter can be specified during the call (PviReadArgumentRequest or PviXReadArgumentRequest function) that can be applied to the list:

<Name>:: | ... | List contains only module objects within the scope of the application module called <Name>
:: | ... | List contains only module objects within the default scope
*:: | ... | Disables the filter (identical to calling the PviReadRequest or PviXReadRequest function)
POBJ_ACC_LIST_TASK CPU List of a PLC's task objects

Syntax of the task list:
[<ApplicationModuleName1>::]<TaskName1> \t [<ApplicationModuleName2>::]<TaskName2> ...
All object entries are separated with the character \t (tabulator).
<ApplicationModuleName>: Name of the application module
<TaskName>: Name of the task object

If the task object is within the scope of an application module, then the application module name is specified as well. An application module name is not specified for task objects within the default scope. The visibility of objects within the scope of application modules must be enabled in the connection description of the CPU object using the /AM parameter.

An optional filter can be specified during the call (PviReadArgumentRequest or PviXReadArgumentRequest function) that can be applied to the list:

<Name>:: | ... | List contains only task objects within the scope of the application module called <Name>
:: | ... | List contains only task objects within the default scope
*:: | ... | Disables the filter (identical to calling the PviReadRequest or PviXReadRequest function)
POBJ_ACC_LIST_PVAR CPU
task 		List of variables in a task or list of global PLC variables

Syntax of the variable object list:
[<ApplicationModuleName1>::]<VariableName1> [<Info>] \t [<ApplicationModuleName2>::]<VariableName2> [<Info>] ...
All object entries are separated by the \t character (tab).
<ApplicationModuleName>: Name of the application module
<VariableName>: Connection name for the task object.
<Info>: Description string for additional information

The variable list contains additional information such as scope (global or local variables) and variable type.

If this access type is executed for a task object, then the list will contain all local and global variable objects in that task. Application module names are not included in this list since it is the task that handles the assignment to an application module.

If this access type is executed for the CPU object, then the list will contain all global variable objects on the PLC. If a global variable object is within the scope of an application module, then the application module name is specified as well. An application module name is not specified for variable objects within the default scope. The visibility of objects within the scope of application modules must be enabled in the connection description of the CPU object using the /AM parameter.

An optional filter can be specified via the CPU object during the call (PviReadArgumentRequest or PviXReadArgumentRequest function) that can be applied to the list:

<Name>:: | ... | List contains only global variable objects within the scope of the application module called <Name>
:: | ... | List contains only global variable objects within the default scope
*:: | ... | Disables the filter (identical to calling the PviReadRequest or PviXReadRequest function)
POBJ_ACC_CPU_INFO | CPU
Access type > 255 | CPU | Line access types approved for PVI customer applications are listed in the ANSL line access types section.

ANSL line access types

The following table lists all of the ANSL line event types approved for use in PVI customer applications. The corresponding process object type is listed in the "Type" column.

Access types | Type | Special features
POBJ_ACC_LN_COMM_DST | CPU | Reads ANSL communication parameters
POBJ_ACC_LN_LKN_LIST | CPU |
POBJ_ACC_LN_XML_LIC_STATUS | CPU |
POBJ_ACC_LN_XML_CPU_INFO | CPU |
POBJ_ACC_LN_XML_MOD_INFO | Module Task |
POBJ_ACC_LN_XML_TASK_INFO | Task | In addition to task information, this access type contains all of the module information of the POBJ_ACC_LN_XML_MOD_INFO access type.
POBJ_ACC_LN_XML_MOD_LIST | CPU | Only if the module list parameter "/MODLIST=1" is specified in the connection description of the CPU object
POBJ_ACC_LN_XML_MEM_INFO | CPU |
POBJ_ACC_LN_XML_HW_INFO | CPU |
POBJ_ACC_LN_XML_RED_INFO | CPU |
POBJ_ACC_LN_XML_TC_INFO | CPU |

ANSL event types

The following table shows an overview of all event types which can be generated from a line. All event types which are not listed are generated by PVI Manager and therefore work independently of the line being used.

Event types | Special features
POBJ_EVENT_STATUS | Only supports link node variables (Pvar process object type) and BR log data modules (Module process object type)
POBJ_EVENT_PROCEEDING | Progress events are supported for access types OBJ_ACC_UPLOAD, POBJ_ACC_UPLOAD_STM, POBJ_ACC_DOWNLOAD, and POBJ_ACC_DOWNLOAD_STM.
Event type > 255 | Line event types approved for PVI customer applications are listed in the ANSL line event types section.

ANSL line event types

The following table lists all of the ANSL line event types permitted for use in PVI customer applications. The corresponding process object type is listed in the "Type" column.

Event types | Type | Special features
POBJ_EVENT_LN_XML_MOD_LIST | CPU | Only if the module list parameter "/MODLIST=1" is specified in the connection description of the CPU object
POBJ_EVENT_LN_XML_RED_CTRL | CPU | Only if the redundancy parameter "/RED=1" is specified in the connection description of the CPU object

<< Previous Topic
PVI lines

Start Page

Next Topic >>
ANSL communication


ANSL communication

The ANSL line can be operated on the following platforms:

Windows platform | Limitations
Windows 7 or higher | -
Windows XP/Vista | -

Functionality

ANSL is an interface based on service objects. Each of these service objects represents an object group or an individual object on the PLC (e.g. CPU, task, process variable, group of all global process variables, etc.). Service objects are created on both sides of an ANSL communication connection (client and server). Each of these service object pairs forms a separate communication channel within an ANSL communication connection. Each ANSL service (request/response, event) is mapped to a service object and executed via the respective communication channel. All communication channels with pending data to be transmitted are entered on a transmit list. The transmit list (and the associated sending of data) then takes place asynchronously in a separate thread (or task). The ANSL interface has a symmetrical structure. For this reason, all stations participating in communication (client and server) use the same transfer strategy.

For each service object mapped to the ANSL line, a corresponding ANSL service object is set up. It should be noted that an ANSL service object is also set up on the PLC (AR ANSL online server). PVI applications must take into account the additional memory requirements on the PLC.

PLC memory requirements for a process variable object:

Operating mode of the process variable | PLC memory requirements
Process variable in "polling" mode | 340 bytes + length of the variable name in characters
Process variable in event mode | 400 bytes + length of the variable name in characters + length of the variable data in bytes (at least 4 bytes, however).
The memory requirements are increased by 8 bytes for a process variable with synchronous read/write access.

Memory requirements must be calculated separated for each ANSL connection and then added together.

Example:

Two PVI stations (PCs) should each establish an ANSL connection to a PLC.
Station 1 requires 10,000 variables with an average variable size of 26 bytes and average variable name length of 10 characters.
Station 2 requires 25,000 variables with an average variable size of 8 bytes and average variable name length of 20 characters.

Calculation for "polling" mode:

(10000 * (340 + 10)) + (25000 * (340 + 20)) = 12.5 MB

Calculation for event mode (PLC event PVs):

(10000 * (400 + 10 + 26)) + (25000 * (400 + 20 + 8)) = 15.1 MB

Redundant PLC system

The ANSL line supports bumpless reading of process variable data on a redundant PLC system.

IP addresses:

In the situation shown above, CPU 1 is the active part of the redundant PLC system. CPU 2 is inactive but ready for operation. If CPU 1 fails (redundancy triggered), then CPU 2 becomes active automatically. The virtual IP address always refers to the active CPU. During the switchover from CPU 1 to CPU 2, however, the virtual address connection is temporarily interrupted.

With bumpless reading, a separate ANSL connection is established from the ANSL line to each CPU using the physical address. The data in registered process variables is read by both CPUs. Only the data of the active CPU is passed on to the PVI application, however. If redundancy is triggered, the ANSL line toggles the data source, and the data from the previously inactive CPU is passed on to the PVI application. Running ANSL services (e.g. write variable data, download, etc.) are always aborted during a redundancy switchover, however.

With a redundant PLC system, the PVI application can configure the type of communication connection through the selection of the IP address (CPU object parameter /IP) and redundancy mode (CPU object parameter /RED).

/IP parameter | /RED parameter | Type of communication connection
Virtual IP address | 1 | Connection to the active CPU. Bumpless reading of process variables. If redundancy is triggered, a connection interruption is not indicated.
Virtual IP address | 0 | Connection to the active CPU. No bumpless reading of process variables. If redundancy is triggered, a connection interruption will be indicated temporarily.
Physical IP address 1 | - | Connection to CPU 1. If CPU 1 fails, the communication connection is interrupted.
Physical IP address 2 | - | Connection to CPU 2. If CPU 2 fails, the communication connection is interrupted.

With bumpless reading of process variable data, two ANSL communication connections are set up in the ANSL line for each CPU object instance. For the PVI station (PC), this means increased resource requirements and reduced performance.

PLC requirements

  • ANSL communication works with restrictions (services) beginning with Automation Runtime 4.00.
  • In order to be able to use all services (e.g. upload/download modules), Automation Runtime 4.08 or higher is needed.

ANSL requests are processed on the PLC during idle time. To ensure suitable response times, an idle time of 25% is a minimum requirement. If 25% idle time cannot be guaranteed for technical reasons, the response time increases resulting in a slower data refresh rate.

ANSL service objects require memory space on the PLC. ANSL memory requirements are listed in the Functionality section.

In this section the following topics are discussed:

ANSL communication

Ethernet TCP communication

ARsim communication

<< Previous Topic
ANSL line

Start Page

Next Topic >>
Ethernet TCP communication


ANSL communication

Ethernet TCP communication

PC requirements

The TCP/IP protocol must be installed.

PLC requirements

To use ANSL communication over Ethernet, Ethernet communication must be enabled in Automation Studio. See user documentation for Automation Studio version being used.

Using several Ethernet network cards on a PC

How can you be sure that PVI uses the correct network card to communicate with the controller if two or more network cards are located on the PC?

The subnet mask needs to be set correctly so that the correct network card for PLC communication is selected. The IP address of the target station (PLC) is linked with the subnet mask with an AND operation resulting in the correct network card being found and used for communication purposes.

Example:

Device parameter: /IF=tcpip /SA=1
CPU Parameter /DA=13 /DAIP=172.43.70.13
IPAdr NW1: 172.43.71.12 Subnet Mask: 255.255.255.0
IPAdr NW2: 172.43.70.12 Subnet Mask: 255.255.255.0
IPAdr SPS: 172.43.70.13

This would make sure that the second network card is used for PLC communication. If a DHCP server is configured for a network card, then it must be known which IP address and subnet masks the DHCP server specifies so that the second network card can be configured correctly.

<< Previous Topic
ANSL communication

Start Page

Next Topic >>
ARsim communication


ANSL ARsim communication

ARsim communication

Communication with ARsim takes place via an Ethernet TCP device and with local IP address 127.0.0.1.

Connection description for device

"/IF=TcpIp",

Connection description for station

"/IP=127.0.0.1 /PT=11169".

PC requirements

ARsim runtime emulation must be installed.

<< Previous Topic
Ethernet TCP communication

Start Page

Next Topic >>
ANSL device object


ANSL device objects

ANSL only supports Ethernet TCP/IP communication. For this reason, "TcpIp" must always be defined in the device object's connection description.

Connection description:

/IF=TcpIp

Device names are not case-sensitive. Additional parameters are not necessary for the device object.

<< Previous Topic
ARsim communication

Start Page

Next Topic >>
ANSL CPU-object


ANSL CPU object

The ANSL CPU object is used to specify the PLC in a network and to configure parameters for the communication connection.

The parameters for determining the PLC and controlling ANSL communication are defined in the connection description of the CPU object. Within the connection description, individual parameters are differentiated between using parameter identifiers. These parameter identifiers always begin with the "/" character.

Syntax of connection description:

[/AM=<Name>] [/IP=<Address>] [/PT=<PortNumber>] [/<Identifier1>=<ParameterValue> [/<Identifier2>=<ParameterValue>... ]]

The connection description must always be specified in quotation marks ("...") in the object description. At least one empty space is to be entered between the individual parameter specifications.

Communication parameters:

The following table shows all the communication parameters that can be defined in the CPU object's connection description.

Par. | Value | Settings | Description
/AM Name *) This parameter defines the scope of application modules and therefore sets the visibility of objects in the PVI. The setting made for the CPU object applies to all mapped module, task and variable objects.

Syntax:
/AM=<Name>[::]
The <Name> can be the name of an application module, an "empty string" or the wildcard "*"(asterisk).
Examples: "/AM=*::", "/AM=Generator::", "/AM=::"

Effects of these settings:
/AM=<Name> or /AM=<Name>:: | ... | The default scope and the scope of the application module with the name <Name> are visible.
/AM='' or /AM=:: | ... | Only the default scope is visible. This setting ensures compatibility with PVI Version 3.0.3 and lower.
/AM=* or /AM=*:: | ... | All scopes are visible in the PVI. Recommended setting for all new PVI applications.
/IP IP address
Host name 		127.0.0.1 IP address of the target station.
Manual identification of the target station from the IP address or identification from the host name (DNS).
Examples: "/IP=68.10.10.27" ... IP address, "/IP=CP340su" ... Host name.
/PT | 1024 - 32767 | 11169 | IP port number of the target station (PLC)
/COMT 500 - 360000 2500 ANSL communication timeout in ms
The value specified here also determines the time frame in which an interrupted connection is detected by ANSL (e.g. after a CPU restart or disconnection of the network cable). For this reason, a very high value should not be used for the ANSL communication timeout.

Recommended values:
500 - 1500 | ... | For connections over a local network with pure variable communication to controllers with sufficient idle time
1500 - 2500 | ... | For connections over a local network with additional PLC services running (e.g. Automation Studio project transfer) on controllers with sufficient idle time
2500 - 5000 | ... | For connections over an in-house network
5000 - 15000 | ... | For connections via Intranet/Internet.
>15,000 | ... | Only for special cases (e.g. debugging PVI applications)
/SDT 0 - 15000 2 ANSL transmission delay in ms
The transmission delay allows ANSL to collect transmission jobs so they can be sent in a single frame. This also prevents the PLC from becoming overloaded by too many jobs. The default value for the transmission delay is 2 ms. In individual cases (e.g. for slow or heavily overloaded PVI stations), however, a higher value can be specified (e.g. 20 ms or higher) to increase the data transfer rate, thereby also improving performance.
/SDT=0 disables the transmission delay. This setting is only designed for test purposes, however, and should not be used in normal operation.
/PVROI | 0 / 1 | 0 | Global setting for the index type of array variables. The setting made for the CPU object applies to all assigned ANSL variable objects (local and global).
/MODLIST 0 / 1 *) Configures the behavior of the ANSL line when identifying (registering) process variables

Possible settings:
/MODLIST=0 | ... | Does not read the module list. Process variables (local and global) are identified via ANSL services. Advantage: The delay time for reading the module list is omitted. Disadvantage: Structure variables cannot be used. The amount of information with the POBJ_ACC_TYPE_EXTERN access type is reduced. Read services for the variable, task and module list cannot be used. This setting is recommended for PVI application that require only a temporary communication connection to read data from a few individual variables.
/MODLIST=1 | ... | Reads the module list. Process variables (local and global) are identified using the module list. Advantage: There are no limitations on services or variable types. Disadvantage: The entire module list must be read by the ANSL line after the first process variable is set up.
/RED 0 / 1 0 Sets the behavior of the ANSL line on redundant PLC systems if redundancy is in force. The ANSL communication connection must be established via the virtual IP address for this. If the ANSL communication connection is routed via the physical IP address, this parameter has no effect.

Possible settings:
/RED=0 | ... | Disables redundancy mode. If a redundancy event occurs, the connection is temporarily interrupted.
/RED=1 | ... | Enables redundancy mode. If redundancy is triggered, a connection interruption is not indicated. Process variable data is read smoothly. Running ANSL services (e.g. writing variable data, downloading, etc.) are always aborted, however.
/DAIP | This parameter is identical to the /IP parameter and only supported to establish INA2000 compatibility. The /DAIP parameter is always overwritten, however, when the /IP parameter is specified.
/REPO | This parameter is identical to the /PT parameter and only supported to establish INA2000 compatibility. The /REPO parameter is always overwritten, however, when the /PT parameter is specified.
/RT | This parameter corresponds to the /COMT parameter and only supported to establish INA2000 compatibility. In contrast to /COMT, the value specified here is multiplied by a factor of 3 in the ANSL line. The /RT parameter is always overwritten, however, when the /COMT parameter is specified.
*) The default value for the /AM and /MODLIST parameters is defined in the PVI configuration file (PviConfig.xml) by the attribute AppMod and ModList.
<Pvi>
   ...
   <PviBase>
   ...
     <PviLine>
       <LNANSL ... AppMod="::" ModList="1" ... >
         ...

The parameters entered in the CPU object always overwrite the parameters in the configuration file. The settings in the configuration file only apply if the corresponding parameters are not specified in the connection description of the CPU object.

Connection description example:

CD="/AM=* /IP=10.43.50.244 /COMT=3000 /RED=1"

<< Previous Topic
ANSL device object

Start Page

Next Topic >>
ANSL module object


ANSL module object

The ANSL module object represents a module that exists on the PLC.

The name of the module must be specified in the connection description. If the module is within the scope of an application module, then the name of the application module needs to be specified along with the module name. The application module name and name of the module are separated by the "::" characters. Application module names and module names are both case-sensitive.

Modules within the scope of an application module can only be addressed by specifying the /AM CPU object parameter.

Syntax of connection description:

/RO=[<NameOfApplicationModule>::]<NameOfModule>

or

[<NameOfApplicationModule>::]<NameOfModule>

If the module name is defined as the /RO parameter, the connection description must always be specified in quotation marks ("...") in the object description.

Connection description examples:

CD="/RO=Module1"
CD="/RO=Generator::Module1"
CD=Module2
CD=Generator::Module2

<< Previous Topic
ANSL CPU-object

Start Page

Next Topic >>
ANSL task object


ANSL task objects

The ANSL task object represents a PLC task.

The name of the task must be specified in the connection description. If the task (module) is within the scope of an application module, then the name of the application module needs to be specified along with the task name (module name). The application module name and name of the task are separated by the "::" characters. Application module names and task names are both case-sensitive.

Tasks within the scope of an application module can only be addressed by specifying the /AM CPU object parameter.

Syntax of connection description:

/RO=[<ApplicationModuleName>::]<TaskName>

or

[<ApplicationModuleName>::]<TaskName>

If the task name is defined as the /RO parameter, the connection description must always be specified in quotation marks ("...") in the object description.

Connection description examples:

CD="/RO=Task1"
CD="/RO=Generator::Task1"
CD=Task2
CD=Generator::Task2

<< Previous Topic
ANSL module object

Start Page

Next Topic >>
ANSL variable object


ANSL variable objects

This section covers normal PLC variables (PVs). The features of link node variables are covered in a different section.

The ANSL line supports PLC event variables (see also the AT parameter). Monitoring for changes in the process data is already being carried out on the PLC. PVI Manager doesn't need to carry out any cyclic read requests. If the data in a PLC variable is not changed very often (at least not as often as the refresh time), then operating as a PLC event variable can reduce the data coming up in ANSL communication. However, one disadvantage of this is an increased need for computing time on the PLC. It needs to be noted that specifying the refresh time (RF parameter) also has an effect on PLC event variables. All variable types can be operated as PLC event variables.

The data format of the variable object is predefined by the ANSL line and corresponds to that of the PLC variable or an element of the PLC variable. The data contained in structure variables is always transferred in compressed form with ANSL (Alignment = 1). Using type casting, a PVI application can set the structure data to a selected alignment. The data format description can be read using access type POBJ_ACC_TYPE or event type POBJ_EVENT_DATAFORM. Information about the dimensions of array variables and the structure elements of structure variables can be read using access type POBJ_ACC_TYPE_EXTERN.

If "/MODLIST=0" is specified in the connection description of the CPU object, structure variables cannot be accessed.

The ANSL variable object represents a PLC variable. An ANSL variable object can be created at two different positions in the PVI object structure. If the variable object is created under a CPU object, then a global PLC variable is addressed. If the variable object is created under an ANSL task object, then a local PLC variable (task variable) is addressed.

The name of the PLC variable must be specified in the connection description. For global variables within the scope of an application module, the name of the application module needs to be specified along with the variable name. The application module name and name of the variable are separated by the "::" characters. For local variables, the scope of the application module is determined by the assigned task. It is not necessary to specify the name of an application module in the connection description of the variable object in this case. Application module names and task names are both case-sensitive.

Global variables within the scope of an application module can only be addressed by specifying the /AM CPU object parameter.

Syntax of connection description:

/RO=[<ApplicationModuleName>::]<Variable> [/<Identifier1>=<ParameterValue> [/<Identifier2>=<ParameterValue> ... ]]

or

[<ApplicationModuleName>::]<Variable> [/<Identifier1>=<ParameterValue> [/<Identifier2>=<ParameterValue> ... ]]

Syntax for <Variable>:

<VariableName> ... Accesses single variables, array variables or structure variables
<VariableName>[<Index>] ...
/ROI=0 | ... | Accesses an element of an array variable using flat indexing
/ROI=1 | ... | Accesses an element of an one-dimensional array variable using dimensional indexing
<VariableName>[<Index>,] ... Accesses an element of an one-dimensional array variable using dimensional indexing
<VariableName>[<Index1>,<Index2>, ...] ... Accesses an element of a multi-dimensional array variable using dimensional indexing
<VariableName>[<Index1>..<Index2>] ... Accesses a range of an one-dimensional array variable
<VariableName>.<ElementName> ... Accesses an element of a structure variable

Dynamic variables are specified like static variables. If a pointer to a dynamic variable should be read, then "&" must precede the variable name.

If the variable name is defined as the /RO parameter, the connection description must always be specified in quotation marks ("...") in the object description.

Variable parameters:

The following table lists parameters that can be defined in the connection description of the variable object.

Par. | Value | Settings | Description
/RO | Definition of variables
/ROI | 0 / 1 | 0 | Defines indexing of array variables
/SYNC 0 / 1 0 Defines synchronized write/read access to variable data on the PLC

Possible settings:
/SYNC=0 | ... | Data consistency can only be ensured for single variables with a maximum size of 4 bytes and single variable of type double (8-byte float). This setting corresponds to write/read access to variables in INA2000. If the data from entire structures or fields should be transferred consistently, the user must implement corresponding measures (e.g. with handshake variables).
/SYNC=1 | ... | Write/Read access to variable data on the PLC is synchronized with the task class, thus guaranteeing data consistency. With synchronized write/read access, the variable data is copied to a buffer in the context of the respective task class. Only one copy procedure takes place in each task class cycle. The size of the buffer is currently 4096 bytes. This results in the following limitations: 1. The maximum data size of a synchronized variable is limited by the size of the buffer. 2. If the data size of all synchronized variables is greater than the size of the buffer, then the copy procedure will be split up across several task class cycles. In this case, it may not be possible to observe the predefined refresh rate or the associated necessary currentness of the variable data. For this reason, synchronized write/read access should be used sparingly.
/ZERO 0 / 1 0 Configures variable initialization.
Specifying "/ZERO=1" initializes single variables with 0 (zero) after setting up the corresponding variable object and restoring an interrupted communication connection.

Indexing of array variables:

Elements of array variables can be indexed 2 different ways:

Indexing | Parameter | Description
Flat | /ROI=0 | The first element is always addressed with index 0. Multi-dimensional array variables are handled one-dimensionally (flat). This type of indexing may only be used for multi-dimensional array variables in connection with the CPU object parameter specification "/MODLIST=1".
Dimensional | /ROI=1 | The first element is addressed with the lower index declared for the variable, and can also be unequal to 0 or negative. To index an element of a multi-dimensional array variable, the indexes must be specified for all dimensions. If fewer indexes are specified, the remaining dimensions are interpreted as an area.

The /ROI parameter can also be specified globally in the CPU object as the /PVROI parameter. Specifying for the variable object overwrites the global setting.

The types of indexing are differentiated by the entry of a "," (comma) or the parameter /ROI (or /PVROI in the CPU object). To use dimensional indexing for single dimension array variables, you must enter a comma or specify the parameter /ROI=1 (or /PVROI=1 in the CPU object) after the index (or index range) (example: "/RO=var[13,]" or "/RO=var[13] /ROI=1").

The following rules apply for the parameter /ROI:

  • Specification of the parameter is optional. Default: /ROI=0.
  • The parameter can be specified for any variable, but is only effective if it has an index number.
  • Entering the character ',' (comma) in the index overwrites the setting /ROI=0.

The following rules apply for the /PVROI (CPU object):

  • Specification of the parameter is optional. Default: /PVROI=0.
  • The parameter affects all variable objects assigned to the CPU object (local and global).
  • The settings for the parameters /PVROI and /ROI are linked by an OR when evaluated.
  • Entering the character ',' (comma) in the index overwrites the setting /PVROI=0.

Example for indexing array variables:

The following indexing examples show dimensional and flat indexing for a two-dimensional array variable [0..3] [0..4] named "Field".

The element numbers 1 to 20 indicate the location of the elements in memory. The numbers 0.0 to 3.4 indicate the index of the elements for dimensional indexing.

Field[2,3]
Field[13]

In both cases the element 14 is indexed.

Field[1,]
Field[5..9]

In both cases, elements 6 to 10 are indexed (range entry).

Field[3.1..4]
Field[16..19]

In both cases, elements 17 to 20 are indexed (range entry).

Field[0..2,]
Field[0..14]

In both cases, elements 1 to 15 are indexed (range entry).

Field[8..11]

Elements 9 to 12 are indexed (range entry). Ranges that overlap dimensions can only be defined using flat indexing.

Connection description examples:

CD="/RO=TempValue"

Single variable "TempValue" is addressed.

CD="/RO=View::TempValue"

Addresses the single variable "TempValue" within the scope of the "View" application module

CD=TempField[2]
CD=TempField[7,]
CD="/RO=TempField[7] /ROI=1"

Addresses the 3rd element of the array variable "TempField [5..10]"

CD=Vert.Stat.TempField[0]
CD=Vert.Stat.TempField[0,]

Addresses the 1st element of the array variable "TempField [0..10]" inside the "Stat" structure and the "Vert" structure

CD=Sensor[3].Value
CD=Sensor[-2,].Value

Addresses the "Value" element within the 4th element of the "Sensor [-5..5]" structure array variable

CD="&ViewBf"

Addresses the pointer to the dynamic variable "ViewBf"

Example of object description:

AT=rwe CD="/RO=View::TempValue"

Addresses the single variable "TempValue" within the scope of the "View" application module and operates it as a PLC event variable

<< Previous Topic
ANSL task object

Start Page

Next Topic >>
Translating BR modules


Translating BR modules

In PVI, a module download is carried out with access type POBJ_ACC_DOWNLOAD or POBJ_ACC_DOWNLOAD_STM, and a module upload is carried out with access type POBJ_ACC_UPLOAD or POBJ_ACC_UPLOAD_STM.

If a module type is defined in the call string (MT parameter), payload is extracted from the BR module during the upload or a BR module is generated from the payload during a download.

This procedure is carried out in special PVI components - BR module translation libraries (Windows DLLs). The first three characters in the module type determine the translation library being used. This is loaded by the ANSL line if need be. The path names of the translation libraries are entered in the PVI configuration file (PviConfig.xml) (Pvi->PviBase->PviLine->LNANSL->BrTrans).

Module type | Description
BRT | Binary module translation

Binary module translation

Additional parameters in the call string during module download / upload:

Param. | Description
MT | "MT=BRT" must be specified.
MN | The name of the module must be specified when downloading.
MV | When downloading, it is possible to specify the version number of the module (default: MV=0).

Example of a complete call string for module downloading:

"C:\BRSRC\test1.txt" MT=BRT MN=Test1 MV=1.0 LD=Ram

Example of a complete call string for module uploading:

"C:\BRSRC\test1.txt" MT=BRT


Link node variables

A link node represents the status of a connection between a PV and an I/O point.

Link node variables in PVI can be used for observation (e.g. evaluating the link node status) or monitoring (e.g. displaying data from inputs regardless of the force state).

In the ANSL line, the data and status of a link node are accessed using ANSL variable objects. Like global PLC variables, these variable objects must be set up under the CPU object. PVI can be used to access the producer, force, and consumer values of a link node. The following image shows the PVI "pick-up" points within a link node for the producer, force, and consumer values.

Each of the three pick-up points (producer, force, and consumer) are mapped in PVI using a separate variable object. Code letters in the variable object's connection description are used for differentiation. The producer and consumer values can only be read (read-only access). The force value can be both read and written. Link node variables cannot be used as PLC event variables. Otherwise, link node variables behave the same as normal variables (PLC PVs) in PVI.

Syntax of connection description:

/RO=<Identifier>+<LinkNodeName>

or

<Identifier>+<LinkNodeName>

<Identifier> | Pick-up point
P | Producer value
F | Force value
C | Consumer value

The link node name begins with the percent character (%). This is followed by the prefix "I" (input), "Q" (output) or "M" (memory) and the prefix "X" (1-bit), "B" (1-byte), "W" (2-byte), "D" (4-byte) or "L" (8-byte) in accordance with IEC 61131-3. The next data point path is separated by a period (.).

If the /RO parameter is specified, the connection description must always be specified in quotation marks ("...") in the object description.

Connection description example:

CD="/RO=C+%IX.SL3.Input10"

Accesses the consumer value of the link node variable "Input10" on slot 3.

Link node status

The status of a link node can be read via all connected variable objects (POBJ_ACC_STATUS access type). Link node variables in the ANSL line also support status events (POBJ_EVENT_STATUS event type).

The link node status in ANSL is read together with the link node data. This allows the status to always be as current as the data.

Link node status syntax:

ST=Lkn.<Source> FC=<Force> UL=<UnresolvedLink> [IO=<Attribute>]

Par. | Description
ST | <Source> is used to specify the source of the link node variable's data. "d" .. Default value, "p" .. Producer value, "f" .. Force value Specifying the source depends on the pick-up point being used.
FC | <force> is used to specify the force state. 1 .. Force active, 0 .. Force inactive
UL | <UnresolvedLink> indicates PV links to the link node. 1 .. At least one PV link present, 0 .. No PV links present
IO | <Attribute> indicates the type of I/O link. "r" .. Link with input, "w" .. Link with output. Simulated I/O modules are identified by an 's'. If the IO parameter is not specified, there is no I/O link.

Example of link node status:

ST=Lkn.p FC=0 UL=1 IO=r

<< Previous Topic
Translating BR modules

Start Page

Next Topic >>
INA2000 line


INA2000 line

The INA2000 line is used for communication with B&R SG3, SGC and SG4 controllers via INA2000 protocol (Industrial Network Architecture).

The following topics are covered in this section:

  • INA2000 process objects
  • INA2000 access types
  • INA2000 line access types
  • INA2000 event types
  • INA2000 communication

INA2000 with AR 3.00

For PVI applications that access a controller with AR 3.00 or higher (SG4) and AR 2.30 (SGC) via the INA2000 line with a PVI version below V3.0.0, error 4813 can be output for all global variables, and error 4806 can be output for all local variables.

Cause: | Due to additions to Automation Studio and Automation Runtime Versions AR 3.00 (SG4) and AR 2.30 (SGC), a new module format was needed for task objects. The INA2000 line in versions of PVI lower than V3.0.0 can no longer interpret this format and therefore can't read any variables from these target systems.
Remedy: | PVI applications that access controllers with a 3.00 (SG4) or 2.30 (SGC) operating system, must use a PVI Version V3.0.0 or higher. PVI Version 3.0.0 (or higher) can interpret both the old and new module format. This makes it possible to communicate with older versions of AR without limitations. Alternatively, it is possible to force Automation Studio to use the "old" module format. To do this in an Automation Studio project, go to the "Build" tab in the PLC properties, and enter the value "-limit2" in the line "Additional build options". This option generates all task objects in the "old" module format. However, the IEC extensions (multidimensional arrays, structure initialization, etc.) can then no longer be used. If an extended function is used in the program, a corresponding error will appear during the build (e.g. "error 6035: Advanced initialization is not supported by this version of AR ..."

INA2000 with AR 4.02

Objects (modules, tasks, variables) within the scope of application modules (SG4 AR 4.02 or higher) can only be addressed with PVI Version V3.0.3 or higher. Before this is possible, however, the scope of application modules must first be enabled in PVI.

There are two ways to do this:

  1. Entry in the connection description of the CPU object using the parameter /AM.
  2. Entry in the PVI configuration file (PviConfig.xml) using the attribute AppMod.

The parameter /AM in the connection description overwrites the entry in the PVI configuration file. If modules, tasks or variables in the scope of application modules should be visible for a PVI application, then the parameter /AM must be specified in the connection description (e.g. CD="/AM=*"). The attribute AppMod in the PVI configuration file should only be changed if absolutely necessary (e.g. when expanding an existing PVI application). Also keep in mind that the PVI configuration file is overwritten when a new PVI version is installed.

Setting the scope of application modules in the PVI configuration file:

<PviLine>
  <LNINA2 ... AppMod="::" ... >

Setting AppMod="*" (or AppMod="*::") enables all scopes.

INA2000 process objects

A line object, a device object, and a CPU object are all need to establish a communication connection to a PLC.

Process objects in the INA2000 line:

Name | Type | Connection | Usage
Line object | Line | "LNINA2" | INA2000 line
Device object | Device | Device parameter | Represents the communication device being used
Station object | Station |  | Can be specified, but not required.
CPU object | CPU | Connection parameter PLC name | Represents a PLC within a network or a routed PLC
Module object | Modules | PLC module name and optional application module name | Represents a module on the PLC
Task object | Task | PLC task name and optional application module name | Represents a task on the PLC
Variable object | Pvar | PLC variable name and optional application module name | Represents a variable on the PLC

Allowed object structure for INA2000 process objects:

There is no limit to the number of process objects. Theoretically, any number of device objects can be assigned to a line object, any number of CPU objects can be assigned to a device object, etc.

INA2000 access types

The following table shows an overview of all standardized access types that are regulated via a line. All access types not listed here as well as access types to the PVI base object are executed by PVI Manager and therefore work independently of the line being used. The corresponding process object type is listed in the "Type" column.

Access types | Type | Special features
POBJ_ACC_VERSION Line,
Device,
Cpu
Module
Task 		Line object: Version of the line DLL.
Device object: Version of the INA frame DLL and device DLL
CPU object: PLC operating system is read ("Vxxx").
Module and task object: Module version is read ("x.xx").
POBJ_ACC_LIST_EXTERN | Line | List of all installed (PVI Setup) INA2000 devices
POBJ_ACC_DATA | Pvar
POBJ_ACC_STATUS Cpu
Module
Task
Pvar
POBJ_ACC_TYPE_EXTERN | Pvar
POBJ_ACC_UPLOAD | Modules | POBJ_EVENT_PROCEEDING is supported. Optionally, the function "Translate BR modules" can be performed.
POBJ_ACC_DOWNLOAD | CPU | POBJ_EVENT_PROCEEDING is supported. Optionally, the function "Translate BR modules" can be performed.
POBJ_ACC_DATE_TIME Cpu
Module
POBJ_ACC_MEM_DELETE | CPU
POBJ_ACC_MEM_INFO | CPU
POBJ_ACC_MOD_TYPE | Modules
POBJ_ACC_UPLOAD_STM | Modules | POBJ_EVENT_PROCEEDING is supported. Optionally, the function "Translate BR modules" can be performed.
POBJ_ACC_DOWNLOAD_STM | CPU | POBJ_EVENT_PROCEEDING is supported. Optionally, the function "Translate BR modules" can be performed.
POBJ_ACC_MOD_DATA Modules Read payload from BR log data modules.
This access type is only supported beginning with PLC operating system V2.85 (SG4 Automation Runtime).
Write access is not supported.
POBJ_ACC_MOD_DELETE | CPU | Deletes BR module.
POBJ_ACC_LIST_STATION | Not supported
POBJ_ACC_LIST_CPU | Not supported
POBJ_ACC_LIST_MODULE CPU List of a PLC's module objects

Syntax of the module object list:
[<ApplicationModuleName1>::]<ModuleName1> \t [<ApplicationModuleName2>::]<ModuleName2> ...
All object entries are separated with the character \t (tabulator).
<ApplicationModuleName>: Name of the application module
<ModuleName>: Name of the module object

If the module object is within the scope of an application module, then the application module name is specified as well. An application module name is not specified for module objects within the default scope. The visibility of objects within the scope of application modules must be enabled in the connection description of the CPU object using the /AM parameter.

An optional filter can be specified during the call (PviReadArgumentRequest or PviXReadArgumentRequest function) that can be applied to the list:

<Name>:: | ... | List contains only module objects within the scope of the application module called <Name>
:: | ... | List contains only module objects within the default scope
*:: | ... | Disables the filter (identical to calling the PviReadRequest or PviXReadRequest function)
POBJ_ACC_LIST_TASK CPU List of a PLC's task objects

Syntax of the task list:
[<ApplicationModuleName1>::]<TaskName1> \t [<ApplicationModuleName2>::]<TaskName2> ...
All object entries are separated with the character \t (tabulator).
<ApplicationModuleName>: Name of the application module
<TaskName>: Name of the task object

If the task object is within the scope of an application module, then the application module name is specified as well. An application module name is not specified for task objects within the default scope. The visibility of objects within the scope of application modules must be enabled in the connection description of the CPU object using the /AM parameter.

An optional filter can be specified during the call (PviReadArgumentRequest or PviXReadArgumentRequest function) that can be applied to the list:

<Name>:: | ... | List contains only task objects within the scope of the application module called <Name>
:: | ... | List contains only task objects within the default scope
*:: | ... | Disables the filter (identical to calling the PviReadRequest or PviXReadRequest function)
POBJ_ACC_LIST_PVAR CPU
task 		List of variables in a task or list of global PLC variables

Syntax of the variable object list:
[<ApplicationModuleName1>::]<VariableName1> [<Info>] \t [<ApplicationModuleName2>::]<VariableName2> [<Info>] ...
All object entries are separated by the \t character (tab).
<ApplicationModuleName>: Name of the application module
<VariableName>: Connection name for the task object.
<Info>: Description string for additional information

The variable list contains additional information such as scope (global or local variables) and variable type.

If this access type is executed for a task object, then the list will contain all local and global variable objects in that task. Application module names are not included in this list since it is the task that handles the assignment to an application module.

If this access type is executed for the CPU object, then the list will contain all global variable objects on the PLC. If a global variable object is within the scope of an application module, then the application module name is specified as well. An application module name is not specified for variable objects within the default scope. The visibility of objects within the scope of application modules must be enabled in the connection description of the CPU object using the /AM parameter.

An optional filter can be specified via the CPU object during the call (PviReadArgumentRequest or PviXReadArgumentRequest function) that can be applied to the list:

<Name>:: | ... | List contains only global variable objects within the scope of the application module called <Name>
:: | ... | List contains only global variable objects within the default scope
*:: | ... | Disables the filter (identical to calling the PviReadRequest or PviXReadRequest function)
POBJ_ACC_CPU_INFO | CPU
Access type > 255 | Line access types approved for PVI customer applications are listed in the INA2000 line access types section.

INA2000 line access types

The following table lists all of the INA2000 line event types approved for use in PVI customer applications. The corresponding process object type is listed in the "Type" column.

Access types | Type | Special features
POBJ_ACC_LN_COMM_DST | CPU | Reads INA2000 communication parameters
POBJ_ACC_LN_LKN_LIST | CPU |
POBJ_ACC_LN_XML_LIC_STATUS | CPU |

INA2000 event types

The following table shows an overview of all event types which can be generated from a line. All event types which are not listed are generated by PVI Manager and therefore work independently of the line being used.

Event types | Special features
POBJ_EVENT_STATUS | Support only for link node variables (process object type: Pvar) beginning with PLC operating system V2.80 and for BR log data modules (process object type: Module) beginning with PLC operating system V2.85.
POBJ_EVENT_PROCEEDING | Progress events are supported for access types OBJ_ACC_UPLOAD, POBJ_ACC_UPLOAD_STM, POBJ_ACC_DOWNLOAD, and POBJ_ACC_DOWNLOAD_STM.
Event type > 255 | INA2000 line event types are not approved for PVI customer applications.

<< Previous Topic
Link node variables

Start Page

Next Topic >>
INA2000 communication


INA2000 communication

The INA2000 line can be operated on the following platforms:

Windows platform | Limitations
Windows 7 or higher | No verification of modem communication.
Windows NT/2000/XP | No verification for Windows NT/2000 in PVI V4.0 or higher.
Windows Vista | CAN communication is not supported.
Windows CE | No longer supported in PVI V3.0.3 and higher

The description of the B&R CAN device driver lists which CAN cards can be used with which Windows platforms.

General PLC requirements

  • The INA2000 communication operates on a restricted basis (services) with PLC operating system 1.91.
  • To use all the services (e.g. module upload, download, etc), PLC operating system 2.10 is required.
  • If multi-master capability or a TCP/IP communication between PC and PLC is needed, PLC operating system 2.20 or higher must be used.
  • For INA2000 event handling over the PLC (PLC monitors data changes), PLC operating system 2.24 or higher is needed.

INA2000 requests are processed on the PLC during idle time. To ensure suitable response times, an idle time of 20% is a minimum requirement. If 20% idle time cannot be guaranteed for technical reasons, the response time increases resulting in a slower data refresh rate.

In this section the following topics are discussed:

INA2000 communication

Serial communication

Ethernet UDP communication

Modem communication

CAN communication

Profibus FDL communication

LS251 communication

ARsim communication

<< Previous Topic
INA2000 line

Start Page

Next Topic >>
Serial communication


INA2000 communication

Serial communication

Serial communication can only be operated as a point-to-point connection (RS232 or RS422).

An RS485 connection (2-line connection) is not possible.

<< Previous Topic
INA2000 communication

Start Page

Next Topic >>
Ethernet UDP communication


INA2000 communication

Ethernet UDP communication

PC requirements

The TCP/IP protocol must be installed.

PLC requirements

To use INA2000 communication over Ethernet, Ethernet communication must be enabled in Automation Studio. See user documentation for Automation Studio version being used.

Using several Ethernet network cards on a PC

How can you be sure that PVI uses the correct network card to communication with the controller if two or more network cards are located on the PC?

The subnet mask needs to be set correctly so that the correct network card for PLC communication is selected. The IP address of the target station (PLC) is linked with the subnet mask with an AND operation resulting in the correct network card being found and used for communication purposes.

Example:

Device parameter: /IF=tcpip /SA=1
CPU parameters /DA=13 /DAIP=172.43.70.13
IPAdr NW1: 172.43.71.12 Subnet Mask: 255.255.255.0
IPAdr NW2: 172.43.70.12 Subnet Mask: 255.255.255.0
IPAdr SPS: 172.43.70.13

This would make sure that the second network card is used for PLC communication. If a DHCP server is configured for a network card, then it must be known which IP address and subnet masks the DHCP server specifies so that the second network card can be configured correctly.

<< Previous Topic
Serial communication

Start Page

Next Topic >>
Modem communication


INA2000 communication

Modem communication

As with serial communication, modem communication is also a point-to-point connection.

Modem features

  • Transparency: Standard Windows functions are used to access the modem. In other words, all modems that can be installed in Windows can be used. The user just needs to install the modem and doesn't need to know anything else about modem technology (AT commands, etc.).
  • Automatic connection establishment: An active, created connection (see below) is constantly monitored. If the connection is lost (e.g. telephone line interrupted, modem disconnected or turned off), it tries to re-establish the connection in periodic intervals. The number of attempts as well as the intervals between attempts can be configured.
  • Active connection: Windows establishes a dial-up connection with a specified telephone number and transfers the protocol determined by the PVI line over this connection.
  • Passive connection: Windows waits for an incoming call, answers automatically, and makes the connection. In this operating mode it is possible, for example, that a PLC initializes the connection to a Windows computer itself.

PC requirements

The PVI modem requires Microsoft TAPI version 2.0. This version is already installed in Windows NT 4.0. When using Windows 95, it is necessary to replace the standard TAPI Version 1.4 with a newer version. The current version from Microsoft (www.microsoft.com) is version 2.1 To install TAPI Version 2.1 in Windows 95, start the "tapi2195.exe" program in the "Pvi\SysSetup\Modem" directory. This file is installed with the PVI Setup option "Modem System Components".

A modem is installed in the Windows Control Panel under Modems. A new modem can be added in the dialog box and its settings can be edited ("Properties"). The modem name shown in this dialog box corresponds to the modem name which needs to be specified as a PVI device parameter (/MO).
Dialing details are set in "Control Panel – Modems" (current location, calling card, etc).

<< Previous Topic
Ethernet UDP communication

Start Page

Next Topic >>
CAN communication


INA2000 communication

CAN communication

CAN communication is operated as an INA2000 network with a maximum of 32 stations (can be expanded to 255).

CAN node numbers are used to differentiate between individual stations.

PC requirements

The description of the B&R CAN device driver can be used to find out which CAN cards can be used with which Windows platforms.

PLC requirements

To use INA2000 communication over CAN, CAN communication must be enabled in Automation Studio. See user documentation for Automation Studio version being used.

<< Previous Topic
Modem communication

Start Page

Next Topic >>
Profibus FDL communication


INA2000 communication

Profibus FDL communication

Starting with PVI Version 3.0.2, Profibus FDL communication is no longer supported!

INA2000 communication over Profibus FDL is only possible on the System 2000. Other systems are not supported by PVI!

Settings for PLC Profibus cards (NW100 / NW150) and the PC card (5A1104.00-090) can be taken from the PROFIBUS User's Manual (MASYS2PB-E).

PC requirements

Data transfer with the PC occurs via a 32 kByte DPR. An available address range must be set on the PC for this purpose. This is set with HEX-switches SW1 and SW2 on the Profibus card (SW1 = 0; SW2 = D). If only one Profibus card is used in the system, the jumpers BR1 and BR2 are left open. Additional information can be found in the Profibus User's Manual.

To ensure that the memory on the PC is also free, the memory area must be excluded in BIOS. On the IPC5000, either 32 bytes (1 Profibus card) or 64 bytes (two Profibus cards) must be excluded starting at the base address D000 under "PNP/PCI Configuration" in BIOS.

PLC requirements

NW100 or NW150 with revision xx.05 or higher

On the PLC, operating system V.2.00 or higher is necessary. The "FBPB.BR" module must be burned for INA2000 communication. The Profibus configuration module is already a component of the operating system and can be modified using suitable tools if necessary.

To allow INA2000 communication via Profibus, the configuration for INA2000 Profibus communication must be updated in the Sysconf module.

<< Previous Topic
CAN communication

Start Page

Next Topic >>
LS251 communication


INA2000 communication

LS251 communication

Starting with PVI Version 3.0.2, LS251 communication is no longer supported!

PC requirements

In Windows NT/2000/XP, the LS251 card is automatically detected by the operating system when inserted.

The corresponding driver can then be selected under "Pvi\Drivers\Ls251\W2k_xx" in the Hardware Wizard.

PLC requirements

PLC operating system V2.01 or higher must be installed on the LS251.

<< Previous Topic
Profibus FDL communication

Start Page

Next Topic >>
ARsim communication


INA2000 communication

ARsim communication

Communication with ARsim takes place via an Ethernet UDP device and with the local IP address 127.0.0.1.

Connection description for device

"/IF=TcpIp",

Connection description for station

"/DAIP=127.0.0.1 /REPO=11160".

PC requirements

ARsim runtime emulation must be installed.

<< Previous Topic
LS251 communication

Start Page

Next Topic >>
INA2000 device objects


INA2000 device objects

The communication device being used is determined with the INA2000 device object.

The communication device is defined in the device object's connection description with the necessary device parameters. Within the connection description, individual parameters are differentiated between using parameter identifiers. These parameter identifiers always begin with the "/" character.

Connection description syntax:

/IF=<DeviceName> [/<Identifier1>=<ParameterValue> [/<Identifier2>=<ParameterValue> ... ]]

The /IF parameter is common to all communication devices. All other parameters depend on the communication device being used. Device names are not case sensitive. At least one empty space is to be entered between the individual parameter specifications.

The connection description must always be specified in quotation marks ("...") in the object description.

Connection description example:

CD="/IF=com1 /BD=57600 /PA=2"

In this section the following topics are discussed:

INA2000 device objects

Serial device

Ethernet UDP device

Modem device

CAN device

Profibus FDL device

LS251 device

<< Previous Topic
ARsim communication

Start Page

Next Topic >>
Serial device


INA2000 device objects

Serial device

The following table shows all parameters which can be defined for serial communication in the device object's connection description.

Par. Values Settings Description
/IF com1 ...
comX 		None By default: COM1 to COM4. With some serial interface cards or adapters, it is possible to have more than COM4.
Example: "/IF=com1"
/BD 9600,
19200,
38400,
57600,
115200 		57600 Baud rate in bits per second
Example: "/BD=38400"
/RS -1, 0,
232,
422,
485 		232 Sets the RS232 or RS422 protocol. RS485 is not supported by INA2000.
Example: "/RS=422"

This parameter sets the flow control of the CTS (clear to send) and RTS (request to send) lines of the serial interface.
Possible parameter values:
= -1: PVI doesn't modify the current setting (see the interface device properties) of the CTS/RTS flow control.
= 0: Always shut off the RTS line (disables RTS flow control).
= 232: Use RTS handshake.
= 422: Always turn on the RTS line.
= 485: Turn on the RTS line at the beginning of a transfer or during the transfer.
CTS flow control is disabled whenever the parameter value >= 0.

Many USB/serial adapters (USB to serial interface) do not handle CTS/RTS flow control correctly. The parameter "/RS=0" must be specified to establish an RS232 connection using these adapters.
/PA 0 - 4 1 Parity setting
0=NO PARITY
1=ODD PARITY
2=EVEN PARITY
3=MARK PARITY
4=SPACE PARITY

Default setting for INA2000 communication is "/PA=2".

Connection description example:

CD="/IF=com2 /BD=115200 /PA=2"

<< Previous Topic
INA2000 device objects

Start Page

Next Topic >>
Ethernet UDP device


INA2000 device objects

Ethernet UDP device

The following table shows all parameters which can be defined for Ethernet UDP communication in the device object's connection description.

Par. | Values | Settings | Description
/IF | tcpip | None | Ethernet UDP device Value: "/IF=tcpip" Communication with the PLC takes place via UDP/IP. There are historical reasons why tcpip and not udpip must be entered for the /IF parameter.
/LOPO | 1024 - 32767 | 11159 | Port number of the source station (separate station) If the value is specified in Hexadecimal, then "0x" must be used to introduce the value (e.g. "/LOPO=0x2b97"). A different default port number then only needs to be set if it is not unique within the local computer. Example: "/LOPO=11159"
/SA | 0 - 99 / 255 | 1 | Station number of the source station (own station). The station number must be unique within the INA2000 network. The highest station number is 99 for SG3 and SGC with AR Version < 2.00, or 255 for SG4 and SGC with AR Verson >= 2.00. Example: "/SA=3"
/UDEV | 0 / 1 | 0 | This parameter determines how the parameters /LOPO and /SA function. With "/UDEV=0" (default) all process objects with the type "device object" are grouped together as one service object and transferred over an INA2000 connection. If the process objects have different values for /LOPO and /SA, the object created first always wins. This setting corresponds to the behavior of PVI Versions <= 3.0.0. With "/UDEV=1", process objects with different values for /LOPO and /SA are transferred using separate service objects. INA2000 communication therefore also takes place via separate INA2000 connections. This setting allows multiple INA2000 connections to be established to one PLC with different port numbers or station numbers (source station).

Connection description example:

CD="/IF=tcpip /SA=3 /UDEV=1"

<< Previous Topic
Serial device

Start Page

Next Topic >>
Modem device


INA2000 device objects

Modem device

The following table shows all parameters which can be defined for modem communication in the device object's connection description.

Par. | Values | Settings | Description
/IF | modem1 ... modemX | None | Modem device Example: "/IF=modem1"
/MO | Modem name | None | Name of the modem, as it appears in the Setup dialog box (Control Panel -> Modems). The string must be enclosed in single quotation marks. If single quotes are to be used in the string, then the whole expression needs to be enclosed by another set of single quotes (e.g. m'56k is specified as /MO='m''56k' ). Example: "/MO='MicroLink 56k'"
/TN | Telephone number | None | Telephone number. The number to be dialed, corresponding to "ITU-T Recommendation E.123", e.g. the number is always given in full (including international codes). Conversion to the actual number is done automatically. This string must be written in single quotation marks. If a call is being waited for, an empty string should be entered (/TN=''). Example: "/TN='+43(7748)6586'"
/MR | 0 - INFINITE | INFINITE | Maximum number of unsuccessful dialing attempts. Specifies how often it should be attempted to re-establish a broken connection. If "INFINITE" is specified, redialing continues indefinitely. A value 0 means that no attempts at redialing are made. The /MR parameter is only relevant if /TN is not empty. Examples: "/MR=50", "/MR=INFINITE"
/RI | 0 - 3600 | 60 | Time interval between dialing attempts in seconds. If a dialing attempt fails, then this time interval is always observed before another attempt is made. The /RI parameter is only relevant if /TN is not empty. Example: "/RI=120"
/IT | 0 - 60000 | 40 | Interval timeout (msec) Defined as the maximum time that can pass between receiving two consecutive characters. Example: "/IT=100"

The /MO and /TN parameters must always be specified along with the /IF parameter.

The operating system automatically reads the serial interface. This function is carried out using a buffer where the data received is stored. The operating system stops reading if one of the following situations occurs:

  1. The buffer is full.
  2. A time span longer than the interval timeout has passed since the last character was received.

Because of this, setting the /IT parameter for the interval timeout is extremely important. If the interval timeout is too small, INA2000 frames can be lost. This would cause the connection to be broken. If it is too big, data throughput is reduced because the interval timeout passes before the PC detects a received frame. The preset value of 40 ms has been selected due to measurements that show that a modem (using internal buffering) can insert breaks of approx. 35 ms into byte flow. Normally, it is not necessary to choose another value. However, increasing the timeout value may be necessary e.g. when using other types of modems or when line quality is poor (modems have their own transfer security with automatic send retry).

Connection description example:

CD="/IF=modem1 /MO='ZyXEL MODEM Omni 288S' /TN='+43(7748)999'"

<< Previous Topic
Ethernet UDP device

Start Page

Next Topic >>
CAN device


INA2000 device object

CAN device

To address an INACAN device under Windows XP, it must first be set up as a CAN device using the B&R CAN device configurator. Under Windows 7 and higher, the driver sets up CAN devices automatically.

CAN devices are configured via the "CAN devices" menu item in the Control Panel. The device list in the configurator shows all CAN devices that have already been set up. The device number must also be specified in the PVI device name. The CAN1 device corresponds to the PVI device name INACAN1. CAN2 corresponds to INACAN2, etc. The B&R CAN device configurator is also used to set device resources (IRQs, port addresses, etc.).

The following table shows all parameters which can be defined for CAN communication in the device object's connection description.

Par. | Value | Preset | Description
/IF | inacan1 ... inacanX | None | CAN device See also B&R CAN device configurator. Example: "/IF=inacan1".
/CNO | 0, 1 | 0 | CAN controller number (channel). The LS172 card has 2 CAN controllers. The desired controller is selected with the /CNO parameter. No value other than 0 (zero) may be specified for the default CAN controller. Examples for LS172 card: CAN bus 1: "/IF=inacan2 /CNO=0", CAN bus 2: "/IF=inacan2 /CNO=1".
/IT | 0 - 60000, 0 = Off | 0 | Interval timeout (ms) Defines the maximum time that is allowed to pass between two CAN messages when receiving or sending an INA frame. This parameter is used together with the /RT parameter for the INA2000 CPU object to detect a broken connection. This parameter must not be less than the response time for the controller (5 - 30 ms) plus a reserve of at least 25 ms (accordingly higher for heavy interrupt loads on the PCs), but should be smaller than /RT. If quick detection of the broken connection is not required, monitoring interval timeouts does not need to be enabled (/IT=0). Example: "/IT=80".
/BI | 0 - 2047 / 536870911 | 1598 | Base CAN ID for INA2000 communication Every station in the INA2000 network must have the same setting. Example: "/BI=1598".
/MDA | 32 - 255 | 32 | Maximum possible number of INA2000 stations (= highest station number) Every station in the INA2000 network must have the same setting. Example: "/MDA=50".
/SA | 1 - /MDA | 1 | Station number of the source station (own station). The station number must be unique within the INA2000 network. Example: "/SA=3".
/BD | 10000, 20000, 50000, 100000, 125000, 150000, 250000, 500000, 800000, 1000000 | *) | Baud rate (data rate) on the CAN bus in bits per second. This parameter can also be specified in kilobits per second. Every station in the INA2000 network must have the same setting. Example: "/BD=250000" or "/BD=250".
/CMODE | 11, 29 | *) | CAN communication with 29-bit identifiers (extended frames) or 11-bit identifiers (standard frames). If 29-bit CAN identifiers (extended frames) are used, then 11-bit identifiers cannot be sent or received. Every station in the INA2000 network must have the same setting. Example: "/CMODE=29".
/CT | >= 1, 0 = Off | *) | Cycle time (in ms) within which no more than the specified number of CAN messages (/MC parameter) are sent. Values < 20 ms are not suitable. Example: "/CT=20".
/MC | >= 1 | *) | Maximum number of CAN messages sent within the specified cycle time (/CT parameter). Example: "/MC=15".
*) The /BD, /CMODE, /CT, and /MC parameters can also be set using the B&R CAN device configurator. If these parameters are not specified in the connection description (the recommended method), then the values set in the configurator are used instead. If one of these parameters is specified in the connection description, then the corresponding configurator setting is overwritten.

The /CT and /MC parameters are used to limit frames. These allow the number of sent CAN messages to be restricted per cycle. This can reduce the load from the PC to the CAN bus. This could be important if other stations on the bus can only process a certain number of received CAN messages with the set baud rate, or if their interrupt load in general should be reduced. However, the disadvantage of limiting frames is slower CAN communication.

For INA2000 communication, each station needs 3 CAN IDs. The CAN IDs are formed from the base CAN ID (/BI parameter), the station number (node number), and the maximum number of stations (/MDA parameter):

ID1 (Initiate request) | = <Base CAN ID> + <Station number> - 1
ID2 (Initiate response) | = <Base CAN ID> + <Station number> - 1 + <Max. number of stations> * 2
ID3 (Data segment) | = <Base CAN ID> + <Station number> - 1 + <Max. number of stations>

Connection description example:

CD="/IF=inacan3 /CNO=1 /SA=3"

<< Previous Topic
Modem device

Start Page

Next Topic >>
Profibus FDL device


INA2000 device objects

Profibus FDL device

Starting with PVI Version 3.0.2, Profibus FDL communication is no longer supported!

The following table shows all parameters which can be defined for Profibus FDL communication in the device object's connection description.

Par. | Values | Settings | Description
/IF | pbusfdl1 ... pbusfdlX | None | Profibus device Example: "/IF=pbusfdl1"
/BA | 0x00000 - 0xFFFFF | 0xD0000 | Base address of the DPR on the Profibus card. If the value is specified in hexadecimal it must be preceded by "0x" . Example: "/BA=0xD0000"
/FF | Path name *) | nw_load.bin | Path of the firmware file for the Profibus card Example: "/FF=nw.bin"
/FC | Path name *) | nw_pb_32.br | Path of the network configuration file for the Profibus card Example: "/FC=nw_pb.br"
/CB | 1 - 255 | 2 | Number of communication buffers on the Profibus card Example: "/CB=4"
/SA | 0-127 | 1 | Station number of the source station (own station). The station number must be unique within the INA2000 network. Example: "/SA=2"
*) Default firmware and configuration files are components of PVI. If a path is not specified, then the files must be located in the PVI Manager directory.

Settings such as baud rate and timeout are not to be defined via the device parameters. This is done by modifying the configuration file using suitable tools.

Connection description example:

CD="/IF=pbusfdl1 /FF=c:\pbconfig\nw_load.bin /FC=c:\pbconfig\nw_pb_32.br /SA=1"

<< Previous Topic
CAN device

Start Page

Next Topic >>
LS251 device


INA2000 device objects

LS251 device

Starting with PVI Version 3.0.2, LS251 communication is no longer supported!

The following table shows all parameters which can be defined for LS251 communication in the device object's connection description.

Par. | Values | Settings | Description
/IF | ls251_1 ... ls251_9 | None | LS251 device Example: "/IF=ls251_1"

Connection description example:

CD="/IF=ls251_1"

<< Previous Topic
Profibus FDL device

Start Page

Next Topic >>
INA2000 CPU objects


INA2000 CPU object

The INA2000 CPU object is used to identify the PLC in a network or using Routing and to set the connection parameters for communication.

The parameters for determining the PLC are defined in the connection description of the CPU object. The communication device being used is defined by the higher-level device object. Within the connection description, individual parameters are differentiated between using parameter identifiers. These parameter identifiers always begin with the "/" character.

Syntax of connection description:

[/AM=<Name>] [/CN=<Routing path>] [/SP=<Path name>] [/<ID1>=<Parameter value> [/<ID2>=<Parameter value> ... ]]

The connection description must always be placed in quotation marks ("...") in the object description. There needs to be at least one empty space between each of the parameters.

General parameters

The following table shows all the general parameters that can be defined in the CPU object's connection description. These parameters can be specified independently of the communication device used.

Par. | Values | Setting | Description
/AM Name *) This parameter defines the scope of application modules and therefore sets the visibility of objects in the PVI. The setting made for the CPU object applies to all mapped module, task and variable objects. If no application modules are used on the addressed PLC (AR V4.02 or higher), then the parameter /AM has no meaning.

Syntax:
/AM=<Name>[::]
The <Name> can be the name of an application module, an empty string or the wild card '*' (asterisk).
Examples: "/AM=*::", "/AM=Generator::", "/AM=::"

Effects of the settings:
/AM=<Name> or /AM=<Name>:: | ... | The default scope and the scope of the application module with the name <Name> are visible.
/AM='' or /AM=:: | ... | Only the default scope is visible. This setting ensures compatibility with PVI Version 3.0.3 and lower.
/AM=* or /AM=*:: | ... | All scopes are visible in the PVI. Recommended setting for all new PVI applications.
/CN Path None Path specification for Routing.
Example: "/CN=IF3/IF2.7".
/SP Path None Path of the working directory for storing temporary module information. Specifying a working directory speeds up the identification of variables.
Example: "/SP=c:\Temp\LnIna2\CPU1\".

The specified working directory must exist before the CPU object is created. If multiple CPU objects exist, each must have its own working directory. If the path name contains any spaces, they must be indicated by single quotes (/SP='...').

/PVROI | 0 / 1 | 0 | Global setting for the index type of array variables. The setting made for the CPU object applies to all assigned INA2000 variable objects (local and global).
*) The default value for the parameter /AM is defined in the PVI configuration file (PviConfig.xml) by the attribute AppMod.
<Pvi> ... <PviBase> ... <PviLine> <LNINA2 ... AppMod="::" ... > ...

The parameters entered in the CPU object always overwrite the parameters in the configuration file. The settings in the configuration file only apply if the parameter /AM is not specified in the connection description of the CPU object.

Connection description example:

CD="/AM=* /CN=IF3/IF2.7 /DA=2 /RT=400"

In this section the following topics are discussed:

INA2000 CPU objects

Serial station

Ethernet UDP station

Modem station

CAN station

Profibus FDL station

LS251 station

Routing

<< Previous Topic
LS251 device

Start Page

Next Topic >>
Serial station


INA2000 CPU object

Serial station

The following table shows all parameters which can be defined for serial communication in the CPU object's connection description.

Par. Values Setting Description
/RT 0 - 65535 275 Response timeout in ms
If a response to a sent frame is not received with this time, then the frame is transferred again. After the third retry, the connection is deemed canceled. The time in which an interrupted connection is detected is a result of ResponseTimeout * 4.
Setting /RT=0 uses the INA2000 default value (275 ms).
Example: "/RT=400".

Recommended values (at a baud rate of 115200 bits/second):
100 - 200 | ... | For connections with only variable communication to SG4 controllers with sufficient idle time with AR 3.00 or higher.
200 - 500 | ... | For connections with only variable communication to any target systems / AR versions.
500 - 1000 | ... | For connections with PLC services running (e.g. Automation Studio project transfer).
Additional parameters for the INA2000 CPU can be found under "General parameters".

Connection description example:

CD="/AM=* /RT=400"

<< Previous Topic
INA2000 CPU objects

Start Page

Next Topic >>
Ethernet UDP station


INA2000 CPU object

Ethernet UDP station

The following table shows all parameters which can be defined for Ethernet UDP communication in the CPU object's connection description.

Par. Values Setting Description
/DA 1 - 255 7 Station number of the target station.
Automatic identification of the target station from the station number. The station number must be unique within the INA2000 network. The highest station number is 99 for SG3 and SGC with AR Version < 2.00, or 255 for SG4 and SGC with AR Verson >= 2.00.
Example: "/DA=56".
/DAIP IP address,
Host name 		None IP address of the target station.
Manual identification of the target station from the IP address or identification from the host name (DNS, only possible for SG4).
Examples: "/DAIP=68.10.10.27" ... IP address, "/DAIP=CP340su" ... Host name.

Specifying the parameter /DA depends on whether the parameter /DAIP is specified:
If the parameter /DAIP is not specified, then the parameter /DA must always be specified. If the parameter /DAIP is specified as an IP address, the parameter /DA is optional. If /DA is specified, however, the defined station number must be correct. If the /DAIP parameter is specified as a host name, the /DA parameter is ignored.

/RT 0 - 65535 275 Response timeout in ms.
If a response to a sent frame is not received with this time, then the frame is transferred again. After the third retry, the connection is deemed canceled. The time in which an interrupted connection is detected is a result of ResponseTimeout * 4.
Setting /RT=0 uses the INA2000 default value (275 ms).
Example: "/RT=400".

Recommended values:
20 - 250 | ... | For simple point-point connections, or connections via a local network with pure variable communication on SG4 controllers with sufficient idle time, with AR 3.00 and higher.
250 - 500 | ... | For connections via a local network with pure variable communication to any target systems / AR versions.
500 - 750 | ... | For connections via a local network with PLC services running (e.g. Automation Studio project transfer).
750 - 1500 | ... | For connections via an in-house network.
1500 - 5000 | ... | For connections via Intranet/Internet.
/REPO 1025 - 32767 11159 IP port number of the target station.
If the value is specified in Hexadecimal, then "0x" must be used to introduce the value (e.g. "/LOPO=0x2b97").
The port number must match the setting on the target station (PLC).
Example: "/REPO=11159".
/CKDA 0 / 1 1 Enables or disables the check to see if the target station number (parameter /DA) is unique.
The parameter /CKDA is irrelevant if used together with the parameter /DAIP (check is always disabled).
Example: "/CKDA=0" ... Checking is disabled.
/ANSL 0 / 1 *) Turn on/off fast TCP download/upload via ANSL.
Example: "/ANSL=0" ... Download/upload via ANSL is turned off.
/APN 1025 - 32767 11169 ANSL IP port number of the target station (peer station) for fast TCP download/upload.
Example: "/APN=11169".
Additional parameters for the INA2000 CPU can be found under "General parameters".
*) The default value for the parameter /ANSL is defined in the PVI configuration file (PviConfig.xml) by the attribute Ansl.
<Pvi> ... <PviBase> ... <PviLine> <LNINA2 ... Ansl="1" ... > ...

The parameters entered in the CPU object always overwrite the parameters in the configuration file. The setting in the configuration file only apply if the parameter /ANSL is not specified in the connection description of the CPU object.

The target station can be identified with either the /DA parameter or with the /DAIP parameter. If the /DA parameter is used, then all PLC stations on the network must have their own unique station numbers (node switch setting or configured node number). When the connection is established, the INA2000 line checks whether the PLC station numbers are unique. If more than one PLC has the same station number in the network, the connection is broken. This check can be disabled with the /CKDA parameter.

Target stations are identified automatically using broadcasts. However, some network components (switches / ISDN routers, etc.) do not pass along the broadcast. Because of this, automatically identifying the target station is not possible. In this case, the target station muse be identified with the /DAIP parameter. If there are more than 99 or 255 PLC stations connected to the network, then the /DAIP parameter must also be used. Then all PLC stations can use the same node numbers.

The download (access type POBJ_ACC_DOWNLOAD or POBJ_ACC_DOWNLOAD_STM) and the upload (access type POBJ_ACC_UPLOAD or POBJ_ACC_UPLOAD_STM) can take place via an INA connection (default connection) or via an ANSL connection (TCP). During the download/upload, there is an automatic check whether a connection to the target station can be established via ANSL (Automation Network Service Link). If not, the download/upload take place via the existing INA connection. If it can, the download/upload take place via ANSL. The advantage is that the download/upload generally goe faster via ANSL than via INA. The setting "/ANSL=0" forces the download/upload via INA.

Connection description examples:

CD="/DA=5 /RT=200"
CD="/DAIP=10.43.50.244 /RT=200"

<< Previous Topic
Serial station

Start Page

Next Topic >>
Modem station


INA2000 CPU object

Modem station

The following table shows all parameters which can be defined for modem communication in the CPU object's connection description.

Par. | Values | Setting | Description
/RT | 0 - 65535 | 275 | Response timeout in ms. If a response to a sent frame is not received with this time, then the frame is transferred again. After the third retry, the connection is deemed canceled. The time in which an interrupted connection is detected is a result of ResponseTimeout * 4. Setting /RT=0 uses the INA2000 default value (275 ms). Example: "/RT=350". For modem communication, this parameter's default value is usually not suitable. For in-house communication, 350 ms is appropriate. A larger value (e.g. 3000 ms) must be used during long-distance telephone connections (especially satellite calls).
Additional parameters for the INA2000 CPU can be found under "General parameters".

Response timeout:

The response timeout necessary can be calculated by adding up the following times.

  1. 2 * transfer time when using a defined transfer rate between modems (or between the PC and modem should this be smaller) for 255 bytes
  2. Signal delay in both directions (significant during satellite communication or long distance landline connections).
  3. 2 * delay, which normally results in 80 ms (2*40 ms).
  4. Response time of the peer station (a maximum value of 20 ms can be assumed for a PLC)
  5. When routing to the peer station (path specification), 20 ms must be added for each path segment

Connection description example:

CD="/RT=350"

<< Previous Topic
Ethernet UDP station

Start Page

Next Topic >>
CAN station


INA2000 CPU object

CAN station

The following table shows all parameters which can be defined for CAN communication in the CPU object's connection description.

Par. | Values | Setting | Description
/DA | 1 - 32 / 255 | 2 | Station number of the target station. The station number must be unique within the INA2000 network. Example: "/DA=5".
/RT | 1 - 65535 | 275 | Response timeout in ms. If a response to a sent frame is not received with this time, then the frame is transferred again. After the third retry, the connection is deemed canceled. The time in which an interrupted connection is detected is a result of ResponseTimeout * 4. Example: "/RT=600". Rule of thumb for the RT setting for CAN: 275 ms * number of CAN stations + 100 ms
/RW | 1 – 10000 0=none | *) | Write request delay time in ms With a delay time for write requests, a defined delay must pass between receiving a message from a CAN station on the bus and sending the next message to this CAN station. Example : "/RW=30".
Additional parameters for the INA2000 CPU can be found under "General parameters".
*) The /RW parameter can also be set with the B&R CAN device configurator. If this parameter is not specified in the connection description, then the value set in the configurator is used. If this parameter is specified in the connection description, then the corresponding configurator setting is overwritten for this station (PLC communication connection).

Connection description example:

CD="/DA=13 /RT=600"

<< Previous Topic
Modem station

Start Page

Next Topic >>
Profibus FDL station


INA2000 CPU objects

Profibus FDL station

Starting with PVI Version 3.0.2, Profibus FDL communication is no longer supported!

The following table shows all parameters which can be defined for Profibus FDL communication in the CPU object's connection description.

Par. | Values | Settings | Description
/CN | Path | None | Path specification for Routing. Example: "/CN=IF3/IF2.7"
/SP | Path name | None | Pathname of the working directory for storing temporary module information. Specifying a working directory speeds up the identification of variables. Example: "/SP=c:\Temp\LnIna2\CPU1\". The specified working directory must exist before the CPU object is created. If multiple CPU objects exist, each must have its own working directory. If the path name contains any spaces, they must be indicated by single quotes (/SP='...').
/DA | 1 - 127 | 5 | Station number of the target station. The station number must be unique within the INA2000 network. Example: "/DA=2"
/RT | 1 - 65535 | 275 | Response timeout in ms. If a response to a sent frame is not received with this time, then the frame is transferred again. After the third retry, the connection is deemed canceled. The time in which an interrupted connection is detected is a result of ResponseTimeout * 4. Example: "/RT=300".

Connection description example:

CD="/DA=2 /RT=300"

<< Previous Topic
CAN station

Start Page

Next Topic >>
LS251 station


INA2000 CPU objects

LS251 station

Starting with PVI Version 3.0.2, LS251 communication is no longer supported!

The following table shows all parameters which can be defined for LS251 communication in the CPU object's connection description.

Par. | Values | Settings | Description
/CN | Path | None | Path specification for Routing. Example: "/CN=IF3/IF2.7"
/SP | Path name | None | Pathname of the working directory for storing temporary module information. Specifying a working directory speeds up the identification of variables. Example: "/SP=c:\Temp\LnIna2\CPU1\". The specified working directory must exist before the CPU object is created. If multiple CPU objects exist, each must have its own working directory. If the path name contains any spaces, they must be indicated by single quotes (/SP='...').
/RT | 1 - 65535 | 275 | Response timeout in ms. If a response to a sent frame is not received with this time, then the frame is transferred again. After the third retry, the connection is deemed canceled. The time in which an interrupted connection is detected is a result of ResponseTimeout * 4. Example: "/RT=200".

Connection description example:

CD="/RT=200"

<< Previous Topic
Profibus FDL station

Start Page

Next Topic >>
Routing


INA2000 CPU objects

Routing

Routing can be used to establish a connection to PLC stations on other networks via a PLC station communication connection. These connections can also run via several PLC stations. Individual stations are defined in the routing path.

The following graphic shows an example of a network configuration and corresponding PVI process objects:

The PC is only serially connected to PLC 1. The PLC stations are connected via a CAN network one after the other. Communication to PLC 2 and PLC 3 take place via PLC 1. For this, the routing path must be specified in the respective CPU objects.

Routing path:

Syntax:

<Entry1>/<Entry2>/.../<EntryN>

Individual path entries are separated by a "/" character.

Syntax for entry:

SL<Slot>.SS<Subslot>.IF<Interface>.<Address>

All parts of the entry are separated by "." (period) characters. The specifications for SL<Slot> and SS<Subslot> do not need to be specified for 0 or 1. The <Address> entry is only needed for connection over a network.

SL<Slot> | Slot number: 0 (1) - 15.
SS<Subslot> | Subslot number: 1 - 3.
IF<Interface> | Interface number: 1 - 15.
<Address> | Station address: 1 - ff (hexadecimal)

Routes to or via peripheral processors:

CP | Main processor
PP<Slot> | Peripheral process, slot number: 0 (1) - 15.

If a peripheral processor should be routed to another peripheral processor, then the path specification must be conducted via the CPU.

Examples:

/CN=IF3/IF2.7

From the PC to the first PLC, then via IF3 to the next station (PLC) and from there to a CAN station with station number 7 via IF2.

/CN=SL6.IF1

From PC to the first PLC, then from there via Slot 6 (e.g. IF050) and IF1.

/CN=PP3

From the PC to the first PLC and then to peripheral processor 3.

PLC requirements:

PLC operation system beginning with version V2.20.
The number of parallel connections defines how many entries are possible in the internal routing table. The maximum configurable number of parallel connections is 16. Configuring parallel connections has an effect on the memory being used by the system. Memory is "given away" by configuring unnecessary parallel connections. The number of communication channels defines the number of "physical communication channels", so that for each open connection an entry is dynamically occupied and, additionally, an entry for the default configured "PG2000" connection is necessary. For this reason, the configured number must be at least one greater than the number of parallel connections.

The following changes need to made in Sysconf:

Communication | Connections | Number of parallel connections (sum from client and server connections) 1<= conn_cnt <= 16
 | Communication channels | 5 + conn_cnt (+1 for each inserted PB card)
System | Semaphores | LocIQDrv: 2 InaIQDrv: 2 + 2 * 2 * conn_cnt ==>(default+8) <= Semaphores <= (default+68)
 | Stack | >=0x00014000

<< Previous Topic
LS251 station

Start Page

Next Topic >>
INA2000 module objects


INA2000 module objects

The INA2000 module object represents the module present on the PLC.

The name of the module must be specified in the connection description. If the module is within the scope of an application module, then the name of the application module needs to be specified along with the task name (module name). The names of the application module and the module are separated by the characters "::". The names of the application module and the module are both case sensitive.

Modules within the scope of an application module can only be addressed if the CPU object parameter /AM is specified. For more info, see the section "INA2000 with AR 4.02".

Syntax of connection description:

/RO=[<Name of application module>::]<Module name>

or

[<Name of application module>::]<Module name>

If the module name is defined as the /RO parameter, the connection description must always be placed in quotation marks ("...") in the object description.

Connection description examples:

CD="/RO=Module1"
CD="/RO=Generator::Module1"
CD=Module2
CD=Generator::Module2

<< Previous Topic
Routing

Start Page

Next Topic >>
INA2000 task objects


INA2000 task object

The INA2000 task object represents a PLC task.

The name of the task must be specified in the connection description. If the task (module) is within the scope of an application module, then the name of the application module needs to be specified along with the task name (module name). The names of the application module and the task are separated by the characters "::". The names of the application module and the task are both case sensitive.

Tasks within the scope of an application module can only be addressed if the CPU object parameter /AM is specified. For more info, see the section "INA2000 with AR 4.02".

Syntax of connection description:

/RO=[<Name of application module>::]<Task name>

or

[<Name of application module>::]<Task name>

If the task name is defined as the /RO parameter, the connection description must always be specified in quotation marks ("...") in the object description.

Connection description examples:

CD="/RO=Task1"
CD="/RO=Generator::Task1"
CD=Task2
CD=Generator::Task2

<< Previous Topic
INA2000 module objects

Start Page

Next Topic >>
INA2000 variable objects


INA2000 variable objects

This section covers normal PLC variables (PVs). The features of link node variables are covered in a different section.

INA2000 can only address variable up to 64 KB in size. Variables bigger than 64 KB can only be used with the extended BR module format. The extended BR module format is supported by PLC operating system V2.85 or higher (SG4 Automation Runtime only).

The INA2000 line supports PLC event variables (see also the parameter AT). Monitoring for changes in the process data is already being carried out on the PLC. PVI Manager doesn't need to carry out any cyclic read requests. If the data in a PLC variables is not changed very often (at least not as often as the refresh time), then operating as a PLC event variable can reduce the data coming up in INA2000 communication. However, one disadvantage of this is increased computing time on the PLC. Note that specifying the refresh time (RF parameter) also affects PLC event variables. Only single variables can be operated as PLC event variables.

INA2000 only guarantees data consistency for single variables that are a maximum of 4 bytes in size. If the data from entire structures or fields should be transferred consistently, the user must implement corresponding measures (e.g. with handshake variables).
Example: The data for a structure should be written on one side (e.g. PLC), and read and checked for consistency on the other side (e.g. PC). When doing this, a counter variable is used at the start (first element) and at the end (last element) of the structure. A 1 or 2 byte counter is sufficient for applications. On the PLC, the second counter (last element in the structure) is increased by 1 (add 1 to counter state) before writing the structure data. Then the structure data between the counters can be written. After the write procedure, the value of the second counter is transferred to the first counter (first element in the structure). On the PC, the states of the two counters can be compared. If they are the same, the structure data between the counters is consistent.

The data format of the variable object is given by the INA2000 line and corresponds to that of the PLC variable or an element of the PLC variable. An alignment of 2 is used for structure variables on SG3 targets and an alignment of 4 on SG4 targets. The PVI application can read the data format description using access type POBJ_ACC_TYPE or event type POBJ_EVENT_DATAFORM. Information about the dimensions of array variables and the structure elements of structure variables can be read using access type POBJ_ACC_TYPE_EXTERN.

The INA2000 variable object represents a PLC variable. An INA2000 variable object can be created at two different positions in the PVI object structure. If the variable object is created under a CPU object, then a global PLC variable is addressed. If the variable object is created under an INA2000 task object, then a local PLC variable (task variable) is addressed.

The name of the PLC variable must be specified in the connection description. If a global variable is within the scope of an application module, then the name of the application module needs to be specified along with the variable name. The names of the application module and the variable are separated by the characters "::". For local variables, the scope of the application module is determined by the mapped task. In this case it is not necessary to enter a name for the application module in the connection description of the variable object. The names of the application module and the task are both case sensitive.

Global variables within the scope of an application module can only be addressed if the CPU object parameter /AM is specified. For more info, see the section "INA2000 with AR 4.02".

Syntax of connection description:

Single variables, array variables and structure variables:

/RO=[<Name of application module>::]<Variable name>

or

[<Name of application module>::]<Variable name>

Element of an array variable using flat indexing:

/RO=[<Name of application module>::]<Variable name>[<Index>] /ROI=0

or

/RO=[<Name of application module>::]<Variable name>[<Index>]

or

/RO=[<Name of application module>::]<Variable name>[<Index>]

Element of a one-dimensional array variable using dimensional indexing:

/RO=[<Name of application module>::]<Variable name>[<Index>] /ROI=1

or

/RO=[<Name of application module>::]<Variable name>[<Index>,]

or

[<Name of application module>::]<Variable name>[<Index>,]

Element of a multi-dimensional array variable using dimensional indexing:

/RO=[<Name of application module>::]<Variable name>[<Index 1>,<Index 2>,...]

or

[<Name of application module>::]<Variable name>[<Index 1>,<Index 2>,...]

Range of an array variable:

/RO=[<Name of application module>::]<Variable name>[<Index 1>..<Index 2>]

or

[<Name of application module>::]<Variable name>[<Index 1>..<Index 2>]

Element of a structure variable:

/RO=[<Name of application module>::]<Variable>.<Element name>

or

[<Name of application module>::]<Variable name>.<Element name>

Dynamic variables are specified like static variables. If a pointer to a dynamic variables should be read, then "&" needs to precede the name of the variable.

If the variable name is defined as the /RO parameter, the connection description must always be specified in quotation marks ("...") in the object description.

Indexing array variables:

Elements of array variables can be indexed 2 different ways:

Indexing | Parameter | Description
flat | /ROI=0 | The first element is always addressed with index 0. Multi-dimensional array variables are handled one-dimensionally (flat).
dimensional | /ROI=1 | The first element is addressed with the lower index declared for the variable, and can also be unequal to 0 or negative. To index an element of a multi-dimensional array variable, the indexes must be specified for all dimensions. If fewer indexes are specified, the remaining dimensions are interpreted as an area.

The parameter /ROI can also be specified globally in the CPU object as /PVROI.

The types of indexing are differentiated by the entry of a "," (comma) or the parameter /ROI (or /PVROI in the CPU object). To use dimensional indexing for single dimension array variables, you must enter a comma or the parameter /ROI=1 (or /PVROI=1 in the CPU object) after the index (or index range) (example: "/RO=var[13,]" or "/RO=var[13] /ROI=1").

The following rules apply for the parameter /ROI:

  • The parameter /ROI can only be specified together with the /RO parameter.
  • Specification of the parameter is optional. Default value: /ROI=0.
  • The parameter can be specified for any variable, but is only effective if it has an index number.
  • Entering the character ',' (comma) in the index overwrites the setting /ROI=0.
  • The parameter /ROI is only supported by the INA2000 line with Version 3.44 (LnIna2.dll file version).

The following rules apply for the /PVROI (CPU object):

  • Specification of the parameter is optional. Default value: /PVROI=0.
  • The parameter affects all variable objects assigned to the CPU object (local and global).
  • The settings for the parameters /PVROI and /ROI are linked by an OR when evaluated.
  • Entering the character ',' (comma) in the index overwrites the setting /PVROI=0.
  • The parameter /PVROI is only supported by the INA2000 line with Version 3.51 (LnIna2.dll file version).

Example for indexing array variables:

The following indexing examples show dimensional and flat indexing for a two-dimensional array variable [0..3] [0..4] named "Field".

The element numbers 1 to 20 indicate the location of the elements in memory. The numbers 0.0 to 3.4 indicate the index of the elements for dimensional indexing.

Field[2,3]
Field[13]

In both cases the element 14 is indexed.

Field[1,]
Field[5..9]

In both cases, elements 6 to 10 are indexed (range entry).

Field[3.1..4]
Field[16..19]

In both cases, elements 17 to 20 are indexed (range entry).

Field[0..2,]
Field[0..14]

In both cases, elements 1 to 15 are indexed (range entry).

Field[8..11]

Elements 9 to 12 are indexed (range entry). Ranges that overlap dimensions can only be defined using flat indexing.

Connection description examples:

CD="/RO=TempValue"

Singe variable "TempValue" is addressed.

CD="/RO=View::TempValue"

Individual variable "TempValue" in the scope of application module "View" is addressed.

CD=TempField[2]
CD=TempField[7,]
CD="/RO=TempField[7] /ROI=1"

The 3rd element of the array variable "TempField [5..10]" is addressed.

CD=Vert.Stat.TempField[0]
CD=Vert.Stat.TempField[0,]

The 1st element of the array variable "TempField [0..10]" inside the "Stat" structure and the "Vert" structure is addressed.

CD=Sensor[3].Value
CD=Sensor[-2,].Value

The "Value" element within the 4th element of the "Sensor [-5..5]" structure array variable is addressed.

CD="&ViewBf"

Pointer to the dynamic variable "ViewBf" is addressed.

Example of object description:

AT=rwe CD="/RO=View::TempValue"

Individual variable "TempValue" in the scope of application module "View" is addressed and used as a PLC event variable.

<< Previous Topic
INA2000 task objects

Start Page

Next Topic >>
Translating BR modules


Translating BR modules

In PVI, a module download is carried out with access type POBJ_ACC_DOWNLOAD or POBJ_ACC_DOWNLOAD_STM, and a module upload is carried out with access type POBJ_ACC_UPLOAD or POBJ_ACC_UPLOAD_STM.

If a module type is defined in the call string (MT parameter), payload is extracted from the BR module during the upload or a BR module is generated from the payload during a download.

This procedure is carried out in special PVI components - BR module translation libraries (Windows DLLs). The first three characters in the module type determine the translation library being used. This is loaded by the INA2000 line if need be. The path names of the translation libraries are entered in the PVI configuration file (PviConfig.xml) (Pvi->PviBase->PviLine->LNINA2->BrTrans).

Module type | Description
BRT | Binary module translation
NC_ | NC module translation

Binary module translation

Additional parameters in the call string during download / upload:

Param. | Description
MT | "MT=BRT" must be specified.
MN | The name of the module must be specified when downloading.
MV | When downloading, it is possible to specify the version number of the module (default: MV=0).

Example of a complete call string for module downloading:

"C:\BRSRC\test1.txt" MT=BRT MN=Test1 MV=1.0 LD=Ram

Example of a complete call string for module uploading:

"C:\BRSRC\test1.txt" MT=BRT

NC module translation

Starting with PVI Version 3.0.2, translating NC modules is no longer supported!

Additional parameters in the call string during download / upload:

Param. | Description
MT | The desired NC module type ("NC_...") must be specified.
RL | When uploading, the language of any comments can be specified in a generated text.

Supported module types for module downloading (MT parameter):

Module type | Description
NC_CNC | CNC program
NC_ZP0 | Zero offset table
NC_TDT | Tool data table
NC_RPT | R parameter table
NC_CAM | Cam profile, definition using slave position(s)
NC_CAP | Cam profile, definition using polynomial(s)

Supported module types for module uploading (MT parameter):

Module type | Description
NC_xxx | NC data object. When uploading the module, specifying "MT=NC_" is sufficient since the module type is read from the module header.

Adjustable languages (RL parameter):

Language | Description
GER, DEU, 49 or 049 | Comments in German
ENG, USA, 1, 001 | Comments in English

Example of a complete call string for module downloading:

"C:\BRSRC\cnctest.txt" "MT=NC_CNC MN=CncObj1" LD=Ram

Example of a complete call string for module uploading:

"C:\BRSRC\cnctest.txt" "MT=NC_ RL=ENG"


Link node variables

A link node represents the status of a connection between a PV and an I/O point.

Link node variables in PVI can be used for observation (e.g. evaluating the link node status) or monitoring (e.g. displaying data from inputs regardless of the force state). INA2000 data acquisition is a bit slower with link node variables as it is with normal variables (PVs). For this reason, normal variables are the better choice for visualization tasks.

Link node variables can only be used beginning with PLC operating system V2.80 (SG4 Automation Runtime). If the PLC operating system doesn't support link node variables, error 4599 is reported in the PVI variable object.

In the INA2000 line, the data and status of a link node are accessed using INA2000 variable objects. Like global PLC variables, these variable objects must be set up under the CPU object. PVI can be used to access the producer, force, and consumer values of a link node. The following image shows the PVI "pick-up" points within a link node for the producer, force, and consumer values.

Each of the three pick-up points (producer, force, and consumer) are mapped in PVI using a separate variable object. Code letters in the variable object's connection description are used for differentiation. The producer and consumer values can only be read (read-only access). The force value can be both read and written. Link node variables cannot be used as PLC event variables. Otherwise, link node variables behave the same as normal variables (PLC PVs) in PVI.

Connection description syntax:

/RO=<code>+<link_node_name>

or

<code>+<link_node_name>

<code> | Pick-up point
P | Producer value
F | Force value
C | Consumer value

The link node name begins with the percent character (%). This is followed by the prefix 'I' (input), 'Q' (output) or 'M' (memory) and the prefix 'X' (1-bit), 'B' (1-byte), 'W' (2-byte), 'D' (4-byte) or 'L' (8-byte) according to IEC IEC 61131-3. The next data point path is separated by a period (.).

If the /RO parameter is specified, the connection description must always be specified in quotation marks ("...") in the object description.

Connection description example:

CD="/RO=C+%IX.SL3.Input10"

Accesses the consumer value of the link node variable "Input10" on slot 3.

Link node status

The status of a link node can be read via all connected variable objects (POBJ_ACC_STATUS access type). Link node variables in the INA2000 line also support status events (POBJ_EVENT_STATUS event type).

The link node status in INA2000 is read together with the link node data. This allows the status to always be as current as the data.

Link node status syntax:

ST=Lkn.<source> FC=<force> UL=<unresolved_link> [IO=<attribute>]

Par. | Description
ST | <source> is used to specify the source of the link node variable's data. "d" .. Default value, "p" .. Producer value, "f" .. Force value Specifying the source depends on the pick-up point being used.
FC | <force> is used to specify the force state. 1 .. Force active, 0 .. Force inactive
UL | <unresolved_link> signals PV links to the link node. 1 .. At least one PV link present, 0 .. No PV links present
IO | <attribute> signals the type of I/O link. "r" .. Link with input, "w" .. Link with output. Simulated I/O modules are identified by an 's'. If the I/O parameter is not specified, there is no I/O link.

Example of link node status:

ST=Lkn.p FC=0 UL=1 IO=r

<< Previous Topic
Translating BR modules

Start Page

Next Topic >>
NET2000 line


NET2000 line

The NET2000 line is used to communicate with B&R SG3 and SG4 controllers (System 2000) using the NET2000 protocol.

The following topics are covered in this section:

  • NET2000 process objects
  • NET2000 access types
  • NET2000 event types
  • NET2000 communication

NET2000 process objects

A line object, a device object, and a station object are all needed to establish a communication connection to a PLC. However, the connection is only established with the first variable object.

Process objects in the NET2000 line:

Name | Type | Connection | Usage
Line object | Line | "LNNET2" | NET2000 line
Device object | Device | Device parameter | Represents the communication device being used
Station object | Station | Station number | Represents a NET2000 station (PLC) in a network
CPU object | CPU |  | Can be specified, but not required.
Module object | Modules |  | Can be specified, but not required.
Task object | Task | PLC task name | Represents a task on the PLC
Variable object | Pvar | PLC variable name | Represents a variable on the PLC

Allowed object structure for NET2000 process objects:

NET2000 access types

The following table shows an overview of all access types which are regulated via a line. All access types not listed here as well as access types to the PVI base object are executed by PVI Manager and therefore work independently of the line being used. The corresponding process object type is listed in the "Type" column.

Access types | Type | Special features
POBJ_ACC_VERSION | Line Device | Line object: Version of the line DLL. Device object: Version of the NET2000 state machine, INA frame DLL, and device DLL
POBJ_ACC_LIST_EXTERN | Line | List of all installed (PVI Setup) NET2000 devices
POBJ_ACC_DATA | Pvar |
POBJ_ACC_STATUS |  | Not supported
POBJ_ACC_TYPE_EXTERN | Pvar |
POBJ_ACC_UPLOAD |  | Not supported
POBJ_ACC_DOWNLOAD |  | Not supported
POBJ_ACC_DATE_TIME |  | Not supported
POBJ_ACC_MEM_DELETE |  | Not supported
POBJ_ACC_MEM_INFO |  | Not supported
POBJ_ACC_MOD_TYPE |  | Not supported
POBJ_ACC_UPLOAD_STM |  | Not supported
POBJ_ACC_DOWNLOAD_STM |  | Not supported
POBJ_ACC_MOD_DATA |  | Not supported
POBJ_ACC_MOD_DELETE |  | Not supported
POBJ_ACC_LIST_STATION |  | Not supported
POBJ_ACC_LIST_CPU |  | Not supported
POBJ_ACC_LIST_MODULE |  | Not supported
POBJ_ACC_LIST_TASK |  | Not supported
POBJ_ACC_LIST_PVAR |  | Not supported
POBJ_ACC_CPU_INFO |  | Not supported
Access type > 255 |  | Not supported

NET2000 event types

The following table shows an overview of all event types which can be generated from a line. All event types which are not listed are generated by PVI Manager and therefore work independently of the line being used.

Event types | Special features
POBJ_EVENT_STATUS | Not supported
POBJ_EVENT_PROCEEDING | Not supported
Event type > 255 | Not supported

<< Previous Topic
Link node variables

Start Page

Next Topic >>
NET2000 communication


NET2000 communication

NET2000 is a master/slave protocol where the PVI NET2000 line carries out the functions of the master.

A multi-master function is not possible via the NET2000 protocol.

Identifying variables using NET2000 requests is carried out during the idle time by the PLC. NET2000 requests for reading and writing variable data are executed in a defined task class (NET2000.task_class). This enables the response time to be influenced by the selected task class.

A NET2000 communication connection doesn't provide life sign monitoring. If the NET2000 line is not requesting any data from the PLC (e.g. if there are no active variable objects present), then the existence of the NET2000 communication connection cannot be monitored.

General PC requirements

The NET2000 line can be operated on the following platforms:

Windows platform | Limitations
Windows 7 or higher | -
Windows NT/2000/XP/Vista | No verification for Windows NT/2000 in PVI V4.0 or higher.
Windows CE | No longer supported in PVI V3.0.3 and higher

General PLC requirements

PLC operating system V2.20 or higher is needed for NET2000 communication.

In addition, a NET2000 slave driver is needed on the PLC (NET2000 library).

In this section the following topics are discussed:

NET2000 communication

Serial communication

Modem communication

LS251 communication

<< Previous Topic
NET2000 line

Start Page

Next Topic >>
Serial communication


NET2000 communication

Serial communication

All necessary components are installed with PVI Setup.

Serial communication can be operated as a point-to-point connection (RS232/RS422) or as a network connection (RS485).

PLC requirements

For RS485 operation, take note that active/passive switching of the RS485 interface can take up to 15msec in Windows NT and up to 10msec in Windows 95. This can cause a bus collision with a PLC response. Setting the idle time on the PLC can delay the response frame by the required time. The idle time is specified in characters when NET2000 is initialized.

Example: NET2000.mode = "RS485,19200,I=100"

Since the response frame requires a minimum of 10 ms because it runs in the PLC task class (NET2000.task_class=1), the difference can be determined with the idle time (1 character corresponds to: 1/baud rate * 11 bits).

RS485 network

Executed as an RS485 twisted pair cable, shielded. Cross-section: min. 0.5 mm². Wave impedance: 120 ohms. Terminating resistor: 120 ohms on both ends. Length: maximum 1,200 meters. Maximum line resistance: 50 ohms per wire.

The cabling for the RS485 network can only be made using a bus structure. The bus connection can be made either directly or using a maximum 0,25 m long branch line.

<< Previous Topic
NET2000 communication

Start Page

Next Topic >>
Modem communication


NET2000 communication

Modem communication

All necessary components are installed with PVI Setup.

As with serial communication (RS232/RS422), modem communication is also a point-to-point connection.

Modem features

  • Transparency: Standard Windows functions are used to access the modem. In other words, all modems that can be installed in Windows can be used. The user just needs to install the modem and doesn't need to know anything else about modem technology (AT commands, etc.).
  • Automatic connection establishment: An active, created connection (see below) is constantly monitored. If the connection is lost (e.g. telephone line interrupted, modem disconnected or turned off), it tries to re-establish the connection in periodic intervals. The number of attempts as well as the intervals between attempts can be configured.
  • Active connection: Windows establishes a dial-up connection with a specified telephone number and transfers the protocol determined by the PVI line over this connection.
  • Passive connection: Windows waits for an incoming call, answers automatically, and makes the connection. In this operating mode it is possible, for example, that a PLC initializes the connection to a Windows computer itself.

PC requirements

The PVI modem requires Microsoft TAPI version 2.0. This version is already installed in Windows NT 4.0. When using Windows 95, it is necessary to replace the standard TAPI Version 1.4 with a newer version. The current version from Microsoft (www.microsoft.com) is version 2.1 To install TAPI Version 2.1 in Windows 95, start the "tapi2195.exe" program in the "Pvi\SysSetup\Modem" directory. This file is installed with the PVI Setup option "Modem System Components".

A modem is installed in the Windows Control Panel under Modems. A new modem can be added in the dialog box and its settings can be edited ("Properties"). The modem name shown in this dialog box corresponds to the modem name which needs to be specified as a PVI device parameter (/MO).
Dialing details are set in "Control Panel – Modems" (current location, calling card, etc).

<< Previous Topic
Serial communication

Start Page

Next Topic >>
LS251 communication


NET2000 communication

LS251 communication

Starting with PVI Version 3.0.2, LS251 communication is no longer supported!

"LS251" needs to be selected as an additional interface in PVI Setup.

PC requirements

In Windows NT/2000/XP, the LS251 card is automatically detected by the operating system when inserted. The corresponding driver can then be selected under "Pvi\Drivers\Ls251\W2k_xx" in the Hardware Wizard.

PLC requirements

PLC operating system V2.01 or higher must be installed on the LS251.

<< Previous Topic
Modem communication

Start Page

Next Topic >>
NET2000 device objects


NET2000 device objects

The communication device being used is determined with the NET2000 device object.

The NET2000 protocol parameters apply for all communication devices.

The communication device with the necessary device parameters and NET2000 protocol parameters are defined in the connection description of the device object. Within the connection description, individual parameters are differentiated between using parameter identifiers. These parameter identifiers always begin with the "/" character.

Connection description syntax:

/IF=<DeviceName> [/<Identifier1>=<ParameterValue> [/<Identifier2>=<ParameterValue> ... ]]

The /IF parameter as well as the NET2000 protocol parameters are common to all communication devices. Device parameters depend on the communication device being used. Device names are not case sensitive, and at least one space character must be between each parameter specification.

The connection description must always be specified in quotation marks ("...") in the object description.

Connection description example:

CD="/IF=com1 /BD=57600 /RS=422"

In this section the following topics are discussed:

NET2000 device objects

Serial device

Modem device

LS251 device

NET2000 protocol parameters

<< Previous Topic
LS251 communication

Start Page

Next Topic >>
Serial device


NET2000 device objects

Serial device

The following table shows all device parameters which can be defined for serial communication in the device object's connection description.

Par. Values Settings Description
/IF com1 ...
comX 		None By default: COM1 to COM4. With some serial interface cards or adapters, it is possible to have more than COM4.
Example: "/IF=com1"
/BD 9600,
19200,
38400,
57600,
115200 		57600 Baud rate in bits per second
Example: "/BD=38400"
/RS -1, 0,
232,
422,
485 		232 Sets the RS232, RS422, or RS485 protocol
Example: "/RS=485"

This parameter sets the flow control of the CTS (clear to send) and RTS (request to send) lines of the serial interface.
Possible parameter values:
= -1: PVI doesn't modify the current setting (see the interface device properties) of the CTS/RTS flow control.
= 0: Always shut off the RTS line (disables RTS flow control).
= 232: Use RTS handshake.
= 422: Always turn on the RTS line.
= 485: Turn on the RTS line at the beginning of a transfer or during the transfer.
CTS flow control is disabled whenever the parameter value >= 0.

Many USB/serial adapters (USB to serial interface) do not handle CTS/RTS flow control correctly. The parameter "/RS=0" must be specified to establish an RS232 connection using these adapters.

/PA 0 - 4 1 Parity setting
0=NOPARITY
1=ODDPARITY
2=EVENPARITY
3=MARKPARITY
4=SPACEPARITY

Default setting for NET2000 communication is "/PA=1".
/IT 0 - 60000 20 Interval timeout (msec)
Defined as the maximum time that can pass between receiving two consecutive characters. The NET2000 protocol uses this time to recognize the end of a received frame.
Example: "/IT=40"
For additional parameters, see NET2000 protocol parameters.

Connection description example:

CD="/IF=com2 /BD=115200 /RS=485"

RS232 Vs. RS485:

When using several PLCs, the RS232 single connection (n device objects, each with one station object) offers a higher overall transfer speed when compared with an RS485 network connection (one device object with n station objects). The reason for this is that only one PLC can be accessed at a time (request/response operation) over an RS485 network connection. Communication with RS232 single connections is carried out simultaneously. However, the disadvantage of RS232 single connections is the more complex hardware and wiring systems required.

<< Previous Topic
NET2000 device objects

Start Page

Next Topic >>
Modem device


NET2000 device objects

Modem device object

The following table shows all device parameters which can be defined for modem communication in the device object's connection description.

Par. | Values | Settings | Description
/IF | modem1 ... modemX | None | Modem device Example: "/IF=modem1"
/MO | Modem name | None | Name of the modem, as it appears in the Setup dialog box (Control Panel -> Modems). The string must be enclosed in single quotation marks. If single quotes are to be used in the string, then the whole expression needs to be enclosed by another set of single quotes (e.g. m'56k is specified as /MO='m''56k' ). Example: "/MO='MicroLink 56k'"
/TN | Telephone number | None | Telephone number. Telephone number to be dialed according to the "ITU-T Recommendation E.123" format, e.g. +43(7748)6586. The entire telephone number should always be specified (with country code). Conversions to the actual number are done automatically. This string must be written in single quotation marks. If a call is being waited for, an empty string should be entered (/TN=''). Example: "/TN='+43(7748)6586'"
/MR | 0 - INFINITE | INFINITE | Maximum number of unsuccessful dialing attempts. Specifies how often it should be attempted to re-establish a broken connection. If "INFINITE" is specified, redialing continues indefinitely. A value 0 means that no attempts at redialing are made. The parameter /MR is only relevant when /TN is not empty. Example: "/MR=50", "/MR=INFINITE"
/RI | 0 - 3600 | 60 | Time interval between dialing attempts in seconds. If a dialing attempt fails, then this time interval is always observed before another attempt is made. The Parameter /RI is only relevant when /TN is not empty. Example: "/RI=120"
/IT | 0 - 60000 | 40 | Interval timeout (msec) Defined as the maximum time that can pass between receiving two consecutive characters. The NET2000 protocol uses this time to recognize the end of a received frame. Example: "/IT=100"
For additional parameters, see NET2000 protocol parameters.

The /MO and /TN parameters must always be specified along with the /IF parameter.

The operating system automatically reads the serial interface. This function is carried out using a buffer where the data received is stored. The operating system stops reading if one of the following situations occurs:

  1. The buffer is full.
  2. A time span longer than the interval timeout has passed since the last character was received.

Because of this, setting the /IT parameter for the interval timeout is extremely important. If the interval timeout is too small, NET2000 frames can be lost. This would cause the connection to be broken. If it is too big, data throughput is reduced because the interval timeout passes before the PC detects a received frame. The preset value of 40 ms has been selected due to measurements that show that a modem (using internal buffering) can insert breaks of approx. 35 ms into byte flow. Normally, it is not necessary to choose another value. However, increasing the timeout value may be necessary e.g. when using other types of modems or when line quality is poor (modems have their own transfer security with automatic send retry).

Connection description example:

CD="/IF=modem1 /MO='ZyXEL MODEM Omni 288S' /TN='+43(7748)999'"

<< Previous Topic
Serial device

Start Page

Next Topic >>
LS251 device


NET2000 device objects

Device object LS251

The following table shows all device parameters which can be defined for LS251 communication in the device object's connection description.

Par. | Values | Settings | Description
/IF | ls251_1 ... ls251_9 | None | LS251 device Example: "/IF=ls251_1"
For additional parameters, see NET2000 protocol parameters.

Connection description example:

CD="/IF=ls251_1"

<< Previous Topic
Modem device

Start Page

Next Topic >>
NET2000 protocol parameters


NET2000 device objects

NET2000 protocol parameters

The following table shows the adjustable NET2000 protocol parameters for the device object.

Par. | Values | Settings | Description
/SA | 1 - 254 | 1 | Node number for the NET2000 master Example: "/SA=2"
/RC | 0 - 255, 0 = none | 3 | Retry counter for errors Example: "/RC=0"
/TE | 100 - 60000 | 3000 | Timeout for identification requests (ms) Example: "/TE=1000"
/TT | 100 - 60000 | 500 | Timeout for read/write requests (ms) Example: "/TT=100"
/TQ | 100 - 60000 | 3000 | Timeout for cross talk (ms) Example: "/TQ=2000"
/SR | 0 - 3 | 0 | Suppress identification retry depending on the error. See the following table. Example: "/SR=2"

Suppressing identification retries

In NET2000, PVI has to identify all variables on the PLC (Get OV Service) before they can be addressed (read / write variable data). If an error occurs during identification, PVI retries the identification procedure until the error situation is corrected. For certain system configurations, it is possible that the error status is desired. For example, a PVI application (e.g. visualization) can use variables which will only be created on the PLC in a later system expansion. In this case, the identification of these variables would be repeated continuously and greatly slow down NET2000 communication. Make sure that the PLC identification requests are handled in the idle time. If there is not very much idle time available on the PLC, this will cause additional delays in the NET2000 protocol. The "/SR" parameter can help. With this parameter, identification retries can be suppressed for certain errors.

"/SR=0" | No suppression (default setting)
"/SR=1" | Suppresses error 12601 (variable does not exist on the PLC)
"/SR=2" | Suppresses all errors from the PLC (12600 to 12699)
"/SR=3" | Suppresses all NET2000 errors except for the communication timeout (error 12510)

The "/SR=3" setting should only be used sparingly since this could also include errors which could be caused by temporary disturbances on the cable connection. If an error occurs with "/SR" selected, PVI switches the corresponding process object to a continuous error status. This can only be corrected by changing the connection description (CD=...) or by deleting and re-creating the affected process object.

Procedure for setting parameters

The /RC parameter (retry counter) should first be set to zero ("/RC=0) to set the optimum values of the communication parameters. The parameters for baud rate (/BD parameter) and timeouts (/TE and /TT parameters) are then trimmed. The following basic rule applies: Highest possible baud rate, lowest possible timeout times. The lowest allowed value for timeouts results from the following: Maximum PLC response time + maximum transfer time for 512 bytes + 10 ms (reserve). The /RC parameter (retry counter) can only be set to a higher value when the communication can function without disturbances.

The /TE parameter is only effective when identifying variables (initialization phase) and reading external data types. Variable identification is carried out on the PLC during idle time. As a result, it is important to ensure that there is enough idle time available. If there is not, the /TE parameter has to be increased.

The /TT parameter is effective when reading and writing variable data. On the PLC, write/read services are not processed during idle time, but in a defined task class (NET2000.task_class). In this way, response time can be influenced by the task class being used.

Example of a connection description in good communication conditions:

CD="/IF=com1 /BD=115200 /RC=2 /TE=500 /TT=100 /SR=1"

Example of a connection description in bad communication conditions:

CD="/IF=com2 /BD=38400 /IT=40 /RC=3 /TE=2500 /TT=500 /SR=1"

<< Previous Topic
LS251 device

Start Page

Next Topic >>
NET2000 station objects


NET2000 station objects

The NET2000 station object defines a NET2000 station (PLC) in a network.

The station number of the NET2000 station must be specified in the connection description. Values of 1 through 254 are possible as station numbers.

Connection description syntax:

/CN=<StationNumber>

or

<StationNumber>

If the station number is defined as the /CN parameter, the connection description must always be specified in quotation marks ("...") in the object description.

Connection description examples:

CD="/CN=127"
CD=200

<< Previous Topic
NET2000 protocol parameters

Start Page

Next Topic >>
NET2000 task objects


NET2000 task objects

The NET2000 task object represents a PLC task.

The name of the task must be specified in the connection description. Task names are case sensitive.

Connection description syntax:

/RO=<TaskName>

or

<TaskName>

If the task name is defined as the /RO parameter, the connection description must always be specified in quotation marks ("...") in the object description.

Connection description examples:

CD="/RO=Task1"
CD=Task2

<< Previous Topic
NET2000 station objects

Start Page

Next Topic >>
NET2000 variable objects


NET2000 variable objects

The NET2000 variable object represents a PLC variable. A NET2000 variable object can be created at two different positions in the PVI object structure. If the variable object is created under a station object, then a global PLC variable is addressed. If the variable object is created under an NET2000 task object, then a local PLC variable (task variable) is addressed.

The name of the PLC variable must be specified in the connection description. These names are case sensitive.

NET2000 can only address variables up to 502 bytes in size.

The NET2000 line supports PLC event variables (see also the AT parameter). Monitoring for changes in the process data is already being carried out on the PLC. PVI Manager doesn't need to carry out any cyclic read requests. If the data in a PLC variables is not changed very often (at least not as often as the refresh time), then operating as a PLC event variable can reduce the data coming up in NET2000 communication. However, one disadvantage of this is an increased need for computing time on the PLC. It needs to be noted that specifying the refresh time (RF parameter) also has an effect on PLC event variables. Only single variables can be operated as PLC event variables.

Since NET2000 can only transfer data from PLC event variables with read or write requests, pay attention that at least one variable is read cyclically (polled) per station. A refresh rate should be defined for these variables which is less than or equal to the smallest PLC event variable refresh rate.

The data format of the variable object is given by the NET2000 line and corresponds to that of the PLC variable or an element of the PLC variable. An alignment of 2 is used for structure variables.

Connection description syntax:

Single variables, array variables, and structure variables:

/RO=<variable_name>

or

<variable_name>

Element of an array variable:

/RO=<variable_name>[<index>]

or

<variable_name>[<index>]

Element of a structure variable:

/RO=<variable_name>.<element_name>

or

<variable_name>.<element_name>

Dynamic variables must begin with the "*" character.

If the variable name is defined as the /RO parameter, the connection description must always be specified in quotation marks ("...") in the object description.

Connection description examples:

CD="/RO=TempValue"

Singe variable "TempValue" is addressed.

CD=TempField[2]

The 3rd element (index begins with 0) of an array variable is addressed.

CD=Vert.Stat.TempField[0]

The 1st element of an array variable inside the "Stat" structure and the "Vert" structure is addressed.

CD="*ViewBf"

Pointer to the dynamic variable "ViewBf" is addressed.

Example of object description:

AT=rwe CD="/RO=TempValue"

Single variable "TempValue" is addressed and operated as a PLC event variable.

<< Previous Topic
NET2000 task objects

Start Page

Next Topic >>
DCAN line


DCAN line

It is possible to send and receive CAN messages to and from a CAN bus using the DCAN (direct CAN) line (message exchange according to the producer/consumer principle). The DCAN line also supports RTR (Remote Transmission Request) objects.

Unlike INA2000 communication via CAN, the contents of the CAN messages are not interpreted. This allows communication with CAN slaves to be established for example.

The following topics are covered in this section:

  • DCAN process objects
  • DCAN access types
  • DCAN event types
  • DCAN communication

DCAN process objects

A line object, a device object, a station object, and a variable object are all necessary to send or receive CAN messages with a certain CAN ID.

Process objects in the DCAN line:

Name | Type | Connection | Usage
Line object | Line | "LNDCAN" | DCAN Line
Device object | Device | Device parameter | DCAN device.
Station object | Station | Station parameters | Virtual station
CPU object | CPU |  | Can be specified, but not required.
Module object | Modules |  | Can be specified, but not required.
Task object | Task |  | Can be specified, but not required.
Variable object | Pvar | CAN ID | Represents a CAN object

Allowed object structure for DCAN process objects:

DCAN access types

The following table shows an overview of all access types which are regulated via a line. All access types not listed here as well as access types to the PVI base object are executed by PVI Manager and therefore work independently of the line being used. The corresponding process object type is listed in the "Type" column.

Access types | Type | Special features
POBJ_ACC_VERSION | Line Device | Line object: Version of the line DLL. Device object: Version of the INA frame DLL and device DLL
POBJ_ACC_LIST_EXTERN | Line | Lists entry for DCAN device if installed (PVI Setup)
POBJ_ACC_DATA | Pvar |
POBJ_ACC_STATUS |  | Not supported
POBJ_ACC_TYPE_EXTERN |  | Not supported
POBJ_ACC_UPLOAD |  | Not supported
POBJ_ACC_DOWNLOAD |  | Not supported
POBJ_ACC_DATE_TIME |  | Not supported
POBJ_ACC_MEM_DELETE |  | Not supported
POBJ_ACC_MEM_INFO |  | Not supported
POBJ_ACC_MOD_TYPE |  | Not supported
POBJ_ACC_UPLOAD_STM |  | Not supported
POBJ_ACC_DOWNLOAD_STM |  | Not supported
POBJ_ACC_MOD_DATA |  | Not supported
POBJ_ACC_MOD_DELETE |  | Not supported
POBJ_ACC_LIST_STATION |  | Not supported
POBJ_ACC_LIST_CPU |  | Not supported
POBJ_ACC_LIST_MODULE |  | Not supported
POBJ_ACC_LIST_TASK |  | Not supported
POBJ_ACC_LIST_PVAR |  | Not supported
POBJ_ACC_CPU_INFO |  | Not supported
Access type > 255 |  | Not supported

DCAN event types

The following table shows an overview of all event types which can be generated from a line. All event types which are not listed are generated by PVI Manager and therefore work independently of the line being used.

Event types | Special features
POBJ_EVENT_STATUS | Not supported
POBJ_EVENT_PROCEEDING | Not supported
Event type > 255 | Not supported

<< Previous Topic
NET2000 variable objects

Start Page

Next Topic >>
DCAN communication


DCAN communication

A particular communication device is used for DCAN (direct CAN) communication. "CAN" needs to be selected as an additional interface in PVI Setup.

PC requirements:

The DCAN line can be operated on the following platforms:

Windows platform | Restrictions
Windows NT/2000/XP | -
Windows Vista/Win7 | Not supported.
Windows CE | Not supported.

The description of the B&R CAN device driver can be used to find out which CAN cards can be used with which Windows platforms.

<< Previous Topic
DCAN line

Start Page

Next Topic >>
DCAN device objects


DCAN device objects

The communication device being used is determined with the DCAN device object. To address the DCAN device, it first has to be set up as a CAN device with the B&R CAN device configurator. Configuring CAN devices is done via the "CAN Devices" menu item in the Control Panel. The device list in the configurator shows all CAN devices which have already been set up. The device number must also be specified in the PVI device name. The CAN1 device corresponds to the PVI device name DCAN1. CAN2 corresponds to DCAN2, etc. the B&R CAN device configurator is also used to set device resources (IRQs, port addresses, etc.).

The communication device with the necessary device parameters is defined in the connection description of the device object. Within the connection description, individual parameters are differentiated between using parameter identifiers. These parameter identifiers always begin with the "/" character.

Connection description syntax:

/IF=<DeviceName> [/<Identifier1>=<ParameterValue> [/<Identifier2>=<ParameterValue> ... ]]

Device names are not case sensitive, and at least one space character must be between each parameter specification.

The connection description must always be specified in quotation marks ("...") in the object description.

The following table shows all parameters which can be defined for DCAN communication in the device object's connection description.

Par. | Values | Settings | Description
/IF | dcan1 ... dcanX | None | CAN device. The device being used has to be entered in the device list of the B&R CAN device configurator. Example: "/IF=dcan1"
/CNO | 0, 1 | 0 | CAN controller number (channel). 2 CAN controllers are available on the LS172 card. The desired controller is selected with the /CNO parameter. No value other than 0 (zero) may be specified for the default CAN controller. Example for LS172 card: CAN bus 1: "/IF=dcan2 /CNO=0" CAN bus 2: "/IF=dcan2 /CNO=1"
/BD | 10000, 20000, 50000, 100000, 125000, 150000, 250000, 500000, 800000, 1000000 | *) | Baud rate (data rate) on the CAN bus in bits per second. This parameter can also be specified in kBits per second. Example: "/BD=250000" or "/BD=250"
/CMODE | 11, 29 | *) | CAN communication with 29-bit identifiers (extended frames) or 11-bit identifiers (standard frames). If 29-bit CAN identifiers (extended frames) are used, then 11-bit identifiers cannot be sent or received. Example: "/CMODE=29"
/CT | >= 1, 0 = off | *) | Cycle time (in ms) within which the specified number (maximum) of CAN messages are sent (/MC parameter). Values < 20 ms don't make sense. Example: "/CT=20"
/MC | >= 1 | *) | Maximum number of CAN messages sent within the specified cycle time (/CT parameter). Example: "/MC=15"
*) The /BD, /CMODE, /CT, and /MC parameters can also be set using the B&R CAN device configurator. If these parameters are not specified in the connection description (the recommended method), then the values set in the configurator are used instead. If one of these parameters is specified in the connection description, then the corresponding configurator setting is overwritten.

The /CT and /MC parameters are used to limit messages. These allow the number of sent CAN messages to be restricted per cycle. This can reduce the load from the PC to the CAN bus. This could be important if other stations on the bus can only process a certain number of received CAN messages with the set baud rate, or if their interrupt load in general should be reduced. However, the disadvantage of limiting frames is slower CAN communication.

Connection description example:

CD="/IF=dcan3 /CNO=1"

<< Previous Topic
DCAN communication

Start Page

Next Topic >>
DCAN station objects


DCAN station objects

A station object describes a virtual DCAN station (CAN connection). If more than one DCAN station is used, then a unique virtual name has to be assigned to each station object.

Each DCAN station has its own FIFO to buffer received CAN messages. The size of the FIFO buffer and the corresponding timeouts are set with station parameters. On a DCAN station, bus nodes with different designs can be grouped together and operated with different settings (Receive FIFO, Timeouts).

The user can determine the distribution in DCAN stations according to his requirements. However, note that each station requires Windows resources (RAM, path objects, threads, etc.). Therefore, the number of stations should be kept within limits.

The virtual station name and station parameters are defined in the station object's connection description. Within the connection description, individual parameters are differentiated between using parameter identifiers. These parameter identifiers always begin with the "/" character. At least one blank space needs to be between individual parameter entries.

Connection description syntax:

[/CN=<Name>] [/<Identifier1>=<ParameterValue> [/<Identifier2>=<ParameterValue> ... ]]

The following table shows all parameters which can be defined for DCAN communication in the station object's connection description.

Par. | Values | Settings | Description
/CN | Name | "DefStation" | Virtual station name Only alphanumeric characters and the "_" (underscore) character may be included in names. Names may only be up to 31 characters long. Names are also case sensitive. Example: "/CN=Main". In an earlier version, the virtual station name was defined using the /DA parameter. This parameter can continue to be used in place of the /CN parameter. However, new applications should always use the /CN parameter.
/FS | 1 - 65535 | 100 | Size of the receive buffer (FIFO) in the CAN driver The value specifies the number of CAN messages. Only CAN messages whose IDs are enabled using an assigned variable object (read object) are written to the receive buffer. The necessary buffer size is therefore arranged only according to the frequency with which enabled CAN messages can occur on the CAN bus. Example: "/FS=200"
/TR | 1 - 60000 | 1000 | Timeout for RTR read request in ms After an RTR read request, the response from the opposite station needs to be received within the set time. If this doesn't happen, then Timeout Error 14987 is reported. This parameter is only significant if used in connection with RTR read objects. Example: "/TR=100"
/TW | 1 - 2000 | 250 | Write procedure timeout in msec If the write request cannot be executed within the set time (e.g. CAN bus is occupied by CAN messages with higher priority), then the write procedure is cancelled and Timeout Error 14986 is reported. Internal write procedures (such as registering or deregistering RTR objects) can also report Error 13036. Example: "/TW=50"
/RW | 1 – 10000 0=none | *) | Write request delay time in msec Along with the delay time for write requests, a defined delay time is adhered to between the most recently received CAN message and the next CAN message to be sent. Example: "/RW=0"
/CF | 0, 1 | 0 | "/CF=0": Do not empty receive buffer (FIFO) before the write procedure (default setting). "/CF=1": Empty receive buffer (FIFO) before each write procedure (deletes).
*) The /RW parameter can also be set with the B&R CAN device configurator. If this parameter is not specified in the connection description, then the value set in the configurator is used. If this parameter is specified in the connection description, then the corresponding configurator setting is overwritten.

Connection description example:

CD="/CN=ExtIO /FS=250 /TW=100"

<< Previous Topic
DCAN device objects

Start Page

Next Topic >>
DCAN variable objects


DCAN variable objects

A DCAN variable object represents a CAN object on the CAN bus. A CAN object is defined using the CAN ID. All CAN messages are assigned to the CAN object using this CAN ID.

Message doubling can occur when using CAN in a malfunctioning environment (see CiA "CAN Data Link Layer"). In this case, the same CAN message is received twice.
For this reason, the following points need to be taken into consideration in a malfunctioning environment:
- No "Toggle" messages or counted messages may be evaluated
- No messages with relative data (such as increments) may be sent
- Data segments may only be transferred with a protected protocol or with sequence numbers.

CAN objects can hold a maximum of 8 data bytes. The data format of the variable object can either be set by the user or by the DCAN line.

DCAN Variable objects can be defined for either send or receive operation within a station object. This definition takes place with the object attribute property (AT parameter). "AT=w" is specified for send operations, "AT=e" for receive operations. Send and receive operation on the same CAN object is not possible. In receive operation, CAN data is transferred as an event to the application (POBJ_EVENT_DATA event type). Specifying the refresh time (RF parameter) has no significance.

RTR send objects are not supported by the SJA1000 driver.

CAN variable objects can also be operated as CAN RTR objects. An RTR object can be defined either as a send ("AT=w") or receive ("AT=r") object. RTR (Remote Transmission Request) is a method standardized for CAN where a station (Producer) sends a CAN message (data frame - RTR bit not set) only after a read request (remote frame - RTR is set) from another station (Consumer). The read request and response have the same CAN ID and are only differentiated by the RTR bit.

If a DCAN line variable object is created as an RTR receive object (Consumer, "AT=r"), then a RTR read request is sent to the CAN bus with the specified refresh time. As with "normal" PLC variables from other lines, data acquisition can also be controlled here by the PVICOM application. For this, the Value - 1 is set as the refresh time. The application itself determines when the read request is carried out by calling the PviReadRequest or PviXReadRequest and using access type POBJ_ACC_DATA. RTR receive objects work with timeout monitoring. After an RTR read request, the response from the opposite station needs to be received within the given time. If this doesn't happen, then Timeout Error 14987 is reported. The maximum response time can be defined using the /TR parameter in the connection description of the station object.

DCAN line variable objects can also be created as RTR send objects (Producer, "AT=w"). The send object is supplied with data by calling the PviWriteRequest or PviXWriteRequest function. However, the maximum number of send objects is limited and depends on the CAN card being used. A maximum of 12 can be used with the B&R standard CAN interface. Up to 256 send objects can be used with the LS172 card. With the LS172 card, RTR send objects can only be used with an ID less than or equal to 2047 even when using extended frames (29-bit identifiers).

Received data for a CAN object is normally monitored for changes. That means the application is only informed of changes to CAN data. Monitoring for changes can be disabled (specification "AT=de") with the variable attribute "d" (direct). This transfers all received CAN data to the application.

With the "d" object attribute, all received CAN data occupy application memory in PVI until it is read by the application. Therefore, the "d" attribute should be used with extreme care and only when absolutely necessary.

When transferring data, the DCAN line does not carry out byte swapping since CAN data is already in Intel format anyway (least significant byte first).

The CAN object ID must be entered in the connection description. Code letters can be used to determine how the CAN objects function.

Connection description syntax:

/RO=[L][R]<CAN ID>

or

[L][R]<CAN ID>

These code letters are not case sensitive. These code letters can be combined in any way.

Code letter "L" | Description
Not specified | The user can set any data format (e.g. a structure). Note that CAN objects can only transfer a maximum of 8 data bytes. The total length of the set data format determines the length of the data to be transferred in the write direction (sending). In the read direction (receiving), the data is copied dependent on its length. For example, the user defined "i32" (4-byte integer) as a data format. If a CAN message with 2 bytes of data is received, then only the first 2 bytes of the integer value are copied. All other bytes remain undefined. If a data format is not defined when creating the DCAN variable object, then the line automatically uses "VT=u8 VN=8" (byte array with 8 byte length). This variant is especially suitable for CAN objects with a fixed data length. The user has the option of setting the format of a structure, array, or signal variable using the CAN data. This allows PVI functions like type casting, variable addressing, event hysteresis, or data functions to be used.
Specified | Regardless of the user setting, a data format of "VT=u8 VN=9" (byte array with 9 byte length) is set by the DCAN line. The length of the CAN object data to be sent or received is passed in the first byte. Bytes 2-9 are used to pass the data. When writing, the user has to enter the length of the data in the first byte. Values between 0 (zero) and 8 are valid for the data length. This variant is intended for CAN objects with differing data lengths but can also (of course) be used for CAN objects with a fixed data length.
Code letter "R" | Description
Not specified | Standard CAN object for send or receive operation This definition takes place with the object attribute property (AT parameter). "AT=w" is specified for send operations, "AT=e" for receive operations.
Specified | RTR send or receive object This definition takes place with the object attribute property (AT parameter). "AT=w" is specified for the send object, "AT=r" is specified for the receive object. The refresh time property is also evaluated for receive objects.

Example of object description:

CD="/RO=1597" VT=i32 AT=e

After receiving a CAN message with CAN ID 1597, data is mapped to a 4-byte integer.

CD="/RO=L1597" AT=e

After receiving a CAN message with CAN ID 1597, the data length and the data in the CAN message are mapped to a 9-byte array.

CD=1597 VT=i32 AT=w

With the write access to the variable object, the 4-byte integer data is sent together with the CAN ID 1597 as a CAN message.

CD=LR1597 AT=r RF=500

RTR read object for CAN ID 1597. A read request is sent every 500 ms.

CD=R1597 VT=i16 AT=w

RTR write object for CAN ID 1597. 2-byte integer data is sent after an external read request.

<< Previous Topic
DCAN station objects

Start Page

Next Topic >>
SNMP line


SNMP line

The SNMP line maps SNMP (Simple Network Management Protocol) variables from an SG4 PLC to PVI variable objects.

The SNMP line is intended mainly for commissioning a new PLC via the Ethernet interface. SNMP variables can be used to make or call up settings such as host name, IP address, node number, etc..

The following topics are covered in this section:

  • SNMP process objects
  • SNMP access types
  • SNMP event types

SNMP process objects

A line object, a device object, and a variable object are all needed to access a global SNMP variable. Local SNMP variables also require a station object.

Process objects of the ADI line:

Name | Type | Connection | Usage
Line object | Line | "LNSNMP" | SNMP line.
Device object | Device | "SNMP" | SNMP device.
Station object | Station | MAC address | Specifies a particular PLC.
CPU object | CPU |  | Can be specified, but not required.
Module object | Modules |  | Can be specified, but not required.
Task object | Task |  | Can be specified, but not required.
Variable object | Pvar | Variable name | SNMP variable.

Allowed object structure for SNMP process objects:

SNMP access types

The following table shows an overview of all access types which are regulated via a line. All access types not listed here as well as access types to the PVI base object are executed by PVI Manager and therefore work independently of the line being used. The corresponding process object type is listed in the "Type" column.

Access types | Type | Special features
POBJ_ACC_VERSION | Line | Line object: Version of the line DLL. Device object: Version of the B&R SNMP DLL.
POBJ_ACC_LIST_EXTERN | Line, Device, Station | Line object: SNMP device. Device object: List of all PLC MAC addresses that can be identified on the network, as well as all global SNMP variables. Station Object: List of local SNMP variables *)
POBJ_ACC_DATA | Pvar | Read/write data from an SNMP variable.
POBJ_ACC_STATUS | Pvar | Not supported
POBJ_ACC_TYPE_EXTERN | Pvar | Data format of an SNMP variable (as defined by the line).
POBJ_ACC_UPLOAD |  | Not supported
POBJ_ACC_DOWNLOAD |  | Not supported
POBJ_ACC_DATE_TIME |  | Not supported
POBJ_ACC_MEM_DELETE |  | Not supported
POBJ_ACC_MEM_INFO |  | Not supported
POBJ_ACC_MOD_TYPE |  | Not supported
POBJ_ACC_UPLOAD_STM |  | Not supported
POBJ_ACC_DOWNLOAD_STM |  | Not supported
POBJ_ACC_MOD_DATA |  | Not supported
POBJ_ACC_MOD_DELETE |  | Not supported
POBJ_ACC_LIST_STATION | Device | Device object: List of all PLC MAC addresses that can be identified on the network.
POBJ_ACC_LIST_CPU |  | Not supported
POBJ_ACC_LIST_MODULE |  | Not supported
POBJ_ACC_LIST_TASK |  | Not supported
POBJ_ACC_LIST_PVAR | Device, Station | Device object: List of global SNMP variables. Station Object: List of local SNMP variables *)
POBJ_ACC_CPU_INFO |  | Not supported
Access type > 255 |  | Not supported

*) The list contains the possible variables for a PLC. Whether or not these variables are actually supported depends on the addressed PLC.

SNMP event types

The following table shows an overview of all event types which can be generated from a line. All event types which are not listed are generated by PVI Manager and therefore work independently of the line being used.

Event types | Special features
POBJ_EVENT_STATUS | Not supported
POBJ_EVENT_PROCEEDING | Not supported
Event type > 255 | Not supported

<< Previous Topic
DCAN variable objects

Start Page

Next Topic >>
SNMP communication


SNMP communication

All components necessary for SNMP communication are installed with the PVI setup.

PC requirements:

The SNMP line can be operated on the following platforms:

Windows platform | Limitations
Windows 7 or higher | -
Windows XP/Vista | -

PLC requirements:

SNMP must be activated on the PLC.

<< Previous Topic
SNMP line

Start Page

Next Topic >>
SNMP device object


SNMP device object

The SNMP communication device is defined in the device object's connection description with the necessary device parameters.

Connection description syntax:

/IF=<DeviceName> [/<Identifier1>=<ParameterValue> [/<Identifier2>=<ParameterValue> ... ]]

Device names are not case sensitive, and at least one space character must be between each parameter specification.

The connection description must always be specified in quotation marks ("...") in the object description.

The following table shows all parameters which can be defined in a device object's connection description.

Param. | Values | Settings | Description
/IF | snmp | snmp | Only "/IF=snmp" can be specified for the device object.
/RT | 100 - 15000 | 1000 | Response timeout for SNMP data in milliseconds The response timeout specified here is used to monitor the response times for SNMP read or write tasks. For SNMP broadcast telegrams (determination of the MAC addresses for all PLCs that can be reached), response data is waited for throughout the duration of the response timeout. Typical response timeout values range from 500 to 2500 ms.

Connection description example:

CD="/IF=snmp /RT=2000"

<< Previous Topic
SNMP communication

Start Page

Next Topic >>
SNMP station object


SNMP station object

The SNMP station object addresses a specific PLC within the network.

The MAC address of the PLC must be defined in the connection description. The MAC address is 6 bytes long and is entered in the station object as a 12 character hex string in canonical format with or without separator.

The MAC address (Media Access Control, Ethernet ID) is the hardware address of each network adapter, and provides a unique identification of a device in a network.

Connection description syntax:

/CN=<MAC address>

or

<MAC address>

If the station number is defined as the /CN parameter, the connection description must always be specified in quotation marks ("...") in the object description.

Connection description examples:

CD="/CN=00-60-65-02-f0-2c"
CD=00606502f02c

<< Previous Topic
SNMP device object

Start Page

Next Topic >>
SNMP variable object


SNMP variable object

An SNMP variable object represents an SNMP variable or a PLC or service object in the SNMP library. The SNMP variable or the service object is determined by the connection name of the variable object. Case sensitive. All names are predefined in the SNMP library, and can be listed using the respective PVI list services (Type of access POBJ_ACC_LIST_EXTERN or POBJ_ACC_LIST_PVAR).

The data format of most variables is assigned by the SNMP line and cannot be influenced by the user (exceptions listed in the table of predefined variable names).

Syntax of connection description:

Single and array variables:

/RO=<VariableName>

or

<VariableName>

If the variable name is defined as the /RO parameter, the connection description must always be specified in quotation marks ("...") in the object description.

Connection description examples:

CD="/RO=serialNumber"
CD=serialNumber

Predefined variable names

The SNMP line supports the following SNMP variables:

The I/O column shows the permitted type of access (R ... read, W ... write). The MAC column shows whether or not the variable requires a MAC address. Variables without a MAC address are labeled as global SNMP variables, and must be arranged as variable objects below the SNMP device object. Variables with a MAC address are labeled as local SNMP variables, and must be arranged below an SNMP station object.

Variable name | Data format | I/O | MAC | Description
MAC addresses | *) | R | No | List of MAC addresses for all B&R PLCs with SNMP support that can be reached on the network. Entries are separated by a tab character (0x09). Each entry is 18 characters long (including tab character). Each read access is not ended until the response timeout (/RT parameter) configured for the device object has expired. During this time, response data is gathered from the individual PLCs.
snmpMode | VT=i32 | R | Yes | 0 ... SNMP not enabled, 1 ... SNMP read-only, 2 ... SNMP enabled
targetTypeDescription | VT=string VL=32 | R | Yes | Description of the CPU (e.g. 3CP360.60-1).
serialNumber | VT=string VL=32 | R | Yes | PLC serial number.
cfSerialNumber | VT=string VL=32 | R | Yes | CompactFlash serial number
arVersion | VT=string VL=8 | R | Yes | AR version (e.g. N3.00)
arVersionNorm | VT=string VL=32 | R | Yes | Standardized AR version (e.g. 3.00.14)
arState | VT=i32 | R | Yes | AR status: -1 ... Undefined, 1 ... Boot, 2 ... Diagnose, 3 ... Service, 4 ... Run
arBootPhase | VT=i32 | R | Yes | Boot phase: -1 ... Undefined, 10 ... Boot, 20 ... Hardware init / Firmware update, 30 ... Initialization subroutine, 40 ... AR ready
deviceName | VT=string VL=32 | R | Yes | Ethernet device name (e.g. SS1.IF2)
macAddress | VT=string VL=20 | R | Yes | MAC address (e.g. 00-60-ef-01-15-5a)
baudrate | VT=i32 | RW | Yes | Ethernet baud rate: 0 ... Auto, 10 ... 10 MBit HD (half-duplex), 11 ... 10MBit FD (full-duplex), 12 ... 10 MBit Auto, 100 ... 100 MBit HD, 101 ... 100 MBit FD, 102 ... 100 MBit Auto
ipAddress | VT=string VL=16 | RW | Yes | IP address
subnetMask | VT=string VL=16 | RW | Yes | Subnet mask (e.g. 255.255.255.0)
ipMethod | VT=i32 | RW | Yes | 0 ... Static IP, 1 ... DHCP client
nodeNumber | VT=i32 | R | Yes | Hardware node number.
inaNodeNumber | VT=i32 | RW | Yes | INA node number.
inaActivated | VT=i32 | R | Yes | 0 ... INA not enabled, 1 ... INA enabled
inaPortNumber | VT=i32 | RW | Yes | INA port number.
hostName | VT=string VL=32 | RW | Yes | Hostname (e.g. BR_HOST)
defaultGateway | VT=string VL=16 | RW | Yes | Default gateway.
dnsActivated | VT=i32 | RW | Yes | 0 ... INA not enabled, 1 ... INA enabled
dnsFromDhcp | VT=i32 | RW | Yes | Get DNS parameters from DHCP: 0 ... Not enabled, 1 ... Enabled
dnsServer1 | VT=string VL=16 | RW | Yes | DNS server 1
dnsServer2 | VT=string VL=16 | RW | Yes | DNS server 2
dnsServer3 | VT=string VL=16 | RW | Yes | DNS server 3
*) The user must define the data format of the variable object (process object). The variable type must be STRING (VT=string). The length of the string (VL parameter) should be set to the maximum possible length. If the length is smaller than the actual string length, the string will be cut off.

<< Previous Topic
SNMP station object

Start Page

Next Topic >>
ADI line


ADI line

The ADI line provides functions for the B&R Automation Device Interface (ADI).

ADI is the interface for B&R devices (see supported industrial PCs). It can be used to e.g. set LEDs of change brightness settings on B&R displays. The functionalities provided by ADI come from the ADI driver, which needs to be installed on your system.

Topics in this section:

  • ADI process objects
  • ADI access types
  • ADI event types

ADI process objects

A line object, a device object, and a variable object are all needed to access an ADI variable.

Process objects in the ADI line:

Name | Type | Connection | Usage
Line object | Line | "LNADI" | ADI line.
Device object | Device | Device parameter | ADI device.
Station object | Station |  | Can be specified, but not required.
CPU object | CPU |  | Can be specified, but not required.
Module object | modules |  | Can be specified, but not required.
Task object | Task |  | Can be specified, but not required.
Variable object | Pvar | Variable name | ADI variable.

Allowed object structure for ADI process objects:

ADI access types

The following table shows an overview of all access types which are regulated via a line. All access types not listed here as well as access types to the PVI base object are executed by PVI Manager and therefore work independently of the line being used. The corresponding process object type is listed in the "Type" column.

Access types | Type | Special features
POBJ_ACC_VERSION | Line | Line object: Version of the line DLL.
POBJ_ACC_LIST_EXTERN | Line, Device | Line object: List of all installed ADI devices. Device object: List of all supported ADI variables.*
POBJ_ACC_DATA | Pvar |
POBJ_ACC_STATUS | Pvar |
POBJ_ACC_TYPE_EXTERN | Pvar |
POBJ_ACC_UPLOAD |  | Not supported
POBJ_ACC_DOWNLOAD |  | Not supported
POBJ_ACC_DATE_TIME |  | Not supported
POBJ_ACC_MEM_DELETE |  | Not supported
POBJ_ACC_MEM_INFO |  | Not supported
POBJ_ACC_MOD_TYPE |  | Not supported
POBJ_ACC_UPLOAD_STM |  | Not supported
POBJ_ACC_DOWNLOAD_STM |  | Not supported
POBJ_ACC_MOD_DATA |  | Not supported
POBJ_ACC_MOD_DELETE |  | Not supported
POBJ_ACC_LIST_STATION | Line, Device |
POBJ_ACC_LIST_CPU | Line, Device |
POBJ_ACC_LIST_MODULE | Line, Device |
POBJ_ACC_LIST_TASK | Line, Device |
POBJ_ACC_LIST_PVAR | Line, Device | Device object: List of all supported ADI variables.*
POBJ_ACC_CPU_INFO |  | Not supported
Access type > 255 |  | Not supported

* The list contains the possible variables for a device. Whether or not these variables are actually supported depends on the current hardware configuration. Example: An APC620 may have an AP Link transmitter, which is why the "LinkFpgaVersion" and "LinkType" variables are listed. However, if the device doesn't have an AP Link transmitter, then an error will occur when registering the variables.

ADI event types

The following table shows an overview of all event types which can be generated from a line. All event types which are not listed are generated by PVI Manager and therefore work independently of the line being used.

Event types | Special features
POBJ_EVENT_STATUS | Not supported
POBJ_EVENT_PROCEEDING | Not supported
Event type > 255 | Not supported

<< Previous Topic
SNMP variable object

Start Page

Next Topic >>
ADI communication


ADI communication

The ADI line only works in combination with the device-specific ADI driver. This can be downloaded from the B&R website (www.br-automation.com).

The ADI driver does not have to be installed on your computer in order to use the ADI line. The line will then return all supported objects when using access type POBJ_ACC_LIST_EXTERN and POBJ_ACC_LIST_PVAR.

The ADI driver allows B&R industrial PCs, connected B&R Automation Panels and display units and the B&R add-on USV to be accessed.

PC requirements

The ADI line can be operated on the following platforms:

Windows platform | Limitations
Windows 7 or higher | ADI driver only available for certain Windows versions depending on the device.
Windows 2000/XP/Vista | ADI driver only available for certain Windows versions depending on the device.
Windows CE | No longer supported in PVI V3.0.3 and higher

The ADI line requires at least ADI DLL version 2.00. This is included in the ADI driver version 1.50 or higher on the APC620 and PPC700 and ADI driver version 2.00 and higher on the PP100/200 and MP100/200.

Depending on the device being used, a certain version of BIOS or other device-specific firmware may be necessary to take advantage of the full functionality of the ADI. The required versions are listed with the predefined variable names for the devices.

Industrial PC

ADI supports access to these B&R Industrial PCs.

  • Automation PC 510 1
  • Automation PC 511 1
  • Automation PC 620
  • Automation PC 810
  • Automation PC 820
  • Mobile Panel 40/50
  • Mobile Panel 100/200
  • Panel PC 300
  • Panel PC 700
  • Panel PC 800
  • Power Panel 100/200
  • Power Panel 300/400
  • Power Panel 500 1

1 On an Automation PC 510, Automation PC 511 and Power Panel 500, the information and functions of the system unit are accessed. Additionally, information is read from the installed CPU board and memory module and any optional IF board and I/O board.

Panels / Display units

ADI supports access to the display, keys and LEDs of the supported industrial PCs and connected Automation Panel 800 and 900 devices.

UPS

ADI supports access to a B&R add-on UPS device.

CPU board

ADI supports access to the CPU board installed in a Power Panel 500.

Memory module

ADI supports access to the memory module (DRAM) installed a Power Panel 500.

IF board

ADI supports access to the IF board installed in a Power Panel 500.

I/O board

ADI supports access to the I/O board installed in a Power Panel 500.

<< Previous Topic
ADI line

Start Page

Next Topic >>
ADI device objects


ADI device objects

The ADI communication device is determined with the ADI device object.
The following communication devices can be defined:

  • PC devices
  • Panel devices
  • UPS devices
  • CPU devices
  • Memory devices
  • IF devices
  • I/O devices
  • Bus devices
  • Drive devices
  • Link devices

The communication device is defined in the device object's connection description with the necessary device parameters. Within the connection description, individual parameters are differentiated between using parameter identifiers. These parameter identifiers always begin with the "/" character.

Syntax of connection description:

/IF=<device name> [/<ID1>=<parameter value> [/<ID2>=<parametervalue> ... ]]

The /IF parameter is common to all communication devices. All other parameters depend on the communication device being used. Device names are not case-sensitive. At least one empty space is to be entered between the individual parameter specifications.

The connection description must always be specified in quotation marks ("...") in the object description.

Connection description example:

CD="/IF=panel /DA=2"

PC devices

The following table shows all parameters which can be defined for an industrial PC in the device object's connection description.

Param. | Values | Settings | Description
/IF | pc | None | PC device. Value: "/IF=pc".

Connection description example:

CD="/IF=pc"

Panel devices

The following table shows all parameters which can be defined for an Automation Panel or a display unit in the device object's connection description.

Param. | Values | Settings | Description
/IF | PANEL | None | Panel device. Value: "/IF=PANEL".
/DA | 0 - 15 | None | Panel address. Depending on the device, one or more Automation Panels can be connected to the PC or a display unit can be installed. The panel address specifies which connected panel the device object is referring to. If the DA parameter is not specified, the device object refers to the default panel, i.e. the panel connected first or onboard PC display. Example: "/DA=2"

Connection description example:

CD="/IF=panel /DA=2"

UPS devices

The following table shows all parameters which can be defined for a UPS device in the device object's connection description.

Param. | Values | Settings | Description
/IF | ups | None | PC device. Value: "/IF=ups". Please note that, depending on the PC used, a UPS device may not be supported or installed!

Connection description example:

CD="/IF=ups"

CPU devices

The following table shows all parameters which can be defined for a CPU board in the device object's connection description.

Param. | Values | Settings | Description
/IF | cpu | None | CPU device Value: "/IF=cpu". Please note that, depending on the PC used, a CPU board (as CPU device) may not be supported or installed!

Connection description example:

CD="/IF=cpu"

Memory devices

The following table shows all parameters which can be defined for a memory module in the device object's connection description.

Param. | Values | Settings | Description
/IF | mem, mem1, mem2 | None | Memory device: "mem" is supported to ensure compatibility, and like "mem1" represents the PC's first memory module. "mem2" represents the PC's second memory module. Value: "/IF=mem". Please note that, depending on the PC used, a memory module (as memory device) may not be supported or installed!

Connection description example:

CD="/IF=mem"

IF devices

The following table shows all parameters which can be defined for a IF module in the device object's connection description.

Param. | Values | Settings | Description
/IF | if, if1, if2 | None | IF device "if" is supported to ensure compatibility, and like "if1" represents the PC's first IF module. "if2" represents the PC's second IF module. Example: "/IF=if". Please note that, depending on the PC used, an IF module may not be supported or installed!

Connection description example:

CD="/IF=if"

I/O devices

The following table shows all parameters which can be defined for a I/O board in the device object's connection description.

Param. | Values | Settings | Description
/IF | io | None | I/O device Value: "/IF=io". Please note that, depending on the PC used, an I/O board may not be supported or installed!

Connection description example:

CD="/IF=io"

Bus devices

The following table shows all parameters which can be defined for a bus unit in the device object's connection description.

Param. | Values | Settings | Description
/IF | bus | None | Bus device. Value: "/IF=bus". Please note that, depending on the PC used, a bus unit may not be supported or installed!

Connection description example:

CD="/IF=bus"

Fan devices

The following table shows all parameters which can be defined for a fan kit in the device object's connection description.

Param. | Values | Settings | Description
/IF | fan1, fan2 | None | Fan device. "fan1" represents the PC's first fan kit. "fan2" represents the PC's second fan kit. Value: "/IF=fan1". Please note that, depending on the PC used, no fan kits or only one fan kit may be supported or installed!

Connection description example:

CD="/IF=fan1"

Drive devices

The following table shows all parameters which can be defined for a slide-in drive in the device object's connection description.

Param. | Values | Settings | Description
/IF | drive1, drive2 | None | Drive device. "drive1" represents the PC's first slide-in drive. "drive2" represents the PC's second slide-in drive. Example: "/IF=drive1". Please note that, depending on the PC used, no slide-in drives or only one slide-in drive may be supported or installed!

Connection description example:

CD="/IF=drive1"

Link devices

The following table shows all parameters which can be defined for a Display Link in the device object's connection description.

Param. | Values | Settings | Description
/IF | link | None | Link device Example: "/IF=link". Please note that, depending on the PC used, a Display Link may not be supported or installed!

Connection description example:

CD="/IF=link"

<< Previous Topic
ADI communication

Start Page

Next Topic >>
ADI variable objects


ADI variable objects

An ADI variable object represents an object in the ADI. The connection name of the variable object corresponds to the name of the ADI variable. The ADI line supports predefined variable names for various devices.

These are not case sensitive.

The data format of the variable object is given by the ADI line and cannot be influenced by the user.

Syntax of connection description:

Single and array variables:

/RO=<VariableName>

or

<VariableName>

Element of an array variable:

/RO=<variable name>[<index>]

or

<variable name>[<index>]

If the variable name is defined as the /RO parameter, the connection description must always be specified in quotation marks ("...") in the object description.

Connection description examples:

CD="/RO=LedMatrix"

CD=LedMatrix[12]

Access time:

If many variables should be read, then short refresh rates (RF) for these variables should be specified which can react quickly to data changes (e.g. keys). All other variables should be read with high refresh rates.

Predefined variable names

  • Variable names for PC devices
  • Variable names for panel devices
  • Variable names for UPS devices
  • Variable names for CPU devices
  • Variable names for memory devices
  • Variable names for IF devices
  • Variable names for I/O devices
  • Variable names for bus devices
  • Variable names for fan devices
  • Variable names for drive devices
  • Variable names for link devices

<< Previous Topic
ADI device objects

Start Page

Next Topic >>
Variable names for PC devices


Variable names for PC devices

The ADI line supports the following variables for a PC device:

Note: The "C" column indicates whether the variable returns a constant value.

Variable name | Data format | I/O | C | Devices | Description
aPci1Comment PP100/200: VT=string VL=33
PP300/400: VT=string VL=89 		R ü PP100/200 4
PP300/400 		Comment for the FPGA firmware for aPCI slot 1.

By default, the comment contains the date and version of the firmware.
aPci1DeviceId PP100/200: VT=string VL=7
PP300/400: VT=string VL=8 		R ü PP100/200 3
PP300/400 		Device ID of the aPCI module in Slot 1.

Example: "5090" 2
aPci1Eeprom | VT=u8 VN=256 | R | ü | PP300/400 | EEPROM data of the aPCI module in Slot 1.
aPci1ModelNumber PP100/200: VT=string VL=19
PP300/400: VT=string VL=24 		R ü PP100/200 3
PP300/400 		Model number of the aPCI module in Slot 1.

Example: "3IF786.9" 2

PP100/200 with Windows CE: Valid data is returned beginning with Windows CE 5.0 version 5.1 only (with boot loader version 2.3). An empty string is always returned in older Windows CE versions (with older bootloader versions).
aPci1Size VT=u32 R ü PP100/200 4
PP300/400 		Size of the FPGA firmware for aPCI Slot 1 in bytes.
aPci1Status VT=u8 R ü PP100/200 3
PP300/400 		Boot status for the FPGA firmware for aPCI slot 1.
aPci1Variant | VT=u8 | R | ü | PP300/400 | Variant of the aPCI module in Slot 1. 0 to 255.
aPci1XmlHeader VT=string VL=256 R ü PP100/200 4
PP300/400 		XML header for the FPGA firmware for aPCI slot 1.

The XML header contains information about the firmware such as device ID, version, size, etc.
aPci2Comment PP100/200: VT=string VL=33
PP300/400: VT=string VL=89 		R ü PP100/200 4
PP300/400 		Comment for the FPGA firmware for aPCI slot 2.

By default, the comment contains the date and version of the firmware.
aPci2DeviceId PP100/200: VT=string VL=7
PP300/400: VT=string VL=8 		R ü PP100/200 3
PP300/400 		Device ID of the aPCI module in Slot 2.

Example: "5090" 2
aPci2Eeprom | VT=u8 VN=256 | R | ü | PP300/400 | EEPROM data of the aPCI module in Slot 2.
aPci2ModelNumber PP100/200: VT=string VL=19
PP300/400: VT=string VL=24 		R ü PP100/200 3
PP300/400 		Model number of the aPCI module in Slot 2.

Example: "3IF786.9" 2
aPci2Size VT=u32 R ü PP100/200 4
PP300/400 		Size of the FPGA firmware for aPCI Slot 2 in bytes.
aPci2Status VT=u8 R ü PP100/200 3
PP300/400 		Boot status for the FPGA firmware for aPCI slot 2.
aPci2Variant | VT=u8 | R | ü | PP300/400 | Variant of the aPCI module in Slot 2. 0 to 255.
aPci2XmlHeader VT=string VL=256 R ü PP100/200 4
PP300/400 		XML header for the FPGA firmware for aPCI slot 2.

The XML header contains information about the firmware such as device ID, version, size, etc.

BatteryVoltage

 VT=f32 R obsolete - replaced by BatVoltage
BatState VT=i32 R APC510
APC511
APC620 16
APC810
APC820
APC910
PP300/400 15
PP500
PPC300
PPC700 16
PPC800
PPC900 		CMOS battery state.

0 = Unknown
1 = Good
2 = Bad (missing, defective, dead)
BatVoltage VT=f32 R APC510
APC511
APC620
APC910
PP500 27
PPC700
PPC900 		CMOS battery voltage (Vbat) in volts.
BiosBootInfo VT=i32 R ü APC510
APC511
PP500 27 		BIOS Bootinfo.

0 = Booted from backup area
1 = Booted from normal (update) area

BiosCoreVersion VT=string VL=80 R ü APC620 25
MP100/200 10
PP100/200 10
PP300/400
PPC300
PPC700 25 		BIOS core version.

Example: "4.0 Release 6.1"
BiosDate VT=string VL=80 R ü APC510
APC511
APC620
APC810
APC820
APC910
APC2100
MP100/200 10
PP100/200 10
PP300/400
PP500
PPC300
PPC700
PPC800
PPC900
PPC2100 		BIOS date.

Example: "08/26/04"
BiosVersion VT=string VL=80 R ü APC510
APC511
APC620
APC810
APC820
APC910
APC2100
MP100/200
PP100/200
PP300/400
PP500
PPC300
PPC700
PPC800
PPC900
PPC2100 		BIOS version.

Example: "1.10"
BoardCenterTemperature | VT=i8 | R | APC820 | Temparature in the middle of the baseboard in degrees Celsius.
BoardEth2Temperature VT=i8 R APC810
PPC800 		Ambient temperature of ETH2 controller in degrees Celsius.
BoardInTemperature | VT=i8 | R | APC820 | Temperature of the baseboard at air intake in degrees Celsius.
BoardIoTemperature VT=i8 R APC620
APC810
MP100/200
PP100/200
PP300/400
PPC300
PPC700
PPC800 		Temperature in the baseboard I/O area in degrees Celsius (positive values only).

On the APC620 and PPC700, this temperature corresponds to the ambient temperature of the add-on drives.
BoardOutTemperature | VT=i8 | R | APC820 | Temperature of the baseboard at air output in degrees degrees Celsius.
BoardPowerTemperature VT=i8 R APC810
PPC800 		Ambient temperature of power supply controller in degrees Celsius.
BrOsVersion VT=string VL=80 R ü APC510
APC511
APC620 20
APC810
APC820
PP300/400 15
PP500
PPC300 19
PPC700 20
PPC800 		B&R specific operating system version.

Currently, only the version of the Windows CE image is supported.

Example: "V1.0"

CaseFan1Speed VT=u16 R APC620
APC810
APC820
PP300/400
PPC300
PPC700
PPC800 		Speed of the first housing fan in rpm.
CaseFan2Speed VT=u16 R APC620
APC810
APC820
PPC700
PPC800 		Speed of the second housing fan in rpm.
CaseFan3Speed VT=u16 R APC620
APC810
APC820
PPC700
PPC800 		Speed of the third housing fan in rpm.
CaseFan4Speed VT=u16 R APC620
APC810
PPC700
PPC800 		Speed of the fourth housing fan in rpm.
CmosProfile VT=u8 R APC810
APC820
PPC800 		CMOS profile switch setting.
CompatibilityId | VT=u16 | R | ü | All 18 28 | PC compatibility ID.
CpuBoardTemperature VT=i8 R APC620 12 13
APC810
APC820
PPC700 12 13
PPC800 		CPU board temperature in degrees Celsius (positive values only).
CpuBoardType VT=string VL=80 R ü APC510
APC511
APC620
APC810
APC820
APC910
APC2100
PP500
PPC700
PPC800
PPC900
PPC2100 		CPU board type.

Example: "E815", "E855", "X855" and "X945" on APC620 and PPC700 24 or "B945" on APC810, PPC800 and APC820.
CpuTemperature VT=i8 R APC620
APC810
APC820
APC910 30
APC2100 30
MP100/200
PP100/200
PP300/400
PPC300
PPC700
PPC800 21
PPC900 30
PPC2100 30 		Internal CPU temperature in degrees Celsius (positive values only).

APC620, PPC700, APC810, PPC800, APC820: The CPU temperature is read using WMI if ACPI (Advanced Configuration and Power Interface) is enabled in BIOS and WMI support is enabled with the WmiEnable variable. Temperature changes less than 4°C are not reported. If ACPI or WMI is disabled, the CPU temperature is read directly from the hardware monitor block (APC620, PPC700) or from the MTCX (APC810, PPC800, APC820).

PPC800: When using CCAX CPU board, only supported if WmiEnable is enabled.

APC910, PPC900, APC2100, PPC2100: Only supported if WmiEnable is enabled.

CpuVoltage VT=f32 R APC620
PPC700 		First CPU core voltage (VcoreA) in volts.
CpuVoltage2 VT=f32 R APC620 12 13
PPC700 12 13 		Second CPU core voltage (VcoreB) in volts.
DcVoltage VT=f32 R APC620
PPC700 		First DC voltage (+3.3 Vin) in volts.
DcVoltage2 VT=f32 R APC620 12 13
PPC700 12 13 		Second DC voltage (+5 Vin) in volts.
DeviceId | VT=u32 | R | ü | All 18 28 | PC device ID.
DeviceType VT=int32 R ü All Type of B&R PC:

0 = Unknown
4 = PP100/200
5 = MP100/200
6 = APC620
7 = PPC700
8 = PP300/400
9 = MP40
10 = PPC300
11 = MP50
12 = APC810
13 = PPC800
14 = APC820
15 = PP500
16 = APC510
17 = APC511
18 = APC910
19 = PPC900
20 = APC2100
21 = PPC2100
Drive1Temperature VT=i8 R APC620
APC810
PPC700
PPC800 		Temperature of slide-in drive 1 in degrees Celsius (positive values only).
Drive2Temperature VT=i8 R APC620
PPC700 25 31
APC810 		Temperature of slide-in drive 2 in degrees Celsius (positive values only).
Dvi1DisplayHResolution VT=u16 R APC510
APC511
APC620 7
APC810
APC820
APC910
APC2100
PPC700 7
PPC800
PP500
PPC900
PPC2100 		Horizontal resolution of the first DVI display in pixels.
Dvi1DisplayVResolution VT=u16 R APC510
APC511
APC620 7
APC810
APC820
APC910
APC2100
PPC700 7
PPC800
PP500
PPC900
PPC2100 		Vertical resolution of the first DVI display in pixels.
Dvi1FactoryData | VT=u8 VN=256 | R | obsolete - replaced by Dvi1Settings
Dvi1Settings VT=u8 VN=256 R APC510
APC511
APC620 7
APC810
APC820
APC910
APC2100
PPC700 7
PPC800
PP500
PPC900
PPC2100 		Settings for the first DVI display.

For B&R-internal use only!
Dvi2DisplayHResolution VT=u16 R APC620 7
APC810 		Horizontal resolution of the second DVI display in pixels.
Dvi2DisplayVResolution VT=u16 R APC620 7
APC810 		Vertical resolution of the second DVI display in pixels.
Dvi2FactoryData | VT=u8 VN=256 | R | obsolete - replaced by Dvi2Settings
Dvi2Settings VT=u8 VN=256 R APC620 7
APC810 		Settings for the second DVI display.

For B&R-internal use only!
Enable1State VT=u8 17 R MP40/50 Status of the first enable button.

0 = Button not pressed
1 = Button is in the panic position

Only use this variable to check whether the button is working.

Enable2State VT=u8 17 R MP40/50 Status of the second enable button.

0 = Button not pressed
1 = Button is in the panic position

Only use this variable to check whether the button is working.

Eth2Temperature | VT=i8 | R | APC810 | Temperature of ETH2 controller in degrees Celsius.
FactoryData | VT=u8 VN=256 | R | ü | obsolete - replaced by FactorySettings
FactorySettings VT=u8 VN=256 1 R ü All 10 18 28 PC factory settings.

For B&R-internal use only!
FactorySettingsVersion VT=string VL=8 11 R ü All 12 18 28 Version of factory settings

Example: "1.02" 11
FactoryVersion | VT=string VL=8 | R | ü | obsolete - replaced by FactorySettingsVersion
FanOnHours VT=u16 R APC620
APC810
APC820
PP300/400
PPC300
PPC700
PPC800 		Number of operating hours for the PC's fans.
FlashSize | VT=u32 | R | MP40/50 18 | Size of the flash memory of a MP40/50 in bytes.
Fpga1Comment VT=string VL=33 R ü MP100/200 Comment for the FPGA1 firmware.

By default, the comment contains the date and version of the firmware.
Fpga1DeviceId VT=string VL=6 R ü MP100/200 10 Device ID of the onboard FPGA1.

Example: "6504" 2
Fpga1Size | VT=u32 | R | ü | MP100/200 | Size of the FPGA1 firmware in bytes.
Fpga1Status | VT=u8 | R | ü | MP100/200 | Boot status of the FPGA1 firmware.
Fpga1XmlHeader VT=string VL=256 R ü MP100/200 XML header for the FPGA1 firmware.

The XML header contains information about the firmware such as device ID, version, size, etc.
FpgaComment VT=string VL=33 R ü MP100/200
PP100/200 4 		Comment for the FPGA firmware.

By default, the comment contains the date and version of the firmware.

Example: "PowerPanel 10.03.2003 V10"
FpgaDeviceId VT=string VL=6 R ü MP100/200 10
PP100/200 10 		Device ID of the onboard FPGA1.

Example: "5718" (or "5751" with BIOS version 1.04 or lower) on the PP100/200 2)
FpgaSize VT=u32 R ü MP100/200
PP100/200 4 		Size of the FPGA firmware in bytes.
FpgaStatus VT=u8 R ü MP100/200
PP100/200 3 		Boot status of the FPGA firmware.
FpgaXmlHeader VT=string VL=256 R ü MP100/200
PP100/200 4 		XML header for the FPGA firmware.

The XML header contains information about the firmware such as device ID, version, size, etc.
HandwheelPresent VT=boolean R ü MP40/50 "Electronic handwheel installed" indicator.

1 indicates that a handwheel is installed.

HandwheelValue VT=u32 R/W MP40/50
PP500 32 		Counter value of the electronic handwheel.

Range of values: 0 to 65535
HardwareRevision VT=string VL=5 R ü APC510
APC511
APC620
APC810
APC820
APC910
APC2100
MP40/50 18
PP300/400
PP500 28
PPC300
PPC700
PPC800
PPC900
PPC2100 		Hardware revision of the PC.
IfSlotTemperature VT=i8 R APC820
PPC800 		Temperature of the optional module in the IF slot in degrees Celsius.
In voltage VT=f32 R APC510
APC511
APC910
PP500 27
PPC900 		Input voltage (Vin) in volts.
JoystickCalibrate VT=boolean R/W MP40/50 Calibration mode of the joystick.

Writing with 1 begins the calibration and 0 ends it.

JoystickCalibrated VT=boolean R MP40/50 "Joystick calibrated" identifier.

1 indicates that all joystick axes have been calibrated. When 0, the joystick must be calibrated (see also JoystickCalibrate).

JoystickPos VT=u32 VN=3 R MP40/50 Calibrated values of the joystick position: [0] = X axis, [1] = Y axis, [2] = Z axis.

Range of values: Is set during calibration (see also JoystickPosRange).

The joystick must be calibrated (see also JoystickCalibrated).

JoystickPosRange VT=u32 VN=3 R/W MP40/50 Specifies the range for the calibrated value = maximum (+/-) per axis direction: [0] = X axis, [1] = Y axis, [2] = Z axis.

Range of values: 0 to 1023 per axis

On an MP40/50, the value 15 is recommended; this is preset by default with JoystickCalibrate.

JoystickPosRaw VT=u32 VN=3 R MP40/50 Raw values of the joystick position: [0] = X axis, [1] = Y axis, [2] = Z axis.

Range of values: 0 to 1023 per axis

JoystickPosRawCenter VT=u32 VN=3 R/W MP40/50 Raw values of the joystick position for the calibration: [0] = X axis, [1] = Y axis, [2] = Z axis.

Range of values: 0 to 1023 per axis

The values are preset with the current raw values when the calibration is started with JoystickCalibrate.

JoystickPosRawMax VT=u32 VN=3 R/W MP40/50 Maximum raw values of the joystick position for the calibration: [0] = X axis, [1] = Y axis, [2] = Z axis.

Range of values: 0 to 1023 per axis

The values are initialized with the current raw values when the calibration is started with JoystickCalibrate, and maintained throughout the calibration.

JoystickPosRawMin VT=u32 VN=3 R/W MP40/50 Minimum raw values of the joystick position for the calibration: [0] = X axis, [1] = Y axis, [2] = Z axis.

Range of values: 0 to 1023 per axis

The values are initialized with the current raw values when the calibration is started with JoystickCalibrate, and maintained throughout the calibration.

JoystickPresent VT=boolean R ü MP40/50 "Joystick installed" identifier.

1 indicates that a joystick is installed.

KeyCfgBuildDate VT=string VL=11 R 14 All 10 Creation date for the key configuration.

Example: "2004-08-12"
KeyCfgState VT=boolean R

14

 All Key configuration status: 0 = Invalid, 1 = Valid
KeyCfgUserInfo | VT=string VL=89 | R | 14 | All 10 | User information for the key configuration.
KeyCfgVersion VT=string VL=6 R 14 All 10 Version of the key configuration.

Example: "01.00"
KeyLayer | VT=u8 | R/W | All | Number of active key layers: 0 to 3
KeyLayerMode VT=u8 R All Key level operating mode:

0 = Shift
1 = Toggle
2 = One-shot
LinkFpgaVersion VT=string VL=16 R ü APC510
APC511
APC620 5 7
APC810
PPC700 5 7 22 25 		Version of the AP Link FPGA firmware.

Example: "0.01"
LinkPresent VT=boolean R ü APC620 5 7
APC810
PPC700 5 7 22 		Indicates whether an AP link is present:

0 = Not provided
1 = Provided
LinkType VT=string VL=5 R ü APC620 5 7
APC810
PPC700 5 7 22 25 		Type of AP Link.

Example: "SDLT" = SDL transmitter
LockTime VT=u32 R/W APC510
APC511
APC620 6
APC810
APC820
APC910
APC2100
PP500
PPC700 6
PPC800
PPC900
PPC2100 		Panel lock time in ms: 0 (no locking) to 65535
ModelNumber | VT=string VL=41 | R | ü | All 8 10 18 28 | Model number of the PC.
ModeNode VT=u8 R APC511
MP100/200
PP100/200
PP300/400
PP500 26 		Mode/node switch setting.
MtcxBootInfo VT=i32 R ü APC510
APC511
APC910
APC2100
PP500 27
PPC900
PPC2100 		MTCX Firmware Bootinfo:

0 = Booted from low area
1 = Booted from high area

MtcxFpgaVersion VT=string VL=16 R ü APC620
APC810
APC820
PP300/400
PPC300
PPC700
PPC800 		Version of the MTCX (Maintenance Controller Extended) FPGA firmware.

Example: "1.04"
MtcxPx32Version VT=string VL=16 R ü APC620
APC810
APC820
PP300/400
PPC300
PPC700
PPC800 		Version of the MTCX (Maintenance Controller Extended) PX32 firmware.

Example: "1.19"
MtcxVersion VT=string VL=16 R ü APC510
APC511
APC910
APC2100
PP500 26
PPC900
PPC2100 		Version of the MTCX (Maintenance Controller Extended) firmware.

Example: "00.20"
MxcVersion VT=string VL=16 R ü MP100/200
PP100/200 		Version of the MXC (Matrix Controller) firmware.

Example: "02.00"
OptimizedId VT=u8 R ü APC620
PPC700 		Optimized ID.

The optimized ID is set with the DIP switch on the baseboard and determines the BIOS profile to be used.

Bits 0 - 5 define the BIOS profile; bits 6 and 7 are reserved.
ParentCompatibilityId VT=u16 R ü APC510
APC511
APC620 23
APC810
APC820
APC910
APC2100
PP300/400
PP500 28
PPC300
PPC700 23
PPC800
PPC900
PPC2100 		PC parent compatibility ID (FFFFh = no parent).

Specifies the compatibility ID of the PC from which the current device was derived (e.g. for a custom variant of a standard device).
ParentDeviceId VT=u32 R ü APC510
APC511
APC620 23
APC810
APC820
APC910
APC2100
PP300/400
PP500 28
PPC300
PPC700 23
PPC800
PPC900
PPC2100 		PC parent device ID (FFFFFFFFh = no parent).

Specifies the device ID of the PC from which the current device was derived (e.g. for a custom variant of a standard device).
PotentiometerCalibrate VT=boolean R/W MP40/50 Calibration mode of the override potentiometer.

Writing with 1 begins the calibration and 0 ends it.

PotentiometerCalibrated VT=boolean R MP40/50 "Override potentiometer calibrated" identifier.

1 indicates that the override potentiometer is calibrated. When 0, the potentiometer must be calibrated (see also PotentiometerCalibrate).

PotentiometerPresent VT=boolean R ü MP40/50 "Override potentiometer installed" identifier.

1 indicates that an override potentiometer is installed.

PotentiometerValue VT=u32 R MP40/50 Calibrated value of the override potentiometer.

Range of values: Is set during calibration (see also PotentiometerValueRange).

The override potentiometer must be calibrated (see also PotentiometerCalibrated).

PotentiometerValueRange VT=u32 R/W MP40/50 Specifies the range for the calibrated value = maximum value.

Range of values: 0 to 127

On a MP40/50 the value 127 is recommended; this is preset by default with PotentiometerCalibrate.

PotentiometerValueRaw VT=u32 R MP40/50 Raw value of the override potentiometer.

Range of values: 0 to 1023

PotentiometerValueRawMax VT=u32 R/W MP40/50 Maximum raw value of the override potentiometer for the calibration:

Range of values: 0 to 1023

The value is initialized with the current raw value when the calibration is started with PotentiometerCalibrate, and maintained throughout the calibration.

PotentiometerValueRawMin VT=u32 R/W MP40/50 Minimum raw value of the override potentiometer for calibration:

Range of values: 0 to 1023

The value is initialized with the current raw value when the calibration is started with PotentiometerCalibrate, and maintained throughout the calibration.

PowerOnCycles VT=u16 R ü APC510
APC511
APC620
APC810
APC820
APC910
APC2100
PP300/400
PP500 26
PPC300
PPC700
PPC800
PPC900
PPC2100 		Number of power-ons for the PC.
PowerOnHours VT=u16 R APC510
APC511
APC620
APC810
APC820
APC910
APC2100
MP40/50 17
PP300/400
PP500 27
PPC300
PPC700
PPC800
PPC900
PPC2100 		Number of operating hours for the PC.
PowerTemperature VT=i8 R APC620
APC810
APC820
PPC700
PPC800 		Power supply temperature in degrees Celsius (positive values only).
SerialNumber VT=string VL=12 R ü APC510
APC511
APC620
APC810
APC820
APC910
APC2100
MP40/50 18
PP300/400
PP500 28
PPC300
PPC700
PPC800
PPC900
PPC2100 		Serial number of the PC.
SmcVersion VT=string VL=16 R ü MP100/200
PP100/200 		Version of the SMC (System Management Controller) firmware.

Example: "d.4"
StandbyVoltage VT=f32 R APC620
PPC700 		Standby voltage (5 Vsb) in volts.
Sys1Temperature VT=i8 R APC510
APC511
APC910
APC2100
PP500
PPC900
PPC2100 		Temperature of Sensor 1 for the system unit in degrees Celsius. 29
Sys2Temperature VT=i8 R APC510
APC511
APC910
APC2100
PP500
PPC900
PPC2100 		Temperature of Sensor 2 for the system unit in degrees Celsius. 29
Sys3Temperature VT=i8 R APC510
APC511
APC910
APC2100
PP500
PPC900
PPC2100 		Temperature of Sensor 3 for the system unit in degrees Celsius. 29
Sys4Temperature VT=i8 R APC510
APC511
APC910
APC2100
PP500
PPC900
PPC2100 		Temperature of Sensor 4 for the system unit in degrees Celsius. 29
UserLed VT=boolean R/W MP100/200
PP100/200
PP300/400
PPC300 		Status of the User LED: 0 = Off, 1 = On

On a B&R Mobile Panel, the User LED cannot be seen from outside.

On a PPC300 or PP300/400, the User LED is operated as Power LED by default, until the first time UserLed is written. A switched on user LED is lit yellow, whereas a switched off user LED is lit green.

The LED status setting only takes effect until the next time the system is started. After the system is started, the User LED is turned off.
UserlogoComment VT=string VL=33 R ü MP100/200
PP100/200 4
PP300/400
PPC300 		User logo comment.

The comment generally contains the filename, date, and time of the bitmap being used.

Example: "pp640.bmp 2003/08/21 15:03:52"
UserlogoSize VT=u32 R ü MP100/200
PP100/200 4
PP300/400
PPC300 		Size of the user logo in bytes.

UserlogoVgaMode

 VT=u16 R ü obsolete - replaced by UserlogoVesaMode
UserlogoVesaMode VT=u16 R ü MP100/200
PP100/200 4
PP300/400
PPC300 		VESA mode used by the user logo.

0121h = 320 x 240 pixels (QVGA)
0101h = 640 x 480 pixels (VGA)
0103h = 800 x 600 pixels (SVGA)
0105h = 1024 x 768 pixels (XGA)

Only on the PPC300 and PP300/400:

0125h = 1152 x 864 pixels (XGA+)
0107h = 1280 x 1024 pixels (SXGA)
0131h = 1600 x 1200 pixels (UXGA)
UserSerialId VT=u32 R/W 9 All 10 18 User serial ID

The user serial ID allows you to give the B&R device your own identification number. The user serial ID is permanently saved on the B&R device.

With some devices, the PC must be restarted in order for a new user serial ID to take effect.

On the PP100/200 and MP100/200, the user serial ID can only be configured from BIOS setup.
VendorId VT=u32 R ü APC510
APC511
APC620
APC810
APC820
APC910
APC2100
MP40/50 18
PP300/400
PP500 28
PPC300
PPC700
PPC800
PPC900
PPC2100 		Manufacturer ID of the PC (B&R = 0).
WatchdogMaxTime VT=u32 R/W APC510
APC511
APC620
APC810
APC820
APC910
APC2100
PP300/400
PP500
PPC300
PPC700
PPC800
PPC900
PPC2100 		Maximum watchdog time in ms.

The watchdog is disabled once more when writing 0 to this variable.
WatchdogMinTime VT=u32 R/W APC510
APC511
APC620
APC810
APC820
APC910
APC2100
PP300/400
PP500
PPC300
PPC700
PPC800
PPC900
PPC2100 		Minimum watchdog time in ms.

The watchdog is disabled once more when writing 0 to this variable.
WatchdogToggle VT=boolean R/W APC510
APC511
APC620
APC810
APC820
APC910
APC2100
PP300/400
PP500
PPC300
PPC700
PPC800
PPC900
PPC2100 		Variable for acknowledging the watchdog.

This variable always returns the value 0.

The watchdog is acknowledged when this variable is written to. The written value is not evaluated.

Before this variable is "removed" with PviUnlink or PviDelete, the watchdog must be disabled by writing 0 to the WatchdogMinTime or WatchdogMaxTime variable.
WmiEnable VT=boolean R/W

APC620
APC810
APC820
APC910
APC2100
PPC700
PPC800
PPC900
PPC2100 		Specifies whether WMI is used:

0 = WMI not used
1 = WMI used

WMI (Windows Management Instrumentation) is the Microsoft implementation of Web-Based Enterprise Management (WBEM), which builds upon the Common Information Model (CIM), a computer industry standard for defining device and application properties that system administrators and management programs can use to control devices and applications from various manufacturers or sources using the same method.

WMI is not supported in Windows CE.

With Windows 7 and higher, administrator rights are required: PVI Manager must be run as a service or with administrator rights!

If WMI is enabled, ADI uses WMI functions whenever possible, for example to read the CPU temperature with the CpuTemperature variable.
WriteProtect VT=boolean R MP100/200 10
PP100/200 10 		Setting for the write-protect switch: 0 = Off, 1 = On
1 | Only 240 valid bytes are returned with ADI driver version 1.42 or lower on the APC620 and PPC700. The last 16 bytes are returned with 0s.
2 | An empty string is returned if no aPCI module or FPGA is present.
3 | Requires BIOS version 1.04 or higher on the PP100/200.
4 | Requires BIOS version 0.70 or higher on the PP100/200.
5 | Requires MTCX FPGA version 1.12 or higher on the APC620 and PPC700.
6 | Requires MTCX PX32 version 1.30 or higher on the APC620 and PPC700.
7 | Requires MTCX PX32 version 1.50 or higher on the APC620 and PPC700.
8 | Requires factory settings version 6 or higher on the PP100/200 and MP100/200.
9 | The user serial ID can only be read on the PP100/200 and MP100/200.
10 | Requires ADI driver version 2.00 or higher on the PP100/200 and MP100/200.
11 | VL=4 and version returns e.g. "6" on the PP100/200 and MP100/200.
12 | Requires ADI driver version 1.60 or higher on the APC620 and PPC700.
13 | Only available with the X855GME CPU board on APC720 and PPC700.
14 | The value can only be modified by updating the key configuration.
15 | Requires ADI driver version 1.20 or higher on the PP300/400.
16 | Requires ADI driver version 1.70, MTCX PX32 version 1.63 or higher, MTCX FPGA version 1.19 or higher, and a suitable hardware revision on the APC620 and PPC700.
17 | Requires ADI driver version 1.10 or higher on the MP40/50.
18 | Requires ADI driver version 1.20 or higher on the MP40/50.
19 | Requires ADI driver version 1.10 or higher on the PPC300.
20 | Requires ADI driver version 1.80 or higher on the APC620 and PPC700.
21 | To read the CPU temperature via WMI on a PPC800 with a CCAX CPU board (NM10 chipset) you need BIOS version 1.10 or higher.
22 | An AP link is not supported on PPC700 devices - the variables are also supported on PPC700 devices to ensure compatibility with old versions of the ADI line.
23 | Requires ADI driver version 1.90 or higher and MTCX PX32 version 1.67 or higher on APC620 and PPC700.
24 | ADI driver version 1.90 or lower on the APC620 and PPC700 returns "815E", "855GME" or "X855GME".
25 | No longer supported on APC620 and PPC700 with ADI driver version 2.00 or higher.
26 | Requires ADI driver version 1.1 or higher on the PP500.
27 | Requires ADI driver version 1.3 or higher on the PP500.
28 | Requires ADI driver version 1.3 or higher on the PP500. Older versions return data for the CPU board instead of the system unit.
29 | Optional temperature sensor: Depending on the system unit, a temperature may not be supported
30 | The temperature is only provided if WmiEnable is set to 1.
31 | A second slide-in is not supported on PPC700 devices - the variables are also supported on PPC700 devices to ensure compatibility with old versions of the ADI line.
32 | Requires ADI driver version 2.2 or higher on the PP500.

Key configuration

The key configuration is created with the B&R Key Editor and contains the key code assignments for the keys of the B&R device, the operating mode of the key levels, the definitions of the key switches and special LEDs (key level, scroll/lock/shift etc.) and the panel lock time.

When creating the key configuration, a version (see the KeyCfgVersion variable) and user info (see the KeyCfgUserInfo variable) can be specified. The creation date that can be read with the KeyCfgBuildDate variable is set automatically by the B&R Key Editor when the key configuration is generated.

Key layers

The keys on a B&R device can be operated on four different layers, which means each key can send up to four different key codes. The layer can be switched with special layer keys. These key layers are configured with the B&R Key Editor in the key configuration.

The key layers affect the Keys and KeyMatrix variables on all panel devices.

Key layer operating mode

A key layer is only active in "Shift" mode as long as the corresponding layer key is pressed. The layer key must be pressed together with the desired key (corresponds to the function of a SHIFT key).

In "Toggle" mode, a key layer can be turned on or off using the layer key defined. That means each time this key is pressed, the level is toggled between the current level and the configured level.

In "One-shot" mode, pressing the level key only has an effect on the key pressed immediately afterwards. Once the action is complete, it switches back to the current level.

Panel locking time

The panel locking time specifies how long input from keys or touch screens on other connected B&R panels is locked while input is being carried out on a particular panel. The panel lock time is usually set in the key configuration created in the B&R Key Editor.

The panel locking time is reset to the value configured in the key configuration when the system is restarted or when downloading a new key configuration.

Boot status of the FPGA firmware

These states can occur:

0 = Firmware not found
1 = Invalid firmware size (data destroyed)
2 = Module not found
3 = Cannot start boot mode
4 = Boot failed
5 = Boot OK

PP100/200 BIOS version 1.04 and higher:

6 = Old firmware (old version)
7 = Incorrect firmware (incorrect device ID or variant)

PP100/200 BIOS version 1.05 and higher:

8 = Boot disabled (in BIOS setup)

Only on PP300/400:

9 = Boot active
10 = Invalid firmware checksum

User logo

A user log can be displayed instead of the B&R logo when starting BIOS on the PPC300, PP100/200 PP300/400, and the MP100/200. The user log can be created from a Windows bitmap file using the B&R Windows USERLOGO.exe application and programmed onto the device using the ADI Control Center or the device-specific DOS Boot Logo Disk.

DVI

DVI data is intended for internal use at B&R.

The DVI channels are mapped as follows: The first DVI channel is used for the monitor / panel port. The second DVI channel is used for the optional Display / AP Link.

Watchdog

The watchdog can be used for the life sign monitoring of applications.

After setting the minimum and maximum time (WatchdogMinTime and WatchdogMaxTime variables), the watchdog is inactive and must be started by writing to the WatchdogToggle variable. After that happens, the WatchdogToggle variable must be written to periodically within the specified time to acknowledge watchdog.

Specify a long maximum time to keep the load needed to acknowledge the watchdog on the CPU to a minimum.

If the watchdog is acknowledged by writing to the WatchdogToggle variable before the specified minimum time has elapsed, or the maximum time is allowed to run out, and the WatchdogToggle variables hasn't been written to, the PC is reset.

Stop an active watchdog during a download (e.g. key configuration). Otherwise, a PC reset may occur if the specified watchdog time is shorter than the time required for longer flash access.

The watchdog is reactivated by writing the minimum and maximum times again. If the minimum and maximum times are set to 0, the watchdog can no longer be started, even with the WatchdogToggle variable.

Windows requires the system to be shut down properly. This doesn't happen if a reset occurs. This can lead to data loss which can leave the system or application "paralyzed".

Calibrating the joystick

Start the calibration by writing 1 to JoystickCalibrate. To calibrate, move the joystick from the center position to the extreme positions (e.g. by rotating the joystick in a full circle) and read the associated data using JoystickPosRaw. The raw values for the minimum and maximum position are then automatically saved as JoystickPosRawMin, JoystickPosRawMax and JoystickPosRawCenter. Using JoystickPosRange you can set the value range of the joystick.

Note: JoystickPosRawMin, JoystickPosRawMax, JoystickPosRawCenter and JoystickPosRange are set automatically during calibration and maintained, and therefore do not need to be set manually.

End the calibration by writing 0 to JoystickCalibrate.

When the calibration is complete, the joystick's calibrated values can be read using JoystickPos.

The calibration is permanently saved on the device, and is applied after the system is restarted (requires ADI driver version 1.21 or higher on MP40/50).

Calibrating the override potentiometer

Start the calibration by writing 1 to PotentiometerCalibrate. To calibrate the potentiometer, turn it to the minimum and maximum position and read the corresponding raw values using PotentiometerValueRaw. The raw values for the minimum and maximum position are then maintained in PotentiometerValueRawMin and PotentiometerValueRawMax. Using PotentiometerValueRange you can set the value range of the potentiometer.

Note: PotentiometerValueRawMin, PotentiometerValueRawMax and PotentiometerValueRange are set automatically during calibration and maintained, and therefore do not need to be set manually.

End the calibration by writing 0 to PotentiometerCalibrate.

When the calibration is complete, the potentiometer's calibrated values can be read using PotentiometerValue.

The calibration is permanently saved on the device, and is applied after the system is restarted (requires ADI driver version 1.21 or higher on MP40/50).

<< Previous Topic
ADI variable objects

Start Page

Next Topic >>
Variable names for panel devices


Variable names for panel devices

The ADI line supports the following variables for a panel device:

Note: The "C" column indicates whether the variable returns a constant value.

Variable name | Data format | I/O | C | Devices | Description
Address VT=u8 R ü APC510
APC511
APC620
APC810
APC820
APC910
APC2100
PP500
PPC700
PPC800
PPC900
PPC2100 		Panel address: 0 to 15
BacklightOnCycles VT=u16 R APC510
APC511
APC620
APC810
APC820
APC910
APC2100
PP500
PPC300
PPC700 1
PPC800 1
PPC900
PPC2100 		Number of backlight power-ons for the display unit.
BacklightOnHours VT=u16 R APC510
APC511
APC620
APC810
APC820
APC910
APC2100
PP500
PPC300
PPC700 1
PPC800 1
PPC900
PPC2100 		Number of backlight operating hours for the display unit.
BrightnessDef VT=u8 R ü MP100/200
PP100/200
PP300/400 		Default value for the display brightness (raw value).
BrightnessMax VT=u8 R ü MP40/50
MP100/200
PP100/200
PP300/400 		Maximum value for the display brightness (raw value).
BrightnessMin VT=u8 R ü MP40/50
MP100/200
PP100/200
PP300/400 		Minimum value for the display brightness (raw value).
CompatibilityId VT=u16 R APC510
APC511
APC620
APC810
APC820
APC910
APC2100
PP500 19
PPC300
PPC700 1
PPC800 1
PPC900
PPC2100 		Panel compatibility ID.
ContrastDef VT=u8 R ü MP100/200
PP100/200
PP300/400 		Default value for the display contrast (raw value).
ContrastMax VT=u8 R ü MP40/50
MP100/200
PP100/200
PP300/400 		Maximum value for the display contrast (raw value).
ContrastMin VT=u8 R ü MP40/50
MP100/200
PP100/200
PP300/400 		Minimum value for the display contrast (raw value).
Detected VT=boolean R ü APC510
APC511
APC620
APC810
APC820
APC910
APC2100
PP300/400
PP500
PPC300
PPC700
PPC800
PPC900
PPC2100 		Code for whether the panel has been detected:

0 = Not detected
1 = Detected
DeviceId VT=u32 R 2 APC510
APC511
APC620
APC810
APC820
APC910
APC2100
PP500 19
PPC300
PPC700 1
PPC800 1
PPC900
PPC2100 		Panel device ID.
DisplayBrightness | VT=u8 | R/W | All 3 | Brightness of the display (backlighting) in percent: 0 to 100
DisplayContrast VT=u8 R/W MP40/50
MP100/200 3
PP100/200 3
PP300/400 		Contrast of the display in percent: 0 to 100
DisplayDefaultBrightness | VT=u8 | R/W | All 3 12 13 | Default brightness value of the display (backlighting) in percent: 0 to 100
DisplayDefaultContrast VT=u8 R/W MP40/50
MP100/200 3
PP100/200 3
PP300/400 12 13 		Default contrast value of the display in percent: 0 to 100
DisplayEqualizer VT=u8 R/W APC510
APC511
APC620 4
APC810
APC820
APC910
APC2100
PP500 19
PPC700 1 4
PPC800 1
PPC900 1
PPC2100 1 		Equalizer setting of the display: 0 (strong) to 15 (weak) 18

Automatic mode is automatically activated when writing to a variable (see the DisplayEqualizerAuto variable).
DisplayEqualizerAuto VT=boolean R/W APC510
APC511
APC620 4
APC810
APC820
APC910
APC2100
PP500 19
PPC700 1 4
PPC800 1
PPC900 1
PPC2100 1 		Automatic mode of the equalizer setting of the display. 18

If 0 (off), a user-specific equalizer value is used (see the DisplayEqualizer variable).
If 1 (on), the predefined equalizer value is used (see the DisplayEqualizerAutoValue variable).
DisplayEqualizerAutoValue VT=u8 R APC510
APC511
APC620 4 18
APC810
APC820
APC910
APC2100
PP500 19
PPC700 1 4 18
PPC800 1 18
PPC900 1
PPC2100 1 		Automatic value of the equalizer setting of the display. 0 (strong) to 15 (weak) 18
DisplayHResolution | VT=u16 | R | 2 | All | Horizontal resolution of the display in pixels, e.g. 640 for VGA or 1024 for XGA.
DisplayId VT=u8 R ü APC510
APC511
MP100/200
PP100/200
PP500 20 		Display ID.
DisplayVResolution | VT=u16 | R | 2 | All | Vertical resolution of the display in pixels, e.g. 480 for VGA or 768 for XGA.
FactoryData | VT=u8 VN=256 | R | 2 | obsolete - replaced by FactorySettings
FactorySettings VT=u8 VN=256 R 2 APC510
APC511
APC620
APC810
APC820
APC910
APC2100
PP500 19
PPC300
PPC700 1
PPC800 1
PPC900
PPC2100 		Panel factory settings.

For B&R-internal use only!
FanSpeed VT=u16 R APC510
APC511
APC620
APC810
APC820
APC910
APC2100
PP500 19
PPC300
PPC700 1
PPC800 1
PPC900 1
PPC2100 1 		Fan speed in rpm.
HardwareRevision VT=string VL=5 R 2 APC510
APC511
APC620
APC810
APC820
APC910
APC2100
PP500 19
PPC300
PPC700 1
PPC800 1
PPC900
PPC2100 		Hardware revision of the panel.
KeyCount | VT=u8 | R | 2 | All | Number of maximum supported keys: 0 to 128
KeyEnable | VT=boolean | R/W | All 7 | Key locking status: 0 = Locked, 1 = Unlocked
KeyMatrix VT=u8 VN=16 R All State of the keys in the current key layer in "packed" form:

Byte 0, Bit 0 = 1. Key
Byte 0, Bit 1 = 2. Key
...
Byte 1, Bit 0 = 9. Key
...

1 bit per key:

0 = Not pressed
1 = Pressed
Keys VT=boolean VN=128 R All State of the keys in the current key layer.

1 element per key: 0 = Not pressed, 1 = Pressed
KeySwitches VT=boolean VN=8 R All 8 9 11 15 State of the key switches.

1 element per contact: 0 = Open, 1 = Closed
LedCount | VT=u8 | R | 2 | All | Number of maximum supported LEDs: 0 to 128
LedLayer | VT=u8 | R/W | All | Number of current LED layers: 0 to 3
LedMatrix VT=u8 VN=32 R/W 16 All State of the LEDs in the current LED layer in "packed" form:

Byte 0, Bit 0+1 = 1. LED
Byte 0, Bit 2+3 = 2. LED
...
Byte 1, Bit 0+1 = 5. LED
...

2 bits per LED:

00 = Off
01 = Normal blinking
10 = Fast blinking 14
11 = On
LEDs

 VT=u8 VN=128

R/W 16

All 7

 State of the LEDs in the current LED layer.

1 element per LED:

0 = Off
1 = Normal blinking
2 = Fast blinking 14
3 = On
Linked VT=boolean R APC510
APC511
APC620
APC810
APC820
APC910
APC2100
PP300/400
PP500
PPC300
PPC700
PPC800
PPC900
PPC2100 		Code for whether the panel is connected:

0 = Not connected
1 = Connected
LinkFpgaVersion VT=string VL=16 R 2 APC510
APC511
APC620
APC810
APC820
APC910
APC2100
PP500 19
PPC700 1
PPC800 1
PPC900 1
PPC2100 1 		Version of the AP Link FPGA firmware.

Example: "0.03"
LinkType VT=string VL=5 R 2 APC510
APC511
APC620
APC810
APC820
APC910
APC2100
PP500 19
PPC700 1
PPC800 1
PPC900 1
PPC2100 1 		Type of AP Link insert:

"SDLR" = AP900 SDL receiver / transceiver)
"AP8H" = AP800 SDL receiver 10
"SDL8" = AP800/AP830 SDL receiver 22
"SDL9" = AP9x3/AP9xD SDL receiver 23
"SR3D" = AP9x3/AP9xD SDL3 receiver 24
"SR3E" = AP900 SDL3 receiver 24
Locked VT=boolean R/W APC510
APC511
APC620 5
APC810
APC820
APC910
APC2100
PP300/400 12
PP500
PPC300
PPC700 5
PPC800
PPC900
PPC2100 		Code for whether the panel is locked:

0 = Not locked
1 = Locked - input from keys and touch screen 17 not processed
ModelNumber VT=string VL=41 R 2 APC510
APC511
APC620
APC810
APC820
APC910
APC2100
PP500 19
PPC300
PPC700 1
PPC800 1
PPC900
PPC2100 		Model number of the panel.
PowerOnCycles VT=u16 R ü PPC900 21
PPC2100 21 		Number of power-ons of the panel
PowerOnHours VT=u16 R PPC900 21
PPC2100 21 		Number of operating hours of the panel
SerialNumber VT=string VL=12 R 2 APC510
APC511
APC620
APC810
APC820
APC910
APC2100
PP500 19
PPC300
PPC700 1
PPC800 1
PPC900
PPC2100 		Panel serial number.
Temperature VT=i8 R APC510
APC511
APC620
APC810
APC820
APC910
APC2100
PP500 19
PPC300
PPC700 1
PPC800 1
PPC900
PPC2100 		Temperature of the panel (ambient temperature of the display) in degrees Celsius (positive values only).
VendorId VT=u32 R 2 APC510
APC511
APC620
APC810
APC820
APC910
APC2100
PP500 19
PPC300
PPC700 1
PPC800 1
PPC900
PPC2100 		Panel vendor ID.
1 | Not available for Panel 15 on PPCs.
2 | The value can be changed on the APC620, PPC700, APC810, PPC800 and APC820 when connecting another Automation Panel.
3 | Requires BIOS version 1.00 or higher on the PP100/200.
4 | Requires MTCX PX32 version 1.54 or higher on the APC620 and PPC700.
5 | Requires MTCX PX32 version 1.30 or higher on the APC620 and PPC700.
6 | Requires MTCX PX32 version 1.22 or higher on the APC620 and PPC700 when accessing individual LEDs (array elements).
7 | Requires MTCX PX32 version 1.21 or higher on the APC620 and PPC700.
8 | Requires ADI driver version 1.11 or higher on the APC620 and PPC700.
9 | Requires MTCX PX32 version 1.59 or higher on the APC620 and PPC700.
10 | AP Link type "AP8H" requires ADI driver version 1.50 or higher on the APC620 and PPC700.
11 | Requires ADI driver version 2.00 or higher on the PP100/200 and MP100/200.
12 | Requires MTCX PX32 version 1.11 or higher on the PP300/400.
13 | Requires ADI driver version 1.20 or higher on the PP300/400.
14 | MP40/50 devices do not support a fast blink. With ADI driver version 1.21 or higher on the MP40/50, fast blinking is handled like slow blinking.
15 | Requires ADI driver version 1.10 or higher on the MP40/50. With older versions, the key switch status is returned inverted.
16 | Requires ADI driver version 1.20 or higher on the MP40/50 when writing the LED matrix.
17 | On PP300/400 and PPC300 devices, the touch screen cannot be locked.
18 | Requires AP Link FPGA version 1.04 or higher on the AP900.
19 | Not available for Panel 0 on the PP500.
20 | Requires ADI driver version 1.4 or higher on the PP500.
21 | Only available for Panel 15.
22 | "SDL8" is only supported on APC810/PPC800 devices with ADI driver version 1.70 or higher, on APC910/PPC900 devices with ADI driver version 0.6 or higher and on APC2100 devices.
23 | "SDL9" is only supported on APC910/PPC900 devices with ADI driver version 2.2 or higher and on APC2100 devices.
24 | "SR3D" and "SR3E" are only supported on APC2100/PPC2100 devices with ADI driver version 3.1 or higher.

Display IDs

BIOS uses this ID to initialize the display with the appropriate display parameters.

Possible values on APC510, APC511:

FFh = no display

Possible values on PP100/200, MP100/200 devices:

00h = Display parameters not read from the factory settings
10h = Passive display (STN)
11h = LCD B/W QVGA
12h = LCD COL QVGA
20h = Active QVGA display (TFT)
30h = Active VGA display (TFT)
40h = Active SVGA display (TFT)
50h = Active XGA display (TFT)

Possible values on PP500:

00h = 640 x 480, 5.7"
01h = 800 x 600, 8.4"
02h = 800 x 600, 12"
03h = 640 x 480, 10.4"
04h = 800 x 480, 7"
07h = 1024 x 768, 15"

Brightness

The DisplayBrightness setting is only applied until the next time the system is started (except on MP40/50, see below). In order for the brightness to be retained after the next system start you must set the default value using the DisplayDefaultBrightness variable.

The default value for the brightness is automatically set by the ADI driver when the system is started.

The first time the system is started, a fixed value (e.g. 50% or 100%) or the factory setting (see BrightnessDef variable) is used as the default value, depending on the device.

On PP100/200 and MP100/200 devices, the factory setting is also used in service mode (mode/node switches set to 0/0).

On the PP300/400 (with ADI driver version 1.20 or higher and MTCX PX32 version 1.11 or higher) and the PPC300, the default brightness value is used when the PC is booted if the brightness is set to AUTO in BIOS.

MP40/50 devices do not differentiate between the default value and the current value of the brightness. Both DisplayDefaultBrightness and DisplayBrightness read and change the current brightness.

On PP500, APC620, PPC700, APC810, PPC800, APC820, PP100/200 and MP100/200 devices, on PP300/400 devices with an ADI driver version lower than 1.20, and on PPC300 devices with an ADI driver version lower than 1.10, the default brightness value is stored in the Windows registry. In order for the modified value to be present after a restart, in Windows CE the information is saved by the ADI driver under HKEY_LOCAL_MACHINE in the registry.

Contrast

Contrast settings can only be configured on passive displays.

The DiaplayContrast setting is only applied until the next time the system is started (except on MP40/50, see below). In order for the contrast to be retained after the next system start you must set the default value using the DisplayDefaultContrast variable.

The default value for the contrast is automatically set by the ADI driver when the system is started.

The default value for the contrast is the value that is automatically set by the ADI driver when the system is started. The first time the system is started, a fixed value (e.g. 50% or 100%) or the factory setting (see ContrastDef variable) is used as the default value, depending on the device.

On PP100/200 and MP100/200 devices, the factory setting is also used in service mode (mode/node switches set to 0/0).

On the PP300/400 (with ADI version 1.20 or higher and MTCX PX32 version 1.11 or higher), the default contrast value is used when the PC is booted if the brightness is set to AUTO in BIOS.

MP40/50 devices do not differentiate between the default value and the current value of the contrast. Both DisplayDefaultContrast and DisplayContrast read and change the current contrast.

On PP100/200 and MP100/200 devices, and on PP300/400 devices with an ADI version before 1.20, the default contrast value is stored in the Windows Registry. In order for the modified value to be present after a restart, in Windows CE the information is saved by the ADI driver under HKEY_LOCAL_MACHINE in the registry.

Equalizer setting

The equalizer is integrated into Automation Panel devices and adapts the DVI signal to different cable lengths. The equalizer value is automatically calculated based on the cable length. You can use the DisplayEqualizer variable to set a different equalizer value in order to obtain the best possible display quality (e.g. with low-quality cables or poor DVI signal quality).

You can read the automatically predefined equalizer value with the DisplayEqualizerAutoValue variable regardless of the equalizer value currently being used.

Keys

A panel device supports up to 128 keys in four layers.

For technical reasons, all B&R devices that are able to support keys currently report the number of keys as 128. This does not necessarily mean that the device actually has 128 keys. There may in fact be fewer or no keys at all present on the device. It can only be assumed that the device does not support keys if the number of keys returned is 0.

Key states can also be read if the system doesn't have a valid key configuration.

PP100/200, MP100/200, MP40/50 (with ADI driver version 1.10 or lower): In Windows CE, the key states are not returned until GWES (the Graphics, Windows, and Event Subsystem) has started.

MP40/50: The status of the optional key switch or pushbutton is always returned in bit 0 and 1 of the 9th byte.

Prior to ADI driver version 1.10 on MP40/50 devices, bits 0 and 1 of the 9th byte are returned inverted.

Reading several keys can be done more effectively by reading the entire key array. For this, only one access to the ADI driver has to be made for all keys. However, the PVI application itself then has to evaluate the necessary keys (array elements for the Keys variable or bits for the KeyMatrix variable).

Only the current key states are provided by ADI and not, as with a standard keyboard, the sequence of the keys pressed. This means that pressing keys for only a short duration may not be detected depending on the scan times of the ADI driver, the ADI line, and the PVI application. The ADI line scan time is influenced by the number and refresh rates of the registered variables. Key states should therefore only be read for diagnostic purposes!

Key switch

Switch key states can only be read if a valid key configuration with key switch specifications is present in the system. The key configuration must be created with B&R Key Editor version 2.50 or higher.

PP100/200, MP100/200, MP40/50 (with ADI driver version 1.10 or lower): In Windows CE, the key states are not returned until GWES (the Graphics, Windows, and Event Subsystem) has started.

Key locking

If key locking is turned off, then the key codes assigned with the key configuration are sent to the operating system when a key is pressed.

If key locking is enabled, the operating system doesn't receive the key codes. In this case, only the states of the keys can be read using the Keys and KeyMatrix variables.

Key locking can be used e.g. to lock the scan codes when the key matrix is read for testing purposes using the KeyMatrix variable and the operating system should not react to keystrokes during that time.

LEDs

A panel device supports up to 128 LEDs in four layers.

For technical reasons, all B&R devices that are able to support LEDs currently report the number of LEDs as 128. This does not necessarily mean that the device actually has 128 LEDs. There may in fact be fewer or no LEDs at all present on the device. It can only be assumed that the device does not support LEDs if the number of LEDs returned is 0.

LED level

Like keys, LEDs can be operated in four different layers.

The LED layer only affects the LEDs and LedMatrix variables for the respective panel device.

<< Previous Topic
Variable names for PC devices

Start Page

Next Topic >>
Variable names for UPS devices


Variable names for UPS devices

The ADI line supports the following variables for a UPS device:

Note: The "C" column indicates whether the variable returns a constant value.

Variable name | Data format | I/O | C | Devices | Description
BatCapacity | VT=i8 | R |  | APC620 APC810 PPC800 | Remaining capacity of the UPS battery in percent. 5 -1 = Cannot determine capacity
BatCurrent | VT=f32 | R |  | APC620 APC810 APC910 PPC800 PPC900 | > 0: Charging current of the UPS battery in mA. < 0: Discharge current of the UPS battery in mA.
BatDeviceId | VT=u32 | R | 4 | APC620 APC810 PPC800 | Device ID of UPS battery (or ID of user's own UPS battery).
BatModelNumber | VT=string VL=41 | R | 4 | APC620 APC810 PPC800 | Model number of UPS battery (or description of user's own UPS battery).
BatRuntime | VT=u32 | R |  | APC620 APC810 PPC800 | Remaining runtime of the UPS battery in seconds. 2 0 = Cannot determine runtime
BatSettings | VT=u8 VN=256 | R | 4 | APC620 APC810 PPC800 | UPS battery settings. For B&R-internal use only!
BatSettingsVersion | VT=string VL=8 | R | 4 | APC620 APC810 PPC800 | Version of the UPS battery settings. Example: "1.02"
BatTemperature | VT=i8 | R |  | APC620 APC810 APC910 PPC800 PPC900 | Temperature of the UPS battery in degrees °C: 1 The value -128 is shown if the temperature cannot be measured. If the permitted temperature range is exceeded, a temperature alarm is triggered by the UPS (see Status). The permitted temperature range is defined in the UPS battery settings. It can be displayed e.g. in the B&R Control Center.
BatVoltage | VT=f32 | R |  | APC620 APC810 APC910 PPC800 PPC900 | Voltage of the UPS battery in volts.
CompatibilityId | VT=u16 | R | 3 | APC620 APC810 PPC800 | UPS compatibility ID.
Detected | VT=boolean | R | ü | APC620 APC810 APC910 PPC800 PPC900 | Code for whether the UPS has been detected: 0 = Not detected 1 = Detected
DeviceId | VT=u32 | R | 3 | APC620 APC810 PPC800 | Device ID of the UPS.
FactoryData | VT=u8 VN=256 | R | 3 |  | obsolete - replaced by FactorySettings
FactorySettings | VT=u8 VN=256 | R | 3 | APC620 APC810 PPC800 | UPS factory settings. For B&R-internal use only!
FactorySettingsVersion | VT=string VL=8 | R | 3 | APC620 APC810 PPC800 | Version of factory settings Example: "1.02"
FactoryVersion | VT=string VL=8 | R | 3 |  | obsolete - replaced by FactorySettingsVersion
FirmwareVersion | VT=string VL=16 | R |  | APC620 APC810 PPC800 | UPS firmware version. Example: "1.10"
HardwareRevision | VT=string VL=5 | R | 3 | APC620 APC810 PPC800 | Hardware revision of the UPS.
Linked | VT=boolean | R |  | APC620 APC810 APC910 PPC800 PPC900 | Code for whether the UPS is connected: 0 = Not connected 1 = Connected, communication with UPS is functioning properly.
ModelNumber | VT=string VL=41 | R | 3 | APC620 APC810 PPC800 | Model number of the UPS.
OnBatCycles | VT=u16 | R | ü | APC910 PPC900 | Number of battery operation cycles (e.g. power failures) of the UPS
OnBatHours | VT=u16 | R |  | APC910 PPC900 | Number of hours of UPS battery operation.
SerialNumber | VT=string VL=12 | R | 3 | APC620 APC810 PPC800 | UPS serial number.
SpecialsData | VT=u32 | R |  | APC620 APC810 APC910 PPC800 PPC900 | For B&R-internal use only!
Status | VT=u32 | R |  | APC620 APC810 APC910 PPC800 PPC900 | UPS status: 6 Bit 0 = 1: Supply voltage OK Bit 1 = 1: Battery settings missing or invalid Bit 2 = 1: Battery operation Bit 3 = 1: Battery status "Very low" Bit 4 = 1: Reversed battery polarity 9 Bit 5 = 1: Battery error (missing, defective, incorrect voltage/current/temperature) Bit 6 = 1: Battery life exhausted 2 Bit 7 = 1: Shutdown active Bit 8 = 1: Overcurrent alarm 1 Bit 9 = 1: Factory settings missing or invalid 1 Bit 10 = 1: APC add-on UPS: User settings missing or invalid 1, APC IF UPS: User settings not supported 7 Bit 15 = 1: Battery temperature exceeded or can't be measured 1 5
Type | VT=string VL=5 | R |  | APC620 APC810 APC910 PPC800 PPC900 | Type of UPS: "UPSI" for APC add-on UPS or "UPSII" for APC IF USV. 8
VendorId | VT=u32 | R | 3 | APC620 APC810 PPC800 | ID of the UPS manufacturer (B&R = 0).
1 | Requires UPS firmware version 1.10 or higher on the APC610, APC810, PPC800.
2 | Not supported by the current APC add-on UPS firmware 1.10.
3 | The value can only be modified by updating the factory settings.
4 | The value can only be modified by updating the battery settings.
5 | 100% is only supplied by the current UPS firmware if the battery is fully charged.
6 | In APC add-on UPS firmware version 1.07 or lower, the status is sometimes shown as 0 when changing between battery operation and normal operation. Normally, bit 0 or bit 2 is always set.
7 | Requires MTCX version 1.04 or higher on the APC910.
8 | Up to version 2.0 of the driver, the APC IF UPS is registered as UPSI on the APC910/PPC900.
9 | Requires APC add-on UPS firmware version 1.08 or higher.

APC620: Unless otherwise noted, all variables require ADI driver version 1.60 or higher, MTCX FPGA version 1.18 or higher, and MTCX PX32 version 1.61 or higher.
APC910: All variables - unless specified otherwise - require ADI driver version 1.0 or higher.

<< Previous Topic
Variable names for panel devices

Start Page

Next Topic >>
Variable names for CPU devices


Variable names for CPU devices

The ADI line supports the following variables for a CPU device:

Note: The "C" column indicates whether the variable returns a constant value.

Variable name | Data format | I/O | C | Devices | Description
CompatibilityId | VT=u16 | R | 1 | APC510 APC511 APC910 3 PP500 PPC900 4 | Compatibility ID of the CPU board.
DeviceId | VT=u32 | R | 1 | APC510 APC511 APC910 PP500 PPC900 4 | Device ID of the CPU board.
FactorySettings | VT=u8 VN=256 | R | 1 | APC510 APC511 PP500 | Factory settings of the CPU board. For B&R-internal use only!
FactorySettingsVersion | VT=string VL=8 | R | 1 | APC510 APC511 PP500 | Version of factory settings Example: "1.2"
HardwareRevision | VT=string VL=5 | R | 1 | APC510 APC511 APC910 PP500 PPC900 4 | Hardware revision of the CPU board.
ModelNumber | VT=string VL=41 | R | 1 | APC510 APC511 APC910 PP500 PPC900 4 | Model number of the CPU board.
ParentCompatibilityId | VT=u16 | R | ü | APC510 APC511 APC910 3 PP500 PPC900 4 | Parent compatibility ID of the CPU board (FFFFh = no parent). Specifies the compatibility ID of the CPU board from which the current device was derived (e.g. for a custom variant of a standard device).
ParentDeviceId | VT=u32 | R | ü | APC510 APC511 APC910 3 PP500 PPC900 4 | Parent device ID of the CPU board (FFFFFFFFh = no parent). Specifies the device ID of the CPU board from which the current device was derived (e.g. for a a custom variant of a standard device).
Power | VT=f32 | R |  | APC510 APC511 APC910 PP500 PPC900 | CPU power consumption in watts.
PowerOnCycles | VT=u16 | R | ü | APC510 APC511 APC910 PP500 PPC900 | Number of power-ons for the CPU board.
PowerOnHours | VT=u16 | R |  | APC510 APC511 APC910 PP500 PPC900 | Number of operating hours for the CPU board.
SerialNumber | VT=string VL=12 | R | 1 | APC510 APC511 APC910 3 PP500 PPC900 4 | Serial number of the CPU board.
Temperature1 | VT=i8 | R |  | APC510 APC511 APC910 PP500 PPC900 | Value of temperature sensor 1 for the CPU board in degrees Celsius. 2
Temperature2 | VT=i8 | R |  | APC510 APC511 APC910 PP500 PPC900 | Value of temperature sensor 2 for the CPU board in degrees Celsius. 2
Temperature3 | VT=i8 | R |  | APC510 APC511 APC910 PP500 PPC900 | Value of temperature sensor 3 for the CPU board in degrees Celsius. 2
Temperature4 | VT=i8 | R |  | APC510 APC511 APC910 PP500 PPC900 | Value of temperature sensor 4 for the CPU board in degrees Celsius. 2
VendorId | VT=u32 | R | 1 | APC510 APC511 APC910 3 PP500 PPC900 4 | Manufacturer ID of the CPU board (B&R = 0).
1 | The value can only be modified by updating the factory settings.
2 | Optional temperature sensor: Depending on the CPU board used, it is possible that a temperature is not supported.
3 | On a APC910, a pseudo value is provided.
4 | On a PPC900, the same value is provided as on the system unit.

PP500: All variables - unless specified otherwise - require ADI driver version 1.3 or higher.

<< Previous Topic
Variable names for UPS devices

Start Page

Next Topic >>
Variable names for memory devices


Variable names for memory devices

The ADI line supports the following variables for a memory device:

Note: The "C" column indicates whether the variable returns a constant value.

Variable name | Data format | I/O | C | Devices | Description
CompatibilityId | VT=u16 | R | 1 | APC510 APC511 APC910 PP500 PPC900 2 | Memory module compatibility ID.
DeviceId | VT=u32 | R | 1 | APC510 APC511 APC910 PP500 PPC900 2 | Memory module device ID.
FactorySettings | VT=u8 VN=256 4 | R | 1 | APC510 APC511 APC910 PP500 | Memory module factory settings. For B&R-internal use only!
FactorySettingsVersion | VT=string VL=8 | R | 1 | APC510 APC511 APC910 PP500 | Version of factory settings Example: "1.2"
HardwareRevision | VT=string VL=5 | R | 1 | APC510 APC511 APC910 PP500 PPC900 2 | Memory module hardware revision.
ModelNumber | VT=string VL=41 | R | 1 | APC510 APC511 APC910 PP500 PPC900 3 | Memory module model number.
ParentCompatibilityId | VT=u16 | R | ü | APC510 APC511 APC910 PP500 PPC900 2 | Memory module parent compatibility ID (FFFFh = no parent). Specifies the compatibility ID of the memory module from which the current device was derived (e.g. for a custom variant of a standard device).
ParentDeviceId | VT=u32 | R | ü | APC510 APC511 APC910 PP500 PPC900 2 | Memory module parent device ID (FFFFFFFFh = no parent). Specifies the device ID of the memory module from which the current device was derived (e.g. for a custom variant of a standard device).
Present | VT=boolean | R | ü | APC910 PPC900 5 | Indicates whether a memory module is installed: 0 = Not provided 1 = Provided
SerialNumber | VT=string VL=12 | R | 1 | APC510 APC511 APC910 PP500 PPC900 3 | Memory module serial number.
Temperature | VT=i8 | R |  | PPC900 | Temperature of memory module in degrees Celsius.
VendorId | VT=u32 | R | 1 | APC510 APC511 APC910 PP500 PPC900 2 | Manufacturer ID of the memory module (B&R = 0).
1 | The value can only be modified by updating the factory settings.
2 | On a PPC900, a pseudo value is provided.
3 | On a PPC900, the serial/model number of the DRAM is provided (not the B&R serial/model number).
4 | Only 128 valid bytes are returned on APC910 devices. The remaining bytes are returned with 0s.
5 | Temperature values are not supported with MTCX version 1.07 on PPC900 devices.

PP500: All variables - unless specified otherwise - require ADI driver version 1.3 or higher.

<< Previous Topic
Variable names for CPU devices

Start Page

Next Topic >>
Variable names for IF devices


Variable names for CPU devices

Variable names for IF devices

The ADI line supports the following variables for an IF device:

Note: The "C" column indicates whether the variable returns a constant value.

Variable name | Data format | I/O | C | Devices | Description
CompatibilityId | VT=u16 | R | 1 | APC510 APC511 APC910 PP500 PPC900 | Compatibility ID of the IF board.
DeviceId | VT=u32 | R | 1 | APC510 APC511 APC910 PP500 PPC900 | Device ID of the IF board.
FactorySettings | VT=u8 VN=256 | R | 1 | APC510 APC511 APC910 PP500 PPC900 | Factory settings of the IF board. For B&R-internal use only!
FactorySettingsVersion | VT=string VL=8 | R | 1 | APC510 APC511 APC910 PP500 PPC900 | Version of factory settings Example: "1.2"
HardwareRevision | VT=string VL=5 | R | 1 | APC510 APC511 APC910 PP500 PPC900 | Hardware revision of the IF board.
ModelNumber | VT=string VL=41 | R | 1 | APC510 APC511 APC910 PP500 PPC900 | Model number of the IF board.
ParentCompatibilityId | VT=u16 | R | ü | APC510 APC511 APC910 PP500 PPC900 | Parent compatibility ID of the IF board (FFFFh = no parent). Specifies the compatibility ID of the IF board from which the current device was derived (e.g. for a custom variant of a standard device).
ParentDeviceId | VT=u32 | R | ü | APC510 APC511 APC910 PP500 PPC900 | Parent device ID of the IF board (FFFFFFFFh = no parent). Specifies the device ID of the IF board from which the current device was derived (e.g. for a a custom variant of a standard device).
PowerOnCycles | VT=u16 | R | ü | APC510 APC511 APC910 PP500 PPC900 | Number of power-ons for the IF board.
PowerOnHours | VT=u16 | R |  | APC510 APC511 APC910 PP500 PPC900 | Number of operating hours for the IF board.
Present | VT=boolean | R | ü | APC510 APC511 APC910 PP500 PPC900 | Indicates whether an IF board is installed: 0 = Not provided 1 = Provided
SerialNumber | VT=string VL=12 | R | 1 | APC510 APC511 APC910 PP500 PPC900 | Serial number of the IF board.
Temperature1 | VT=i8 | R |  | APC510 APC511 PP500 | Value of temperature sensor 1 for the IF board in degrees Celsius. 2
Temperature2 | VT=i8 | R |  | APC510 APC511 PP500 | Value of temperature sensor 2 for the IF board in degrees Celsius. 2
Temperature3 | VT=i8 | R |  | APC510 APC511 PP500 | Value of temperature sensor 3 for the IF board in degrees Celsius. 2
Temperature4 | VT=i8 | R |  | APC510 APC511 PP500 | Value of temperature sensor 4 for the IF board in degrees Celsius. 2
VendorId | VT=u32 | R | 1 | APC510 APC511 APC910 PP500 PPC900 | Manufacturer ID of the IF board (B&R = 0).
1 | The value can only be modified by updating the factory settings.
2 | Optional temperature sensor: Depending on the IF board used, it is possible that a temperature is not supported.

PP500: All variables - unless specified otherwise - require ADI driver version 1.3 or higher.

<< Previous Topic
Variable names for memory devices

Start Page

Next Topic >>
Variable names for I/O devices


Variable names for I/O devices

The ADI line supports the following variables for an I/O device:

Note: The "C" column indicates whether the variable returns a constant value.

Variable name | Data format | I/O | C | Devices | Description
CompatibilityId | VT=u16 | R | 1 | APC510 APC511 PP500 | Compatibility ID of the I/O board.
DeviceId | VT=u32 | R | 1 | APC510 APC511 PP500 | Device ID of the I/O board.
FactorySettings | VT=u8 VN=256 | R | 1 | APC510 APC511 PP500 | Factory settings of the I/O board. For B&R-internal use only!
FactorySettingsVersion | VT=string VL=8 | R | 1 | APC510 APC511 PP500 | Version of factory settings Example: "1.2"
FpgaBootInfo | VT=i32 | R | ü | APC510 APC511 PP500 3 | I/O Board FPGA Firmware Bootinfo: 0 = Booted from low area 1 = Booted from high area
FpgaVersion | VT=string VL=16 | R | ü | APC510 APC511 PP500 3 | Version of the I/O board FPGA firmware. Example: "0.03"
HardwareRevision | VT=string VL=5 | R | 1 | APC510 APC511 PP500 | Hardware revision of the I/O board.
ModelNumber | VT=string VL=41 | R | 1 | APC510 APC511 PP500 | Model number of the I/O board.
ParentCompatibilityId | VT=u16 | R | ü | APC510 APC511 PP500 | Parent compatibility ID of the I/O board (FFFFh = no parent). Specifies the I/O board's parent compatibility ID that is used to derive the current device (e.g. when using a custom variant of the standard device).
ParentDeviceId | VT=u32 | R | ü | APC510 APC511 PP500 | Parent device ID of the I/O board (FFFFh = no parent). Specifies the device ID of the I/O board that is used to derive the current device (e.g. when using a custom variant of the standard device).
PowerOnCycles | VT=u16 | R | ü | APC510 APC511 PP500 | Number of power-ons for the I/O board.
PowerOnHours | VT=u16 | R |  | APC510 APC511 PP500 | Number of operating hours for the I/O board.
Present | VT=boolean | R | ü | APC510 APC511 PP500 | Indicates whether an I/O board is installed: 0 = Not provided 1 = Provided
SerialNumber | VT=string VL=12 | R | 1 | APC510 APC511 PP500 | Serial number of the I/O board.
Temperature1 | VT=i8 | R |  | APC510 APC511 PP500 | Value of temperature sensor 1 for the I/O board in degrees Celsius. 2
Temperature2 | VT=i8 | R |  | APC510 APC511 PP500 | Value of temperature sensor 2 for the I/O board in degrees Celsius. 2
Temperature3 | VT=i8 | R |  | APC510 APC511 PP500 | Value of temperature sensor 3 for the I/O board in degrees Celsius. 2
Temperature4 | VT=i8 | R |  | APC510 APC511 PP500 | Value of temperature sensor 4 for the I/O board in degrees Celsius. 2
VendorId | VT=u32 | R | 1 | APC510 APC511 PP500 | Manufacturer ID of the I/O board (B&R = 0).
1 | The value can only be modified by updating the factory settings.
2 | Optional temperature sensor: Depending on the I/O board used, it is possible that a temperature is not supported.
3 | Requires ADI driver version 1.4 or higher on the PP500.

PP500: All variables - unless specified otherwise - require ADI driver version 1.3 or higher.

<< Previous Topic
Variable names for IF devices

Start Page

Next Topic >>
Variable names for bus devices


Variable names for bus devices

The ADI line supports the following variables for a bus device:

Note: The "C" column indicates whether the variable returns a constant value.

Variable name | Data format | I/O | C | Devices | Description
CompatibilityId | VT=u16 | R | 1 | APC910 PPC900 | Bus unit compatibility ID.
DeviceId | VT=u32 | R | 1 | APC910 PPC900 | Bus unit device ID.
FactorySettings | VT=u8 VN=256 | R | 1 | APC910 PPC900 | Bus unit factory settings. For B&R-internal use only!
FactorySettingsVersion | VT=string VL=8 | R | 1 | APC910 PPC900 | Version of factory settings Example: "1.2"
HardwareRevision | VT=string VL=5 | R | 1 | APC910 PPC900 | Bus unit hardware revision.
ModelNumber | VT=string VL=41 | R | 1 | APC910 PPC900 | Bus unit model number.
ParentCompatibilityId | VT=u16 | R | ü | APC910 PPC900 | Bus unit parent compatibility ID (FFFFh = no parent). Specifies the compatibility ID of the bus unit from which the current device was derived (e.g. for a custom variant of a standard device).
ParentDeviceId | VT=u32 | R | ü | APC910 PPC900 | Bus unit parent device ID (FFFFFFFFh = no parent). Specifies the device ID of the bus unit from which the current device was derived (e.g. for a custom variant of a standard device).
PowerOnCycles | VT=u16 | R | ü | APC910 PPC900 | Number of power-ons for the bus unit.
PowerOnHours | VT=u16 | R |  | APC910 PPC900 | Number of operating hours for the bus unit.
Present | VT=boolean | R | ü | APC910 PPC900 | Indicates whether bus unit is installed: 0 = Not provided 1 = Provided
SerialNumber | VT=string VL=12 | R | 1 | APC910 PPC900 | Bus unit serial number.
VendorId | VT=u32 | R | 1 | APC910 PPC900 | Manufacturer ID of the bus unit (B&R = 0).
1 The value can only be modified by updating the factory settings.

<< Previous Topic
Variable names for I/O devices

Start Page

Next Topic >>
Variable names for drive devices


Variable names for drive devices

The ADI line supports the following variables for an drive device:

Note: The "C" column indicates whether the variable returns a constant value.

Variable name | Data format | I/O | C | Devices | Description
CompatibilityId | VT=u16 | R | 1 | APC910 PPC900 | Compatibility ID of the slide-in drive.
DeviceId | VT=u32 | R | 1 | APC910 PPC900 | Device ID of the slide-in drive.
FactorySettings | VT=u8 VN=256 | R | 1 | APC910 PPC900 | Factory settings of the slide-in drive. For B&R-internal use only!
FactorySettingsVersion | VT=string VL=8 | R | 1 | APC910 PPC900 | Version of factory settings Example: "1.2"
HardwareRevision | VT=string VL=5 | R | 1 | APC910 PPC900 | Hardware revision of the slide-in drive.
ModelNumber | VT=string VL=41 | R | 1 | APC910 PPC900 | Model number of the slide-in drive.
ParentCompatibilityId | VT=u16 | R | ü | APC910 PPC900 | Parent compatibility ID of the slide-in drive (FFFFh = no parent). Specifies the compatibility ID of the slide-in drive from which the current device was derived (e.g. for a custom variant of a standard device).
ParentDeviceId | VT=u32 | R | ü | APC910 PPC900 | Parent device ID of the slide-in drive (FFFFFFFFh = no parent). Specifies the device ID of the slide-in drive from which the current device was derived (e.g. for a custom variant of a standard device).
Present | VT=boolean | R | ü | APC910 PPC900 | Indicates whether a slide-in drive is installed: 0 = Not provided 1 = Provided
SerialNumber | VT=string VL=12 | R | 1 | APC910 PPC900 | Serial number of the slide-in drive.
Temperature | VT=i8 | R |  | APC910 PPC900 | Temperature of the slide-in drive in degrees Celsius.
VendorId | VT=u32 | R | 1 | APC910 PPC900 | Manufacturer ID of the slide-in drive (B&R = 0).
1 | The value can only be modified by updating the factory settings.
2 | Optional temperature sensor: Depending on the slide-in drive used, it is possible that a temperature is not supported.

<< Previous Topic
Variable names for bus devices

Start Page

Next Topic >>
Variable names for fan devices


Variable names for fan devices

The ADI line supports the following variables for an fan device:

Note: The "C" column indicates whether the variable returns a constant value.

Variable name | Data format | I/O | C | Devices | Description
CompatibilityId | VT=u16 | R | 1 | APC910 APC2100 PPC900 PPC2100 | Compatibility ID of the fan kit.
DeviceId | VT=u32 | R | 1 | APC910 APC2100 PPC900 PPC2100 | Device ID of the fan kit.
FactorySettings | VT=u8 VN=256 | R | 1 | APC910 APC2100 PPC900 PPC2100 | Factory settings of the fan kit. For B&R-internal use only!
FactorySettingsVersion | VT=string VL=8 | R | 1 | APC910 APC2100 PPC900 PPC2100 | Version of factory settings Example: "1.2"
Fan1Speed | VT=u16 | R |  | APC910 APC2100 PPC900 PPC2100 | Speed of the first housing fan in rpm. 2
Fan2Speed | VT=u16 | R |  | APC910 APC2100 PPC900 PPC2100 | Speed of the second housing fan in rpm. 2
Fan3Speed | VT=u16 | R |  | APC910 APC2100 PPC900 PPC2100 | Speed of the third housing fan in rpm. 2
Fan4Speed | VT=u16 | R |  | APC910 APC2100 PPC900 PPC2100 | Speed of the fourth housing fan in rpm. 2
FanOnCycles | VT=u16 | R | ü | APC910 APC2100 PPC900 PPC2100 | Number of power-ons for the fan.
FanOnHours | VT=u16 | R |  | APC910 APC2100 PPC900 PPC2100 | Number of operating hours for the fan.
HardwareRevision | VT=string VL=5 | R | 1 | APC910 APC2100 PPC900 PPC2100 | Hardware revision of the fan kit.
ModelNumber | VT=string VL=41 | R | 1 | APC910 APC2100 PPC900 PPC2100 | Model number of the fan kit.
ParentCompatibilityId | VT=u16 | R | ü | APC910 APC2100 PPC900 PPC2100 | Fan kit parent compatibility ID (FFFFh = no parent). Specifies the compatibility ID of the fan kit from which the current device was derived (e.g. for a custom variant of a standard device).
ParentDeviceId | VT=u32 | R | ü | APC910 APC2100 PPC900 PPC2100 | Fan kit parent device ID (FFFFFFFFh = no parent). Specifies the device ID of the fan kit from which the current device was derived (e.g. for a custom variant of a standard device).
Present | VT=boolean | R | ü | APC910 APC2100 PPC900 PPC2100 | Indicates whether a fan kit is installed: 0 = Not provided 1 = Provided
SerialNumber | VT=string VL=12 | R | 1 | APC910 APC2100 PPC900 PPC2100 | Serial number of the fan kit.
VendorId | VT=u32 | R | 1 | APC910 APC2100 PPC900 PPC2100 | Manufacturer ID of the fan kit (B&R = 0).
1 | The value can only be modified by updating the factory settings.
2 | Optional fan: Depending on the fan kit used, it is possible that no value is supported.

<< Previous Topic
Variable names for drive devices

Start Page

Next Topic >>
Variable names for link devices


Variable names for link devices

The ADI line supports the following variables for a link device:

Note: The "C" column indicates whether the variable returns a constant value.

Variable name | Data format | I/O | C | Devices | Description
CompatibilityId | VT=u16 | R | 1 | APC910 APC2100 | Display Link compatibility ID.
DeviceId | VT=u32 | R | 1 | APC910 APC2100 | Display Link device ID.
FactorySettings | VT=u8 VN=256 | R | 1 | APC910 APC2100 | Display Link factory settings. For B&R-internal use only!
FactorySettingsVersion | VT=string VL=8 | R | 1 | APC910 APC2100 | Version of factory settings Example: "1.2"
FpgaBootInfo | VT=i32 | R | ü | APC910 APC2100 | Display Link FPGA firmware boot info. 0 = Booted from low area 1 = Booted from high area
FpgaVersion | VT=string VL=16 | R | ü | APC910 APC2100 | Version of the Display Link FPGA firmware. Example: "0.03"
HardwareRevision | VT=string VL=5 | R | 1 | APC910 APC2100 | Display Link hardware revision.
LinkType | VT=string VL=5 | R | ü | APC910 4 APC2100 | Display Link type. "PC2S" = APC2100 SDL transmitter 3 "P2S3" = APC2100 SDL3 transmitter 3
ModelNumber | VT=string VL=41 | R | 1 | APC910 APC2100 | Display Link model number.
ParentCompatibilityId | VT=u16 | R | ü | APC910 APC2100 | Display Link parent compatibility ID (FFFFh = no parent). Specifies the compatibility ID of the Display Link from which the current device was derived (e.g. for a custom variant of a standard device).
ParentDeviceId | VT=u32 | R | ü | APC910 APC2100 | Display Link parent device ID (FFFFFFFFh = no parent). Specifies the device ID of the Display Link from which the current device was derived (e.g. for a custom variant of a standard device).
PowerOnCycles | VT=u16 | R | ü | APC910 APC2100 | Number of power-ons for the Display Link.
PowerOnHours | VT=u16 | R |  | APC910 APC2100 | Number of operating hours for the Display Link.
Present | VT=boolean | R | ü | APC910 APC2100 | Indicates whether a Display Link is installed: 0 = Not provided 1 = Provided
SerialNumber | VT=string VL=12 | R | 1 | APC910 APC2100 | Display Link serial number.
Temperature1 | VT=i8 | R |  | APC910 APC2100 | Value of temperature sensor 1 for the Display Link in degrees Celsius. 2
Temperature2 | VT=i8 | R |  | APC910 APC2100 | Value of temperature sensor 2 for the Display Link in degrees Celsius. 2
Temperature3 | VT=i8 | R |  | APC910 APC2100 | Value of temperature sensor 3 for the Display Link in degrees Celsius. 2
Temperature4 | VT=i8 | R |  | APC910 APC2100 | Value of temperature sensor 4 for the Display Link in degrees Celsius. 2
VendorId | VT=u32 | R | 1 | APC910 APC2100 | Manufacturer ID of the Display Link (B&R = 0).
1 | The value can only be modified by updating the factory settings.
2 | Optional temperature sensor: Depending on the Display Link used, it is possible that a temperature is not supported.
3 | Requires ADI driver version 3.1 or higher on the APC2100.
4 | Designed for the new ADI driver version on the APC910.

<< Previous Topic
Variable names for fan devices

Start Page

Next Topic >>
MTC line


MTC line

Starting with PVI Version 3.0.2, the MTC line is no longer supported!

The MTC line provides Maintenance Controller (MTC) functions for B&R Provit 5000 Industrial PCs (IPCs) (see also the "Provit 5000 User's Manual", model number MAPRV5000-0).

The MTC is responsible for the following tasks and components:

  • AT PS/2 keyboard
  • Panelware keypad modules
  • Acquisition of operating data (controller and display unit)
  • Temperature monitoring with fan control
  • Battery state evaluation (good/bad)

MTC functions for configuring keys and key LEDs on the display unit and Panelware modules as well as functions for reading key scan codes are not supported. This can all be taken care of using B&R MKEY utilities.

The following topics are covered in this section:

  • MTC process objects
  • MTC access types
  • MTC events
  • MTC communication

MTC process objects

A line object, a device object, and a variable object are all needed to access an MTC variable.

Process objects of the MTC line:

Name | Type | Connection | Usage
Line object | Line | "LNMTC" | MTC line
Device object | Device | Device parameter | MTC device
Station object | Station |  | Can be specified, but not required.
CPU object | CPU |  | Can be specified, but not required.
Module object | Modules |  | Can be specified, but not required.
Task object | Task |  | Can be specified, but not required.
Variable object | Pvar | Variable name | MTC variable

Allowed object structure for MTC process objects:

MTC access types

The following table shows an overview of all access types which are regulated via a line. All access types not listed here as well as access types to the PVI base object are executed by PVI Manager and therefore work independently of the line being used. The "Access type" column indicates which access types in the MTC line can be used with which process object types.

Access types | Type | Special features
POBJ_ACC_VERSION | Line Device | Line object: Version of the line DLL. Device object: MTC version
POBJ_ACC_LIST_EXTERN | Line | MTC device
POBJ_ACC_DATA | Pvar |
POBJ_ACC_STATUS | Pvar |
POBJ_ACC_TYPE_EXTERN | Pvar |
POBJ_ACC_UPLOAD |  | Not supported.
POBJ_ACC_DOWNLOAD |  | Not supported.
POBJ_ACC_DATE_TIME |  | Not supported.
POBJ_ACC_MEM_DELETE |  | Not supported.
POBJ_ACC_MEM_INFO |  | Not supported.
POBJ_ACC_MOD_TYPE |  | Not supported.
POBJ_ACC_UPLOAD_STM |  | Not supported.
POBJ_ACC_DOWNLOAD_STM |  | Not supported.
POBJ_ACC_LIST_STATION | Line Device |
POBJ_ACC_LIST_CPU | Line Device |
POBJ_ACC_LIST_MODULE | Line Device |
POBJ_ACC_LIST_TASK | Line Device |
POBJ_ACC_LIST_PVAR | Line Device |
POBJ_ACC_CPU_INFO |  | Not supported.

MTC events

The following table shows an overview of all event types which can be generated from a line. All event types which are not listed are generated by PVI Manager and therefore work independently of the line being used.

Event types | Special features
POBJ_EVENT_STATUS | Not supported.
POBJ_EVENT_PROCEEDING | Not supported.

<< Previous Topic
Variable names for link devices

Start Page

Next Topic >>
MTC communication


MTC communication

The MTC line only works together with B&R MTC utilities. These utilities are included on the "HMI Drivers & Utilities CD" (model number 5S0000.01-090) and can also be downloaded from the B&R homepage (www.br-automation.com).

PC requirements

The MTC line can be operated on the following platforms:

Windows platform | Limitations
Windows NT/2000/XP | -
Windows Vista | Not supported.
Windows CE | Not supported.

B&R MTC Utilities (starting from Version 1.09) must be installed on the PC.

At least BIOS Version 00.25 is needed for MTC communication (see also "Provit 5000 MTC Utilities 32-Bit User's Manual"). Otherwise, the MTC driver cannot be loaded.

<< Previous Topic
MTC line

Start Page

Next Topic >>
MTC device objects


MTC device objects

The communication device is determined with the MTC device object.

Connection description syntax:

/IF=mtc [/TO=<Timeout>]

Device names are not case sensitive, and at least one space character must be between each parameter specification.

The following table shows all parameters which can be defined in a device object's connection description.

Param. | Values | Settings | Description
/IF | mtc | None | MTC device Specification: "/IF=mtc"
/TO | 0 - 60000 | 100 | Timeout for MTC requests (ms) The MTC line controls the MTC using asynchronous calls. The timeout specifies how long it must wait before necessary data can be accessed when an MTC request is called. Example: "/TO=250"

Connection description example:

CD="/IF=mtc /TO=1000"

<< Previous Topic
MTC communication

Start Page

Next Topic >>
MTC variable objects


MTC variable objects

A MTC variable object represents an object in the MTC. The connection name of the variable object corresponds to the name of the MTC variable. The MTC line supports predefined variable names. These are not case sensitive.

The data format of the variable object is given by the MTC line and cannot be influenced by the user.

Connection description syntax:

Single and array variables:

/RO=<variable_name>

or

<variable_name>

Element of an array variable:

/RO=<variable_name>[<index>]

or

<variable_name>[<index>]

If the variable name is defined as the /RO parameter, the connection description must always be specified in quotation marks ("...") in the object description.

Connection description examples:

CD="/RO=MkeyLedMatrix"
CD=MkeyLedMatrix[12]

Predefined Variable Names:

The MTC line supports the following MTC variables:

Note: The "C" column specifies whether the variable returns a constant value. The "DA" column indicates whether the variable is being accessed using Direct Access Mode, resulting in a shorter access times (on IPC5000C/5600C only).

Variable name | Data format | I/O | C | DA | Description
BatteryState | VT=boolean | R |  |  | Status of the CMOS battery in the IPC: 0 = Normal 1 = Empty, broken, or not present
CpuAlarm | VT=boolean | R |  | v | CPU over-temperature alarm: 0 = Normal, 1 = Alarm On an IPC5000C/5600C, this value is formed from the "CpuAlarmIntern", "CpuAlarmSocket", and "CpuAlarmFan" variables.
CpuAlarmFan 3) | VT=boolean | R |  | v | CPU fan alarm (fan not running): 0 = Normal, 1 = Alarm
CpuAlarmIntern 3) | VT=boolean | R |  | v | Internal CPU over-temperature alarm: 0 = Normal, 1 = Alarm
CpuAlarmSocket 3) | VT=boolean | R |  | v | CPU socket over-temperature alarm: 0 = Normal, 1 = Alarm
CpuTemperature | VT=u8 | R |  | v | Current CPU temperature in degrees Celsius (positive values only). This value corresponds to the "CpuTemperatureSocket" variable on an IPC5000C/5600C.
CpuTemperatureIntern 3) | VT=u8 | R |  | v | Current internal CPU temperature in degrees Celsius (positive values only).
CpuTemperatureSocket 3) | VT=u8 | R |  | v | Current CPU socket area temperature in degrees Celsius (positive values only).
DriverVersion | VT=string VL=80 | R | v |  | Version of the MTC driver. Example: "MTC Driver 1.11 1998-09-25" This string is also returned with the MTC DLL version for the device object and access type VERSION.
FpdAlarm | VT=boolean | R |  |  | Display over-temperature alarm: 0 = Normal, 1 = Alarm
FpdBrightness | VT=u8 | W |  |  | Brightness setting for the display unit in percent: 0 to 100 This variable is initialized by the MTC line with FpdDefaultBrightness.
FpdContrast | VT=u8 | W |  |  | Contrast setting for the display unit in percent: 0 to 100 This variable is initialized by the MTC line with FpdDefaultContrast.
FpdDefaultBrightness | VT=u8 | R/W |  |  | Default value for the display unit's brightness (background lighting) given in percent: 0 to 100
FpdDefaultContrast | VT=u8 | R/W |  |  | Default value for the display unit's contrast given in percent: 0 to 100
FpdMkeyLedRegisters | VT=u8 | R | v | v | Number of registers for display unit key LEDs: 0 to 16
FpdMkeyRegisters | VT=u8 | R | v | v | Number of registers for display unit keys: 0 to 16
FpdName | VT=string VL=9 | R | v |  | Name of the display unit.
FpdNumber | VT=u16 | R | v |  | ID of the display unit: 0 = no display connected, other values are display-dependent
FpdOperatingHours | VT=u16 | R |  |  | Number of operating hours for the display unit.
FpdOverTempHours | VT=u16 | R |  |  | Number of over-temperature operating hours for the display unit.
FpdPowerOnCycles | VT=u16 | R |  |  | Number of power-ons for the display unit.
FpdTemperature | VT=u8 | R |  | v | Current display unit temperature in degrees Celsius (positive values only).
HardwareDefines | VT=u8 | R | v |  | Reserved for B&R.
IoAlarm | VT=boolean | R |  | v | Over-temperature alarm in the in the I/O area of the IPC: 0 = Normal, 1 = Alarm
IoTemperature | VT=u8 | R |  | v | Current temperature in the I/O area of the IPC in degrees Celsius (positive values only).
IpcFanHours | VT=u16 | R |  |  | Number of operating hours for the fan.
IpcFanRpm 3) | VT=u16 VN=2 | R |  | v | Number of IPC fan revolutions per minute.
IpcOperatingHours | VT=u16 | R |  |  | Number of operating hours for the IPC.
IpcOverTempHours | VT=u16 | R |  |  | Number of over-temperature operating hours for the IPC.
IpcPowerOnCycles | VT=u16 | R |  |  | Number of power-ons for the IPC. "Resets" are also counted.
IpcVersion | VT=string VL=80 | R | v |  | IPC version Example: "IPC5000C B&R Industrial Automation GmbH V1.14"
IpcVoltage12 3) | VT=f32 | R |  | v | 12 V IPC voltage in volts.
IpcVoltage2_5 3) | VT=f32 | R |  | v | 2.5V IPC voltage in volts.
IpcVoltage3_3 3) | VT=f32 | R |  | v | 3.3 V IPC voltage in volts.
IpcVoltage5 3) | VT=f32 | R |  | v | 5 V IPC voltage in volts.
IpcVoltageBattery 3) | VT=f32 | R |  | v | IPC battery voltage in volts.
IpcVoltageCore 3) | VT=f32 | R |  | v | IPC core voltage in volts.
IpcMkeyLedRegisters | VT=u8 | R | v |  | Number of registers for IPC key LEDs: 0 to 16
IpcMkeyRegisters | VT=u8 | R | v |  | Number of registers for IPC keys: 0 to 16
Jumpers | VT=u8 VN=2 | R |  |  | Reserved for B&R.
KeySwitches 2) | VT=u8 | R |  | v | State of the key switches. 1 bit per contact: 0 = Closed 1 = Opened Only those bits can be evaluated for which a key switch has also been defined. The state of all other bits is undefined and can therefore be either 0 or 1. A key switch can also occupy several bits.
KeySwitchesOffset 2) | VT=u8 | R |  |  | Offset of the key switches: 0 to 127
MkeyLedMatrix 2) | VT=u8 VN=32 | W |  |  | State of the key LEDs in the current key level in "packed" form: byte 0, bit 0+1 = 1st LED byte 0, bit 2+3 = 2nd LED ... byte 1, bit 0+1 = 5th LED ... 2 bits per LED: 00 = off 01 = normal blinking 10 = fast blinking 11 = on
MkeyLeds | VT=u8 VN=128 | R/W |  |  | State of key LEDs for the current key level. 1 element per LED: 0 = off 1 = normal blinking 2 = fast blinking 3 = on Only the individual elements (LEDs) of the array can be addressed, not the entire array.
MkeyLevel | VT=u8 | R/W |  |  | Number of key levels: 0 to 3 Key levels have an effect on the "MkeyLeds", "MkeyLedMatrix", "Mkeys", and "MkeyMatrix" variables. If a key level is set to value other than 0, then the MkeyLevelMode variable must be set to 1 (toggle) or 2 (one-shot)!
MkeyLevelMode | VT=u8 | R/W |  | v | Key level operating mode: 0 = default 1 = toggle 2 = one-shot Shift keys for key levels can be defined with the B&R Key Editor.
MkeyMatrix 1) | VT=u8 VN=16 | R |  | v | State of the keys in the current key level in "packed" form: byte 0, bit 0 = 1st key byte 0, bit 1 = 2nd key Etc. byte 1, bit 0 = 9th key ... 1 bit per key: 0 = Pressed, 1 = Not pressed Pressing keys for just a very short time may not be detected.
Mkeys 1) | VT=boolean VN=128 | R |  | v | State of the keys in the current key level. 1 element per key: 0 = Pressed, 1 = Not pressed Pressing keys for just a very short time may not be detected.
MtcVersion | VT=string VL=80 | R | v |  | MTC version Example: "MTC BIOS 1.1 00-04-04"
ScanCodesStateRam | VT=boolean | R |  |  | State of scan codes in RAM for the current key level: 0 = Undefined, 1 = OK
ScanCodesStateRom | VT=boolean | R |  | v | State of scan codes in ROM for the current key level: 0 = Undefined, 1 = OK
UserLed 2) | VT=boolean | R/W |  |  | State of the user LED (one of the status LEDs) on the IPC: 0 = Off, 1 = On
Watchdog 2) | VT=u8 | W |  |  | Variable for acknowledging the watchdog. The watchdog is reset when this variable is written to (regardless of the value). Before this variable is "removed" with PviUnlink or PviDelete, the watchdog must be disabled by writing 0 to the WatchdogTime variable!
WatchdogTime 2) | VT=u32 | W |  |  | Watchdog timeout in ms: 0 = Off, 1 - 1310700 If the timeout expires without the Watchdog variable having been defined, then the IPC resets. Windows requires the system to be shut down properly. This doesn't happen if a reset occurs. This can lead to data loss which can leave the system or application "paralyzed".
1) | Key can codes must be defined (see the " ScanCodesStatesRom " variable).
2) | Requires MTC version 00.10 or higher.
3) | Only supported on the IPC5000C/5600C.

Access time

Reading and writing variables may take a relatively long time (depending on MTC communication) if an IPC5000C or IPC5600C is not being used. These devices support MTC communication using a FIFO buffer and Direct Access Mode.

If an IPC5000 (or older IPC5000C/5600C without FIFO) is used, MTC communication can be "sped up" in the following way: The "PollingRate" parameter for the MTC driver must be set to a higher value (e.g. 10) in the registry (see also the "Provit MTC Utilities User's Manual").

If many variables should be read, then short refresh rates (RF) for these variables should be specified which can react quickly to data changes (e.g. keys). All other variables should be read with high refresh rates.

Key level operating modes

A key level is only active in "Default" mode as long as the corresponding level key is pressed. The level key must be pressed together with the desired key (corresponds to the function of a SHIFT key).

In "Toggle" mode, a key level can be turned on or off using the level key defined. That means each time this key is pressed, the level is toggled between level 0 and the respective level.

In "One-Shot" mode, pressing the level key only has an effect on the key pressed immediately afterwards. Once the action is complete, it switches back to level 0.

Keys

Reading several keys can be done more effectively by reading the entire key array. For this, only one access to the MTC driver has to be made for all keys. However, the PVI application itself then has to evaluate the necessary keys (= array elements for the Mkeys variable or bits for the MkeyMatrix variable).

Only the current key states are provided by MTC and not, as with a standard keyboard, the sequence of the keys pressed. This means that pressing keys for only a short duration may not be detected depending on the scan times of the MTC driver, the MTC line, and the PVI application. The MTC line scan time is influenced by the number and refresh rates of the registered variables. Key states should therefore only be read for diagnostic purposes!

Key switch

Key switches can be defined with the B&R Key Editor.

Operating hours

Operating hours are only updated every full hour. In other words, if a power failure occurs after 55 minutes, then the value of the counter is not raised by an hour.

Temperature Alarms

When an alarm occurs, the temperature LED lights up on the IPC or the display unit (if connected).

Temperature values which trigger an alarm are described in the "Provit 5000 User's Manual".

Temperature alarms depend on the display unit being used.

Contrast and brightness

Values for contrast and brightness are not absolute values. Instead, they are relative to the technically allowed minimum and maximum values. Contrast and brightness settings are lost when the device is switched off.

Contrast and brightness must be set together depending on the MTC interface. For this reason, writing to FpdContrast or FpdBrightness always sends the values of both variables to the MTC. If a variable has not been set by the user, then the corresponding default value is sent in its place.

Default values for contrast and brightness are permanently saved and are not lost when the device is turned off.

Contrast can only be set for LCD displays.

Default values are only set by the display unit when the system is restarted and "FPD Contrast" and "FPD Brightness" are set to "AUTO" under "Additional Peripherals" in BIOS.

Register

A register has a width of 8 bits = 8 LEDs or keys. The number of registers specifies the max. number of possible LEDs or keys which may exist. The actual existing amount depends on the connected keypad modules or the display unit being used.

<< Previous Topic
MTC device objects

Start Page

Next Topic >>
MODBUS line


MODBUS line

The Modbus line provides the functions necessary to operate a Modbus TCP controller.

The following topics are covered in this section:

  • Modbus process objects
  • Modbus access types
  • Modbus event types
  • Modbus communication

Modbus process objects

The following process objects are needed to access a Modbus variable:

Name | Type | Connection | Usage
Line object | Line | "LNMODBUS" | Modbus line.
Device object | Device | Device parameter | Modbus communication device.
Station object | Station | Station parameters | Modbus station (bus connector).
Variable object | Pvar | Variable name | Modbus variable.

Allowed object structure for Modbus process objects:

Modbus access types

The following table shows an overview of all access types which are regulated via a line. All access types not listed here as well as access types to the PVI base object are executed by PVI Manager and therefore work independently of the line being used. The corresponding process object type is listed in the "Type" column.

Access types | Type | Special features
POBJ_ACC_VERSION | Line | Version of the line DLL.
POBJ_ACC_LIST_EXTERN | Line Device Station | Lists all installed Modbus devices Lists all stations (bus controllers) specified in the configuration file Lists all process variables available in the configuration file for a station
POBJ_ACC_DATA | Variable | Access to a variable's data.
POBJ_ACC_STATUS | Variable | Access to a variable's status.
POBJ_ACC_TYPE_EXTERN | Variable | Reads a variable's data type.
POBJ_ACC_UPLOAD |  | Not supported
POBJ_ACC_DOWNLOAD |  | Not supported
POBJ_ACC_DATE_TIME |  | Not supported
POBJ_ACC_MEM_DELETE |  | Not supported
POBJ_ACC_MEM_INFO |  | Not supported
POBJ_ACC_MOD_TYPE |  | Not supported
POBJ_ACC_UPLOAD_STM |  | Not supported
POBJ_ACC_DOWNLOAD_STM |  | Not supported
POBJ_ACC_MOD_DATA |  | Not supported
POBJ_ACC_MOD_DELETE |  | Not supported
POBJ_ACC_LIST_STATION | Device | Lists all defined stations.
POBJ_ACC_LIST_CPU |  | Not supported
POBJ_ACC_LIST_MODULE |  | Not supported
POBJ_ACC_LIST_TASK |  | Not supported
POBJ_ACC_LIST_PVAR | Station | Lists all available process variables.
POBJ_ACC_CPU_INFO |  | Not supported
Access type > 255 |  | Not supported

Modbus event types

The following table shows an overview of all event types which can be generated from a line. All event types which are not listed are generated by PVI Manager and therefore work independently of the line being used.

Event types | Special features
POBJ_EVENT_STATUS | Not supported
POBJ_EVENT_PROCEEDING | Not supported
Event type > 255 | Not supported

<< Previous Topic
MTC variable objects

Start Page

Next Topic >>
MODBUS communication


MODBUS communication

MODBUS communication is supported for the following devices:

  • Ethernet

Modbus communication is a master/slave protocol where the Modbus line performs the functions of the master.

General PC requirements

The Modbus line can be implemented on the following platforms:

Windows platform | Limitations
Windows 7 or higher | -
Windows XP/Vista | -
Windows CE | No longer supported in PVI V3.0.3 and higher

Ethernet communication

PC requirements:

TCP/IP must be installed.

Using multiple network adapters on one PC:

How can you be sure that PVI uses the correct network card if two or more network adapters are located on the PC?

The subnet mask must be configured properly to ensure that the correct network adapter is used for communication. First an AND operation is executed with the IP address of the Modbus slave and the subnet mask of a network adapter. The network adapter whose IP address matches the result of this operation is used.

Example:

Device parameters: /IF=mbustcp
Station parameters: /DAIP=192.168.100.1
IPAdr NW1: 192.168.100.12 Subnet Mask: 255.255.255.0
IPAdr NW2: 192.168.101.12 Subnet Mask: 255.255.255.0
IPAdr Slave: 192,168,100.1

In this example, the first network adapter is used to communicate with the slave.

Line configuration

The FieldbusDESIGNER can be used to set up a Modbus system with all stations and modules, to configure modules and to specify I/O variables. The configuration file is generated from this project and contains all of the necessary data for the Modbus line. The file name of the generated file is ModbusConfig.xml, and the line searches for it under this name as long as no other configuration file was specified when setting up the line.

Station numbers 1 - 127 are configured with IP addresses operating bus connectors. This means that the bus connectors must be assigned an IP address using the Modbus toolbox. The assigned IP address must also be entered in the FieldbusDESIGNER for the respective bus connector. Station numbers 128 - 239 are for DHCP operation. The respective node number must be set on the bus connector, and the bus connector uses it to generate a host name ("brmb" + node number). This host name must be entered in the FieldbusDESIGNER for the respective bus connector. Changes made to the node number on the bus connector do not take effect until a restart.

Specifying the format of the configuration file

This configuration is optional, however it provides the following advantages:

  • The device object can list all defined stations. This makes it easy to set up a station as connection description using an entry in this list.
  • The configuration of the bus controller and the I/O modules can be completed automatically when necessary.
  • The station object can list all defined variables including data format.
  • Access to I/O channels is abstracted using a symbolic name (i.e. the user does not have to determine which address is assigned to a channel and changes to the process image resulting from changes to the module structure or module configuration have no effect on the user software.

If the FieldbusDESIGNER and the Modbus line are operated on the same computer, the FieldbusDESIGNER automatically copies this configuration file to the PVI configuration directory after the build. If the line is operated on a different computer, the file must be copied to the correct location manually. If this file is placed either in the PVI binary directory or in the configuration directory of the PVI line, the line loads it automatically. If the file needs to be renamed or placed in a different directory than the two just mentioned, the complete path for the file must be entered in the connection description when setting up the line.

The configuration directory of the PVI line should be taken from PviConfig.xml. The file can be found in the PVI binary directory.

Example: Defining the configuration directory in PviConfig.xml:

<PviServer>
  <StdCfg Path="..\Pvi\Cfg" />
</PviServer>

The line will run in a non-configured state if this file is not found in either of the two directories. In this mode, the bus connectors and the connected modules are not configured and are operated in the standard function model. Only the generic I/O variables are defined, and all other required I/O variables must be defined separately.

<< Previous Topic
MODBUS line

Start Page

Next Topic >>
MODBUS line object


MODBUS line object

The line is defined in the connection description of the line object including the required line parameters. Within the connection description, individual parameters are differentiated between using parameter identifiers. These parameter identifiers always begin with the "/" character.

Syntax of connection description:

/LN=<LineName> [/<Identifier1>=<ParameterValue> [/<Identifier2>=<ParameterValue> ... ]]

The /LN parameter is common to all line objects. All other parameters are dependent on the line being used. Line names are not case-sensitive. At least one empty space is to be entered between the individual parameter specifications.

The connection description must always be specified in quotation marks ("...") in the object description.

Connection description example:

CD="/LN=LNMODBUS"

The following table shows all parameters that can be defined for the Modbus line in the connection description of the line object.

Parameter | Settings | Description
/CFG | None | Optional specification of the path to the configuration file. The corresponding file absolutely must exist once this parameter has been specified, otherwise the setup of the line will be aborted with the corresponding error. If this parameter has not been specified, then a file with the name "ModusConfig.xml" is expected in certain directories. For a more detailed explanation, see Line configuration.

Connection description example:

CD="/LN=LNMODBUS"
CD="/LN=LNMODBUS /CFG=C:\Config\Modbus.cfg"

<< Previous Topic
MODBUS communication

Start Page

Next Topic >>
MODBUS device objects


MODBUS device objects

The communication device is determined with the Modbus device object.

The communication device is defined in the device object's connection description with the necessary device parameters. Within the connection description, individual parameters are differentiated between using parameter identifiers. These parameter identifiers always begin with the "/" character.

Syntax of connection description:

/IF=<DeviceName> [/<Identifier1>=<ParameterValue> [/<Identifier2>=<ParameterValue> ... ]]

The /IF parameter is common to all communication devices. All other parameters depend on the communication device being used. Device names are not case sensitive. At least one empty space is to be entered between the individual parameter specifications.

The connection description must always be specified in quotation marks ("...") in the object description.

Connection description example:

CD="/IF=MBUSTCP"

Modbus TCP device

The following table shows all parameters which can be defined for the Modbus TCP communication device in the device object's connection description.

Parameter | Value | Settings | Description
/IF | MBUSTCP | None | Value: "/IF=MBUSTCP"

Connection description example:

CD="/IF=MBUSTCP"

<< Previous Topic
MODBUS line object

Start Page

Next Topic >>
MODBUS station objects


MODBUS station objects

A Modbus station object configures the connection to a station.

A station object represents a Modbus TCP bus controller.

The station object is defined in the station's connection description with the necessary station parameters. Within the connection description, individual parameters are differentiated between using parameter identifiers. These parameter identifiers always begin with the "/" character.

Syntax of connection description:

/DAIP=<IPAddress> [/<Identifer1>=<ParameterValue> [/<Identifier2>=<ParameterValue> ... ]]

The connection description must always be specified in quotation marks ("...") in the object description.

Connection description example:

CD="192.168.100.1"

The following table shows all parameters which can be defined in a station object's connection description.

Parameter | Value | Settings | Description
/DAIP | IP address | None | Value: "/DAIP=192.168.100.1"
/PN | Port number | 502 | Value: "/PN=502"

Connection description example:

CD="/DAIP=192.168.100.1 /PN=502"

If the station with the specified IP address should be defined in the Modbus configuration file, the PN parameter is loaded from this file and does not need to be specified. If a parameter is specified, it will be ignored.

<< Previous Topic
MODBUS device objects

Start Page

Next Topic >>
MODBUS variable objects


Modbus variable objects

MODBUS variable object

A Modbus variable object represents an address range in the process image on the station. These types of objects allow the user to access the channels of the I/O modules on a station, to output statistic values or error counters and to initiate a station restart.

Syntax of connection description:

Single and array variables:

/RO=<variable name>

or

<variable name>

Element of an array variable:

/RO=<variable_name>[<index>]

or

<variable_name>[<index>]

If the variable name is defined as the /RO parameter, the connection description must always be specified in quotation marks ("...") in the object description. This name can be a defined variable, generic variable or a register address in the process image. These are not case-sensitive.

Param. | Value | Settings | Description
/RO | Variable name | None | Value: "/RO=Heating"
/VT | Data type | None | Value: "/VT=u16"
/VN | Number of elements | 1 | Value: "/VN=1"
/US | Attribute | rw | Value: "/AT=rw"

Connection description examples:

CD="/RO=Heating"
CD=DO[2]
CD="/RO=0x2400 /VT=u16 /AT=rw"

Defined variables

The defined variables are loaded from a configuration file when setting up a station. This configuration file is created in the AS configurator and contains the assignments of symbolic names for the corresponding register addresses in addition to the configuration of the bus controller and the modules. The data format of these pre-defined variables (i.e. data type, element number and attribute) is also determined in this configuration and cannot be changed by the user.

The symbolic names are specified in the I/O assignment of the AS configurator as shown in the following figure.

Therefore, the only thing left to do when setting up a variable object is to specify this symbolic name in the connection description (e.g. CD=Heating).

Generic variables

Some variables are automatically defined when setting up a station object if a connection with the hardware was able to be established. These variables are the cyclic data of the I/O modules stored in the process image. The variables are stored as array variables and their element number is determined by the type and number of modules present on the bus.

When setting up objects for generic variables, only the name with optional element index has to be specified (e.g. CD=AI or CD=DO[2]).

RO | FT | Description
AI | U16 | Analog input register
AO | U16 | Analog output register
DI | U8 | Digital input register
DO | U8 | Digital output register
NS | U16 | Network status
OS | U16 | Output status

Process image

The following table lists the memory areas in the process image with the permissible data types and access types for the corresponding address range. Refer to the bus controller specification to find out exactly how the individual memory areas are structured. Memory areas are automatically initialized and addresses are automatically assigned to the variables when operating a station with a configuration file.

Therefore, variables must only be set up using a memory address when operating a station without configuration or when setting up or changing the configuration from the software.

When setting up an object via the address, the correct address is required and the data format must be specified with data type, element number and attributes (e.g. CD="/RO=0x2400 /VT=u16 /AT=rw"). When setting up an object, the specified parameters are checked for validity and any occurring errors are reported. The address can be specified as a decimal or hexadecimal value.

RO | FT | AT | Comment
0x00000-0x007FF | U16, I16, U32, I32 | r | Analog inputs
0x00800-0x00FFF | U16, I16, U32, I32 | rw | Analog outputs
0x01000-0x01FFF | U16, I16, U32, I32 | rw | System parameters
0x02000-0x023FF | U16, I16, U32, I32 | r | Digital inputs (word-oriented)
0x02400-0x027FF | U16, I16, U32, I32 | rw | Digital outputs (word-oriented)
0x02800-0x029FF | U16, I16 | r | X2X network status
0x02A00-0x02BFF | U16, I16 | r | Output status
0x0A000-0x0AFCF | U16, I16, U32, I32 | rw | Module data sorted by index
0x0B000-0x0BFFF | U16, I16, U32, I32 | rw | Module data sorted by parameter
0x0C000-0x0DFFF | U16, I16, U32, I32 | rw | Module configuration
0x10000-0x11FFF | U8, I8, U16, I16, U32, I32, BOOLEAN | r | Digital inputs (bit-oriented)
0x20000-0x21FFF | U8, I8, U16, I16, U32, I32, BOOLEAN | rw | Digital outputs (bit-oriented)

<< Previous Topic
MODBUS station objects

Start Page

Next Topic >>
Configuration file


Modbus line configuration

Configuration file

This section contains a detailed description of the Modbus configuration file format, in case it must be created manually or by another automated process and the Fieldbus Designer cannot be used.

In order for a configuration file to be created manually, additional documents from the following list may be required.

  • X20BC0087 Bus Connector User's Manual
  • User's Manuals for the X20 modules used

Specification of the file format

The following description refers to Version 2 of the configuration format. The previous version can still be read by the line, however it doesn't contain any configuration data, and is therefore no longer described in detail. The Version attribute must be set to 2, since the line will otherwise assume Version 1 and be unable to interpret the file.

The configuration contains a <Stations> element with which 1 - 239 station configurations can be nested.

Example of a configuration file:

<ModbusPVIVersion="2">
    <Stations>

Station description 1 <!-- Section for the first station -->
 Station description 2 <!-- Section for the second station -->
 ......
 Station description n <!-- Section for the nth station -->

    </Stations>
</ModbusPVI>

Station description

The station description contains all the parameters for a Modbus node. The description consists of the configuration data and the variable mapping.

The <Station> element can have the following attributes:

  • DAIP specifies the IP address or hostname of the device to which this station configuration is assigned.
  • PN (optional) defines the port number on which the Modbus bus connector waits for connection requests. If this value is not specified, the default Modbus port 502 is used.

Example of a station description:

<StationDAIP="10.43.150.11"PN="502">

     Station configuration

    I/O variable mapping

</Station>

Station configuration

The station configuration contains the system parameters for the bus connector and the module configuration.

The <Configuration> element can have the following attributes:

  • CheckSum contains the checksum for the configuration data in this section. This line uses this checksum to determine the need to transfer the configuration. The FieldbusDESIGNER calculates this checksum using the CRC32 algorithm and the polynomial 0xedb8832 with recursive inclusion of all the attributes of all subordinate elements. Any custom implementation must ensure that changes to the configuration data also result in a change to the checksum in order for the configuration to actually be sent to the bus connector. The checksum can be entered as a decimal or hexadecimal value with a leading "0x".

Example of a station configuration:

<ConfigurationCheckSum="0x31cdba6">
    System parameters

    Module configuration

</Configuration>

System parameters

This section contains the system parameters of the bus connector, which are stored in the flash memory. If the file is created with the FieldbusDESIGNER, this section contains the parameters that are set on the configuration page of the bus connector. The list of all available system parameters and their addresses, data types, and possible values can be found in the description of the X20BC0087 bus connector.

All system values are nested in a <SystemValue> element. The <SystemValue> element has no attributes.

The following list describes the attributes to be entered for a <SystemValue> element:

  • RO defines the runtime object's name. The Register ID is used for this name.
  • RA is the address of the register on the bus controller. This value can be entered as a decimal or hexadecimal value with a leading "0x".
  • VT is the data type of the parameter. The following table lists the possible data types of a system parameter.
    • u16 for a 2 byte unsigned integer
    • u32 for a 4 byte unsigned integer
  • Value defines the value that must be written to the register on the bus controller.

Example of a list of system parameters:

<SystemValues>
    <SystemValueRO="TcpLifeTime"RA="0x01010"VT="u16"Value="30"/>
    <SystemValueRO="MTU"RA="0x01011"VT="u16"Value="1500"/>
    <SystemValueRO="WatchdogMode"RA="0x01043"VT="u16"Value="0xC0"/>
    <SystemValueRO="X2XBusConfig"RA="0x01012"VT="u16"Value="0xC0"/>
    <SystemValueRO="IoAddressCheck"RA="0x01182"VT="u16"Value="0xC1"/>
    <SystemValueRO="ModuleInitDelay"RA="0x01181"VT="u16"Value="0"/>
</SystemValues>

Module configuration

This section contains the module parameters and the configuration of the module register of all the modules.

Example of a module configuration:

<ModuleConfig>

    <Modules>
Parameter module 1 <!-- Parameter list for module 1 -->
Parameter module 2 <!-- Parameter list for module 2 -->
 ......
Parameter module n <!-- Parameter list for module n -->
    </Modules>

    <RegisterConfigs>
Register configuration 1 <!-- Register configuration 1 -->
Register configuration 2 <!-- Register configuration 2 -->
 ......
Register configuration n <!-- Register configuration n -->
    </RegisterConfigs>

</ModuleConfig>

Module parameters

This section defines the parameters of an individual module. A <Parameter> element is created for each parameter. All module parameters are nested in a <Module> element.

The <Module> element can have the following attributes:

  • ST defines the slot where the module is located. The value of this attribute must be between 1 - 239, and must be unique within a module parameter section.

The <Parameter> element can have the following attributes:

  • RO is given the name of the parameter.
  • RA defines the address of the parameter.
  • VT is the data type of the parameter. The following data types are permitted for a module parameter.
    • u16 for a 2 byte unsigned integer
    • u32 for a 4 byte unsigned integer
  • Value defines the value of the parameter.

For a list of available module parameters, detailed descriptions of them, and their possible values, see the description of the X20BC0087 bus connector. The following parameters must be defined in this section:

  • ProductCode defines the ID of the module expected in this slot. The product codes can be found in the descriptions of the individual modules. This value can be entered as a decimal or hexadecimal value with a leading "0x". If this parameter is set to 0, there is no check whether the correct module is connected.
  • FunctionModel defines the function model in which the module will be operated. The function models of a module can also be found in the descriptions of the respective modules.
  • ConfigIndex is the reference to the start address of the module's register configuration. Permitted values range from 0xC000 to 0xDFFF. The values can also be entered in decimal format.
  • ConfigLength is the number of entries in the register configuration for this module.

Example of a list of module parameters:

<ModuleST="1">
    <ParameterRO="ProductCode"RA="0x0A008"VT="u16"Value="8076"/>
    <ParameterRO="FunctionModel"RA="0x0A009"VT="u16"Value="0"/>
    <ParameterRO="ConfigIndex"RA="0x0A00A"VT="u16"Value="0x0C000"/>
    <ParameterRO="ConfigLength"RA="0x0A00B"VT="u16"Value="1"/>
</Module>

Register configuration

This section defines a register configuration for one or more modules. A <Register> element is created for each register configured. These elements are nested in a <RegisterConfig> element.

The <RegisterConfig> element must have the following attributes:

  • ConfigIndex defines the start address for this configuration on the bus connector. The corresponding module parameter references this address. If more than one module has the same register configuration, each of them can reference the same configuration area.

A more detailed description of the available registers and their configuration can be found in the descriptions of the respective modules.

The <Register> element can have the following attributes:

  • Number defines the register number (address). This value can be entered as a decimal or hexadecimal value with a leading "0x".
  • Type defines the register type. The following register types are permitted:
    • 0 ... Dynamic cyclic input
    • 1 ... Dynamic cyclic output
    • 2 ... Fixed cyclic input
    • 3 ... Fixed cyclic output
    • 4 ... Acyclic input
    • 5 ... Acyclic output
  • Size defines the size of the register in bytes. The values 1, 2 and 4 are permitted.
  • Value defines the starting value that must be written to the register in this configuration.

Example of a list of register configurations:

<RegisterConfigConfigIndex="0x0C004">
    <RegisterNumber="0"Type="3"Size="1"Value="0"/>
    <RegisterNumber="1"Type="3"Size="1"Value="0"/>
    <RegisterNumber="1"Type="2"Size="1"Value="0"/>
    <RegisterNumber="2"Type="2"Size="1"Value="0"/>
</RegisterConfig>

I/O variable mapping

This section defines all the modules to which variables are mapped. This mapping takes place in a separate section to maintain a strict distinction from the module configuration and prevent the variables from affecting the checksum. All modules with mapped variables are nested in a <VariableAssignment> element.

The <VariableAssignment> element has no attributes.

Example of a mapping list:

<VariableAssignment>

Module 1 <!-- Assignments for module 1 -->
Module 2 <!-- Assignments for module 2 -->
 ......
Module n <!-- Assignments for module n -->

</VariableAssignment>

Module assignment

This section defines all the registers of a module to which variables are mapped. All registers are nested in a <Module> element.

The <Module> element requires the following attributes:

  • Hardware (optional) with the hardware name of the module
  • ST with the slot number of the module. The value 0 stands for the bus connector and 1- n for the module connected to it.

Example of a mapping list for a module:

<ModuleHardware="X20DO6529"ST="2">

Register 1 <!-- Assignments for register 1 -->
Register 2 <!-- Assignments for register 2 -->
......
Register n <!-- Assignments for register n -->

</Module>

Register mapping

This section defines the mapping of variables to an individual register. A <Variable> element is created for each mapping. These mappings are nested in a <Register> element.

The <Register> element requires the following attributes:

  • ID for unique identification of a register within a module. The FieldbusDESIGNER takes this value from the runtime configuration. For files that were created manually or using other methods, this value can simply be incremented or set with the register address.
  • RT defines the register type. The line supports the following register types:
    • 1 ... Dynamic cyclic
    • 2 ... Fixed cyclic
    • 3 ... Acyclic
    • 4 ... Pseudocyclic
    • 5 ... Info register for constant values that only need to be read by the module once, and are then saved in the line.
    • 6 ... ModuleOk Flag
  • Value defines the start value of the register. This value is usually the same as the value defined in the register configuration. This value only has meaning for bit access to acyclic and pseudocyclic registers, since in these cases the current value is always needed in order to prevent read access so that the value to be written can be determined.

Each <Variable> element can have the following attributes:

  • RA defines the address of the register. This value can be entered as a decimal or hexadecimal value with a leading "0x". The available address areas and their meaning can be found in the description of the bus connector. For register types 3 and 4, the address of the module register is entered here directly.
  • VT defines the data type of the variable. The line checks whether the specified data type is permitted for the respective address. The following data types are possible for a variable:
    • Boolean for digital channels
    • u8 for an unsigned byte channel
    • i8 for a signed byte channel
    • u16 for an unsigned 2 byte channel
    • i16 for a signed 2 byte channel
    • u32 for an unsigned 4 byte channel
    • i32 for a signed 4 byte channel
  • VN (optional) defines the number of elements in an array. If an array is defined, it can be accessed with Name[index].
  • AT defines a variable's PVI attribute. The line checks whether an attribute is permitted for the respective address area, and if necessary produces a corresponding error message. A list of attributes possible for variables can be found in the PVI documentation. In most cases, however, "r" for inputs and "rw" for outputs is sufficient.
  • Flags (optional) to define additional options for the variable. Possible flags include:
    • "s" for single variables, which can only be accessed with a single register function. Required for special control registers of the bus connector.
  • Bit (optional) defines the bit offset of a digital channel within the assigned register. This is only relevant for register types 3 and 4.
  • RO defines the symbolic name that must be specified by the application when creating a variable.

Example of a mapping list for a register:

<RegisterID="1"RT="3"Value="0">
    <VariableRA="0x20000"VT="boolean"AT="rw"Bit="0"RO="Fan"/>
    <VariableRA="0x20001"VT="boolean"AT="rw"Bit="1"RO="Heating"/>
    <VariableRA="0x20002"VT="boolean"AT="rw"Bit="2"RO="Light"/>
</Register>

<< Previous Topic
MODBUS variable objects

Start Page

Next Topic >>
MININET line


MININET line

The MININET line uses the MININET protocol and is primarily intended for communication with B&R MULTI/MIDI/MINI and compact (SG2) controllers. In principle, it is also possible to communicate with SG3 and SG4 controllers (System 2000) using Mininet. However, the NET2000 or INA2000 line is more suitable for this.

The following topics are covered in this section:

  • MININET process objects
  • MININET access types
  • MININET event types
  • MININET communication

MININET process objects

A line object, a device object, and a station object are all needed to establish a communication connection to a MININET station.

Process objects in the MININET line:

Name | Type | Connection | Usage
Line object | Line | "LNMINI" | MININET line
Device object | Device | Device parameter | Represents the communication device being used
Station object | Station | Station number | Represents a MININET station (PLC) in a network
CPU object | CPU |  | Can be specified, but not required.
Module object | Modules |  | Can be specified, but not required.
Task object | Task |  | Can be specified, but not required.
Variable object | Pvar | Variable name | Represents a variable on the PLC

Object structure for MININET process objects:

MININET access types

The following table shows an overview of all access types which are regulated via a line. All access types not listed here as well as access types to the PVI base object are executed by PVI Manager and therefore work independently of the line being used. The corresponding process object type is listed in the "Type" column.

Access types | Type | Special features
POBJ_ACC_VERSION | Line Device | Line object: Version of the line DLL. Device object: Version of the INA frame DLL
POBJ_ACC_LIST_EXTERN | Line | List of all installed MININET devices
POBJ_ACC_DATA | Pvar |
POBJ_ACC_STATUS |  | Not supported
POBJ_ACC_TYPE_EXTERN |  | Not supported
POBJ_ACC_UPLOAD |  | Not supported
POBJ_ACC_DOWNLOAD |  | Not supported
POBJ_ACC_DATE_TIME |  | Not supported
POBJ_ACC_MEM_DELETE |  | Not supported
POBJ_ACC_MEM_INFO |  | Not supported
POBJ_ACC_MOD_TYPE |  | Not supported
POBJ_ACC_UPLOAD_STM |  | Not supported
POBJ_ACC_DOWNLOAD_STM |  | Not supported
POBJ_ACC_MOD_DATA |  | Not supported
POBJ_ACC_MOD_DELETE |  | Not supported
POBJ_ACC_LIST_STATION |  | Not supported
POBJ_ACC_LIST_CPU |  | Not supported
POBJ_ACC_LIST_MODULE |  | Not supported
POBJ_ACC_LIST_TASK |  | Not supported
POBJ_ACC_LIST_PVAR |  | Not supported
POBJ_ACC_CPU_INFO |  | Not supported
Access type > 255 |  | Not supported

MININET event types

The following table shows an overview of all event types which can be generated from a line. All event types which are not listed are generated by PVI Manager and therefore work independently of the line being used.

Event types | Special features
POBJ_EVENT_STATUS | Not supported
POBJ_EVENT_PROCEEDING | Not supported
Event type > 255 | Not supported

<< Previous Topic
Configuration file

Start Page

Next Topic >>
MININET communication


MININET communication

MININET communication is only supported on serial devices. Serial communication can be operated as a point-to-point connection (RS232) or as a network connection (RS485).

MININET is a master/slave protocol where the PVI MININET line carries out the functions of the master. A multi-master function is not possible via the MININET protocol.

PC requirements:

All necessary components are installed with PVI Setup.

The MININET line can be operated on the following platforms:

Windows platform | Limitations
Windows 7 or higher | -
Windows NT/2000/XP/Vista | No verification for Windows NT/2000 in PVI V4.0 or higher.

Requirements for SG2 controllers (MULTI/MIDI/MINI and Compact):

B&R standard software (model number: SWSPSCOM01-0 for 3.5")

Function blocks:

 | PLC mode | Hardware |  | Max. baud rate
DFMN.MSL | NETWORK ADAPTER MININET V0.01 |  |  |
DPMN.PRG | Mininet Driver NP02 / PP40 | Network p. NP02 |  | 19200
DTMN.TAB | Configuration Table for DFMN |  |  |
NDSA.MSL | MININET - SLAVE DRIVER A V2.40 | PIFA/PIF1/PIF3 |  | 7200
NDSB.MSL | MININET - SLAVE DRIVER B V2.15 | PP40/CP31/.. |  | 19200
NDSC.MSL | MININET - SLAVE DRIVER C V2.40 | CP63/CP80/PP60 |  | 19200
NDSD.MSL | MININET - SLAVE DRIVER D V0.00 | PRTS without FIFO |  | 19200
NDSE.MSL | MININET - SLAVE DRIVER E V0.00 | PRTS with FIFO |  | 19200
NPLS.MSL | MININET - SLAVE PLC V2.04 |  |  |
MDSA.MSL | MININET/PLC - SLAVE A V2.30 | PIFA/PIF1/PIF3 | =NDSA + NPLS | 7200
MDSB.MSL | MININET/PLC - SLAVE B V2.15 | PP40/CP31/.. | =NDSB + NPLS | 19200
MDSC.MSL | MININET/PLC - SLAVE C V2.50 | CP63/CP80/PP60 | =NDSC + NPLS | 19200
 | SPOIO mode | Hardware |  | Max. baud rate
NDSA.MSL | MININET - SLAVE DRIVER A V2.40 | PIFA/PIF1/PIF3 |  | 7200
NDSB.MSL | MININET - SLAVE DRIVER B V2.15 | PP40/CP31/.. |  | 19200
NDSC.MSL | MININET - SLAVE DRIVER C V2.40 | CP63/CP80/PP60 |  | 19200
NDSD.MSL | MININET - SLAVE DRIVER D V0.00 | PRTS without FIFO |  | 19200
NDSE.MSL | MININET - SLAVE DRIVER E V0.00 | PRTS with FIFO |  | 19200
NSPO.MSL | MININET - SLAVE SPOIO PLC V2.04 |  |  |
MSSA.MSL | MININET/SPOIO - SLAVE A V2.41 | PIFA/PIF1/PIF3 | =NDSA + NSPO | 7200
MSSB.MSL | MININET/SPOIO - SLAVE B V2.21 | PP40/CP31/.. | =NDSB + NSPO | 19200
MSSC.MSL | MININET/SPOIO - SLAVE C V2.60 | CP63/CP80/PP60 | =NDSC + NSPO | 19200

Requirements for SG3/SG4 controllers (System 2000):

PLC operating system V1.91 and higher

dvframe.br starting from V3.30 (included starting with PG2000 V2.39 / model no. 1A2000.01)
drv_mn.slb starting from V1.30 (model number: 1A2224.01)

RS485 network:

A maximum of 32 stations can be connected to a bus.

Executed as an RS485 twisted pair cable, shielded. Cross-section: min. 0.5 mm². Wave impedance: 120 ohms. Terminating resistor: 120 ohms on both ends. Length: maximum 1,200 meters. Maximum line resistance: 50 ohms per wire.

The cabling for the RS485 network can only be made using a bus structure. The bus connection can be made either directly or using a maximum 0,25 m long branch line.

<< Previous Topic
MININET line

Start Page

Next Topic >>
MININET device objects


MININET device objects

The communication device being used is determined with the MININET device object. The communication device with the necessary device parameters and MININET protocol parameters are defined in the connection description of the device object. Within the connection description, individual parameters are differentiated between using parameter identifiers. These parameter identifiers always begin with the "/" character.

Connection description syntax:

/IF=<DeviceName> [/<Identifier1>=<ParameterValue> [/<Identifier2>=<ParameterValue> ... ]]

Device names are not case sensitive, and at least one space character must be between each parameter specification.

The connection description must always be specified in quotation marks ("...") in the object description.

The following table shows all parameters which can be defined in a device object's connection description.

Par. Values Settings Description
/IF com1 ...
comX 		None By default: COM1 to COM4. With some serial interface cards or adapters, it is possible to have more than COM4.
Example: "/IF=com1"
/BD 1200,
1800,
2400,
3600,
4800,
7200,
9600,
19200 		57600 Baud rate in bits per second
Example: "/BD=19200"
/RS -1, 0,
232,
422,
485 		232 Sets the RS232 or RS422 protocol.
Example: "/RS=485"

This parameter sets the flow control of the CTS (clear to send) and RTS (request to send) lines of the serial interface.
Possible parameter values:
= -1: PVI doesn't modify the current setting (see the interface device properties) of the CTS/RTS flow control.
= 0: Always shut off the RTS line (disables RTS flow control).
= 232: Use RTS handshake.
= 422: Always turn on the RTS line.
= 485: Turn on the RTS line at the beginning of a transfer or during the transfer.
CTS flow control is disabled whenever the parameter value >= 0.

Many USB/serial adapters (USB to serial interface) do not handle CTS/RTS flow control correctly. The parameter "/RS=0" must be specified to establish an RS232 connection using these adapters.

/PA 0 - 4 1 Parity setting
0=NOPARITY
1=ODDPARITY
2=EVENPARITY
3=MARKPARITY
4=SPACEPARITY

Default setting for MININET communication is "/PA=0".
/IT 0 - 60000 20 Interval timeout (msec)
Defined as the maximum time that can pass between receiving two consecutive characters. The MININET protocol uses this time to recognize the end of a received frame.
Example: "/IT=40"
/TT 0 - 60000 3000 Timeout for requests (ms)
This value must correspond at least to the maximum response time of the controller + the transfer time of 256 characters (depends on the baud rate).
Example: "/TT=512"
/RETRY 1 - 255 3 Retry counter for errors
After a request is sent, a valid response must be received with the time /TT. Otherwise, the procedure is repeated. The maximum number of retries can be modified with /RETRY. An error is only reported after the last retry takes place.
Example: "/RETRY=2"

Connection description example:

CD="/IF=com1 /RS=485 /BD=19200 /PA=0 /IT=20 /TT=500 /RETRY=2"

<< Previous Topic
MININET communication

Start Page

Next Topic >>
MININET station objects


MININET station objects

The MININET station object defines a MININET station (controller) in a network.

The station number of the MININET station (controller) must be specified in the connection description. It is also possible to set the SPOIO protocol type.

The values 17 - 31, 33 - 47, and 49 - 63 are allowed as station numbers.

Connection description syntax:

/CN=<StationNumber> [/MODE=<ProtocolType>]

or

<StationNumber> [/MODE=<ProtocolType>]

Par. | Values | Settings | Example | Description
/MODE | SPS, SPOIO | PLC | "/MODE=SPOIO" | Protocol type used on the controller The SPOIO protocol type allows simultaneous read and write data transfer of several data blocks in a frame. In contrast, only one request can be transferred in a frame with the SPS protocol type.

If at least one parameter is defined, the connection description must always be specified in quotation marks ("...") in the object description.

Connection description examples:

CD="/CN=17 /MODE=SPOIO"
CD=17

<< Previous Topic
MININET device objects

Start Page

Next Topic >>
MININET variable objects


MININET variable objects

The data format of the variable object is not given by the MININET line. It has to be defined by the user. The total length of the process variable cannot exceed the maximum length of a MININET frame (240 bytes).

A counter (register) or flag is defined for the controller in the connection description.

Connection description syntax:

/RO=<Connection>

or

<Connection>

Memory type | Connection | Min. offset | Max. offset | Example
Counter | C<Offset> or R<Offset> | 0000 | 7095 | "C1000"
Flag *) | M<Offset> or F<Offset> | 000 | 799 | "M137"
*) Can only be used in SPOIO mode.

If the connection is defined as the /RO parameter, the connection description must always be specified in quotation marks ("...") in the object description.

Example of object description:

CD="/RO=C926" VT=i16
CD=C926 VT=i16

The memory range beginning with Counter 926 is read and written as a 2-byte integer value.

<< Previous Topic
MININET station objects

Start Page

Next Topic >>
Diagnostics


Diagnostics

PVI supports the following diagnostic procedures:

Procedure | Description
Snapshot Function | Diagnoses operating states of PVI objects from PVI Manager
Data logger | Diagnoses sequences in individual PVI components

<< Previous Topic
MININET variable objects

Start Page

Next Topic >>
Snapshot Function


Snapshot files

Snapshot Function

The Snapshot function is a useful tool for diagnosing the operational state of PVI Manager PVI objects.

The Snapshot function can be triggered via PVI Monitor (Snapshot function) or from a PVI application (access type POBJ_ACC_SNAPSHOT). In both cases, a list of all PVI objects along with their status and a list of all registered clients as text (ASCII) is written to a file. When using access type POBJ_ACC_SNAPSHOT you can also write only a smaller group of PVI objects.

The Snapshot file always shows an instantaneous image of the object situation at the moment the function is triggered. All other functions in PVI Manager are blocked while the Snapshot function is carried out. This secures the consistency of the Snapshot data, but can also lead to immense timing variations when there are large quantities of data being handled by PVI Manager.

The contents of the snapshot file can be viewed and analyzed with any text editor or the Snapshot Viewer integrated into PVI Monitor.

Structure of the snapshot file

Snapshot information is divided into 5 sections:

  1. General PVI information
  2. List of all registered communication instances (clients)
  3. List of link objects
  4. List of process objects
  5. List of service objects

Snapshot information is divided into lines. Depending on the first character in the line, the rest of the line is interpreted as follows:

Character | Description
'*' | Comment line with general PVI information
'>' | Time stamp (date and time) of the Snapshot information
':' | Indicates the start of a list entry
' ' | A space character indicates a following line of a list entry

At the beginning of each list entry is a code with an identification number (ID) directly after the ":" character. This ID number is unique within a list and is displayed as a hex number.

ID | Description
CId | Entry for registered communication instance (client)
C | Entry for a link object
P | Entry for a process object
S | Entry for a service object

The assignment of individual objects is also displayed with the ID number. Several process objects can be assigned to one service object, and several link objects can be assigned to one process object. The following image shows the codes which are responsible for object assignment.

The ID numbers used in the Snapshot file and the ID numbers used in the PVI Data Logger by the main components are identical.

The list of all registered communication instances, the list of link objects, and the list of process objects are all of particular significance to the user.

General PVI information

Comment lines containing general PVI information are output at the beginning of the Snapshot file. The first line contains information about the operating system platform and the system operating mode of PVI Manager. The second line displays the file version and product version of PVI Manager. The next few lines contain information about how PVI Manager properties are set, provided they are different from the default settings.

Communication instance (client) entry

Syntax:

:CId=<ID> Name="<Name>" ComType=<Num> ProcID=<Num> PriorClass=<Num> [Platform=<Platform>] COMT=<Sec> RETR=<Sec> PT=<Sec> LM=<Cnt>

Parameter:

ID | Description
CId | ID number of the communication instance (client)
Name | Name of the application process
ComType | Communication type: 0 ... Local, 1 ... Remote.
ProcID | ID of the user process in hex format
PriorClass | Priority class of the user process
Platform | Platform where the user processes are running
COMT | Setting being used for the communication timeout in seconds (COMT initialization parameter or "Timeout" argument in the PviInitialize or PviXInitialize function)
RETR | Setting being used for the retry time for PVICOM user messages in seconds (RETR initialization parameter or "RetryTime" argument in the PviInitialize or PviXInitialize function)
PT | Setting being used for the process timeout in seconds (PT initialization parameter in the PviInitialize or PviXInitialize function)
LM | Setting being used for limiting user messages (LM initialization parameter in the PviInitialize or PviXInitialize function)

Example:

:CId=599a0005 Name="PviDemo.exe" ComType=0 ProcID=fff2e8ab PriorClass=32 COMT=10 RETR=0 PT=0 LM=1

Link object entry

Syntax:

:C=<ID> P=<ID> CId=<ID>
Desc: <LinkObjectDescription>
State: <Act/Idl> Msg=(<Msg>) [E=<Code>] [LastE=<Code>] Ctr=<State> DCond=<State>

Parameter:

ID | Description
C | ID number of the link object
P | ID number of the assigned process object
CId | ID number of the communication instance (client) which created the link object
Desc: | Code for lines with the current link object property settings. The parameters output here correspond to those of the link object description.
State: | Code for lines with a link object status
<Act/Idl> | Current active status: "Act": active, "Idl": inactive (idle)
Msg | User message assigned to the link object to signal event data Windows message: W:<WindowHandle>,<MessageNumber>,<MessageParameter> message function: F:<MessageHandle>,<MessageParameter> Callback with data: CBD:<CallbackPointer>,< MessageParameter> Callback without data: CB:<CallbackPointer>,<MessageParameter> Asynchronous callback: CBA:<CallbackPointer>,<MessageParameter> "Msg=(NULL)" is output if no user message is defined.
E LastE | If the link object is in an error state, then the error code is output with "E=<Code>". "LastE=<Code>" shows the last occurring error. The link object is no longer in an error state here.
Ctr DCond | This displays additional internal operating modes for the link object. These operating modes cannot be interpreted by the user.

Example:

:C=0091 P=00e11f60 CId=599a0005
Desc: EV=de LT=prc VT=string VL=80 VN=1
State: Act Msg=(W:000009a0,1026,1001) LastE=0 Ctr=12 DCond=20

Process object entry

Syntax:

:P=<ID>(<HID>) S=<ID> Pn=<PathName> OT=<Type>
Desc: <ProcessObjectDescription>
State: <Act/Idl>,<WState>[,Temp] [E=<Code>] Ctr=<State> DCond=<State>

Parameter:

ID | Description
P | ID number of the process object. The ID number of the higher-level process object in the object structure is output in parentheses.
S | ID number of the assigned service object. If no service objects are assigned to the process object (e.g. for internal process objects), then ID number 0 (null) is output.
Pn | Path name of the process object
OT | Object type of the process object
Desc: | Code for lines with the current process object property settings. The parameters output here correspond to those of the process object description.
State: | ID for lines with specifications regarding the process object status.
<Act/Idl> | Current active status: "Act": active, "Idl": inactive (idle)
<WState> | Current operating state: "NotRdy": not ready, "Rdy": ready, "Err": error. The following value in parentheses shows the operating state in binary format.
Temp | This displays a temporary process object.
E | If the process object is in an error state, then the error code is output with "E=<Code>".
Ctr DCond | This displays additional internal operating modes for the process object. These operating modes cannot be interpreted by the user.

Example:

:P=00e11f60(00e10180) S=0082 Pn=@Pvi/LNINA2/COM2/CPU/Pvar1 OT=Pvar
Desc: CD="PV1" AT=rw RF=250 VT=i32 VL=4 VN=1
State: Act,Rdy(1),Temp Ctr=03 DCond=21

Service object entry

Syntax:

:S=<ID>(<HID>) L=<ID> Pn=<PathName> OT=<Type>
State: <Act/Idl>,<WState> [E=<Code>] [AT=<Mask>] [RF=<Num>] [Ev=<Mask>] [CdP=<ID>] [FrP=<ID>] [HyP=<ID>] Ctr=<State> PrL=<State> StL=<State>

Parameter:

ID | Description
S | ID number of the service object. The ID number of the higher-level service object in the object structure is output in parentheses.
L | Identification number of the assigned object within the line This ID number is used in the PVI logger output for the line.
Pn | Path name of the service object. Unlike the process object, the path name is formed from the connection name here.
OT | Object type of the service object
State: | ID for lines with specifications regarding the service object status
<Act/Idl> | Current active status: "Act": active, "Idl": inactive (idle)
<WState> | Current operating state: "NotRdy": not ready, "Rdy": ready, "Err": error. The following value in parentheses shows the operating state in binary format.
E | If the service object is in an error state, then the error code is output with "E=<Code>".
AT | Shows the object attributes for the service object (only for variable objects). "r": Allows read access "w": Allows write access "e": PLC event operation.
RF | The refresh time in ms being used for the service object (only for variable objects)
Ev | Enabling mask for events in the line.
CdP | Identification number of the process object for the connection description
FrP | Identification number of the process object for the data format (only for variable objects)
HyP | Identification number of the process object for the hysteresis (only for variable objects)
Ctr PrL StL | This displays additional internal operating modes for the service object. These operating modes cannot be interpreted by the user.

Example:

:S=0082(0081) L=016b0360 Pn=lnina2/com2/null/test/PV1 OT=Pvar
 State: Act,Rdy(1) AT=rw RF=250 CdP=00e11f60 FrP=00e11f60 Ctr=9e PrL=07 StL=02

<< Previous Topic
Diagnostics

Start Page

Next Topic >>
Data logger


Data logger

The PVI Data Logger is a useful tool for diagnosing sequences in PVI components.

Unlike the Snapshot function, the Data Logger records the timing of processes in the individual PVI layers. The logging output of PVI components are primarily intended for B&R to analyze problems. However, the outputs of some components can also provide users with useful information.

PVI components use the Data Logger to write text (ASCII) information to a file during runtime. This file is handled as a ring buffer. This means: If the end of the file is reached when writing, then the write pointer is set to zero and output continues at the beginning of the file. The size of the ring buffer corresponds to the adjustable file size. Each PVI component uses its own logger file. A timestamp given with each logger entry provides a time overview of entries in the various files.

Logger output requires quite a bit of computing time. Depending on the amount of information being output, the Data Logger can greatly affect the timing of PVI components. Because of this, a warning appears on the screen when PVI Manager is started and the Data Logger is enabled. This warning cannot be turned off.

The PVI Data Logger is controlled via the Windows registry database and can be configured using thePVI Monitor. The approach to and effects of logger parameters are described in the Setting up the Data Logger section. By default, the Data Logger is disabled for all components.

A component key can be created for each PVI component with logger output under the "HKEY_LOCAL_MACHINE\SOFTWARE\BR_Automation\Pvi\DataLogger" key. The name of a component key is comprised of the process context, the component's filename, and an optional section. The logger settings for the components are stored here in these individual keys.

The PVI components with logger output can be found in the "PVI components with logger output" table.

The following is an overview of all registry entries of the PVI Data Logger.

DataLogger
--> Mode         ... global Logging-Mode
--> Time         ... global Timestamp format
--> Verbose      ... global Verbose-Mode
--> <Component>  ... Key: Logging component
    --> Mode         ... Logging-Mode
    --> Time         ... Timestamp format
    --> Verbose      ... Verbose-Mode (0/1)
    --> LineLen      ... maximum length of a text line in characters
    --> DumpLen      ... maximum length of a hex dump output in bytes
    --> LogPath      ... Path of logger file
    --> LogSize      ... Size of the logger file in bytes
    --> LogBackup    ... Number of logger backup files
    --> BreakMode    ... Break function (0/1)
    --> BreakTime    ... Break delay
    --> BreakStr     ... break expression

Example of a registry file:

[HKEY_LOCAL_MACHINE\SOFTWARE\BR_Automation\Pvi\DataLogger]
"Mode"=dword:00000000
"Time"=dword:00000001
"Verbose"=dword:00000001

[HKEY_LOCAL_MACHINE\SOFTWARE\BR_Automation\PVI\DataLogger\PviDemo.exe/PviCom.dll/Client]
"Mode"=dword:00000002
"Time"=dword:00000002
"Verbose"=dword:00000001
"LineLen"=dword:00000200
"DumpLen"=dword:00001000
"LogPath"="C:\\Temp\\PviLog\\PviDemo_Cl.log"
"LogSize"=dword:000a0000
"LogBackup"=dword:00000001
"BreakMode"=dword:00000000

[HKEY_LOCAL_MACHINE\SOFTWARE\BR_Automation\PVI\DataLogger\PviMan.exe]
"Mode"=dword:00000003
"Time"=dword:00000002
"Verbose"=dword:00000001
"LineLen"=dword:00000200
"DumpLen"=dword:00001000
"LogPath"="C:\\Temp\\PviLog\\PviMan.log"
"LogSize"=dword:00100000
"LogBackup"=dword:00000000
"BreakMode"=dword:00000001
"BreakTime"=dword:000003e8
"BreakStr"="Ty=11"

PVI components with logger output

The most important PVI components with Data Logger support are listed in the following table. Along with the verbose mode, the logging mode determines the extent of logger output.

Component | Description
<Prog>/PviCom.dll/Client or <Prog>/PviCom64.dll/Client | Logger output for the PVICOM user interface: Logging mode "Log Error": All occurring system errors and errors reported to the application are logged. Logging mode "Log Main": Logs all function calls from the PVICOM user interface and user messages which are triggered. In addition, a hex dump of all data is output with the verbose mode. Logging mode "Log Details": The communication with PVI Manager is logged from the point of view of the client. The complete file name of the application process is used for <Prog>. The name of registered PVI applications can also be taken from the list of communication instances in the Snapshot file.
PviMan.exe | Default logger output of PVI Manager: Logging mode "Log Error": All system errors which occur when requests are executed are logged along with errors reported to the application. Logging mode "Log Main": All requests, responses, and events from and to PVI applications are logged. In addition, a hex dump of all data is output with the verbose mode. Logging mode "Log Details": Communication with the connected line is logged from the point of view of PVI Manager.
PviMan.exe/System | System logger output of PVI Manager: Logging mode "Log Error": All system errors which occur in operating system functions of PVI Manager are logged. Logging mode "Log Main": Logging of the program flow of operating system functions during initialization or deinitialization as well as in operation as an NT service. Logging of installation and deinstallation as a Windows NT service.
PviMan.exe/LnAnsl.dll | Logger output of the ANSL line: Logging mode "Log Error": Logging for errors that occur within the ANSL line Logging mode "Log Main": Logging for the line / PVI Manager interface (line interface) and ANSL connection management. In addition, a hex dump of all data is output with the verbose mode. Logging mode "Log Details": Also logs the sequence for internal management data (module list, link node list, etc.) as well as the most important ANSL interface information. In addition, a hex dump of all data is output with the verbose mode.
PviMan.exe/LnAnsl.dll/Ansl | Logger output of the ANSL interface in the ANSL line: Logging mode "Log Error": Logging for errors that occur within the ANSL interface Logging mode "Log Main": Logging of ANSL interface services, with the exception of variable services. In verbose mode, all service parameters as well as a hex dump of service data are also displayed. Logging mode "Log Details": Logging of all ANSL interface services. In verbose mode, all service parameters as well as a hex dump of service data are also displayed.
PviMan.exe/LnAnsl.dll/Objects | Logger ouptut of the ANSL line for identifying lines and ANSL objects: This logger output only records the creation and closing of line objects and ANSL objects. Logging mode "Log Error": Logging for errors that occur when setting up the object Logging mode "Log Main": Logging for external line objects and the corresponding ANSL objects Logging mode "Log Details": Logging of all line objects and all ANSL objects. Line objects and ANSL objects are defined by an identification number within the logger output of the ANSL line (PviMan.exe/LnAnsl.dll and PviMan.exe/LnAnsl.dll/Ansl). Logging the creation procedure makes it possible to match an identification number to its object name. This option is not possible, however, if this procedure is overwritten by other logger output in the logger file. For this reason, the ANSL line can additionally log the creation and closing procedures to a separate logger file.
PviMan.exe/LnNet2.dll | Logger output of the NET2000 line: Logging mode "Log Details": Variable identification (GetOV) logged.
PviMan.exe/Net2000.dll | Logger output of the NET2000 line (state machine): Logging mode "Log Error": Errors reported by the NET2000 state machine are logged. Logging mode "Log Details": Function calls from the state machine are logged. In addition, a hex dump of payload is output with the verbose mode.
PviMan.exe/LnIna2.dll | Logger output of the INA2000 line: Logging mode "Log Details": The internal program flow is logged. In addition, a hex dump of all data transferred to and from the ICOMM is output with the verbose mode.
PviMan.exe/IComm.dll | Logger output of the INA2000 line (ICOMM): Logging mode "Log Details": The internal program flow is logged.
PviMan.exe/InaFrms.dll/<Dev> | Logger output of the INA frame library: Logging mode "Log Error": All system and communication errors which occur are logged. Logging mode "Log Main": All function calls of the frame interface are logged. In addition, a hex dump of all frame data is output with the verbose mode. The INA frame library is used to transport log data from the NET2000, INA2000, Direct CAN, and MININET lines. The corresponding device name is used for <Dev> (e.g. COM1, INACAN3, TCPIP, etc.). If the "/CNO" parameter with a value not equal to 0 (null) is used in connection with the INACAN or DCAN devices, then the '.' character (period) and the value of the device name have to be connected (e.g. "/IF=INACAN2 /CNO=1" results in <Dev>: "INACAN2.1").
PviMan.exe/DvTcpIp.dll/<Dev> | Logger output of the INA frame TCP/IP device library: Logging mode "Log Error": All system and communication errors which occur are logged. Logging mode "Log Main": All function calls of the frame interface are logged. Logging mode "Log Details": Network communication is logged. In addition, a hex dump of sent and received frames is output with the verbose mode. The INA frame TCP/IP device library is a part of the INA frame library (InaFrms). The corresponding TCP/IP device name is used for <Dev> (see description for the INA frame library).
PviMan.exe/DvInaCan.dll/<Dev> | Logger output of the INA frame INACAN device library: Logging mode "Log Error": All system and communication errors which occur are logged. Logging mode "Log Main": All function calls of the frame interface are logged. Logging mode "Log Details": CAN communication is logged. In addition, a hex dump of all sent and received CAN messages is output with the verbose mode. The INA frame INACAN device library is a part of the INA frame library (InaFrms). The corresponding INACAN device name is used for <Dev> (see description for the INA frame library).
PviMan.exe/DvDCan.dll/<Dev> | Logger output of the INA frame DCAN device library: Logging mode "Log Error": All system and communication errors which occur are logged. Logging mode "Log Main": All function calls of the frame interface are logged. The INA frame DCAN device library is a part of the INA frame library (InaFrms). The corresponding DCAN device name is used for <Dev> (see description for the INA frame library).
PviMan.exe/LnSnmp.dll | Logger output of the SNMP line: Logging mode "Log Error": All occurring system errors and errors reported by the SNMP library are logged. Logging mode "Log Main": All function calls of the SNMP library are logged. Logging mode "Log Details": Object information is logged. In addition, a hex dump of data is output with the verbose mode.
PviDDE.exe | Logger output of the DDE server: Logging mode "Log Main": The DDE interface is logged.

Note that "Log Main" also activates "Log Error", and that "Log Details" activates both "Log Main" and "Log Error".

The PVI Data Logger is primarily intended for B&R to analyze problems. For this reason, much of the logger output refers to internal program sequences or internal PVI component states. However, some logger output can be interpreted by the user. In this way, the "PviMan.exe" component (logging mode ("Log Main") and the "<Prog>/PviCom.dll/Client" component (logging mode "Log Main") can be used by the user to analyze problems which arise in connection with the PVICOM interface. The component "PviMan.exe/InaFrms.dll/<Dev>" (logging mode "Log Error") can be used to analyze problems in connection with PLC communication.

Logger output of the components "<Prog>/PviCom.dll/Client" and "PviMan.exe", as well as the PVI line, define PVI objects with clear identification numbers. The Snapshot function can be used to coordinate the assignment between identification numbers and object names. It should be noted that giving the identification number takes place when the object is set up. If this object is released and then set up again, then the identification number can also be changed.

Logger output format

Each log entry begins on a new line and one of the following markings:

">" | Output in "Log Error" logging mode
">>" | Output in "Log Main" logging mode
">>>" | Output in "Log Detail" logging mode

A space and the timestamp always follow the marking. The actual log information is output next after an additional space.

Changes in logging states are identified with the sequence "###" followed by a corresponding text and name of the component:

### start trace | Logger output was started while the component was running (online)
### change trace | Logger mode was changed while the component was running
### stop trace | Logger output was stopped while the component was running
### begin trace | Logger output was started with the component
### end trace | Logger output was ended with the component
### break trace | Logger output was automatically stopped with the cancel function

The "### start trace" and "### begin trace" logger entries define when logger recording begins. However, the Data Logger handles the logger file like a ring buffer. If recording takes a long time, the beginning of the logger record may be overwritten. The "### stop trace", "### end trace" and "### break trace" logger entries define when logger recording ends. One of these labels is almost always present. However, the Data Logger cannot output any of these "end markings" if the program crashes. In this case, the timestamp must be used to determine the last logger entry.

Example:

>> 10:36:26.560 ### begin trace PVIDEMO.EXE/PviCom.dll/Client
...
>> 10:39:42.920 ### end trace PVIDEMO.EXE/PviCom.dll/Client

Logger output of PVI Manager and the PVICOM interface:

Object properties are represented by the parameters in the object description. Separate parameters are used for other information. Some of these parameters (e.g. identification numbers) are also output in the Snapshot file.

The following table shows the most important logger parameters:

Parameter | Description
C=<ID> | Identification number (ID) for the link object
P=<ID> | Identification number (ID) for the process object
S=<ID> | Identification number (ID) for the service object
CId=<ID> | Identification number (ID) for the registered communication instance (client)
RId=<ID> | Identification number (ID) for request and response data
L=<ID> | Identification number (ID) of the assigned object within the line
Pn=<PathName> | Path name of the process or service object
E=<Code> | PVI error code. A "no error" status can also be signaled with "E=0".
SysE=<Code> | System error code (general Windows error code)
SockE=<Code> | Windows socket error code
Ty=<Type> | PVI access type (numeric)
Md=<Mode> | PVI function mode, numeric or string ("WR": Write, "RD": Read).
Dl=<Length> | Data length of PVI request, response, or event data
Ih=<Handle> | Handle of the PVICOM communication instance
Ot=<Type> | PVI process object type as a numeric value
OT=<Type> | PVI process object type as a string (Pvi, Line, Device, Station, Cpu, Module, Task, Pvar)
St=<Status> | PVI status flags (bits) of response or event data (RESPONSE_INFO structure)
Msg=(<Msg>) | User message for signaling response or event data Windows message: W:<WindowHandle>,<MessageNumber>,<MessageParameter> Message function: F:<MessageHandle>,<MessageParameter> Callback with data: CBD:<CallbackPointer>,< MessageParameter> Callback without data: CB:<CallbackPointer>,<MessageParameter> Asynchronous callback: CBA:<CallbackPointer>,<MessageParameter> "Msg=(NULL)" is output if no user message is defined.
CDesc=(<Par>) | Specifies the link object description
PDesc=(<Par>) | Specifies the process object description
Len=<Num> | Length (general)
Offs=<Num> | Offset (general)
Ev=<Flags> | Enabling mask for events in the line.
Svc=<Mode> | Line service ("RD", "WR", "IDENT", "INFO")
CdP=<ID> | Identification number of the process object for the connection description
FrP=<ID> | Identification number of the process object for the data format (only for variable objects)
HyP=<ID> | Identification number of the process object for the hysteresis (only for variable objects)

PVI Manager log entries ("PviMan.exe" component) which begin with the "Comm" label indicate the communication between the PVI Manager (server) and the PVICOM communication instance (clients).

"Comm.Event" | Sends event data
"Comm.ReadRequ" | Receives request data for read request
"Comm.ReadResp" | Sends response data for read request
"Comm.WriteRequ" | Receives request data for write request
"Comm.WriteResp" | Sends response data for write request
"Comm.CreateRequ" | Receives request data for "Set up process object" request
"Comm.CreateResp" | Sends response data for "Set up process object" request
"Comm.LinkRequ" | Receives request data for "Set up link object" request
"Comm.LinkResp" | Sends response data for "Set up link object" request
"Comm.ChgLinkRequ" | Receives request data for "Change user message" request
"Comm.ChgLinkResp" | Sends response data for "Change user message" request
"Comm.UnlinkRequ" | Receives request data for "Release link object" request
"Comm.UnlinkResp" | Sends response data for "Release link object" request
"Comm.UnlinkAllRequ" | Receives request data for "Release all link objects" request
"Comm.UnlinkAllResp" | Sends response data for "Release all link objects" request
"Comm.DeleteRequ" | Receives request data for "Delete process object" request
"Comm.DeleteResp" | Sends response data for "Delete process object" request
"Comm.ClientAttach" | Registers a communication instance
"Comm.ClientDetach" | Deregisters a communication instance

Request and response data can be assigned with the "CId" or "C" parameters together with the "RId" parameter.

Examples:

>> 12:00:14.340 Comm.WriteRequ Ty=11 C=0010 RId=80000018 Dl=2
>> 12:00:14.390 Comm.WriteResp Ty=11 C=0010 RId=80000018 Dl=0
>> 12:00:15.040 Comm.CreateRequ CId=2d370003 RId=80000003 Name='@Pvi/LNINA2' OT=Line
>> 12:00:15.040 Comm.CreateResp C=000b CId=2d370003 RId=80000003

The "DI" parameter specifies the number of transferred bytes when request and response data is written or read.

The PVICOM interface ("<Prog>/PviCom.dll/Client" component) logs all user function calls.

"Initialize" | Calls the PviInitialize or PviXInitialize function
"Deinitialize" | Calls the PviDeinitialize or PviXDeinitialize function
"SetGlobEventMsg" | Calls the PviSetGlobEventMsg or PviXSetGlobEventMsg function
"CreateRequest" | Calls the PviCreateRequest or PviXCreateRequest function
"CreateResponse" | Calls the PviCreateResponse or PviXCreateResponse function
"DeleteRequest" | Calls the PviDeleteRequest or PviXDeleteRequest function
"DeleteResponse" | Calls the PviDeleteResponse or PviXDeleteResponse function
"LinkRequest" | Calls the PviLinkRequest or PviXLinkRequest function
"LinkResponse" | Calls the PviLinkResponse or PviXLinkResponse function
"UnlinkRequest" | Calls the PviUnlinkRequest or PviXUnlinkRequest function
"UnlinkResponse" | Calls the PviUnlinkResponse or PviXUnlinkResponse function
"ChgLinkRequest" | Calls the PviChgLinkRequest or PviXChgLinkRequest function
"ChgLinkResponse" | Calls the PviChgLinkResponse or PviXChgLinkResponse function
"UnlinkALL" | Calls the PviUnlinkAll or PviXUnlinkAll function
"ReadRequest" | Calls the PviReadRequest, PviXReadRequest, PviReadArgumentRequest or PviXReadArgumentRequest function
"ReadResponse" | Calls the PviReadResponse or PviXReadResponse function
"WriteRequest" | Calls the PviWriteRequest or PviXWriteRequest function
"WriteResponse" | Calls the PviWriteResponse, PviXWriteResponse, PviWriteResultResponse or PviXWriteResultResponse function
"GetResponseInfo" | Calls the PviGetResponseInfo or PviXGetResponseInfo function

With user functions, a log entry is output after entering the function and before leaving it. Synchronous function variants are represented by each matching request or response function.

User message execution is also logged.

"Call" | Before calling a callback user function
"Return" | After returning from a callback user function
"Send" | Windows message has been sent

Example for writing:

>> 12:00:14.340 WriteRequest Ih=0 C=0010 Ty=11 Dl=2
>> 12:00:14.340 WriteRequest OK
...
>> 12:00:14.390 Send W:00000974,1027,1001 RId=80000018
>> 12:00:14.420 WriteResponse Ih=0 RId=80000018
>> 12:00:14.420 WriteResponse OK C=0010 Ty=11 E=0 Dl=0

Example for event data:

>> 12:00:14.365 Send W:00000974,1026,1007 RId=8000005a
>> 12:00:14.378 ReadResponse Ih=0 RId=8000005a
>> 12:00:14.378 ReadResponse OK C=0013 Ty=11 E=0 Dl=7

<< Previous Topic
Snapshot Function

Start Page

Next Topic >>
Appendix


Appendix

In this section the following topics are discussed:

Appendix

Appendix A - Definitions

Appendix B - Base components

Appendix C - Registry

<< Previous Topic
Data logger

Start Page

Next Topic >>
Appendix A - Definitions


Appendix A - Definitions

List of access types:

Access types | No. | Description
POBJ_ACC_OBJECT | #1 | Reads object type
POBJ_ACC_VERSION | #2 | Reads version of PVI components or corresponding PLC object
POBJ_ACC_ERROR | #3 | Reads error code of the most recent error
POBJ_ACC_EVMASK | #5 | Reads/Sets enabling mask for events
POBJ_ACC_LIST | #6 | Reads list of all setup process objects
POBJ_ACC_LIST_EXTERN | #7 | Reads list of all possible process objects
POBJ_ACC_CONNECT | #10 | Reads/Writes connection description
POBJ_ACC_DATA | #11 | Reads/Writes process data
POBJ_ACC_STATUS | #12 | Reads/Sets PLC object status
POBJ_ACC_TYPE | #13 | Reads/Writes object attributes, mode for type conversion, and/or data format
POBJ_ACC_TYPE_EXTERN | #14 | Reads object attributes and data format as well as structure definition and element names of a PLC variable
POBJ_ACC_REFRESH | #15 | Reads/Writes refresh rate
POBJ_ACC_HYSTERESE | #16 | Reads/Writes the event hysteresis of a variable object
POBJ_ACC_DEFAULT | #17 | Reads preset value for a variable object. The value is returned in string format.
POBJ_ACC_FUNCTION | #18 | Reads/Writes the data function of a variable object
POBJ_ACC_TYPE_INTERN | #19 | Reads the object attribute, data format and the mode for type conversion (cast mode) of a PVI process variable object.
POBJ_ACC_UPLOAD | #20 | Reads BR module from PLC and saves it to a file
POBJ_ACC_DOWNLOAD | #21 | Reads BR module from file and transfers it to PLC
POBJ_ACC_DATE_TIME | #22 | Reads/Sets date and time
POBJ_ACC_MEM_DELETE | #23 | Deletes specified data memory on the PLC
POBJ_ACC_MEM_INFO | #24 | Reads information about existing PLC data memory
POBJ_ACC_MOD_TYPE | #25 | Reads information about a PLC module
POBJ_ACC_UPLOAD_STM | #26 | Reads BR module from PLC and transfers it as binary user data
POBJ_ACC_DOWNLOAD_STM | #27 | Transfers BR module from binary user data to PLC
POBJ_ACC_MOD_DATA | #28 | Reads/Writes BR log module payload data
POBJ_ACC_MOD_DELETE | #29 | Deletes the BR module on AR
POBJ_ACC_LIST_LINE | #30 | Reads list of all possible line objects
POBJ_ACC_LIST_DEVICE | #31 | Reads list of all possible device objects
POBJ_ACC_LIST_STATION | #32 | Reads list of all possible station objects
POBJ_ACC_LIST_CPU | #33 | Reads list of all possible CPU objects
POBJ_ACC_LIST_MODULE | #34 | Reads list of all possible module objects
POBJ_ACC_LIST_TASK | #35 | Reads list of all possible task objects
POBJ_ACC_LIST_PVAR | #36 | Reads list of all possible variable objects
POBJ_ACC_CPU_INFO | #50 | Reads CPU information
POBJ_ACC_CANCEL | #128 | Cancels sent PVI request.
POBJ_ACC_USERTAG | #129 | Reads / configures user tag
POBJ_ACC_INFO_LICENCE | #200 | Reads PVI Manager license information.
POBJ_ACC_LIST_CLIENTS | #210 | Reads list of all clients registered with PVI Manager
POBJ_ACC_PVI_VERSION | #211 | Reads PVI version.
POBJ_ACC_SNAPSHOT | #240 | Executes Snapshot function.
POBJ_ACC_PVIMAN_EXIT | #243 | Closes PVI manager.
POBJ_ACC_LN_COMM_DST | #291 | Reads communication parameters
POBJ_ACC_LN_LKN_LIST | #296 | Reads list of link nodes
POBJ_ACC_LN_XML_LIC_STATUS | #351 | Reads the license status on the PLC (XML format)
POBJ_ACC_LN_XML_CPU_INFO | #400 | Reads CPU information (XML format)
POBJ_ACC_LN_XML_MOD_INFO | #401 | Reads information about a PLC module (XML format)
POBJ_ACC_LN_XML_TASK_INFO | #402 | Reads information about a PLC task module (XML format)
POBJ_ACC_LN_XML_MOD_LIST | #403 | Reads the PLC module list (XML format)
POBJ_ACC_LN_XML_MEM_INFO | #404 | Reads CPU memory information (XML format)
POBJ_ACC_LN_XML_HW_INFO | #405 | Reads PLC hardware information (XML format)
POBJ_ACC_LN_XML_RED_INFO | #406 | Reads PLC redundancy information (XML format)
POBJ_ACC_LN_XML_TC_INFO | #408 | Reads PLC task class information (XML format)

List of event types and global event types:

Event types | No. | Description
POBJ_EVENT_ERROR | #3 | Change in error state or error code
POBJ_EVENT_CONNECT | #10 | Change in connection definition
POBJ_EVENT_DATA | #11 | Change in process data
POBJ_EVENT_STATUS | #12 | Change in status
POBJ_EVENT_DATAFORM | #13 | Change in data format
POBJ_EVENT_PROCEEDING | #128 | Progress information
POBJ_EVENT_USERTAG | #129 | User tag modification
POBJ_EVENT_PVI_CONNECT | #240 | Connection made to PVI Manager
POBJ_EVENT_PVI_DISCONN | #241 | Connection to PVI Manager lost
POBJ_EVENT_PVI_ARRANGE | #242 | New registration on PVI Manager
POBJ_EVENT_LN_XML_MOD_LIST | #403 | Changes the PLC module list
POBJ_EVENT_LN_XML_RED_CTRL | #440 | Event on redundant PLC systems

Parameters for the object description:

Par. | Definition | Description
CD | KWDESC_CONNECT | Connection definition
EV | KWDESC_EVMASK | Enabling mask for events.
LT | KWDESC_LINKTYPE | Link type
AT | KWDESC_ATTRIBUTE | Object attributes
RF | KWDESC_REFRESH | Refresh time
FT | KWDESC_PVTYPE | Variable type (data format)
VL | KWDESC_PVLEN | Variable length (data format)
VN | KWDESC_PVCNT | Number of elements (data format)
{...} | PVICHR_SUB_ON, PVICHR_SUB_OFF | Definition of structure elements (data format)
VS | KWDESC_PVSPEC | Additional specification for the data format
AL | KWDESC_ALIGNMENT | Structure alignment (data format)
CM | KWDESC_CASTMODE | Mode for type conversion
VA | KWDESC_PVADDR | Variable addressing
DV | KWDESC_DEFAULT | Default value
HY | KWDESC_HYSTERESE | Event hysteresis
FS | KWDESC_FUNCTION | Data function
UT | KWDESC_USERTAG | User tag

Parameters for initialization parameters:

Par. | Definition | Description
AS | KWINIT_AUTOSTART | PVI Manager auto-start
LM | KWINIT_MSG_LIMIT | Limit on user messages.
PT | KWINIT_PRC_TIMEOUT | Process timeout (not suitable for standard applications)
IP | KWINIT_IPADDR | TCP/IP address or host name for remote communication type
PN | KWINIT_IPPORT | TCP/IP port number.

Parameters for object services:

Par. | Definition | Description
Package unit | KWDESC_PVELEM | Additional information for structure elements
VO | KWDESC_PVOFFS | Offset for structure elements
VS | KWDESC_PVSPEC | Additional specification for the data format
OT | KWDESC_OBJTYPE | Object type
SC | KWDESC_SCOPE | Scope
SN | KWDESC_SNAME | Name of the superior type for enumeration or structure variables.
TN | KWDESC_TNAME | Name of the derived data type.
LD | KWDESC_LOADTYPE | Load type / memory type
IM | KWDESC_INSTMODE | Installation mode
MN | KWDESC_MODNAME | Module name
ST | KWDESC_STATUS | Status
FC | KWDESC_FORCESTATE | Force state
IO | KWDESC_IOTYPE | I/O type (attribute: r/w)
MT | KWDESC_MODTYPE | Module type
ML | KWDESC_MODLEN | Module length in bytes
SL | KWDESC_MEMLEN | Memory length in bytes
SF | KWDESC_MEMFREELEN | Available memory length in bytes
SB | KWDESC_MEMBLOCKLEN | Largest available memory area

List of process object types:

Object type definition |  |  |  | Name
Binary |  | String
POBJ_PVI | #0 | KWOBJTYPE_PVI | Pvi | Base object
POBJ_LINE | #1 | KWOBJTYPE_LINE | Line | Line object
POBJ_DEVICE | #2 | KWOBJTYPE_DEVICE | Device | Device object
POBJ_STATION | #3 | KWOBJTYPE_STATION | Station | Station object
POBJ_CPU | #4 | KWOBJTYPE_CPU | CPU | CPU object
POBJ_MODULE | #5 | KWOBJTYPE_MODULE | Modules | Module object
POBJ_TASK | #6 | KWOBJTYPE_TASK | Task | Task object
POBJ_PVAR | #7 | KWOBJTYPE_PVAR | Pvar | Variable object

Keywords for load state / memory type:

Keyword | Definition | Description
SysRam | KWLOADTYPE_SYS_RAM | System RAM
RAM | KWLOADTYPE_RAM | User RAM
SysRom | KWLOADTYPE_SYS_ROM | System Flash (ROM)
Rom | KWLOADTYPE_ROM | User Flash (ROM)
MemCard | KWLOADTYPE_MEMCARD | Memory Card
FixRam | KWLOADTYPE_FIX_RAM | Fix RAM
DRam | KWLOADTYPE_DRAM | DRAM
PerMem | KWLOADTYPE_PER_MEM | Permanent memory
Delete | KWLOADTYPE_DELETE | Deletes module (access type POBJ_ACC_STATUS)

Installation mode keywords for cyclic tasks:

Keyword | Definition | Description
Overload | KWINSTMODE_OVERLOAD | Default mechanism
Copy | KWINSTMODE_COPY | Exchanges in several cycles
OneCycle | KWINSTMODE_ONECYCLE | Exchanges in one cycle

<< Previous Topic
Appendix

Start Page

Next Topic >>
Appendix B - Base components


Appendix B - Base components

The following tables shows the components that make up the PVI base system:

Component | Directory | 32-bit platform | 64-bit platform | Description
PviMan.exe | Bin | NT/2K/XP/W7/CE | W7 | PVI Manager
PviConfig.xml | Bin | NT/2K/XP/W7/CE | W7 | PVI configuration file, suitable for the PVI Manager.
PviFcLin.dll | Bin | NT/2K/XP/W7/CE | W7 | PVI data function LIN
PviMon.exe | Bin | NT/2K/XP/W7/CE | W7 | PVI Monitor
PviCom.dll | System | NT/2K/XP/W7/CE |  | PVICOM interface for 32-bit applications.
PviCom64.dll | System |  | W7 | PVICOM interface for 64-bit applications.
PviLog.dll | System | NT/2K/XP/W7/CE |  | PVICOM interface for 32-bit applications.
PviLog64.dll | System |  | W7 | PVICOM interface for 64-bit applications.
BrSecChk.exe | Tools | NT/2K/XP/W7 | W7 | Program to check B&R security key
LnIna2.dll | Bin | NT/2K/XP/W7/CE | W7 | INA2000 line (line server)
iComm.dll | Bin | NT/2K/XP/W7/CE | W7 | INA2000 line (communication)
BrBase.dll | Bin | NT/2K/XP/W7/CE | W7 | INA2000 line (sub-component)
BrMod104.dll | Bin | NT/2K/XP/W7/CE | W7 | B&R module classes (sub-component for LnIna2 <= V3.30).
BrPgVm32.dll | Bin | NT/2K/XP/W7/CE | W7 | INA2000 line (sub-component)
InaFrm.dll | Bin | NT/2K/XP/W7/CE | W7 | INA2000 line (sub-component)
BrBrmGen.dll | Bin | NT/2K/XP/W7/CE | W7 | Compilation library for binary modules
LnNet2.dll | Bin | NT/2K/XP/W7/CE* | W7 | NET2000 line (line server)
Net2000.dll | Bin | NT/2K/XP/W7CE* | W7 | NET2000 line (NET2000 state machine)
LnMini.dll | Bin | NT/2K/XP/W7 | W7 | MININET line (line server)
LnDCan.dll | Bin | NT/2K/XP |  | Direct CAN line (line server)
LnSnmp.dll | Bin | 2K/XP/W7 | W7 | SNMP line (line server).
BrSnmp.dll | Bin | 2K/XP/W7 | W7 | SNMP library (SNMP communication).
LnAdi.dll | Bin | NT/2K/XP/W7/CE** |  | ADI line (line server)
LnMtc.dll *) | Bin | NT/2K/XP |  | MTC line (line server)
InaFrms.dll | Bin | NT/2K/XP/W7/CE | W7 | INA frame library (communication)
DvInaCan.dll | Bin | NT/2K/XP |  | INACAN device DLL for the INA frame library
DvDCan.dll | Bin | NT/2K/XP |  | DCAN device DLL for the INA frame library
InaCan.sys | System | NT/2K/XP |  | Driver for B&R CAN devices
CanDvCfg.cpl | System | NT/2K/XP |  | B&R CAN device configurator
DvTcpIp.dll | Bin | NT/2K/XP/W7/CE | W7 | TCP/IP device DLL for the INA frame library
DvModem.dll | Bin | NT/2K/XP/W7 | W7 | Modem device DLL for the INA frame library
DvPBusFDL.dll *) | Bin | NT/2K/XP |  | PBUSFDL device DLL for the INA frame library
PBus.sys *) | System | NT/2K/XP |  | Driver for shared memory communication
DvLs251.dll *) | Bin | NT/2K/XP |  | LS251 device DLL for the INA frame library
Ls251Drv.sys *) | System | NT/2K/XP |  | Driver for LS251 communication
LnModbus.dll | Bin | 2K/XP/W7/CE | W7 | MTC line (line server)
BrModbus.dll | Bin | 2K/XP/W7/CE | W7 | MODBUS line (communication)
NT stands for Windows NT >= 5.0 | CE stands for Windows CE 5.0/6.0
2K stands for Windows 2000 |  | CE* | only for devices with X68 processors
XP stands for Windows XP |  | CE** | only for B&R devices
W7 stands for Windows 7 + Vista |  |  |
*) The component is no longer included starting with PVI Version 3.0.2

Starting with PVI Version 3.0.3, the CE platforms are longer supported!

<< Previous Topic
Appendix A - Definitions

Start Page

Next Topic >>
Appendix C - Registry


Appendix C - Registry

PVI Setup sets up all necessary Windows registry entries for the PVI base system. This appendix is intended for users who carry out separate installation programs and need to replicate PVI base system registration themselves.

The PVI base system uses the Windows registry to store operating parameters and system entries. PVI entries are divided among the following keys:

  1. "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\App_Paths\PviMan.exe":
    Registered versions of the PVI Manager are located under this key.
  2. "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet":
    Drive information is saved under this key.
  3. "HKEY_LOCAL_MACHINE\SOFTWARE\BR_Automation\BrAuthorization":
    B&R security key (dongle) access is controlled under this key.
  4. "HKEY_LOCAL_MACHINE\SOFTWARE\BR_Automation\Pvi":
    Central operating parameters are stored under this key.
  5. "HKEY_CURRENT_USER\SOFTWARE\BR_Automation\Pvi":
    User-dependent operating parameters are stored under this key.

Key "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\App_Paths\PviMan.exe":

The following entries define the registered PVI version.

PviMan.exe --> (default) ... Complete path name of the PVI manager
--> Path         ... Path name for the PVI Manager directory

Example from the registry file:

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\Pviman.exe]
@="C:\\Program Files\\BrAutomation\\Pvi\\V2.5.2\\Bin\\PviMan.exe"
"Path"="C:\\Program Files\\BrAutomation\\Pvi\\V2.5.2\\Bin"

See also the section "Changing the registry for PVI Manager".

Key "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet":

The following is an overview of the registry entries for B&R drivers.

Registration for CAN drivers in Windows NT/2000/XP:
Services
--> InaCan      ... Schlüssel für CAN Treiber
    --> DisplayName    = "B&R CAN Driver"
    --> Type           = 1 (dword)
    --> Start          = 2 (dword)
    --> ErrorControl   = 1 (dword)
    --> Group          = "BuR_Drivers"
    --> Devices        ... Key for CAN devices (device configurator)
        --> ...
--> Eventlog
    --> System
        --> InaCan            ... Key for CAN driver
            --> EventMessageFile     ... Entry for system log file
            --> TypesSupported       = 7

Entry for system log file:
"%SystemRoot%\System32\Drivers\InaCan.sys;%SystemRoot%\System32\IoLogMsg.dll"

Registrierung für LS251 Treiber unter Windows NT/2000/XP:
The LS251 driver is no longer included starting with PVI Version 3.0.2.
Services
--> Ls251drv    ... Key for LS251 driver
    --> DisplayName    = "B&R LS251 Driver"
    --> Type           = 1 (dword)
    --> Start          = 2 (dword)
    --> ErrorControl   = 1 (dword)
    --> Group          = "BuR_Drivers"
    --> Tag            = 32 (dword)
    --> Parameters
        --> NmiOnShutDown     = 0 (dword)
        --> ServeMTC          = 0 (dword)
        --> CycleTimeMTC      = 60 (dword)
        --> NmiOnShutDown     = 0 (dword)
        --> DeviceNameMTC     = "\Device\brMtcDevice0"
Control
--> GroupOrderList
    --> BuR_Drivers    = 0x02,0x00,0x00,0x00,0x0f,0x00,0x00,0x00,0x1f,0x00,0x00,0x00

Registration for Profibus driver in Windows NT/2000/XP:
The Profibus driver is no longer included starting with PVI Version 3.0.2.
Services
--> PBUS        ... Key for Profibus driver
    --> Type           = 1 (dword)
    --> Start          = 2 (dword)
    --> ErrorControl   = 1 (dword)
    --> Group          = "Extended base"

Key "HKEY_LOCAL_MACHINE\SOFTWARE\BR_Automation\BrAuthorization":

The following entry is used for the B&R security key (dongle) query.

BrAuthorization
--> DsConfig      ... Configuration for B&R Security Key (dword)
                      Bit 0 -> Look for security key on LPT
                      Bit 2 -> Look for security key on USB

This registry entry is optional. Default value: 0x00000003. The BrSecChk tool can create and modify this entry.

Key "HKEY_LOCAL_MACHINE\SOFTWARE\BR_Automation\Pvi":

The PVI base system evaluates the following registry entries:

Pvi
--> SockUse        ... Communication type remote/local
--> SockPort       ... Port number (remote)
--> ManDispTrial   ... Warning message for security mode (0/1)
--> ManSysTray     ... Display in the taskbar (0/1)
--> ManPriority    ... PVI manager priority
--> ManAutoExit    ... automatic exit (0/1)
--> SnapshotFile   ... Default path name for snapshot file
--> DataLogger     ... Key for the PVI Data Logger

Example from the registry file:

[HKEY_LOCAL_MACHINE\SOFTWARE\BR_Automation\Pvi]
"SockUse"=dword:00000000
"SockPort"=dword:00004e20
"ManDispTrial"=dword:00000001
"ManSysTray"=dword:00000001
"ManPriority"="normal"
"ManAutoExit"=dword:00000000
"SnapshotFile"="C:\\Temp\\PviLog\\PviMan.pvisnp"

These registry entries are optional. If an entry doesn't exist, the PVI base system uses a corresponding default value. The "PVI Manager properties" and "PVI Diagnose" functions in PVI Monitor create and configure the registry entries.

PVI Setup can write current path names to the path entries or overwrite the default values by new values.

Key "HKEY_CURRENT_USER\SOFTWARE\BR_Automation\Pvi":

This key contains all user-dependent registry entries for the PVI base system. The individual entries are created and managed by the PVI components themselves. Presetting these entries with PVI Setup is not required.

Changing the registry for PVI Manager:

The PVI Monitor function "PVI Registry Changer" involves the following process:

  1. PVI Manager path names of the target version entered in "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\App_Paths\PviMan.exe".
  2. Existing Windows system service registration for old PVI Manager deleted ("> PviMan.exe /SvUnreg").
  3. If system service is entered in the dialog box: Windows system service registered for PVI Manager ("> PviMan.exe /SvReg").
  4. Bach file for target version executed.

The path name of the batch file is read from the PVI configuration file (PviConfig.xml) of the target version. The PVI configuration file must be located in the same directory as the PVI Manager.

The path of the batch file and the execution mode are defined in the configuration file:

<Pvi>
  <PviRegistry CmdFile=".\PviRegistryChanger.bat" CmdView="0" />
  ...
</Pvi>

The path of the batch file is defined with CmdFile. The path for the directory can be absolute, or relative to the directory of the PVI Manager (directory of the target version).

The execution mode of the batch file is defined with CmdView as follows:

CmdView="0" | Silent execution (Default setting) The fender of the command interpreter is not displayed. The execution of the batch file is monitored with a 16 second timeout.
CmdView="1" | The fender of the command interpreter is displayed. The execution time of the batch file is not monitored.
CmdView="2" | The fender of the command interpreter is displayed. The end of the execution must be acknowledged by pressing a button. This mode is intended for testing the batch file.

cmd.exe is used to interpret the commands. Program options /D and /C or /K are listed.

<< Previous Topic
Appendix B - Base components

Start Page

Next Topic >>
FAQ


FAQs

In this section the following topics are discussed:

FAQ

Establish connection to PVI Manager

Monitoring the communication connection to PVI Manager

Setting up object structures for process image

Connecting project objects

Establishing a connection to the process image

Using static or temporary process objects

Setting the process object state to active or inactive

Acquiring process data

Setting up the read cycle

<< Previous Topic
Appendix C - Registry

Start Page

Next Topic >>
Establish connection to PVI Manager


FAQs

Establish connection to PVI Manager

To be able to communicate with PVI Manager, you must first set up a communication instance.

This communication instance establishes a connection between the PVICOM application and PVI Manager. The PVICOM function PviInitialize or PviXInitialize must be called to set up a communication instance.

This also sets up the communication type "local" (application and PVI Manager on the same computer) or "remote" (application and PVI Manager on different computers) as well as the timeout for life sign monitoring (communication timeout).

Unlike the function "PviInitialize", "PviXInitialize" can be called more than once. Each call sets up a new communication instance. This allows a PVICOM application to be able to communicate with several PVI Managers on different computers. If a communication instance is set up with PviXInitialize, then PVICOM functions must subsequently be called with an instance handle (PviX...).

If a communication instance is no longer needed, then it has to be freed up with either the PviDeinitialize or PviXDeinitialize PVICOM function.

The number of PVICOM communication instances (clients) registered with PVI Manager is shown in the Clients line of the PVI Monitor.

<< Previous Topic
FAQ

Start Page

Next Topic >>
Monitoring the communication connection to PVI Manager


FAQs

Monitoring the communication connection to PVI Manager

Global events can be set so that the PVICOM application can monitor the communication connection to PVI Manager of a communication instance.

If PVI Manager is ended or the network connection (communication type "remote") is interrupted for a long time (communication timeout), then all link objects which have been set up, as well as the communication instance's temporary process objects in PVI Manager, are lost.

After the manager is restarted or the communication connection is reestablished, the application has to set up these objects again. The global event POBJ_EVENT_PVI_ARRANGE notifies the application of when objects need to be recreated.

Using global events is an optional feature.

We recommend evaluating global events when using the "remote" communication type in particular.

With the global event POBJ_EVENT_PVI_ARRANGE, applications can either reestablish the last existing object state in PVI Manager (set up PVI objects and set to active or inactive) or prepare an initial status (e.g. object status of the start image).

Global events are set with the PVICOM function PviSetGlobEventMsg or PviXSetGlobEventMsg.

<< Previous Topic
Establish connection to PVI Manager

Start Page

Next Topic >>
Setting up object structures for process image


FAQs

Setting up object structures for process image

Accessing the data in a PLC variable or executing special services such as downloading/uploading modules, querying the CPU status, etc., are done via the process image.

In PVI Manager, the process image is represented using the object structure. Object structures consist of individual process objects arranged in the form of a tree structure. Because of this, it is also called the process object tree. When setting up the process object, the application also has to assign an object name. The user can select any name for this process object name.

e.g. object name for the CPU object:

@/Pvi/LNINA2/TCPIP/PVITEST/CPU

Putting together the process object name with the object path can be done to ascertain an individual process object within the object structure (Object Name with Path Specification).

There are different types of process objects:
  • Base object
  • Line object
  • Device object
  • Station object
  • CPU object
  • Module object
  • Task object
  • Variable object

Each object type has a certain task in the object structure.

The base object is the highest-level process object in the object structure. This object is always present and doesn't need to be set up.

The line object determines the PVI line being used. Normally, device objects, station objects, and CPU objects are used to establish the communication connection to the PLC and address a PLC in the network.

Module objects, task objects, and variable objects represent a corresponding PLC object. The section of the object structure underneath the line object is set aside for the line being used. How individual process objects are to be arranged can be found in the section concerning PVI lines.

Process objects are created with the PVICOM function PviCreateRequest or PviXCreateRequest.

<< Previous Topic
Monitoring the communication connection to PVI Manager

Start Page

Next Topic >>
Connecting project objects


FAQs

Connecting project objects

Each newly setup process object with line connection triggers a process of establishing connection (station and CPU process object) or of object identification (module, task, and variable process object).

Depending on the line being used, this process can take some time to complete.

INA2000 line:
It is recommended to set up all variable objects in one task object. This enables faster identification of variables than if they are set up in the CPU object.

If the process object is disconnected and then freshly set up again, then this process has to be repeated. It is therefore an advantage if PVICOM applications only have to set up process objects once.

A disrupted connection (unplugging the cable between the PC and controller) also causes (after the response timeout has expired following x number of the configured or defined repetitions) a new attempt to establish a connection as long as the connection to the controller has been re-established.

If an object is created temporarily, an automatic read task (active process object) is performed after the object has been identified and therefore also a read task to the controller. A data event is sent to the PVI Client application after a data change.

Static objects are only identified. The object is only read and the data event sent to the PVI Client application after a link object has been created.

The functions for setting up a temporary or static object, or for setting up a link object only go as far as the PVI Manager. Only when the object has been set up completely is the request sent to the line or the controller (identification, read request, etc.).

<< Previous Topic
Setting up object structures for process image

Start Page

Next Topic >>
Establishing a connection to the process image


FAQs

Establishing a connection to the process image

To establish a connection to a process object in the process image, the PVICOM application has to set up a link object.

The application then uses this link object to access process data, object properties or object states of the process object, or to carry out special services.

Link objects are set up with the PVICOM function PviLinkRequest or PviXLinkRequest and released with PviUnlinkRequest or PviXUnlinkRequest.

<< Previous Topic
Connecting project objects

Start Page

Next Topic >>
Using static or temporary process objects


FAQs

Using static or temporary process objects

A process object can be set up as a temporary or static process object (PVICOM function PviCreateRequest or PviXCreateRequest).

A static process object is only set up once and remains throughout the entire runtime of PVI Manager. A temporary process object is set up together with a link object. When the link object is released (PVICOM function PviUnlinkRequest or PviXUnlinkRequest) or when the PVICOM application is exited, the temporary process object is also freed up.

A newly set up link object with a line connection triggers a process for either establishing a connection (station objects, CPU objects) or for PLC object identification (module objects, task objects, variable objects). Depending on the line being used, this process can take some time to complete. If the process object is disconnected and then freshly set up again, then this process has to be repeated. It is therefore an advantage if PVICOM applications only have to set up process objects once.

Static process objects are advantageous in the following situations:

  • A PVICOM application which is started and stopped many times and which needs a large number of process objects
  • The object structure should be managed centrally. At the start (e.g. Windows start-up), a generator or configurator (as the PVICOM application) sets up all required process objects. To do so, information about the object structure can be read from an ASCII text file or database. Then the application can be ended again.
  • An interface server which remains active during the entire PVI Manager runtime and provides information about the necessary object structure right after being started. In principle, interface servers can also use temporary process objects. However, all link objects then need to remain set up at runtime.

Temporary process objects are advantageous in the following situations:

  • A PVICOM application which is not started and stopped many times or which needs just a few process objects
  • Process objects which are only used briefly in a PVICOM application and which are seldom needed (e.g. for carrying out services)
  • If the connection description of a process object is modified during runtime (access type POBJ_ACC_CONNECT), then it and all subordinate objects should be set up as temporary process objects.

The points mentioned above are only intended as decision guidance. The type of process object used by the PVICOM application needs to be decided according to requirements. However, if in doubt, temporary process objects are preferred since they are more easily handled.

For more information, see the Static and Temporary Process Objects section.

Example:

A visualization with multiple screen pages is a classic example of using static and temporary process objects.

Using static process objects

  • When starting the visualization, all objects are set up as static (i.e. only the process object is created – no link object).

  • To display a variable on a screen page, a link object must now be created on the corresponding variable process object.

  • The variable will now be read and monitored by the PVI Manager / PVI Line. A data change is received in the response data of the link object and can be evaluated accordingly = active process object.

  • When changing pictures, the link object is cleared again, but the process object remains. Variable reading is deactivated = inactive process object.

  • Another link object is created on the same process object if it is necessary for the same variable to be displayed multiple times. This makes it possible to display and close the pages independently from one another.

  • Another advantage of this method is that each link object can have a different scaling or data type.

Using temporary process objects

  • All process objects are set up temporarily when starting (i.e. the process object already has a link object).
  • If a variable is displayed on a page, then the process object is switched to "active".
  • The variable will now be read and monitored by the PVI Manager / PVI Line. A data change is received in the response data of the link object and can be evaluated accordingly = active process object.
  • When changing a picture, the process object is switched to "inactive" again (i.e. variable reading is deactivated = inactive process object).
  • If the same variable must be displayed multiple times, then the client application must be used to monitor whether the variable is displayed multiple times. The process object can be switched to "inactive" when the variable is no longer required.

<< Previous Topic
Establishing a connection to the process image

Start Page

Next Topic >>
Setting the process object state to active or inactive


FAQs

Setting the process object state to active or inactive

Each process object can be in either an active or inactive state.

This state is controlled by the link object. In principle, PVICOM applications should only keep process objects in an active state if they are needed at that moment. All other process objects should be set to inactive. This applies to variable objects in particular.

The fewer variables that are active, the faster the active variables can be refreshed.

There are basically 2 methods for a PVICOM application to set a process object to active or inactive during runtime:

  1. The existence of at least one link object sets the state to active:
    Example for visualization: At the start, all necessary process objects are set up as static objects. Then the application can set up the link objects for all of the process objects used in the picture by enabling it. If the picture is turned off, then the link objects from the application are released again. If two or more picture are enabled at the same time, then there are two or more link objects present for each process object used together. The advantage of this method is that each picture only has to be aware of its own process objects. Event data is automatically distributed to the individual pictures via the link objects. A picture-comprehensive management of process object states and event data is therefore not necessary.
  2. The active or inactive state is set using the enable mask, aided by access type POBJ_ACC_EVMASK:
    Example for visualization: The application sets up all necessary process objects (static or temporary) each with a link object during the initialization phase. If a picture is enabled or turned off, then the application sets all of the process objects in the picture to the desired active or inactive state using access type POBJ_ACC_EVMASK. However, this method requires a central management of process object states and event data. If several pictures use the same process objects, then the active and inactive states have to be coordinated with one another. The event data read has to be distributed to the active pictures.

For more information, see the Process Object State Active or Inactive section.

Which variables should be switched to active:

  • Variables that are displayed on a screen page
  • Variables that must be read in the background of the application (e.g. alarm and trend data)

Which variables should be switched to inactive:

  • Variables that are only requested by the controller or written to the controller when specific actions occur
  • Variables that are not displayed

The PVI Monitor can be used to evaluate the number of process objects registered to the PVI Manager and the number of active process objects.

<< Previous Topic
Using static or temporary process objects

Start Page

Next Topic >>
Acquiring process data


FAQs

Acquiring process data

Process data is always read using PVI variable objects (process objects of type POBJ_PVAR).

Each variable object holds an image of a PLC variable. To update this image, variable data is read from the PLC.

There are basically 3 ways to acquire data:

  1. Data is gotten through cyclic read instructions (standard method):
    PVI sends cyclic read instructions to the PLC. The object attribute 'e' cannot be specified. The refresh time determines the read cycle.
    Example for the process object description: "CD=var1 AT=rw RF=250".
  2. Data is gotten through event variables:
    Event variables are set up on the PLC. They only send their process data to PVI when they have changed. The object attribute 'e' must be specified. The refresh time defines the PLC-internal read cycle here.
    Example for the process object description: "CD=var1 AT=erw RF=250".
  3. Data acquisition is controlled by the PVICOM application:
    Either 0 (zero) or -1 is set for the refresh time. The application itself determines when data is gotten by calling the PviReadRequest or PviXReadRequest and using access type POBJ_ACC_DATA. With this method, process data can be received either as response data from the read instruction or as event data. It is not recommended to define a user message to occur for response data when the read instruction is given. The process data is then sent to the application as event data, like the other types of data acquisition. However, this method is not suitable for read cycles less than 1 second.
    Example for the process object description: "CD=var1 AT=rw RF=0".

Data from cyclic read instructions (polling):

If a process variable arrives with active event mask (access type POBJ_ACC_EVMASK) and a refresh time > 0, then the PVI line starts cyclically reading this active process variable from the controller.

As you can see in the following image, the process variable "PV1" is read cyclically from the controller.

The PVI Manager compares the value of the internal process image with the read value and sends a data event to the PVI Client application anytime a data change occurs.

Multiple active variables are simultaneously read from the controller in a request frame.

Advantage of polled communication:

Quicker update of variables with shorter refresh time

Disadvantage of polled communication:

When there is a large number of active variables, the defined refresh time for all variables is no longer guaranteed because all variables cannot be read in one request from the controller.

Data from event variables (event-driven):

INA2000 and NET2000 line offer the possibility of event-driven communication (object attribute "e").

The following view shows the communication between PVI and the controller when only event variables are used.

In this case, only one life sign monitor is active between the PVI and the controller with the Response Timeout (/RT=x) defined for the CPU process object.

The controller monitors every event variable with the defined refresh time (RF=x) in the controller's idle time.

When a data change occurs on the controller, the PVI is notified in the response frame of the life sign monitor or a "normal" data response that event variables have changed. These variables are then read by the PVI Line.

Advantages of event-driven communication:

  • Variables that do not change often (e.g. alarm variables) reduce the load on the cyclic communication.
  • This allows variables with a short refresh time to be read faster.
  • No load on the controller because monitoring takes place in the idle time.

<< Previous Topic
Setting the process object state to active or inactive

Start Page

Next Topic >>
Setting up the read cycle


FAQs

Setting up the read cycle

The refresh time determines how frequently a variable object is updated.

The PVI Manager / PVI Line attempts to acquire the process data within this time period. The controller monitors the event variables for data changes within this time period.

The defined refresh time is not a guarantee of the actual acquisition time because this can be affected by other factors:

• Controller response time
• Number of active variables
• Tasks processed asynchronous to the normal read cycle of variables
• Protocol/medium used

Real-time communication between the PC and controller is not possible with PVI because the defined times cannot be guaranteed due to the dynamic setup of the variables and communication between the PVI Manager and the client application.

Setting refresh times:

  • Data that changes slowly (e.g. temperature values) should have a corresponding refresh time in the seconds range.
  • Variables that only have to be read when starting the application, such as set values, should be registered with a refresh time of "= 0".
  • Data that only has to be read after a specific application action should be registered with a refresh time of = "-1".
  • Data that is used to display movements should be registered with a short refresh time.

<< Previous Topic
Acquiring process data

Start Page


CAN device configurator

The following CAN device configurators are used for the respective Windows platforms:

  • CAN device configurator - Windows 7 or higher
  • CAN device configurator - Windows NT/2000/XP

The CAN device configurator can be opened by selecting "CAN Devices" in the Windows Control Panel.

CAN device configurator in Windows 7 or higher:

The CAN device configurator is used to define the properties of CAN communication.

Parameter

Property | Description
Baud rate | Data rate of the CAN bus in bits/s.
Use extended format (29-bit ID) | Use of 29-bit identifier (extended frames) instead of 11-bit identifier (standard frames) for CAN communication. If 29-bit CAN identifiers (extended frames) are used, then 11-bit identifiers cannot be sent or received.
Restart controller after "Bus off" | The driver tries to automatically restart the controller after a "Bus off" condition. A "Bus off" condition occurs if the internal error counter in the controller, i.e. through short circuit of the CAN line, reaches a certain value (transmit error count). In this case, CAN communication is terminated and can only resume after a restart of the controller.

Timing

Property | Description
Use frame limitation for CAN write requests | Specifies whether frame limitation is active. The number of CAN write requests sent per cycle can be limited by selecting this option. This reduces the outgoing load from the PC to the CAN bus. This could be important if other stations (CAN cards) on the bus can only process a certain number of received CAN messages using the set baud rate or if their interrupt load in general should be reduced. However, the disadvantage of limiting frames is slower CAN communication. Setting frame limitations has an effect on all CAN communication that passes through this CAN controller.
Number of frames per cycle | Maximum number of CAN messages sent within the specified cycle time. Only active if frame limiting is in effect.
Time for write cycle (ms) | Cycle time (in ms) within the frame cycle maximum in which the specified number of CAN messages are sent. Only active if frame limiting is in effect.
Use delay time for CAN write requests | Specifies whether delay time for write requests is active. With a delay time for write requests, a defined delay must pass between receiving a frame from a CAN station on the bus and sending the next frame to this CAN station. Unlike frame limitation, delay time is path-specific. This means: A delay can be defined and controlled for each path in the driver. The value specified here is used as a preset value. A different time delay can be assigned to station paths in an application, for example in PVI ("/RW" parameter in the station object connection description of the direct CAN line).
Delay time (ms) | Write request delay time in ms This is only active if CAN write request delay time is in effect.

CAN device configurator - Windows NT/2000/XP:

The CAN device configurator manages the registration of all B&R CAN devices in the device list. The assigned device number corresponds to the index in the device name of a CAN device. The PVI addresses CAN devices using their device names (INACAN1, DCAN1).

Device list

The device list shows all registered CAN devices as well as all plug-and-play LS172 cards that have not been registered. Registered devices are device entries with assigned device numbers (CAN1, CAN2, etc.). An icon shows the status of the device in the left-hand column. Registered devices have their device names next to the status icon. The index in the name corresponds to the device number. In the PVI, the name CAN should be replaced by INACAN or DCAN (CAN1 corresponds to INACAN1 / DCAN1, CAN2 corresponds to INACAN2 / DCAN2, etc.). The type of card is shown in the column on the right. Plug-and-play cards are displayed with their set card number (value in parenthesis).

Meanings of status icons:

Symbol | Function
 | Device registered and enabled
 | Device registered but not enabled Possible cause: - A PnP CAN card with the specified card number could not be found. - The device has been disabled by the user. See "Properties" function, "General" tab.
 | Driver indicates an error for a registered device Any corresponding error text can be read under the "General" tab found in "Properties".
 | PnP device not registered

The "Add device" and "Delete device" functions are available to manage the device list.

Any changes to the device list or to device properties will only take effect after the computer is restarted.

"Add device" function

To address a CAN card, it must first be registered as a device and entered in the device list. The following dialog box opens when you click on the "Add device" button:

An available device number must be assigned for the new device. The input field defaults to the lowest available number. The first 10 possible numbers (if still available) are listed in the input field selection list. For standard CAN interface and LS172 ISA (Legacy) cards, the type of card must be set in addition to the device number.

Windows platform | Permissible device numbers | Supported card types
Windows NT/2000/XP | 1 to 99 | Standard, LS172 ISA (Legacy), LS172 PCI

Register plug-and-play PCI LS172 card as device:

  1. Mark the line with the question mark icon [image] in the device list.
  2. Click on the "Add device" button.
  3. Choose a free device number.
  4. Click "OK" to close the dialog box.

Register standard CAN interface or ISA (Legacy) LS172 card as device:

  1. Do not mark a line or mark the line without the question mark icon [image] in the device list.
  2. Click on the "Add device" button.
  3. Choose a free device number.
  4. Set card type (standard or LS172 ISA).
  5. Click "OK" to close the dialog box.

"Remove device" function:

To remove a device, select the device in the device list and click on the "Remove device" button.

All unnecessary devices should be disabled or removed since each one uses resources.

Device properties

To set device properties, highlight the desired device in the Device list and then click on "Properties" (shortcut menu).

General

Property | Description
Disable device | Disables the selected device. When the computer is restarted, no drivers will be loaded for this device. However, the device will still be shown in the device list and its settings will be preserved.
Device status | The selected device name and card type are shown in the window. Corresponding error messages are also displayed here for faulty devices.

Resources

Property | Description
PnP card number | Used only for LS172 PCI and LS172 ISA PnP cards. The card number specified here must match the setting on the LS172 card.
Interrupt number (IRQ) | Displays the current interrupt number used for the device. Setting the interrupt number is only necessary for standard CAN interface (card) and LS172 ISA (Legacy) cards. Normal setting for standard CAN interface: 10 (selectable on IPC 4000 using jumper). The required setting for LS172 ISA (Legacy) cards depends on the card's jumper setting.
Port address (I/O) | Displays the current port address used for the device. Setting the port address is only necessary for the standard CAN interface and LS172 ISA (Legacy) cards. Normal setting for standard CAN interface: 0x384 for IPC 2000 and 5000, 0x310 for IPC 4000. The required setting for LS172 ISA (Legacy) cards depends on the card's jumper setting.
IST priority (only for Windows CE) | Specifies the IST (Interrupt Service Thread) priority. Preset value: 100. A value can be selected between 97 (highest priority) and 152 (lowest priority). Since the standard CAN interface doesn't have FIFO for receiving CAN messages, the value should not exceed 100. If data loss occurs during communication, a lower value should be set. LS172 cards have a receive FIFO. Values larger than 100 can therefore be set. This can become necessary when data loss occurs during intensive CAN communication using other interfaces (i.e. Ethernet).

Parameter

Property | Description
Selection of the CAN controller | The selection field shows the currently selected CAN controller. On cards with more than one CAN controller (LS172 card), all parameter settings apply to the controller specified here.
Baud rate | Data rate of the CAN bus in bits/s. Depending on the card type, all supported baud rate values are listed in the selection list of the input field.
Use extended format (29-bit ID) | Use of 29-bit identifier (extended frames) instead of 11-bit identifier (standard frames) for CAN communication. If 29-bit CAN identifiers (extended frames) are used, then 11-bit identifiers cannot be sent or received.
Restart controller after "Bus off" | The driver tries to automatically restart the controller after a "Bus off" condition. A "Bus off" condition occurs if the internal error counter in the controller, i.e. through short circuit of the CAN line, reaches a certain value (transmit error count). In this case, CAN communication is terminated and can only resume after a restart of the controller.

Timing

Property | Description
Selection of the CAN controller | The selection field shows the currently selected CAN controller. On cards with more than one CAN controller (LS172 card), all timing settings apply to the controller specified here.
Use frame limitation for CAN write requests | Specifies whether frame limitation is active. The number of CAN write requests sent per cycle can be limited by selecting this option. This reduces the outgoing load from the PC to the CAN bus. This could be important if other stations (CAN cards) on the bus can only process a certain number of received CAN messages using the set baud rate or if their interrupt load in general should be reduced. However, the disadvantage of limiting frames is slower CAN communication. Setting frame limitations has an effect on all CAN communication that passes through this CAN controller.
Number of frames per cycle | Maximum number of CAN messages sent within the specified cycle time. Only active if frame limiting is in effect.
Time for write cycle (ms) | Cycle time (in ms) within the frame cycle maximum in which the specified number of CAN messages are sent. Only active if frame limiting is in effect.
Use delay time for CAN write requests | Specifies whether delay time for write requests is active. With a delay time for write requests, a defined delay must pass between receiving a frame from a CAN station on the bus and sending the next frame to this CAN station. Unlike frame limitation, delay time is path-specific. This means: A delay can be defined and controlled for each path in the driver. The value specified here is used as a preset value. A different time delay can be assigned to station paths in an application, for example in PVI ("/RW" parameter in the station object connection description of the direct CAN line).
Delay time (ms) | Write request delay time in ms This is only active if CAN write request delay time is in effect.

<< Previous Topic
CAN Device Drivers


CAN Devices

In this section the following topics are discussed:

CAN Devices

CAN Device Drivers

CAN Device Configurator

Start Page

Next Topic >>
CAN Device Drivers


CAN device drivers

The following drivers are used:

Windows platform | Driver | Functionality
Windows NT/2000/XP | InaCan.sys | The driver is normally loaded in startup type 2 - "Automatic" - and started automatically when the system is booted. The device list stored in the registry is read and a device instance is created for each device.
Windows 7 and higher | BrCanDrv.sys | The driver is loaded in startup type 3 - "Demand" - and started by the PnP Manager automatically when the system is booted.

Depending on the Windows platform used, the corresponding CAN driver is installed with the PVI Setup. To do this, the CAN driver must be selected in the PVI Setup dialog box.

For installation under Windows 7 SP1 and Windows Embedded Standard 7 SP1, you must first install Windows update KB3033929.

Communication

Communication between the CAN driver (Windows PC) and CAN nodes occurs using CAN messages with identifiers defined by the application. Standard frames (11-bit identifier) and extended frames (29-bit identifier) are supported.

The CAN driver acts as a producer (writes data) and as a consumer (receives data); other CAN stations can function as producers and consumers as well.

Supported hardware

The following CAN cards are supported:

Windows platform | Supported hardware
Windows NT/2000/XP | B&R Standard CAN interface on B&R Provit 2000 and 4000, B&R Standard CAN interface on B&R Provit 5000 interface card, B&R add-on CAN interface module on APC and Panel PC, B&R dual CAN card LS172.6 - PCI, B&R dual CAN card LS172.4 - Legacy ISA
Windows 7 and higher | CAN driver CC770: B&R Interface option 5AC901.ICAN-00 B&R Interface option 5ACCIF01.ICAN-000 CAN driver SJA1000: B&R Interface option 5AC901.ICAN-01 B&R Interface option 5ACCIF01.ICAN-C00 B&R Interface option 5ACCIF02.CANE-000

Standard CAN interface on Provit 2000

CAN connections are made by connecting a two-wire cable to COM3, which can be used as a RS485/TTY/CAN interface, using a DSUB connector. The CAN interface is automatically selected when the corresponding pins are connected.

Resources used: Port address: 0x384, interrupt number: 10.

Standard CAN interface on Provit 4000

CAN connections are made by connecting a two-wire cable to the separate CAN interface using a DSUB connector.

Resources used: Port address: 0x310, Interrupt number: 10 (with revisions, < 10 also 11, 12 or 15).

Standard CAN interface on a Provit 5000 interface card

CAN connections are made using a two-wire cable with a DSUB connector.

Resources used: Port address: 0x384, interrupt number: 10.

Add-on CAN interface

The add-on interface is configured and addressed like a standard CAN interface.

CAN connections are made using a two-wire cable with a DSUB connector.

Resources used: Port address: 0x384, interrupt number: 10.

LS172 card

The LS172 card has 2 CAN controllers. CAN connections are made by connecting a two-wire cable to a B&R dual CAN card LS172 (4-pin plug).

The LS172.4 (ISA) card can be operated in Legacy ISA or PnP ISA mode. When used in Legacy ISA mode, interrupt numbers can be selected from 5, 10 or 15, and port addresses from 0x250, 0x290, or 0x350. All of these settings can be made on the card using jumpers. Up to three LS172.4 cards in Legacy ISA mode can be used on a PC as long as the corresponding interrupt numbers and port addresses are not already used by other components.

With the use of LS172 plug-and-play cards (LS172.6 PCI), the card number is used to differentiate between the individual cards within a PC. The card number is set on the card using a code switch. A value between 0 and 15 can be chosen. If more than one LS172.6 PCI card is used, each card must have a different card number.
Note: The card number setting is only evaluated once by the driver after the computer is restarted.

For a baud rate of 800 kbit/s, firmware version 2.10 (LS172.4) or 2.90 (LS172.6x) is required. Extended frames (29-bit identifiers) with an ID larger than 25 bits can only be transmitted when using firmware version 2.00 (LS172.4) or 2.80 (LS172.6x). RTR send objects can be used with firmware version 1.90 (LS172.4) or 2.40 (LS172.6x).

<< Previous Topic
CAN Devices

Start Page

Next Topic >>
CAN Device Configurator