LAN

Concept Link IconSee also Concept Link IconExample

Communication control for client/server networking.

See also the Help book on Networked applications.

If executed in a WebVue session context this instruction is processed by the computer that hosts the web back end, which is a station running the PcVue software within the distributed system.

WebVue support - Yes.

Mode Mnemonic Syntax
1 CONNECT 1
2 PRODUCT_MODE 2
3 GET_LISTS 3
4 GET_STATIONS_INLIST 4
5 SET_SERVER_MODE 5
6 GET_STATION_NUMBER 6
7 GET_STATION_NAME 7
10 SET_AVAILABLE_RATE 9
11 SET_READ_SERVER 10
12 RESET_READ_SERVER 11
13 START_CONNECTIONS 12
14 STOP_CONNECTIONS 12
15 START_CONNECTION 13
16 STOP_CONNECTION 13
17 SET_ACTIVE_NODE 14
19 START_NODE 15
20 STOP_NODE 15

From version 7.20a onwards, the mode PRODUCT_MODE is obsolete, mode SET_SERVER_MODE should be used instead.

The mode CONNECT is obsolete, mode START_CONNECTION should be used instead.

Some modes require a connection name to be passed as parameter. See the topic Network status variables naming rules in the Application Explorer book for more information about the naming rule for connections.

Syntax 1

IntVal = LAN (Mode, RemoteServerConnection);

Return type: INTEGER.

Argument

Meaning

RemoteServerConnection

The name of a connection of type server as configured on a node attached to a station running the PcVue software in the distributed application. Type STR.

Execution

Mode

Mnemonic

Action

1

CONNECT

The station that runs the program containing the LAN instruction is connected to the specified server. The station running the program must be configured as a client and the remote server must belong to an association of servers.

Return: 1 if OK, else 0.

Syntax 2

IntVal = LAN (Mode, AssocNb, Flag);

Return type: INTEGER.

Argument

Meaning

AssocNb

The association number as specified in the network configuration.

Flag

A flag indicating the new status of the server.

1 The server becomes active.
0 The server becomes passive.

Execution

Mode

Mnemonic

Action

2

 

PRODUCT_MODE

The status of the station running the program is switched to the requested state (active or passive).

When a server station is switched to passive, any Equipment, DDE or Internal variables are temporarily changed to External, and their value comes from the active server.

When a server station is switched to active any variables that were temporarily changed to External return to their original state.

Return: 1 if OK, else 0.

The database bit variable SYSTEM.SERVER.Association Name.Station Name is set to 1 when the local station is an active server, and 0 when it is passive

Syntax 3

BuffList = LAN (Mode, ListType, StationName);

Return type: LONG.

Argument

Meaning

ListType

Type INTEGER:

1 = Server list
2 = Client list
3 = Other list

StationName

The station name for selection. Type STR.

Execution

Mode

Mnemonic

Action

3

GET_LISTS

Fill BuffList with all the lists of type ListType containing StationName.

Return: The handle of the buffer.

Format of BuffList: list1,list2,list3....

The buffer BuffList will be allocated automatically. Remember to release the buffer via FREE_BUFFER.

Syntax 4

BuffList = LAN(Mode, ListType, ListName);

Return type: LONG.

Argument

Meaning

ListType

Type INTEGER:

1 = Server list
2 = Client list
3 = Other list

ListName

The name of the list to be selected. Type STR.

Execution

Mode

Mnemonic

Action

4

GET_STATIONS_INLIST

Fills the buffer identified by BuffList with the station identifiers in the list List Name.

Return: The handle of the buffer.

Format of BuffList: list1,list2,list3....

The buffer BuffList will be allocated automatically. Remember to release the buffer via FREE_BUFFER.

Syntax 5

IntVal = LAN(Mode, AssocName, ServerName, ServerMode);

Return type: INTEGER.

Argument

Meaning

AssocName

Association name.

ServerName

Name of the server station to be switched between active and passive states.

ServerMode

Required state:

SET_SERVER_ACTIF = active

SET_SERVER_PASSIF = passive

Execution

Mode

