X12 Time Reader

Key point

X12 dates, times and time codes

No X12 date or time carries an offset. The time code beside them is the only thing that says where the clock was, and a named code such as ET is a zone name, not an offset.

X12 sends one point in time as three elements: a date (373), a time (337) and a time code (623). Type them, and the tool takes them apart and says what they state. A second section reads a DTP value. The one thing to know is that the date and the time carry no offset, so the time code is the only thing that says where the clock was: parseX12DateAndTime reads the date and the time, classifyX12TimeCode classifies the code, and everything on the page is what those calls returned.

1. The date, the time and the time code

Date (373) optionalTime (337) optionalTime code (623) optional

ET names a zone and says neither standard nor daylight. X12 states no offset for it, so the instant needs an IANA zone. This example reads it in two places on Eastern time: America/New_York, which is on daylight time on this June date, and America/Atikokan in Ontario, which keeps standard time all year. They are an hour apart, so the name alone does not fix the offset. Both zones are the example's picks, not something X12 or the code says: pick the zone your message means.

ET names a zone and says neither standard nor daylight. X12 states no offset for it, so the instant needs an IANA zone. This example reads it in two places on Eastern time: America/New_York, which is on daylight time on this June date, and America/Atikokan in Ontario, which keeps standard time all year. They are an hour apart, so the name alone does not fix the offset. Both zones are the example's picks, not something X12 or the code says: pick the zone your message means.

ED names the same zone as ET and adds that it is daylight time. It still states no offset. This example reads it in America/New_York, which is on daylight time on this June date, so the flag and the zone agree. The zone is the example's pick: change it to the zone your message means.

ES names the same zone as ET and adds that it is standard time. It states no offset. This example uses a January date and reads it in America/New_York, which is on standard time then, so the flag and the zone agree. The zone is the example's pick: change it to the zone your message means.

UT states an offset of +00:00, so the date and the time name one instant with no zone to pick.

Codes 13 to 24 run downward from UTC-12 to UTC-1. Code 13 is UTC-12, not UTC-1, so the instant falls on the next UTC day.

Code 24 is UTC-1, the last of the downward run that starts at 13. The date and the time are the same as for code 13.

Element 337 can carry tenths or hundredths of a second. The library reads them, and formatX12TimeElement writes them back in the form they were sent (HHMMSSDD here). The four zones are this example's picks, so the strip shows the instants: change them to the places your message means.

With no time code the time is local to the event, and the place is elsewhere in the message. The library returns the local date-time and never reads it as UTC. The four zones are this example's picks, not something the message says: change them to the places your message means.

LT says the time is local to the event, whose place is elsewhere in the message. The zone is yours to supply. The four here are this example's picks, not something LT says: change them to the places your message means.

A segment may carry a date and no time. A date alone names no instant in any zone.

A segment may carry a time and no date. A time alone names no instant: it is on no day.

Element 373 is CCYYMMDD. Element 337 is HHMM, HHMMSS, HHMMSSD or HHMMSSDD. Any of the three may be empty, and an empty element is left out of the call.

2. What the calls return

3732024CCYY06MM15DDdate33714HH30MM00SS12DDtime623ABCDEFGH623offset

classifyX12TimeCode("ABCDEFGH") does not know it: not a 623 time code.The last two digits of the time are hundredths of a second.

No result

The time is not one of the four element 337 forms: HHMM, HHMMSS, HHMMSSD or HHMMSSDD, with an hour from 00 to 23 and a minute and second from 00 to 59.

parseX12DateAndTime("20240615", "14300012")
classifyX12TimeCode("ABCDEFGH")
x12TimeCodeOffset("ABCDEFGH")

Offset: stated (-12:00)

Offset: not stated

The time code gives the offset from UTC, so the date and the time name one instant.

The time code gives the offset from UTC. A time alone names no instant: it is on no day.

The time code says local to the event. The place is elsewhere in the message. You supply its zone. A time alone names no instant: it is on no day.

The code names the zone and says neither standard nor daylight, so the date decides. X12 states no offset for a named zone: Eastern. A time alone names no instant: it is on no day.

