Internal data points

This chapter describes the internal data points _SNMPManager, _SNMPAgent, _SNMPLive agent and "_SNMPV3Entity".

Data point type _SNMPManager

Data point Description
_SNMPManager The control data point type for the SNMP manager (= SNMP driver). The name of the data point is composed of the driver number and of the name specified in the config file. In standard case it is _1_SNMPManager. The elements of this data point serve for communication with SNMP driver layer and inform about the state of the driver.

Elements of _SNMPManager

Element Type Meaning
Command string Commands can be sent to the driver layer via this element. This element serves for test purposes.
Trap.EnterpriseOID string Shows details on the last (received) SNMP trap. The enterprise OID contains information about the agent that sent the trap.
Trap.IPAddress string The IP address field contains the IP address of the agent that sent the trap.
Trap.genericTrap string

This field shows when a so called generic trap was sent. The following possibilities are available:

  • Coldstart
  • Warmstart
  • LinkUp
  • LinkDown
  • AuthenticationFailure
  • EgpNeighborLoss

For the meaning of these terms see RFC 3418 (SNMP v2)

Trap.PayloadType Text Data type of the trap payload.
Trap.specificTrap string If a standard trap was not sent, this field contains the value of the last element of the Trap OID.
Trap.timestamp uint The time stamp specifies when the trap was sent (run time of the agent according to the system.sysUpTime)
Trap.PayloadOID dyn_string The SNMP trap can contain further SNMP elements. The elements show details on the trap. These elements depend on the particular trap and are always sent as OIDPair <-> Value. The PayloadOID field contains the object identifier.
Trap.PayloadValue dyn_string

This element contains the values of payload elements.

To handle octet strings containing non-printable characters the config entry [snmpdrv] trapPayloadOctetStringHex can be activated.

Trap.HomelessTrap string

This element contains information regarding homeless traps.

The message will be saved in following format:

<Agent name>|<AgentId>|<SNMP data type as string (SNMP data type as integer value)>|<OID>|<agent IP>

Example

  • If the agent is not configured, which has sent the trap, following message will be set to the data point:

    ?|?|INT32
    (2)|1.3.6.1.4.1.8691.10.2242.11.6|192.168.152.25

    A trap has been received from a device at IP 192.168.152.25. The unknown fields for <Agent name> and <AgentId> show a '?'.

  • If the agent has been configured but the OID is unknown, following message will be set to the data point:

    _1_SNMPAgent_6|6|INT32
    (2)|1.3.6.1.4.1.12148.9.1.10.0|192.168.152.18

    A trap has been received from agent _1_SNMPAgent_6 at IP 192.168.152.18 but the OID 1.3.6.1.4.1.12148.9.1.10.0 is not known inside the WinCC OA System

Redirector uint Obsolete.
TrapFilter.Address dyn_string The trap recipient can filter traps by source address. This filtering is possible via the TrapFilter.Address element.
TrapFilter.OID dyn_string The trap filter can also analyze the EnterpriseOID of the traps and respond to only specific traps. Thus, the traps can be divided to several SNMP managers.

Data point type _SNMPAgent

Data point Description
_SNMPAgent

The SNMP agent data point type represents the configuration for an agent. The data point names are composed of a driver number, the string from the config file and the agent number. Normally, a data point would be named e.g. _1_SNMPAgent_5.

Note: Additionally, a data point with a description _SNMPAgent has to exist. If it does not exist the config entry [snmpdrv] agentDPTemplate has to be changed.

Elements of _SNMPAgent

Element Type Meaning
Access.IPAddress string The IP address of the agent, e.g. 192.168.1.13, or a computer name, e.g. eiwrk068. If no IP address was set here or it has been deleted (empty string) the entity is disabled automatically and the internal DPE Status.Timeout is set to FALSE independent of the state it was before.
Access.ReadCommunity string The SNMP Read communitystring.
Access.WriteCommunity string The SNMP Write Communitystring.
Access.Timeout uint The timeout for SNMP messages in 1/100 seconds. This means that a reply to a message has to be sent before this timeout elapses. The default value is 100 (=1s). It might be necessary to increase the timeout in case of slow networks /agents . Valid values are 100 - 1000 (= 1 - 10secs).
Access.Retries uint Retries before a SNMP protocol error is shown. The standard value is 1, maximum 10 retries can be configured.
Access.Protocol uint The SNMP protocol. 0,1 mean v1 and 2 means v2c. The standard is v1.
Access.Port uint The port number that should be used to communicate with the agent. The standard SNMP port is 161. You can, however, specify any other port.
Access.Flags bit32

