MES Stateless API

GetUtilByTimePeriod Method

Save PDF

GetUtilByTimePeriod Method

Save PDF

Last UpdatedNov 06, 2025
7 minute read

The GetUtilByTimePeriod() method retrieves one or more utilization history records from the Util_History table, as specified by the time period filter parameters.

Syntax

'Declaration
 
Public Shared Function GetUtilByTimePeriod( _
   ByVal entId As Integer, _
   ByVal filterTimeUnit As Nullable(Of Integer), _
   ByVal filterStartOffset As Nullable(Of Integer), _
   ByVal filterEndOffset As Nullable(Of Integer), _
   ByVal shiftId As Nullable(Of Integer), _
   ByVal minDuration As Nullable(Of Integer), _
   ByVal maxDuration As Nullable(Of Integer), _
   ByVal reasonCode As Nullable(Of Integer), _
   ByVal stateCode As Nullable(Of Integer), _
   ByVal reasonPending As Nullable(Of Boolean), _
   ByVal runtime As Nullable(Of Boolean), _
   ByVal downtime As Nullable(Of Boolean), _
   ByVal comments As String, _
   ByVal rawReasonCode As String, _
   ByVal lastNEvents As Nullable(Of Integer) _
) As DataSet

'Usage
 
Dim entId As Integer
Dim filterTimeUnit As Nullable(Of Integer)
Dim filterStartOffset As Nullable(Of Integer)
Dim filterEndOffset As Nullable(Of Integer)
Dim shiftId As Nullable(Of Integer)
Dim minDuration As Nullable(Of Integer)
Dim maxDuration As Nullable(Of Integer)
Dim reasonCode As Nullable(Of Integer)
Dim stateCode As Nullable(Of Integer)
Dim reasonPending As Nullable(Of Boolean)
Dim runtime As Nullable(Of Boolean)
Dim downtime As Nullable(Of Boolean)
Dim comments As String
Dim rawReasonCode As String
Dim lastNEvents As Nullable(Of Integer)
Dim value As DataSet
 
value = UtilLog.GetUtilByTimePeriod(entId, filterTimeUnit, filterStartOffset, filterEndOffset, shiftId, minDuration, maxDuration, reasonCode, stateCode, reasonPending, runtime, downtime, comments, rawReasonCode, lastNEvents)

public static DataSet GetUtilByTimePeriod( 
   int entId,
   Nullable<int> filterTimeUnit,
   Nullable<int> filterStartOffset,
   Nullable<int> filterEndOffset,
   Nullable<int> shiftId,
   Nullable<int> minDuration,
   Nullable<int> maxDuration,
   Nullable<int> reasonCode,
   Nullable<int> stateCode,
   Nullable<bool> reasonPending,
   Nullable<bool> runtime,
   Nullable<bool> downtime,
   string comments,
   string rawReasonCode,
   Nullable<int> lastNEvents
)

Parameters

entId

Required. Specifies the entity whose utilization history records are being retrieved.

filterTimeUnit

Optional filter parameter. An enumeration that specifies the unit for the time filter. For more information, see the FilterTimeUnit enumeration help topic for the FactMES.API.Util namespace.

filterStartOffset

Required when a filterTimeUnit is specified. The filterStartOffset and the filterEndOffset together define an interval that filters the data to be returned (i.e., only data that falls within the interval will be returned). These offsets both go backwards from the current time: a value of 1 indicates the current time, a value of 2 indicates one time unit ago, etc.

The filterStartOffset must be greater (i.e., further back in time) than the filterEndOffset. If the filterEndOffset is zero, it is ignored (i.e., the end of the interval will be the current time). For example, if filterTimeUnit is set to 2 (Day), filterStartOffset is set to 2, and filterEndOffset is set to 1, then only data with an event time that occurred yesterday will be returned. If filterTimeUnit is set to 1 (Shift), filterStartOffset is set to 1, and filterEndOffset is set to 0, then only events that occurred during the current shift will be returned.

filterEndOffset

Required when filterTimeUnit is specified. Specifies the end point of the time interval for which the events are to be filtered. See filterStartOffset for more information.

shiftId

Optional filter parameter. Specifies a shift by which to filter the events.

minDuration

Optional filter parameter. Specifies the lower bound for the duration (in seconds) by which to filter the events.

maxDuration

Optional filter parameter. Specifies the upper bound for the duration (in seconds) by which to filter the events.

reasonCode

Optional filter parameter. Specifies an entity reason code by which to filter the events.

stateCode

Optional filter parameter. Specifies an entity state by which to filter the events.

reasonPending

Optional filter parameter. Holds a flag that specifies the setting of the reason pending flag, which determines whether the user is prompted for an override reason, by which to filter the events.

runtime

Optional filter parameter. Holds a flag that indicates whether or not the event counts as runtime.

downtime

Optional filter parameter. Holds a flag that indicates whether or not the event counts as downtime.

comments