Mnemonic

Action

5

SET_SERVER_MODE

This mode makes it possible to switch the server station to the active state only if that station belongs to a single active server association.

When the station switches out of the passive server state, the variables of the types internal, equipment, DDE, OPC and LON produced by the association temporarily become external and subscribe on the active, remote server station.

When the station switches out of the active server state, those temporarily external variables stop subscribing and revert their original type.

Return: 1 if OK, else 0.

The specialized bit variable SYSTEM.Association_Name.Station_Name has the value 1 when the server station is active, 0 when it is passive.

This only works if the Availability Rate is the same in both historic servers.

For compatibility, the variables that do not have a list of server stations also change.

The internal variables that start with SYSTEM do not switch.

When the station that is active is forced passive, the station in the association (apart from the station that is forced) which has the lowest number will be forced active.

Syntax 6

IntVal = LAN(Mode, StationName [, AlsoSearchAssociation]);

Return type: INTEGER.

Argument

Meaning

StationName

Name of the station.

AlsoSearchAssociation

What to return if the station name corresponds to an association name: (optional)

0 Return the station number, else

1 Return the association number if the station number is not found.

Execution

Mode

Mnemonic

Action

6

GET_STATION_NUMBER

Provides the station number from its name.

Return: Station number if OK, else 0 (station name does not exist...).

Syntax 7

StrVal = LAN(Mode, StationNumber, AlsoSearchAssociation);

Return type: STR.

Argument

Meaning

StationNumber

Number of the station.

AlsoSearchAssociation

What to return if the station number corresponds to an association number: (optional)

0 Return the station name, else

1 Return the association name if the station name is not found.

Execution

Mode

Mnemonic

Action

7

GET_STATION_NAME

Provides the station name from its number.

Return: Station name if OK, else an empty string (station number does not exist...)

Syntax 9

IntVal = LAN (Mode, AssocName, StationName, AvailableRate);

Return type: INTEGER.

Argument

Meaning

AssocName

Name of the association.

StationName

Name of the server station in the association.

AvailableRate

Availability rate (between 0 and 100). Type INTEGER

Execution

Mode

Mnemonic

Action

10

SET_AVAILABLE_RATE

Modify dynamically the availability rate of a server station StationName that is part of an association AssocName.

This mode can be run on any station.

Return: 1 if OK, else 0.

The availability rate may be changed when it is anticipated that an archive server will be slowed down by a maintenance procedure (e.g. purge). For a real time association it may be used for example to set a server in main mode.

This mode provides for the situation where two server stations of an association with a single active producer have been disconnected. Both are active but when they are re-connected, only the priority station remains active.

If all stations are at the same availability rate, the one with the lower station number remains active. Otherwise, it’s the station with the highest availability rate that remains active.

The change does not persist since it does not involve any change of configuration.

Syntax 10

IntVal = LAN (Mode, AssocName, StationName [, ClientStationName]);

Return type: INTEGER.

Argument

Meaning

AssocName

The name of a historic association.

StationName

The name of one of the servers in historic association.

ClientStationName

The name of a client for the historical data produced by the association AssocName.

If ClientStationName is not given, the local station that runs the instruction is used.

Execution

Mode

Mnemonic

Action

11

SET_READ_SERVER

The server station in an historic association can be selected dynamically to process read requests for a client station.

This mode can be used to redistribute the workload.

The active server station for the client station ClientStationName in the association AssocName will then be StationName regardless of the availability rate of servers in the association.

Return: 1 if OK, else 0.

Syntax 11

IntVal = LAN (Mode, AssocName, StationName[, ClientStationName]);

Return type: INTEGER.

Argument

Meaning

AssocName

Name of the association.

StationName

The name of one of the servers in historic association.

ClientStationName

The name of a client for the historical data produced by the association AssocName.
If ClientStationName is not given, the local station that runs the instruction is used.

Execution

Mode

Mnemonic

Action

12

RESET_READ_SERVER

The server station StationName for the client station ClientStationName in the association AssocName is no longer forced to be the active server. Whichever server has the higher availability rate will be active.