This element defines when a redundancy switch happens. A redundancy switch is only possible if a valid target is configured (.Redu.Access).

  • bit0: Redundancy switch when a timeout occurs. Defines if an agent switch is performed if the response of a READ or WRITE request returns the timeout status.
  • bit1: Redundancy switch when a keepAlive-error occurs. Defines if an agent switch is performed if a KEEPALIVE check fails.
  • bit2: Driver uses getBulk requests instead of individual getNext requests.
  • bit3: The connection is terminated if a USM error occurs (error code ≤ 100).
  • bit4: The connection is terminated when a user USM error occurs (error code > 100).
  • bit5: An alive query is performed when the configuration is changed.
  • bit6: Determines whether an octet string within the browse result should be displayed in hexadecimal format (=1) or as a visible string (=0; default).
Important: Redundancy switching is only possible if a valid target (.Redu.Access) is configured.
Restriction: getBulk requests (see bit 2) can not be used for SNMP V1 agents.
Status.ErrorOID dyn_string

If a protocol error occurs, this data point shows the corresponding OID. Since the element is a dynText, all current not available OIDs are shown. Furthermore, the invalid bits of the WinCC OA elements are set accordingly.

Format:

errorcode#OID - ERROR: errortext

The possible error codes are:

OID errors
  • 2//!< No such VB name, see error index
  • 3 //!< Bad Vb
  • 6 //!< No access to MIBs data
  • 7 //!< Requested type was incorrect
  • 8 //!< Request Pdu has inccorect length
  • 9 //!< Request Pdu has wrong encoding
  • 10 //!< Request Pdu has wrong value
  • 11 //!< Unable to create object specified
  • 12 //!< Inconsistent value in request
  • 13 //!< Resources unavailable
  • 14 //!< Unable to comit
  • 15 //!< Unable to undo
  • 16 //!< Authorization error
  • 17 //!< Mib Object not writeable
  • 18 //!< Inconsistent naming used
Protocol errors
  • -5 //!< outstanding request timed out
  • -8 //!< snmp::destroyed with oustanding reqs pending
Transport errors
  • -20 //!< transport unsupported
  • -21 //!< transport in use
  • -22 //!< transport operation failed
  • -23 //!< transport missing rights
Note: If the debug flag 29 is set, the error messages are also shown in the WinCC OA log viewer.
Status.QueueLength uint This element shows the current length of the request queue of the agent. This value is only updated when also a protocol error occurred. The value is shown for diagnostic purposes and is irrelevant for the running operation.
Status.Timeout bool This bit is set when no message was exchanged with the agent for a specific time (configured via the config entry agentConnectTimeout). If no IP address was set in the DPE Access.IPAddress or has been deleted (empty string), this bit iis set to FALSE, independent of its current state.
Status.ConnState bool

The DPE displays the connection state of the SNMP Agent

The following applies to each Agent configured for an SNMP manager:

  • On startup of the manager the value for Status. ConnState is set to FALSE.
  • Configuring the first peripheral address for an agent triggers an alive check, the value of the DPE will be set to TRUE if the configured Agent is available. After this the value is updated on each alive check
  • For triggering this first check the address must be set to active.
Note: Configuring further peripheral addresses does not trigger trigger an alive check.
Status.WriteResponse string

The data point element contains the response of the writing attempt of the SNMP agent. Following information is stored:

<error code>#<internal agent ID>_<OID> [ -error <error description>],

Example for a successful write process:

0#1_1.3.6.1.4.1.8691.10.2242.10.1.1.4.11

Example for an writing process error:

-5#1_1.3.6.1.4.1.8691.10.2242.10.1.1.4.11 - error: SNMP++: SNMP request timed out

The corresponding error codes can be seen in the description of the DPE element Status.ErrorOID.

Status.ActiveConn int

This element indicates the active target the driver communicates with:

  • 0: first target
  • 1: redundant target
Command uint

Two commands can be sent to the local agent via this element:

  • Clearerror (1) deletes the ErrorOID data point and also all internal errors.
  • Checkerror (2) updates the ErrorOID data point and the QueueLength element.
Browse.Start string

Defines the start-OID for querying all data of the agent. These will be written to the Browse.Result DPE.

If this DPE is left empty, the query is started with the start-OID "1.3.6.1".

It is possible to initiate several browsing requests by dpSet on this data point element. The requests are added to a queue one by one and are executed in the same order.

Basically there is no limit to the number of browsing requests in the queue. However, a browsing request is discarded if the exact same request is already in the queue.

