AddEvent Method
- Last UpdatedMay 26, 2026
- 4 minute read
The AddEvent() method adds a utilization event record to the Util_History table for an event of a specific duration and that can span one or more existing events. This method allows you to split an existing event or merge one or more events.
'Declaration
Public Shared Sub AddEvent( _
ByVal sessionId As Integer, _
ByVal entityId As Integer, _
ByVal newEventTimeUtc As Date, _
ByVal reasonCode As Integer, _
ByVal reasonPending As Nullable(Of Boolean), _
ByVal newEventEndTimeUtc As Nullable(Of Date), _
ByVal comments As String, _
ByVal rawReasonCode As String, _
ByVal spare1 As String, _
ByVal spare2 As String, _
ByVal spare3 As String, _
ByVal spare4 As String, _
ByVal category1 As String, _
ByVal category2 As String, _
ByVal category3 As String, _
ByVal category4 As String, _
ByRef recordsAffected As Nullable(Of Integer) _
)
'Usage
Dim sessionId As Integer
Dim entityId As Integer
Dim newEventTimeUtc As Date
Dim reasonCode As Integer
Dim reasonPending As Nullable(Of Boolean)
Dim newEventEndTimeUtc As Nullable(Of Date)
Dim comments As String
Dim rawReasonCode As String
Dim spare1 As String
Dim spare2 As String
Dim spare3 As String
Dim spare4 As String
Dim category1 As String
Dim category2 As String
Dim category3 As String
Dim category4 As String
Dim recordsAffected As Nullable(Of Integer)
UtilHistory.AddEvent(sessionId, entityId, newEventTimeUtc, reasonCode, reasonPending, newEventEndTimeUtc, comments, rawReasonCode, spare1, spare2, spare3, spare4, category1, category2, category3, category4, recordsAffected)
public static void AddEvent(
int sessionId,
int entityId,
DateTime newEventTimeUtc,
int reasonCode,
Nullable<bool> reasonPending,
Nullable<DateTime> newEventEndTimeUtc,
string comments,
string rawReasonCode,
string spare1,
string spare2,
string spare3,
string spare4,
string category1,
string category2,
string category3,
string category4,
out Nullable<int> recordsAffected
)
Parameters
- sessionId
- Required. Holds the session ID and thus the user who is making this method call.
- entityId
- Required. Holds the ID of the entity to which this utilization event is being added.
- newEventTimeUtc
- Required. Holds the start date/time for the new utilization event, in UTC.
- reasonCode
- Required. Holds the code that identifies the reason for the utilization event.
- reasonPending
- Optional. Holds a flag that, if true, specifies that the reason is pending and needs to be finalized.
- newEventEndTimeUtc
- Optional. Holds the end date/time for the new utilization event, in UTC. If no value is supplied, then this method behaves the same as the Add() method.
- comments
- Optional. Holds text to describe the event.
- rawReasonCode
- Optional. Holds the code that identifies the raw reason that used to determine the utilization reason.
- spare1
- Optional. Holds the contents of the user-defined spare1 field.
- spare2
- Optional. Holds the contents of the user-defined spare2 field.
- spare3
- Optional. Holds the contents of the user-defined spare3 field.
- spare4
- Optional. Holds the contents of the user-defined spare4 field.
- category1
- Optional. Holds a user defined field that describes category1.
- category2
- Optional. Holds a user defined field that describes category2.
- category3
- Optional. Holds a user defined field that describes category3.
- category4
- Optional. Holds a user defined field that describes category4.
- recordsAffected
Output. Holds the number of records affected.
The transactions that can be executed using the AddEvent() method are described below.
To add a new past event:
Pass the start time in UTC in the newEventTimeUtc parameter and the end time in the newEventEndTimeUtc parameter. If the newEventEndTimeUtc parameter is null, the end time of the new event will be the end time of the existing event that this new event is splitting.
For any existing past events that are split by the new past event, the end time (for the previous event) or start time (for the next event) are adjusted accordingly. Any events that are completely spanned by the new event are deleted. If the new past event has the same reason as the previous or next event, those two events are merged.
To add a new current event:
Pass the start time in UTC in the eventTimeUtc parameter and pass a time in the future (i.e. add a few seconds to the current UTC time) in the newEventEndTimeUtc parameter.
The new event becomes the current event. The end time of the existing past event that is split by the new event is adjusted accordingly. Any events that are completely spanned by the new event are deleted. If the new current event has the same reason as the previous event, those two events are merged.
Observe the following input parameter rules:
- Required non-DB* parameters: Must pass a value. Cannot be empty or null.
- Optional non-DB* parameters: Either enter a value or pass a null. If passing a null and a default value has been defined, the default value will be used for the parameter.