Attached to this article is an example of cicode which might be used to manage SNMP traps in a CitectSCADA project.  Also attached is an example project which demonstrates one way to implement the cicode file.  The project was created in version 5.5 Citect SCADA and can be upgraded to newer version if required.

This code exposes four functions for creating and sending traps and one for monitoring traps and recoding traps in a dbf device. 

STM_Trap_Monitor()
This function sets in motion an endless loop which checks the trap queue for new traps once per second.  For each varibind in the trap an entry is created in the DBF device with a complete set of trap data.  If a new trap is found a semaphore is raised to block the trap new creation functions from modifying the values in the trap tags.

-No Arguments
-No Return, never returns

In order to use this code a DBF device must be configured in the project called “TrapRecord” and have the following format:

{Num,10},{Enterprise,50},{Address,16},{GenTyp,6},{SpecTyp,6},{TimeStamp,14},{OID,50},{Data,122},{Forward,16},{Subfeid,10}

STM_startup()
Also included in the attached file is which can be called by a projects’ start up routine to run STM_Trap_Monitor() in a new thread.

-No arguments
-No Returns

STM_Build_Trap( STRING Enterprise_T0,
    STRING Address_T1,
    STRING GenericType_T2,
    STRING SpecificType_T3,
    STRING Forwarding_TF)

This function is the first of three steps in creating a trap to send.  All the necessary trap data is required when calling this function.  Note that this function loads the provided data into a set of module variables and not the trap tags so that the Trap monitor code is still able to process incoming traps. 

NB: this function will not check the validity of the arguments entered.  If the data is not valid a hardware alarm will occur when calling STM_Send_Trap().

-Enterprise_T0:
The enterprise number of the application or device sending the trap.

-Address_T1:
The IP address as a string of the application or device sending the trap.

-GenericType_T2:
The generic type of the trap.  Unless the trap is a type specified in RFC 1215 this should be set to “6”.

-SpecificType_T3:
The specific type is a user defined positive integer which can be used by the trap recipient to differentiate between traps.

-Forwarding_TF:
The target IP address for the trap.  This code does not allow for multiple recipients.  The trap community name must be included with the target IP address ie.
“192.168.1.1 trap”

-Returns:
A string “0” for successful for an empty string.  The last error will be stored in msLast_Error. 

STM_Add_Tag(STRING TagName)
The add tag function is included as a short cut to adding Citect SNMP tags to a trap before sending.  This function will locate the tag in the snmpvars.dbf file to retrive the tags OID.  Also when the tags value will be read and added the varibind list of the trap data currently being generated.

Each time this function is called an entry will be added to the trap in sequential order.

-TagName:
The name of an SNMP tag already defined in Citect.

-Returns:
A string “0” for successful for an empty string.  The last error will be stored in msLast_Error. 

STM_Add_OID(STRING OID, STRING Value)
Add OID allows a varibind to be added to the trap before sending.  There is no need for the data to exist in a variable tag in the Citect project, any strings can be added to the arguments of the function. 

Each time this function is called an entry will be added to the trap in sequential order.

OID:
The SNMP Object id of the data to send.  Note that the OID should start with ‘.’, otherwise the driver will append a standard prefix to the OID.

Value:
The value to be added to the varibind.  This function will only add data to the varibind as a string.  The datatype extension “STRING” will be added to the varibind by the cicode.

Returns:
A string “0” for successful for an empty string.  The last error will be stored in msLast_Error. 

STM_Send_Trap()
This function will send the trap that has been created with the above two functions
No Arguments

Returns:
A string “0” for successful for an empty string.  The last error will be stored in msLast_Error. 



Addition Note:
The STM_Trap_Monitor() function includes several SleepMS() functions to allow the reading and writing to the TNVB tag to settle before continuing the code.  Those SleepMS() function can be removed if the IO device Cache is disabled by setting the cache time to '0' in the option on the IO devices form in Citect Project Editor.