Each browsing request is identified (see Browse.RequestId below) by the string that was set on this data point element. This means that the following requests are different and unique requests that will be added to the queue concurrently:

  • “1.3.6.1.2.1.1”
  • “1.3.6.1.2.1.1:7”
  • “1.3.6.1.2.1.1:3”
  • “1.3.6.1.2.1”
  • “1.3.6.1.2.1.2”
Browse.Result dyn_string

Contains the result of the query that was started with the Browse.Start DPE. During the browsing the value of this DPE is "1 - started browsing".

Once the browsing is completed, the result contains the data of the agent. One data set always consists of three lines:

1st line: OID

2nd line: Value in a default transformation

3rd line: Data type as number#data type as text

Example with two data sets:

1.3.6.1.2.1.1.1.0
Hardware: x86 Family 6 Model 15 Stepping 8 AT/AT COMPATIBLE
4#OCTETS
1.3.6.1.2.1.1.3.0
0:00:26.60
67#TIMETICKS

Possible values for the data type:

  • 2 - INT32
  • 3 - BITS
  • 4 - OCTETS
  • 6 - OID
  • 64 - IPADDR
  • 65 - CNTR32
  • 66 - UINT32
  • 67 - TIMETICKS
  • 68 - OPAQUE
  • 70 - CNTR64

If the result does not contain a number of entries which can be divided by 3, then it is a state message. In this case the first line indicates the status code:

1 - query started
-1 - error

The error code and the description are contained in the second line.

For example:

-1
-5#SNMP++: SNMP request timed out
Browse.RequestId string Request ID to identify browsing requests and the corresponding results. The ID is set together with the Browse.Result DPE. It is exactly the same as the string which is set on Browse.Start to initiate a browse request.
Redu.Access.IPAdress string The IP address of the secondary agent, or a computer name. If no IP address was set or it has been deleted (empty string) the entity is disabled automatically, the internal DPE-Status.Timeout is set to FALSE independent from the state it was before and no redu switch can be performed.
Redu.Access.Port uint The port number for communication with the agent. The standard SNMP port is 161.
Redu.Access.ReadCommunity string The SNMP Read community string of the redu agent.
Redu.Access.WriteCommunity string The SNMP Write Community string of the redu agent.
Redu.Status.ConnState bool

Displays the connection state of the redundant SNMP agent.

On startup of the manager, the value for Redu.Status.ConnState is set to FALSE. After the first successfully received message the state will be set to TRUE.

Note: If agentAliveTimeout is set to 0 the connState will be false until the redu target receives a message (after a redu switch).
Redu.Status.Timeout bool This bit is set when no message was exchanged with the agent for a specific time (configured via the config entry agentConnectTimeout). If no IP address was set in the DPE Redu.Access.IPAddress or has been deleted (empty string), this bit is set to FALSE, independent of its current state.

Data point type SNMPLiveAgent

Data point Description
_SNMPLiveAgent Contains the WinCC OA DPE elements that can be queried via SNMP.

Elements of _SNMPLiveAgent

Element Type Meaning
Command string This element can be set via SNMP. If the MIB object 1.3.6.1.4.1.13828.2.1.12 is described with a text, this text is shown on the DPE. Thus, a CTRL script can connect to this DPE and is activated when the value changes.
Response string This element is represented via the MIB object 1.3.6.1.4.1.13828.2.1.13. The above mentioned CTRL script can show a result with the aid of this element. The result is available via SNMP.
SpecificTrap string If a value is written and saved in this element, the value is sent as a UserTrap from Live Agent via the PmonProxyAgent to all configured TrapTargets. This only happens when the UserTraps are activated in the config file.
DPTableElements dyn_string This element contains the DP elements and their indexes, which can be queried via SNMP.

Data point type _SNMPV3Entity

Note: Additionally, a data point with a description _SNMPAgent has to exist. If it does not exist the config entry [snmpdrv] agentDPTemplate has to be changed.
Element Type Meaning
Command uint

Commands can be sent to the driver layer via this element. This element servers for test purposes.

  • Alive query (1) is sent to the connected targets
Access.IPAddress string The IP address of the entity, e.g. 192.168.1.13, or a computer name, e.g. eiwrk068. If no IP address was set here or it has been deleted (empty string) the entity is disabled automatically and the internal DPE Status.Timeout is set to FALSE independent of the state it was before.
Access.Port uint The port number used to speak to the agent. The standard SNMP port is 161. You can, however, use an arbitrary port.
Access.Timeout uint The timeout in 1/100 seconds. This means that a reply to a message has to be sent before this timeout elapses. The default value is 1sec. It might be necessary to increase the timeout in case of slow networks /agents . Valid values are 1 - 10secs.
Access.Retries uint Retries before a SNMP protocol error is shown. In case of a timeout, the telegram is repeated. The standard value is 1. Maximum 10 retries can be configured.
Access.SecurityName string The SecurityName describes the user/program that requires access to the data.
Access.SecurityLevel uint

