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:
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
|
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. 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).
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:
The possible error codes are:
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:
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:
Example for a successful write process:
Example for an writing process error:
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:
|
Command | uint |
Two commands can be sent to the local agent via this 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:
|
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:
Possible values for the data type:
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:
The error code and the description are contained in the second line. For example:
|
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
_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.
|
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.
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:
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.
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).
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
|
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:
|
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:
Possible values for the data type:
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.
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:
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.
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. |