Return: 1 if OK, else 0.

Syntax 12

IntVal = LAN (Mode, RemoteStation);

Return type: INTEGER.

Argument

Meaning

RemoteStation

Name of the remote station in the distributed application (as specified in the multi-station configuration). Type STR.

Execution

Mode

Mnemonic

Action

13

START_CONNECTIONS

If the station running the program has a connection configured with the specified remote station, it connects to that station.

If the station running the program is configured as a server, it accepts connections from the specified remote station.

14 STOP_CONNECTIONS

If the station running the program has a connection configured with the specified remote station, it disconnects from that station.

If the station running the program is configured as a server, it no longer accepts connections from the specified remote station.

    Return: 1 if OK, else 0.

Syntax 13

IntVal = LAN (Mode, RemoteStation, RemoteConnection);

Return type: INTEGER.

Argument

Meaning

RemoteStation

Name of the remote station in the distributed application (as specified in the multi-station configuration). Type STR.

RemoteConnection Name of the Server or Client connection of the remote station RemoteStation. Type STR.

Execution

Mode

Mnemonic

Action

15

START_CONNECTION

If RemoteConnection is a server connection and the station running the program has a link configured with RemoteStation, it connects to RemoteStation using the RemoteConnection connection.

If RemoteConnection is a client connection and the station running the program is configured as a server, it connects to RemoteStation via the RemoteConnection connection.

16 STOP_CONNECTION

If RemoteConnection is a server connection and the station running the program has a link configured with the RemoteStation, it disconnects to RemoteStation using the RemoteConnection connection.

If RemoteConnection is a client connection and the station running the program is configured as a server, it no longer accepts connections from RemoteStation via the RemoteConnection connection.

    Return: 1 if OK, else 0.

Syntax 14

IntVal = LAN (Mode SourceNodeName[, DestinationNodeName]);

Return type: INTEGER.

Argument

Meaning

SourceNodeName Name of the source node. Type STR.
DestinationNodeName Name of the destination node, unless blank in which case all stations are affected. Type STR.

Execution

Mode

Mnemonic

Action

17

SET_ACTIVE_NODE

Enables selection of the active node for a particular station or all stations to which it is connected. This mode can be run from any station.

The following system variables are updated:

SYSTEM.ClientConnectionNodeName.ACTIVECXT

SYSTEM.ServerConnectionNodeName.ACTIVECXT

SYSTEM.NodeName.ACTIVECXT

SYSTEM.ClientConnectionNodeName.ACTIVE_NUMBER

SYSTEM.ServerConnectionNodeName.ACTIVE_NUMBER

SYSTEM.NodeName. ACTIVE_NUMBER

Return: 1 if OK, else 0.

Syntax 15

IntVal = LAN (Mode, RemoteStation, RemoteNode);

Return type: INTEGER.

Argument

Meaning

RemoteStation

Name of the remote station in the distributed application (as specified in the multi-station configuration). Type STR.

RemoteNode Name of the node of the remote station RemoteStation. Type STR.

Execution

Mode

Mnemonic

Action

19

START_NODE

If the station running the program has a connection configured with the specified node of the remote station, it connects to that node of this station.

If the station running the program is configured as a server, it accepts connection from the specified node of this remote station.

20 STOP_NODE

If the station running the program has a connection configured with the specified node of the remote station, it disconnects from that node of this station.

If the station running the program is configured as a server, it no longer accepts connection from the specified node of this remote station.

    Return: 1 if OK, else 0.

Example

There are three stations with each two nodes.

• SERVER1 with nodes SERVER1_0 and SERVER1_1

• SERVER2 with nodes SERVER2_0 and SERVER2_1

• CLIENT1 with nodes CLIENT1_0 and CLIENT1_1

The instruction to make node 0 of station SERVER1 active for all stations is:

LAN( "SET_ACTIVE_NODE", "SERVER1_0");

The instruction to make node 0 of station SERVER1 active only for node 0 of station SERVER2 is:

LAN( "SET_ACTIVE_NODE", "SERVER1_0", "SERVER2_0");