A date alone names no instant in any zone.

There is no date and no time code, so nothing says which day or where the clock was. A time alone names no instant: it is on no day.

A blank time code means local to the event. The place is elsewhere in the message. You supply its zone.

Kind

no result

Value

no result

Time code

no result

Offset

no result

Zone name

no result

Daylight

no result

Instant

no result

 

"2024-06-15T14:30:00.12" { kind: "offset", timeCode: "ABCDEFGH" } "-05:00"

3. The instant, and where the same digits land

No value.

The time code states the offset, so there is nothing to choose.

A date or a time alone names no instant in any zone.

The elements state no offset. Each zone above is a pick, from the example or from you, and not something the elements say: the same digits, read there. Every row uses resolveLocal with disambiguation: "reject", so a time the clock shows twice or never is not resolved.

Widest gap: 26 h, between Zonename/Wwwwwwwwwwwwwwwwwwwww and Zonename/Wwwwwwwwwwwwwwwwwwwww

Choose two zones to see how far apart the answers are.

resolveLocal("2024-06-15T14:30:00.12", "Zonename/Wwwwwwwwwwwwwwwwwwwww", { disambiguation: "reject" })

ZoneInstantOffsetWith offset

1No zoneUTCAmerica/New_YorkAmerica/ChicagoAmerica/DenverAmerica/Los_AngelesEurope/LondonEurope/ParisEurope/BerlinEurope/MoscowAsia/TokyoAsia/ShanghaiAsia/KolkataAsia/DubaiAustralia/SydneyAustralia/AdelaidePacific/AucklandPacific/HonoluluAfrica/CairoAfrica/LagosAfrica/JohannesburgEurope/AmsterdamAsia/SingaporeAmerica/Atikokan

2No zoneUTCAmerica/New_YorkAmerica/ChicagoAmerica/DenverAmerica/Los_AngelesEurope/LondonEurope/ParisEurope/BerlinEurope/MoscowAsia/TokyoAsia/ShanghaiAsia/KolkataAsia/DubaiAustralia/SydneyAustralia/AdelaidePacific/AucklandPacific/HonoluluAfrica/CairoAfrica/LagosAfrica/JohannesburgEurope/AmsterdamAsia/SingaporeAmerica/Atikokan

3No zoneUTCAmerica/New_YorkAmerica/ChicagoAmerica/DenverAmerica/Los_AngelesEurope/LondonEurope/ParisEurope/BerlinEurope/MoscowAsia/TokyoAsia/ShanghaiAsia/KolkataAsia/DubaiAustralia/SydneyAustralia/AdelaidePacific/AucklandPacific/HonoluluAfrica/CairoAfrica/LagosAfrica/JohannesburgEurope/AmsterdamAsia/SingaporeAmerica/Atikokan

4No zoneUTCAmerica/New_YorkAmerica/ChicagoAmerica/DenverAmerica/Los_AngelesEurope/LondonEurope/ParisEurope/BerlinEurope/MoscowAsia/TokyoAsia/ShanghaiAsia/KolkataAsia/DubaiAustralia/SydneyAustralia/AdelaidePacific/AucklandPacific/HonoluluAfrica/CairoAfrica/LagosAfrica/JohannesburgEurope/AmsterdamAsia/SingaporeAmerica/Atikokan

No result

Zonename/Wwwwwwwwwwwww: The 01:30 time happens twice in Zonename/Wwwwwwwwwwwww on that date. With disambiguation: "reject", resolveLocal does not pick one.

Zonename/Wwwwwwwwwwwww: The 01:30 time happens twice in Zonename/Wwwwwwwwwwwww on that date. With disambiguation: "reject", resolveLocal does not pick one.

 

The local date-time read at the offset the time code states, with resolveLocal.

A time alone names no instant: there is no date.

A date alone names no instant.

Read with disambiguation: "reject": a time the clock shows twice or never is not resolved.

No instant: the code names Eastern time and states no offset. Pick the IANA zone it means for you.

No instant: nothing here states an offset. Pick the zone.

No value.

4. Written back by formatX12Date and formatX12TimeElement

The date as element 373, with D8.

 