The security level describes which security measures should be used for the data exchange.

  • noAuthNoPriv (1) No authentication and no encryption

  • authNoPriv (2) Authentication but no encryption

  • authPriv (3)Authentication and data encoding

Default value is (1).

Access.ContextName string

The addressed context name on the target computer. The context contains specific MIB objects.

Per agent only one context name can be specified. If several context ranges should be queried per agent, several data points have to be created.

Access.ContextEngineID string The engine ID of the target computer. If the ID is not specified, it is specified when the data is queried.
Access.AuthProtocol uint

There are two protocols available for the authentication of the SNMP users:

  • none (1) no authentication protocol
  • HMAC_MD5 (2) MD5 authentication
  • HMAC_SHA (3) SHA authentication
  • HMAC_SHA2_224 (4) SHA2 authentication
  • HMAC_SHA2_256 (5) SHA2 authentication
  • HMAC_SHA2_384 (6) SHA2 authentication
  • HMAC_SHA2_512 (7) SHA2 authentication

Default value is (1).

Access.AuthPasswd string The password which is used for authorization.

The password is saved encrypted.

Access.PrivProtocol (unsigned) uint

The sent data can also be encrypted in order to increase the security. For the encryption a protocol has to be selected.

  • none (1): no encryption
  • DES (2): DES encryption (Data Encryption Standard)
  • IDEA (9): IDEA encryption (International Data Encryption Algorithm)
  • AES128 (4) Advanced Encryption Standard encryption with 128 bit key
  • AES192 (20) Advanced Encryption Standard encryption with 192 bit key
  • AES256 (21) Advanced Encryption Standard encryption with 256 bit key

Default is (1).

Access.PrivPasswd string The password used for the encryption.

The password is saved encrypted.

Access.Flags bit32

This element defines when a redundancy switch happens. A redundancy switch is only possible if a valid target is configured (.Redu.Access).

  • bit0: Redundancy switch when a timeout occurs. Defines if an agent switch is performed if the response of a READ or WRITE request returns the timeout status.
  • bit1: Redundancy switch when a keepAlive-error occurs. Defines if an agent switch is performed if a KEEPALIVE check fails.
  • bit2: Driver uses getBulk requests instead of individual getNext requests.
  • bit3: The connection is terminated if a USM error occurs (error code ≤ 100).
  • bit4: The connection is terminated when a user USM error occurs (error code > 100).
  • bit5: An alive query is performed when the configuration is changed.
  • bit6: Determines whether an octet string within the browse result should be displayed in hexadecimal format (=1) or as a visible string (=0; default).
  • If this flag is set the counter check for the corresponding V3 Agent, where the V3 Inform/Trap is coming from will be deactivated.

    Per default (= 0) the counter check is active.

    Note: This flag can also be changed while the driver is running and the change becomes effective immediately.
    Tip: This flag must be enabled to allow the reception of SNMP V3 Inform/Trap messages from SCALANCE devices.
Important: Redundancy switching is only possible if a valid target (.Redu.Access) is configured.
Status.ErrorOID dyn_string If a protocol error occurs, the corresponding OID is shown using this data point. Since this element is a dynText, all current and not available OIDs are always shown. Furthermore, also the corresponding invalid bits are set for the WinCC OA elements. If an SNMPv3 USM error occur, this will be also written to this DPE.
Status.QueueLength uint Shows the current length of the request queue of the agent. This value is only updated when a protocol error occurs. The value should be shown for diagnosis purposes and is irrelevant for the runtime operation.
Status.Timeout bool This bit is set when no message was exchanged with the entity for a specific time (configured via the config entry agentConnectTimeout). If no IP address was set in the DPE Access.IPAddress or has been deleted (empty string), this bit iis set to FALSE, independent of its current state.
Status.ActiveConn int

Indicates the active target the driver communicates with

  • 0: first target
  • 1: redundant target
Notify.ID uint

Last number of OID (Object identifier). This number is appended to the OID notification defined in the WinCC OA MIB. If you modify this DPE a trap is sent to the corresponding SNMP V3 entity by the SNMP manager.

-dbg 26 can be used to get debug information when a trap was sent.

Notify.Text string Specify the trap text here. If this element contains a text, the text is sent when Notify.Id is changed.
Browse.Start string

Defines the start-OID for querying all data of the agent. These will be written to the Browse.Result DPE.

If this DPE is left empty, the query is started with the start-OID "1.3.6.1".

