HOS Driver Violation Events by Group ID
Available in PIT v2.3
This ILE API wraps the HOS Driver Violation Events by Group ID web service. See its documentation for a further explanation of the input and output parameters, as well as the possible error conditions.
API Name: HSDRVVG
Parameter Interface:
| Parameter | Direction | Type | Length | Precision | Description |
|---|---|---|---|---|---|
| Group ID | Input | Character | 50 | n/a | ID of a driver group or "- All -" for all groups. |
| Rule Set | Input | Character | 50 | n/a | Rule set for which violations will be returned e.g. "USA" - see HOS web service for complete list of valid rule set values. |
| Start Timestamp | Input | Character | 19 | n/a | Start timestamp (YYYY-MM-DDTHH:MM:SS) of first violation in the local driver depot timezone. Specifying a blank value will default the start timestamp to the beginning of the current day. Note: the maximum start to end timestamp time span cannot exceed 30 days. |
| End Timestamp | Input | Character | 19 | n/a | End timestamp (YYYY-MM-DDTHH:MM:SS) of the last violation in the local driver depot timezone. Specifying a blank value will default the end timestamp to the end of the current day. Note: the maximum start to end timestamp time span cannot exceed 30 days. |
| Time Resolution | Input | Character | 1 | n/a | This parameter specifies whether certain values in the response are returned in seconds or minutes, where '1' = Values are returned in seconds, and '0' = values are returned in minutes. |
| Prior Edit? | Input | Character | 1 | n/a | Calculate violations prior to any edits, where: '1' = Yes and '0' = No |
| Drivers in Violation Array | Output | Character | n/a | n/a | An array of up to 400 drivers that have one or more violation events. See HSDRVVIOARR structure defined in HSDRVVGDS copy file and also outlined below. |
| Violation Events per Driver Array | Output | Character | n/a | n/a | An array of up to 100,000 driver violation events consisting of one to many violation event entries per driver. See HSDRVEVTARR structure defined in HSDRVVGDS copy file and also outlined below. |
| Response Group ID | Output | Character | 50 | n/a | Response ID of the driver group. |
| Response Rule Set | Output | Character | 50 | n/a | Response Rule set for which violations are being returned. |
| Response Drivers in Violation Array Count | Output | Decimal | 5 | 0 | The number of entries (drivers) in the Drivers in Violation output array |
| Error Category | Output | Decimal | 3 | 0 | Error Category, if any |
| Error Code | Output | Decimal | 5 | 0 | Error Code, if any. An OUTCODE = 999 indicates the response exceeded the maximum allowable size supported by this wrapper. The call should be re-issued with more restrictive filtration criteria. |
| Error Description | Output | Character | 150 varying | n/a | Error description, if any |
Note: Depending on the target company and the filtration criteria specified by the caller, this web service can return very large responses which can exceed the maximum sizes of some of the pre-defined receiving structures. In these cases the call must be re-issued with more restrictive filtration criteria e.g. shorter date range and/or specific group ID rather than all groups. An OUTCODE = 999 indicates this condition has occurred.
Two distinct yet related arrayed structures are defined to contain the set of drivers that have at least one violation event, and the set of one or more of each driver's violation event data. The two structures are linked by driver ID. The output driver structure (hsDrvVioArr) contains one entry per driver - see HSVIOEXPORT structure below. The driver violation event structure (hsDrvEvtArr) contains one to many violation event entries per driver - see HSEVTEXPORT structure below.
An error category of 0 means that the call completed successfully.
Drivers in Violation Structure (HSVIOEXPORT):
This data structure may be mapped over each of the 400 elements of the drivers in violation array output parameter. The array contains a fixed number of elements (400). All fields are varying character - a length of zero indicates a value was not returned by the web service. The output violation array count parameter indicates the number of entries (drivers) in the array. The See the HSDRVVGDS copy file for all related external structure definitions:
| Field | Type | Length | Precision | Description |
|---|---|---|---|---|
| DriverID | Character Varying | 50 | n/a | Driver ID |
| TimeZone | Character Varying | 50 | n/a | Timezone |
| RestBreakVio | Character Varying | 10 | n/a | Rest Break Violations |
| DrivingVio | Character Varying | 10 | n/a | Driving Violations |
| OnDutyVio | Character Varying | 10 | n/a | On Duty Violations |
| CumOnDutVio | Character Varying | 10 | n/a | Cumulative On Duty Violations |
| ShiftVio | Character Varying | 10 | n/a | Shift Violations |
| DayOffVio | Character Varying | 10 | n/a | Day Off Violations |
| PassRuleVio | Character Varying | 10 | n/a | Passenger Rule Violations |
| DailyOffVio | Character Varying | 10 | n/a | Daily Off Violations |
| DailyOff2HVio | Character Varying | 10 | n/a | Daily Off Two Hour Violations |
| DeferDrvVio | Character Varying | 10 | n/a | Deferral Driving Violations |
| TotODDefVio | Character Varying | 10 | n/a | Total Off Duty ForD eferral Violations |
| DefD1ODVio | Character Varying | 10 | n/a | Deferral Day 1 Off Duty Violations |
| DefD2ODVio | Character Varying | 10 | n/a | Deferral Day 2 Off Duty Violations |
| RestBrkExVio | Character Varying | 10 | n/a | Rest Break After Exemption Violations |
| EventCount | Decimal | 5 | 0 | Driver violation event count i.e number of driver violations for this driver in the driver violation event array |
Driver Violation Event Structure (HSEVTEXPORT):
This data structure may be mapped over each of the 100,000 elements of the driver violation event array output parameter. The array contains a fixed number of elements (100,000). All fields are varying character - a length of zero indicates a value was not returned by the web service. The EventCount field of the driver's entry in the array of HSVIOEXPORT structures (above) indicates the number of violation event entries for the given driver. See the HSDRVVGDS copy file for all related external structure definitions:
| Field | Type | Length | Precision | Description |
|---|---|---|---|---|
| Driver ID | Character Varying | 50 | n/a | Driver ID |
| Type | Character Varying | 50 | n/a | Violation event type |
| Time | Character Varying | 19 | n/a | Violation event timestamp (YYYY-MM-DDTHH:MM:SS) |
| Duration | Character Varying | 10 | n/a | Violation event duration |