Optional filter parameter. Specifies text describing the event.

rawReasonCode

Optional filter parameter. Specifies an underlying raw reason code by which to filter the events.

lastNEvents

Optional. Specifies that the most recent N events should be returned.

Return Value

Returns a DataSet that contains the event records from the Util_History table that match the specified filters. If no matching records are found, an empty DataSet is returned.

The columns of the returned DataSet are described below.

Column Name	Description
log_ID	An integer that uniquely identifies a record in the Util_History table.
event_time_utc	A datetime that indicates the start of the event, in UTC. This value will be adjusted to the start time of the shift if the utilization event starts before the beginning of the time period being used to filter the data.
event_time_local	A datetime that indicates the start of the event, in the local time of the entity. This value will be adjusted to the start time of the shift if the utilization event starts before the beginning of the time period being used to filter the data.
event_time	A datetime that indicates the start of the event, in the local time of the client application that is making the call. This value will be adjusted to the start time of the shift if the utilization event starts before the beginning of the time period being used to filter the data.
ent_id	An integer that identifies the entity on which the event occurred.
ent_name	The name of the entity on which the event occurred.
shift_id	An integer that identifies the shift during which the event occurred. A value of 0 will be returned if there is no shift associated with this record.
shift_desc	The description of the shift during which the event occurred.
shift_start_utc	A datetime that indicates when the shift started, in UTC. Will have a value of 1/1/1900 if there is no shift associated with the record.
shift_start_local	A datetime that indicates when the shift started, in the local time of the entity. Will have a value of 1/1/1900 if there is no shift associated with the record.
shift_start	A datetime that indicates when the shift started, in the local time of the client application that is making the call. Will have a value of 1/1/1900 if there is no shift associated with the record.
state_cd	An integer that is the code for the entity state.
state_desc	The description of the entity state.
color	An integer that identifies the background color corresponding to the entity state.
reas_cd	An integer that is the code for the entity reason (e.g., the reason for downtime) associated with the event.
reas_desc	The description of the entity reason (e.g., the reason for downtime) associated with the event.
severe	A Boolean flag that indicates whether the utilization event exceeds the maximum duration for the event’s reason. If the utilization event is the current one for the entity, this flag is true only if there is a maximum duration defined for the reason and the current date/time is greater than the starting time of the utilization event plus the maximum duration. However, if the utilization event is not the current one, this flag is true only if there is a maximum duration defined for the reason and the duration of the event is greater than the maximum duration of the reason.
reas_grp_id	An integer that is the ID of the group to which the reason belongs.
reas_grp_desc	The description of the reason group to which the reason belongs.
standard_time	A float that identifies the standard time in minutes for an override reason.
reas_pending	A flag that indicates whether the user should be prompted for an override reason.
runtime	A flag that indicates that the event counts as runtime.
downtime	A flag that indicates that the event counts as downtime.
setuptime	A flag that indicates that the event counts as setup time.
teardowntime	A flag that indicates that the event counts as teardown time.
fixedtime	A flag that indicates that the event counts as fixed time.
vartime	A flag that indicates that the event counts as variable time.
failure	A flag that indicates that the event counts as failure time.
duration_in_seconds	The duration of the event in seconds. This value will be adjusted to use the start time of the shift if the utilization event starts before the beginning of the time period being used to filter the data.
duration	The duration of the event formatted as HH:MM:SS. This value will be adjusted to use the start time of the shift if the utilization event starts before the beginning of the time period being used to filter the data.
act_event_time_utc	A datetime that indicates the start of the event, in UTC. This value is the actual start time of the shift if the utilization event starts before the beginning of the time period being used to filter the data.
act_event_time_local	A datetime that indicates the start of the event, in the local time of the entity. This value is the actual start time of the shift if the utilization event starts before the beginning of the time period being used to filter the data.
act_event_time	A datetime that indicates the start of the event, in the local time of the client application that is making the call. This value is the actual start time of the shift if the utilization event starts before the beginning of the time period being used to filter the data.
act_duration_in_seconds	The duration of the event in seconds. This value is the actual duration of the shift if the utilization event starts before the beginning of the time period being used to filter the data.
act_duration	The duration of the event formatted as HH:MM:SS. This value is the acutal duration of the shift if the utilization event starts before the beginning of the time period being used to filter the data.
comments	Text that describes the event.
raw_reas_cd	A string that specifies the underlying raw reason code.
wo_id	A string that specifies the work order for which the event occurred.
oper_id	A string that specifies the operation for which the event occurred.
seq_no	An integer that specifies the sequence number for which the event occurred.
category1	A string that is the contents of the category1 field.
category2	A string that is the contents of the category2 field.
category3	A string that is the contents of the category3 field.
category4	A string that is the contents of the category4 field.
last_edit_comment	A string that contains comments about why the record was changed.
last_edit_by	A string that is the ID of the user who last edited this record.
last_edit_at	A datetime that specifies when the record was added or last modified.

MES Stateless API