Macro Field Types
Appendix C - Macro Field Types
The following tables show the format of the macro field types as they appear to the user and are sent to the external applications. Application engineers who are writing external applications that receive data from macro messages should use this table to determine the format of the data that will be received for each field type. These formats must be used when defining the data structures into which the return macro data is to be received.
Note that the _ symbol is used to indicate a blank character.
User-Fill Fields
The fields in this table are filled by the user. In the case of forward messages, these fields are filled by the QTRACS user at the user interface, or from an external application. In the case of return messages, these fields are filled by the driver.
Field Type | Format on Mobile & QTRACS Display | Format Sent to External Applications |
---|---|---|
00 Free Form |
May be 1 to 38 characters long. Displays characters as entered by user. Stores data padded with trailing blanks to fill out the field to its defined length. | Characters as entered by user padded with trailing blanks to fill out the field to its defined length. Valid Characters: .<(+&!$*);-/,%>?:#@'=" ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz 0123456789 |
ABC;123;"XYZ"_ _ _ _ _ _ _ (length=20) |
ABC;123;"XYZ"_ _ _ _ _ _ _ (length=20) |
|
01 Alphabetic |
May be 1 to 38 characters long. Consists of a run of alphabetic characters ('A'...'Z'). Leading & trailing blanks are permitted. Displays characters as entered by user. Stores data padded with trailing blanks to fill out the field to its defined length. | Characters as entered by user padded with trailing blanks to fill out the field to its defined length. Valid Characters: ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz |
CHAR SAMPLE_ _ _ _ _ _ _ _ _ (length=20) |
CHAR SAMPLE_ _ _ _ _ _ _ _ _ (length=20) |
|
02 Integer |
May be 1 to 10 characters long. Consists of digits ('0'...'9') with trailing blanks allowed. Embedded blanks are not permitted. Sign characters ('+' & '-') are not permitted. | Digits, right justified with leading zeros to fill the full length of the defined field. If field is left blank, then all zeros will be sent to the external application. Valid Characters: 0123456789 |
12345_ _ _ _ _ (length=10) |
0000012345 (length=10) |
|
03 Full Field Integer |
May be 1 to 10 characters long. Consists of digits ('0' ... '9'). User must fill entire field in order to validate. Leading & trailing blanks are prohibited. User may leave entire field blank. If field is filled, all the digits are stored; else all blanks are stored. | Digits with no leading, trailing, or embedded blanks. Total number of digits received equals length of field. If field is not filled, then all 0s (zeros) are returned. Valid Characters: 0123456789 |
1234567890 (length=10) _ _ _ _ _ _ _ _ _ _ (length=10) |
1234567890 (length=10) 0000000000 (length=10) |
|
04 Signed Integer |
May be 1 to 10 characters long. Consists of digits ('0'...'9') with an optional + or - as leading character. Trailing blanks are permitted. Embedded blanks are not permitted. | A zoned decimal value of the size of the defined field is sent to the external application. In the example below, the 234 value is negative as indicated in the last character of the value. In the case of forward macro messages, the maximum absolute negative value is reduced by one digit when sending negative values. The maximum value for a 5 character negative number is -9999, not -99999. |
+45_ _ _ _ _ _ _ (length=10) -234 _ _ _ _ _ (length=9) |
0000000045 (length=10) 000000234 (length=9) |
|
05 Alphanumeric |
May be from 1 to 38 characters long. Alphabetic and numeric characters are permitted. Leading, trailing and embedded blank characters are allowed. All other characters are prohibited. | Alphabetic characters and numbers as entered by the user padded with trailing blanks to complete the length of the field. Valid Characters: ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz 0123456789 |
ALPHA1BETA2_ _ _ _ (length=15) |
ALPHA1BETA2_ _ _ _ (length=15) |
|
06 Real Number |
May be from 1 to 12 characters long. Consists of an optional sign character ('+' or '-'), followed by a run of decimal digits ('0'...'9'). A single, optional, decimal point ('.') may appear before the run of digits, after the run of digits or within the run of digits. There can be trailing blanks. Embedded blanks are prohibited. If field is not filled, then all blanks are stored. | Characters as entered by user padded with trailing blanks to fill out the field to its defined length. Real numbers are returned in character format because the decimal place may appear in any position and RPG does not support a true floating point representation. There may be any number of digits after the decimal place. The application software must parse this value as required. Valid Characters: +-.0123456789 |
+123.78_ _ _ (length=10) 3.9876_ _ _ _ (length=10) 9045_ _ _ _ _ _ (length=10) |
+123.78_ _ _ (length=10) 3.9876_ _ _ _ (length=10) 9045_ _ _ _ _ _ (length=10) |
|
07 |
May be 5 to 12 characters long. Dollar sign ("$") is fixed as first character, followed by digits which represent dollars and which are filled with leading blanks, followed by fixed decimal point (".") followed by two digits representing number of cents. If field is not filled, then leading blanks with embedded $ and . are stored. |
An unsigned zoned decimal value is sent with two decimal places implied. Note that the length of the returned field equals the defined field length minus two (the dollar sign and decimal point). Monetary values are always fixed decimal with two places. If field is not filled a value of zero is returned. |
|
|
|
08 |
The standard date is displayed as 8 characters in the form: MM/DD/YY or DD/MM/YY depending on the value of the QTRACS system value QMMDAT (MCT macro field date format). The slashes are replaced with the date separators as selected by the QTRACS Router job (usually equivalent to the OS400 system value QDATSEP). If the field is not filled, six blanks with embedded date separators are stored and displayed. |
Six digits are returned to the external application. The format is dependent on the setting of the QMMDAT QTRACS system value. MMDDYY is returned if QMMDAT is *MDY. DDMMYY is returned if QMMDAT is *DMY. Blanks are returned if the field is not filled. |
|
|
|
09 |
The brief date is displayed as 5 characters in the form: MM/DD or DD/MM depending on the value of the QTRACS system value QMMDAT (MCT macro field date format). The slash is replaced with the date separator as selected by the QTRACS Router job (usually equivalent to the OS400 system value QDATSEP). Four blanks are displayed with an embedded date separator if the field is not filled. |
Four digits are returned to the external application. The format is dependent on the setting of the QMMDAT QTRACS system value. MMDD is returned if QMMDAT is *MDY. DDMM is returned if QMMDAT is *DMY. Blanks are returned if the field is not filled. |
|
|
|
10 |
Six characters are stored; first two digits represent hours, followed by a colon ( : ) then two digits representing minutes followed by A or P representing AM or PM. If time is not entered, then blanks with embedded colon are stored. (:_) |
Five characters are sent to the external application. The first two represent the hour, the second two represent the minute and the last character is either an A (for AM) or a P (for PM). If the field is not filled, then all blanks are returned. |
|
|
|
11 |
This is the 24-hour clock time contained in five characters in the HH:MM format where HH represents the hour and MM represents the minute. |
Four characters are returned to the external application in the form HHMM where HH indicates the hour (00...23) and MM indicates the minute (00...59). All blanks are returned if the field is not filled by the user. |
|
|
|
12 |
This is a 7 digit phone number stored in the 8-character nnn-nnnn. A blank value is stored as hyphen delimited blank characters. Leading, trailing or embedded blanks may not appear in the phone number. |
Seven digits are returned to the external application. Seven blanks are returned if the phone number is not entered. |
|
|
|
13 |
This is a ten-digit phone number stored in a twelve-character string of the form "aaa-ppp-nnnn" where aaa is the area code, ppp is the prefix and nnnn is the number. Leading, trailing or embedded blanks may not appear in the phone number. |
The ten digit unformatted phone number is sent to the external application. If the phone number is not entered, then all blanks are sent. |
|
|
|
14 |
This is the 5-character simple US zip code. This value is not validated to determine if the zip code exists. The user must enter 5 digits into this field. |
The five digits are returned to the external application. |
|
|
|
15 |
Ten characters are stored; first five are zip, followed by dash ( - ) then 4-digit extension. If zip code is not entered, then blanks with embedded dash are stored. |
Zero or five or nine digits are returned to the host depending on what was entered at the mobile. No other amount of digits is returned. |
|
|
|
16 |
One character, either Y or N, is stored. If nothing is entered, then a blank is stored. |
One character, either Y or N, is sent. If nothing is entered, then a blank is sent. |
|
|
|
17 |
Three characters are stored. If nothing is entered, then three blanks are stored. |
Three characters are sent. If nothing is entered, then three blanks are sent. |
Auto-Fill Fields
The mobile device automatically fills the following field types if it has capable firmware installed. These field types are only valid in return macro templates.
Auto-Fill Fields
The mobile device automatically fills the following field types if it has capable firmware installed. These field types are only valid in return macro templates.
Auto-fill field types behave differently depending upon the firmware in the mobile device. The external application programmer can determine the firmware version of the transmitting mobile unit by looking in the header of the returned message. The external application program should be written to handle all cases of returned data for these field types. Note that the length of the data returned may vary.
24 Time Stamp
This field is automatically filled if the MCT firmware version is 10.51.
If the MCT firmware version is < 10.51 then the field behaves like a 24 character free format input field. The field is not automatically filled by the MCT. The QTRACS Router processes the data as a 24-character free format field.
Note: Due to problems in MCTs with firmware versions 10.51 and <10.83, there is no guarantee that the date/time information is correct. Even though the field is automatically filled by the MCT, the driver may have the ability to type over the field. The router will convert the timestamp value that it receives from the NMC. This may be a distorted timestamp since the driver can type over the auto-fill timestamp field in these versions of firmware. The converted form will be the same as for versions above 10.83.
Format of Data Returned by NMC |
Format of MCT & QTRACS Display |
Format of Data Sent to External Apps |
---|---|---|
MCT Firmware Version > 10.51 |
|
|
Ten digits representing number of seconds since 01/01/1988 00:00:00 in Greenwich Mean Time are returned. |
The timestamp is displayed as 24-characters in the form: MM/DD/CCYY HH:MM:SS ZZZZ |
24-character string containing the timestamp as displayed by QTRACS. |
Example MCT > 10.51 |
||
0258564663 |
03/11/1996_ 10:31:03_ _ EST |
03/11/1996_ 10:31:03_ _ EST |
MCT Firmware Version < 10.51 |
||
24 free format characters containing whatever information is entered by the driver. |
Field behaves like a 24-character free format field. The field is not automatically filled by the MCT in this case. The router will store the free format data as it is returned, padded with blanks to obtain a length of 24 characters. |
24-character string is sent containing data as entered by the driver into a free form 24 characters field on the MCT. The field will be padded with blanks so that a full 24 characters are always returned to the external application. The QTRACS date/time API routines may be called to attempt to parse this information. |
Example MCT > 10.51 |
||
03/11/96_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
03/11/96_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
03/11/96_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
25 Odometer
This field is automatically filled if the MCT firmware version is 10.51.
If the MCT firmware version is \< 10.51 then the input field behaves like an 11 character free format input field. The field is not automatically filled by the MCT. The QTRACS router processes the data as an 11-character free format field.
Note: Due to problems in MCTs with firmware versions 10.51 and <10.83, there is no guarantee that the information is correct. These bytes are not guaranteed to be numeric because even though the field is automatically filled, the driver may be able to type over the data in some cases. The field may contain any character that can be entered on the MCT. The burden of data validation falls on the external application in this case.
Format of Data Returned by NMC |
Format of MCT & QTRACS Display |
Format of Data Sent to External Apps |
---|---|---|
MCT Firmware Version > 10.51 |
||
Eight characters are returned in the form: MMMMMM.T where the first six are digits representing whole distance, then a decimal point, then a final digit representing tenths of distance. The odometer reading is returned in units of miles regardless of country--specific firmware. |
The display is dependent on the setting of the QTRACS system value QMKILO. |
The units converted value is returned to the external application in an 11-character field as displayed. The format is MMMMMM.T UU where MMMMMM.T is the odometer reading and UU is the units. |
Example MCT > 10.51 |
||
014602.3 |
014602.3_ MI 0 |
014602.3_ MI |
MCT Firmware Version < 10.51 |
||
11 free format characters containing whatever information is entered by the driver. |
Field behaves like an 11-character free format field. The field is not automatically filled by the MCT in this case. The router will store the free format data as it is returned, padded with blanks to obtain a length of 11 characters. |
11-character string is sent containing data as entered by the driver into a free form 11 characters field on the MCT. The field will be padded with blanks so that a full 11 characters are always returned to the external application. |
Example MCT < 10.51 |
||
ANYTHING_ _ _ |
ANYTHING_ _ _ . |
ANYTHING_ _ _ . |
26 Total Fuel Used
27 Idle Fuel Used
28 PTO Fuel Used
29 Parked Idle Fuel Used
These fields are automatically filled if the MCT firmware version is 10.51.
If the MCT firmware version is < 10.51 then the input fields behave like 12 character free format input fields. The fields are not automatically filled by the MCT. The QTRACS router processes the data as a 12-character free format field.
Note: Due to problems in MCTs with firmware versions 10.51 and <10.83, there is no guarantee that the information is correct. These bytes are not guaranteed to be numeric because even though the field is automatically filled, the driver may be able to type over the data in some cases. The fields may contain any character that can be entered on the MCT. The burden of data validation falls on the external application in this case.
Format of Data Returned by NMC |
Format of MCT & QTRACS Display |
Format of Data Sent to External Apps |
---|---|---|
MCT Firmware Version > 10.51 |
||
Eight characters are returned in the form: VVVVVV.T where the first six are digits representing whole volume, then a decimal point, then a final digit representing tenths of volume. |
The display is dependent on the setting of the QTRACS system value QMVOLU. |
The value as displayed (including units) is returned to the external application. |
Example MCT > 10.51 |
||
000130.5 |
000130.5_ GAL |
000130.5_ GAL |
MCT Firmware Version < 10.51 |
||
12 free format characters containing whatever information is entered by the driver. |
Field behaves like a 12-character free format field. The field is not automatically filled by the MCT in this case. The router will store the free format data as it is returned, padded with blanks to obtain a length of 12 characters. |
12-character string is sent containing data as entered by the driver into a free form 12 characters field on the MCT. The field will be padded with blanks so that a full 12 characters are always returned to the external application. |
Example MCT < 10.51 |
||
ANYTHING_ _ _ _ |
ANYTHING_ _ _ _ . |
ANYTHING_ _ _ _ . |
30 Reefer Temperatures
This field is automatically filled if the MCT firmware version is 11.38.
If the MCT firmware version is < 11.38 then the input field behaves like a 14 character free format input field. The field is not automatically filled by the MCT. The QTRACS router processes the data as a 14-character free format field.
Format of Data Returned by NMC |
Format of MCT & QTRACS Display |
Format of Data Sent to External Apps |
---|---|---|
MCT Firmware Version > 11.38 |
||
14 characters (0-9, A-F) indicating the temperature values and trailer identifier in HEX representation. |
The MCT displays this data as a 14-character field containing the HEX representation of the data. |
The external application is sent a 20-character field. The first 12 characters contain the temperatures. Each temperature is returned as a 4-digit zoned decimal (signed) value. The trailer identifier is returned in the remaining 8 characters. |
MCT Firmware Version < 11.38 |
||
14 characters in free format containing whatever information was entered by the driver. |
Field is displayed exactly as above except that the contents of the fields are always set to 0. Any data entered by the driver is lost. |
20-character string is sent containing all zeros. |
32 Arrival Date & Time
34 Message Send Date & Time
Macro Field |
Description |
Arrival Date & Time (32) |
This field is auto-filled on the T/MCT when a macro containing this field is edited. |
Message Send Date & Time (34) |
This field will be auto-filled on the T/MCT when a macro containing this field is edited. |
The formats of the two new Date & Time fields (32 and 34) are identical. They are depicted in the following table.
Transmittable CI Format |
Displayable Format |
EAL Format |
---|---|---|
The format of the data across the CI is a 7-character field as depicted below: |
The format of the data on both the MCT and the QTRACS UI is a 22-character field as depicted below: |
The format of the data as delivered by QTRACS to an External Application is a 24-character field as depicted below:
|
33 Arrival GPS Position
35 Message Send GPS Position
Macro Field |
Description |
---|---|
Arrival GPS Position (33) |
This field is auto-filled on the mobile when a macro containing this field is edited. |
Message Send GPS Position (35) |
This field will be auto-filled on the mobile when a macro containing this field is edited. |
The formats of the two new GPS Position fields (33 and 35) are identical. They are depicted in the following table.
Transmittable CI Format |
Displayable Format |
EAL Format |
---|---|---|
The format of the data across the CI is a 10-character field as depicted below: |
The format of the data on both the MCT and the QTRACS UI is a 25-character field as depicted below: |
The format of the data as delivered by QTRACS to an External Application will be a 19-character field as depicted below: |
These macro fields (32, 33, 34, and 35) are found in the body of return macro messages only. These fields have nothing whatsoever to do with the existing Vehicle Position that is returned from the NMC in the 115 series of return messages. The existing Vehicle Position continues to be returned to the host in the DDDMMSS format.
36 Life-to-Date Distance
This field is automatically filled when using an MCT with a firmware version 16.61, or a TMCT with a firmware version 21.73.
If the MCT firmware version is < 16.61 or the TMCT firmware is < 21.73, then the input field behaves like a 12 character free format input field. The field is not automatically filled by the T/MCT. The QTRACS router processes the data as a 12-character free format field.
Format of Data Returned by NMC |
Format of MCT & QTRACS Display |
Format of Data Sent to External Apps |
---|---|---|
MCT Firmware Version > 16.61 and |
|
|
Nine characters are returned in the form: MMMMMMM.T where the first seven are digits representing whole distance, then a decimal point, then a final digit representing tenths of distance. The life-to-date distance reading is returned in units of miles regardless of country-specific firmware. |
The display is dependent on the setting of the QTRACS system value QMKILO. |
The units converted value is returned to the external application in a 12-character field as displayed. The format is MMMMMMM.T UU where MMMMMMM.T` is the life-to-date distance reading and UU is the units. |
Example |
||
0146021.3 |
0146021.3_ MI |
0146021.3_ MI |
MCT Firmware Version < 16.61 and |
||
12 free format characters containing whatever information is entered by the driver. |
Field behaves like a 12-character free format field. The field is not automatically filled by the T/MCT in this case. The router will store the free format data as it is returned, padded with blanks to obtain a length of 12 characters. |
12-character string is sent containing data as entered by the driver into a free form 12 characters field on the T/MCT. The field will be padded with blanks so that a full 12 characters are always returned to the external application. |
Example |
||
ANYTHING_ _ _ _ . |
ANYTHING_ _ _ _ . |
ANYTHING_ _ _ _ . |