HOS US Driver Log Report 2
Available in PIT v2.3
This ILE API wraps the HOS US Driver Log Report 2 web service. See its documentation for a further explanation of the input and output parameters, as well as the possible error conditions.
API Name: HSDRVLR
Parameter Interface:
|
Parameter |
Direction |
Type |
Length |
Precision |
Description |
|---|---|---|---|---|---|
|
Driver ID |
Input |
Character |
50 |
n/a |
Driver ID whose log reports will be returned for the given date range. |
|
Start Timestamp |
Input |
Character |
19 |
n/a |
Optional start timestamp in the format (YYYY-MM-DDTHH:MM:SS). Note that the time component (HH:MM:SS) will be ignored and defaults to the beginning of the start date. A blank timestamp value defaults to the beginning of the current day. |
|
End Timestamp |
Input |
Character |
19 |
n/a |
Optional end timestamp in the format (YYYY-MM-DDTHH:MM:SS). Note that the time component (HH:MM:SS) will be ignored and defaults to the beginning of the end date. A blank timestamp value defaults to the end of the current day. |
|
Customer Name |
Input |
Character |
50 |
n/a |
The name of the customer making the web service call. |
|
Driver Region |
Input |
Character |
50 |
n/a |
Driver region rule set to apply, e.g. USA, CA, FL, TX or AK. |
|
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. |
|
Output Start Timestamp |
Output |
Character |
19 |
n/a |
Requested start timestamp (echoed in response) |
|
Output End Timestamp |
Output |
Character |
19 |
n/a |
Requested end timestamp (echoed in response) |
|
Output Request Timestamp |
Output |
Character |
19 |
n/a |
Timestamp of this web service request |
|
Output Driver Full Name |
Output |
Character |
100 |
n/a |
Driver first and last name |
|
Output Company Name |
Output |
Character |
100 |
n/a |
Company name |
|
Output Company Address |
Output |
Character |
100 |
n/a |
Company address |
|
Output Distance Units |
Output |
Character |
20 |
n/a |
Mile or KiloMeters |
|
Output Region |
Output |
Character |
50 |
n/a |
Requested driver region (echoed in response) |
|
Output Driver Duty Cycle |
Output |
Character |
20 |
n/a |
Driver duty cycle enum e.g. None, SevenDay or EightDay |
|
Output Driver Daily Duty Status Entry Array |
Output |
Arrayed Data Structure |
n/a |
n/a |
Array of up to 200 driver daily duty entries (see hsDrvDlyArr extern DS defined in HSDRVLRDS copy file) |
|
Output Driver Daily Duty Status Entry Count |
Output |
Decimal |
5 |
0 |
Count of driver daily duty array entries |
|
Output Driver Duty Status Changes Entry Array |
Output |
Arrayed Data Structure |
DS |
n/a |
Array of up to 500 driver duty status entries for ALL daily duty status entries (see hsDrvDtyArr extern DS defined in HSDRVLRDS copy file) |
|
Output Driver Duty Status Changes Entry Array Count |
Output |
Decimal |
5 |
0 |
Count of driver duty status array entries for ALL daily duty status entries |
|
Output Driver Affiliated Carriers Array |
Output |
Arrayed Data Structure |
DS |
n/a |
Array of up to 500 driver affiliated carriers for ALL daily duty status entries (see hsDrvCarArr extern DS defined in HSDRVLRDS copy file) |
|
Output Driver Affiliated Carriers Array Count |
Output |
Decimal |
5 |
0 |
Count of driver affiliated carrier array entries for ALL daily duty status entries |
|
Output Driver Rule Sets Array |
Output |
Arrayed Data Structure |
DS |
n/a |
Array of up to 500 rule sets for ALL daily duty status entries (see hsDrvRulArr extern DS defined in HSDRVLRDS copy file) |
|
Output Driver Rule Sets Array Count |
Output |
Decimal |
5 |
0 |
Count of rule set array entries for ALL daily duty status entries |
|
Output |
Decimal |
3 |
0 |
Error Category, if any |
|
|
Output |
Decimal |
5 |
0 |
Error Code, if any. A value of 999 = Web service response exceeded maximum allowable size - the call should be reissued with a shorter start to end timestamp interval |
|
|
Output |
Character |
150 varying |
n/a |
Error description, if any |
An error category of 0 means that the driver's details were returned successfully.
Description of Output Arrays and Their Relationships
Four distinct yet related arrayed structures are defined to contain the set of driver log reports and their related data. The structures are linked by a duty log timestamp field i.e. entries across the 4 distinct arrayed structures that share the same duty log timestamp field value are related and constitute all the driver log information returned for the driver on that particular day.
The 4 arrayed structures are as follows:
(1) Daily duty logs 200 <---- One duty log per DAY for the range requested
(2) Duty status changes 500 <--- Zero or more duty status changes per duty log day
(3) Carrier affiliations 500 <--- Zero or more carriers per duty log day
(4) Rule set changes 500 <--- Zero or more rule set changes per duty log day
The Daily Duty Log array (1) contains one entry per day and can be considered the primary array, with its Duty Log Timestamp field being its unique primary key. The key is referenced by the other three arrays to form a one-to-many relationship between the primary array (1) and the other three arrays: (2), (3) & (4).
For the sake of convenience, the Daily Duty Log array (1) structure has 3 fields indicating the counts of the number of related entries in the other three arrays for the given day. The related entries in these three arrays (if any) will all share the Duty Log Timestamp value of a single entry in the Daily Duty Log array (1).
Drivers Daily Duty Logs Structure (hsDlyExport):
This data structure may be mapped over each of the elements of the drivers daily duty logs array output parameter. The array contains a fixed number of elements (200). The Output Driver Daily Duty Status Entry Count output parameter indicates the number of actual (non-empty) array elements returned. The structure's dayDate field acts as a type of key allowing entries in each of the 4 output arrays to be linked. A blank dayDate field value indicates the array element is empty. See the HSDRVLRDS copy file for all related external definitions.
|
Field |
Type |
Length |
Precision |
Comments |
|---|---|---|---|---|
|
DayDate |
Character |
19 |
n/a |
Primary "key" ref by other arrays |
|
Documents |
Character |
100 varying |
n/a |
|
|
Trailers |
Character |
100 varying |
n/a |
|
|
Tractors |
Character |
100 varying |
n/a |
|
|
CoDrivers |
Character |
100 varying |
n/a |
|
|
CoEffectime |
Character |
19 |
n/a |
Company affiliation |
|
CoName |
Character |
100 varying |
n/a |
" |
|
CoFullName |
Character |
100 varying |
n/a |
" |
|
CoStreet1 |
Character |
100 varying |
n/a |
" |
|
CoStreet2 |
Character |
100 varying |
n/a |
" |
|
CoCity |
Character |
100 varying |
n/a |
" |
|
CoStateProv |
Character |
50 varying |
n/a |
" |
|
CoPostal |
Character |
50 varying |
n/a |
" |
|
CoMisc |
Character |
100 varying |
n/a |
" |
|
DpEffectime |
Character |
19 |
n/a |
Depot affiliation |
|
DpName |
Character |
100 varying |
n/a |
" |
|
DpFullName |
Character |
100 varying |
n/a |
" |
|
DpStreet1 |
Character |
100 varying |
n/a |
" |
|
DpStreet2 |
Character |
100 varying |
n/a |
" |
|
DpCity |
Character |
100 varying |
n/a |
" |
|
DpStateProv |
Character |
50 varying |
n/a |
" |
|
DpPostal |
Character |
50 varying |
n/a |
" |
|
DpMisc |
Character |
100 varying |
n/a |
" |
|
DpStartOfDay |
Character |
50 varying |
n/a |
" (int) |
|
DpTimeZone |
Character |
50 varying |
n/a |
" (int) |
|
DpTimeZoneName |
Character |
50 varying |
n/a |
" |
|
DpTimeZoneAbrv |
Character |
50 varying |
n/a |
" |
|
EditCount |
Character |
50 varying |
n/a |
(int) |
|
SensorFailCnt |
Character |
50 varying |
n/a |
(int) |
|
OffDuty |
Character |
50 varying |
n/a |
(int) |
|
OffDutyOilWell |
Character |
50 varying |
n/a |
(int) |
|
SleeperBerth |
Character |
50 varying |
n/a |
(int) |
|
SleeperOilWell |
Character |
50 varying |
n/a |
(int) |
|
Driving |
Character |
50 varying |
n/a |
(int) |
|
OnDutyNotDriv |
Character |
50 varying |
n/a |
(int) |
|
OnDutyToday |
Character |
50 varying |
n/a |
(int) |
|
OnDutyThisWeek |
Character |
50 varying |
n/a |
(int) |
|
DistanceDriven |
Character |
50 varying |
n/a |
(int) |
|
StartOfDay |
Character |
50 varying |
n/a |
|
|
DutyEntryCount |
Decimal |
5 |
0 |
Related duty status array entries |
|
CarrEntryCount |
Decimal |
5 |
0 |
Related carrier array entries |
|
RuleEntryCount |
Decimal |
5 |
0 |
Related rule set array entries |
Drivers Duty Status Changes Structure (hsDtyExport)
This data structure may be mapped over each of the elements of the drivers duty status changes array output parameter. The array contains a fixed number of elements (500). The Output Driver Duty Status Changes Entry Array Count output parameter indicates the number of actual (non-empty) array elements returned. The structure's dayDate field acts as a type of key allowing entries in each of the 4 output arrays to be linked. A blank dayDate field value indicates the array element is empty. See the HSDRVLRDS copy file for all related external definitions.
| Field | Type | Length | Precision | Comments |
|---|---|---|---|---|
| DayDate | Character | 19 | n/a | Daily duty log primary "key" ref |
| StartTime | Character | 19 | n/a | |
| Duration | Character | 50 varying | n/a | (int) |
| CurrActivity | Character | 100 varying | n/a | |
| Location | Character | 100 varying | n/a | |
| EditFlag | Character | 100 varying | n/a | |
| Confirmed | Character | 1 varying | n/a | |
| SensorFailure | Character | 1 varying | n/a | |
| DistanceEdit | Character | 1 varying | n/a | |
| WaitingOilWell | Character | 1 varying | n/a | |
| HazmatODRest | Character | 1 varying | n/a | |
| Comment1 | Character | 100 varying | n/a | |
| Comment2 | Character | 100 varying | n/a | |
| UsCycleReset | Character | 19 | n/a | |
| EditReason | Character | 100 varying | n/a |
Drivers Affiliated Carriers Structure (hsCarExport)
This data structure may be mapped over each of the elements of the drivers affiliated carriers array output parameter. The array contains a fixed number of elements (500). The Output Driver Affiliated Carriers Array Count output parameter indicates the number of actual (non-empty) array elements returned. The structure's dayDate field acts as a type of key allowing entries in each of the 4 output arrays to be linked. A blank dayDate field value indicates the array element is empty. See the HSDRVLRDS copy file for all related external definitions.
| Field | Type | Length | Precision | Comments |
|---|---|---|---|---|
| DayDate | Character | 19 | n/a | Daily duty log primary "key" ref |
| CoEffectime | Character | 19 | n/a | |
| CoName | Character | 100 varying | n/a | |
| CoFullName | Character | 100 varying | n/a | |
| CoStreet1 | Character | 100 varying | n/a | |
| CoStreet2 | Character | 100 varying | n/a | |
| CoCity | Character | 100 varying | n/a | |
| CoStateProv | Character | 50 varying | n/a | |
| CoPostal | Character | 50 varying | n/a | |
| CoMisc | Character | 100 varying | n/a |
Drivers Rule Set Changes Structure (hsRulExport)
This data structure may be mapped over each of the elements of the drivers rule set changes array output parameter. The array contains a fixed number of elements (500). The Output Driver Rule Set Changes Array Count output parameter indicates the number of actual (non-empty) array elements returned. The structure's dayDate field acts as a type of key allowing entries in each of the 4 output arrays to be linked. A blank dayDate field value indicates the array element is empty. See the HSDRVLRDS copy file for all related external definitions.
| Field | Type | Length | Precision | Comments |
|---|---|---|---|---|
| DayDate | Character | 19 | n/a | Daily duty log primary "key" ref |
| RuleSet | Character | 100 varying | n/a | |
| EffectiveTime | Character | 19 | n/a |