formatX12TimeElement("14:30:00.12", "HHMMSSDD")

The time as element 337, in the form it was sent.

 

formatX12TimeElement("14:30:00.12", "HHMMSSDD")

The date is element 373 read alone by parseX12Date. The time is element 337 read alone by parseX12Time.

5. A DTP value

Qualifier (1250)Value (1251)

A range of dates is sent with a hyphen between its two ends. It names no instant, and a qualifier has no time code.

A range of dates is sent with a hyphen between its two ends. It names no instant, and a qualifier has no time code.

A range of date-times, each end with seconds, joined by a hyphen. The qualifier states no offset, so neither end names an instant.

The same date as D8 with the fields in another order: DB is MMDDCCYY. The library reads the order the qualifier states.

D6 has a two-digit year, and no standard says which century it belongs to. The EDI functions do not read it, so the library returns the sentinel. The pattern parsers read the same digits with a yearWindow that states the century.

A DTP segment carries a 1250 qualifier and an element 1251 value. It carries no time code, and no 1250 code states an offset.

6. What the DTP calls return

061520241251 valueDB125006MM15DD2024CCYYdateno offset  

20240615143000-202406201600001251 valueDTS1250start2024CCYY06MM15DDdate14HH30MM00SStime-end2024CCYY06MM20DDdate16HH00MM00SStimeno offset  

No result

Code TR has a two-digit year. No standard says which century it belongs to, so the EDI functions do not read it. Read it with parseDateWithPattern or parseDateTimeWithPattern: the pattern ddMMyyHHmm and a yearWindow, which states the century you choose.

Kind

no result

Value

no result

Range end

no result

classifyX12DateTimePeriodFormat("DTS")
parseX12DateTimeRange("20240615143000-20240620160000", "DTS")

 

{ kind: "dateTimeRange", format: "DTS" } { start: "2024-06-15T14:30:00", end: "2024-06-20T16:00:00" }

formatX12DateTimeRange("2024-06-15T14:30:00", "2024-06-20T16:00:00", "DTS")

 

formatX12DateRange returned the sentinel for this value and qualifier.

The three elements. X12 is a United States standard. The 214’s AT7, the 204’s G62 and DTM carry the date, the time and the time code side by side. Any of the three may be empty. The tool reads a date and a time together with parseX12DateAndTime, and a date or a time sent alone with parseX12Date or parseX12Time.

What a time code states. It states an offset, as 01 does for UTC+1 and 13 does for UTC−12. It names a zone and states no offset, as ET does. Or it says local to the event, as LT does, and so does a blank code, because the place is elsewhere in the message. The verdict has two forms: the offset is stated, and the instant comes from resolveLocal(local, offset); or it is not stated, and the instant comes from the zones you pick.

Why the zones are yours. The library maps no time code, place or partner to a zone. Each preset that states no offset opens with the zones its example picked, and those are the example’s choice, not something X12 or the code says. Typing a time code never fills a zone, and the tool does not check a daylight flag against the zone you pick. Each row calls resolveLocal with disambiguation: "reject", so a time the clock shows twice or never is not resolved, and the row says why.

A DTP value. A DTP carries a 1250 qualifier and an element 1251 value. It has no time code and no instant, and the tool classifies the qualifier with classifyX12DateTimePeriodFormat and calls the parser of the kind that came back. A two-digit-year qualifier such as D6 is not read: the sentence under NO SIGNAL names the pattern parser and the yearWindow that read it.

Worth trying: ET with America/New_York picked — then change the date to January and watch the instant move an hour. Then code 13 — the offset is UTC−12, not UTC−1, and the instant is on the next UTC day. Type 24 to see UTC−1.

Reference: parseX12DateAndTime reads the date and the time, x12TimeCodeOffset and x12TimeCodeZone say what the code states, and the classifiers tell a code from an abbreviation when a read is refused. formatX12Date and formatX12TimeElement write the date and the time back, the time in the form it was sent. resolveLocal, toOffsetInstant and fromOffsetInstant turn a local time into an instant, and diffUtcAsDuration states the gap between the zones. The rules are in Intermodal: EDI Timestamps.