It is possible to initiate several browsing requests by dpSet on this data point element. The requests are added to a queue one by one and are executed in the same order.

Basically there is no limit to the number of browsing requests in the queue. However, a browsing request is discarded if the exact same request is already in the queue.

Each browsing request is identified (see Browse.RequestId below) by the string that was set on this data point element. This means that the following requests are different and unique requests that will be added to the queue concurrently:

  • “1.3.6.1.2.1.1”
  • “1.3.6.1.2.1.1:7”
  • “1.3.6.1.2.1.1:3”
  • “1.3.6.1.2.1”
  • “1.3.6.1.2.1.2”
Browse.Result dyn_string

Contains the result of the query that was started with the Browse.Start DPE. During the browsing the value of this DPE is "1 - started browsing".

Once the browsing is completed, the result contains the data of the agent. One data set always consists of three lines:

1st line: OID

2nd line: Value in a default transformation

3rd line: Data type as number#data type as text

Example with two data sets:

1.3.6.1.2.1.1.1.0
Hardware: x86 Family 6 Model 15 Stepping 8 AT/AT COMPATIBLE
4#OCTETS
1.3.6.1.2.1.1.3.0
0:00:26.60
67#TIMETICKS

Possible values for the data type:

  • 2 - INT32
  • 3 - BITS
  • 4 - OCTETS
  • 6 - OID
  • 64 - IPADDR
  • 65 - CNTR32
  • 66 - UINT32
  • 67 - TIMETICKS
  • 68 - OPAQUE
  • 70 - CNTR64

If the result does not contain a number of entries which can be divided by 3, then it is a state message. In this case the first line indicates the status code:

1 - query started

-1 - error

The error code and the description are contained in the second line.

For example:

-1

-5#SNMP++: SNMP request timed out

Browse.RequestId string Request ID to identify browsing requests and the corresponding results. The ID is set together with the Browse.Result DPE. It is exactly the same as the string which is set on Browse.Start to initiate a browse request.
Redu.Access.IPAdress string The IP address of the secondary agent, or a computer name. If no IP address was set or it has been deleted (empty string) the entity is disabled automatically, the internal DPE-Status.Timeout is set to FALSE independent from the state it was before and no redu switch can be performed.
Redu.Access.Port uint The port number for communication with the agent. The standard SNMP port is 161.
Redu.Access.SecurityName string The SecurityName describes the user/program that requires access to the data of the redundant agent.
Redu.Access.SecurityLevel uint

Describes which security measures shall be used for the data exchange of the redundant agent.

  • noAuthNoPriv (1): no authentication and no encryption
  • authNoPriv (2): authentication but no encryption
  • authPriv (3): authentication and data encoding

Default value is (1).

Redu.Access.ContextName string ContextName of the redundant agent.
Redu.Access.ContextEngineID string ContextEngineID of the redundant agent.
Redu.Access.AuthProtocol uint

There are two protocols available for the authentication of the redundant SNMP users:

  • none (1) no authentication
  • HMAC_MD5 (2) MD5 authentication
  • HMAC_SHA (3) SHA authentication
  • HMAC_SHA2_224 (4) SHA2 authentication
  • HMAC_SHA2_256 (5) SHA2 authentication
  • HMAC_SHA2_384 (6) SHA2 authentication
  • HMAC_SHA2_512 (7) SHA2 authentication

Default value is (1).

Redu.Access.AuthPassword string The password which is used for authorization for the redundant agent.
Redu.Access.PrivProtocol uint

The sent data for the redundant target can also be encrypted in order to increase the security. A protocol must be selected for the encryption.

  • none (1): no encryption
  • DES (2): DES encryption (Data Encryption Standard)
  • IDEA (9): IDEA encryption (International Data Encryption Algorithm)
  • AES128 (4): Advanced Encryption Standard with 128 bit key.
  • AES192 (20): Advanced Encryption Standard with 192 bit key.
  • AES256 (21): Advanced Encryption Standard with 256 bit key.

Default is (1).

Redu.Access.PrivPasswd string The password used for the encryption of the redundant target.
Redu.Status.ConnState bool

Displays the connection state of the redundant SNMP agent.

On startup of the manager, the value for Redu.Status.ConnState is set to FALSE. After the first successfully received message the state will be set to TRUE.

Note: If agentAliveTimeout is set to 0 the connState will be false until the redu target receives a message (after a redu switch).
Redu.Status.Timeout bool This bit is set when no message was exchanged with the agent for a specific time (configured via the config entry agentConnectTimeout). If no IP address was set in the DPE Redu.Access.IPAddress or has been deleted (empty string), this bit is set to FALSE, independent of its current state.