Specifications > Interrogation > File Specification

M4 File

Email Comments

 

The M4 file format has been in use for production data since 2013. It is an XML file format that has a one-to-many header-to-detail structure. The File Submission element contains the header information, and can contain one or many Message Data elements with the detail records. The XML schema file (XSD) for the M4 file type can be found online and used to validate the M4 file structure is correct. This is a good free online XML validator, which may be useful if you are trying to construct an M4 file.

 

M4 and PIFF 2 software can be used to create files of this type.

 

 

The columns in the FileSubmission table represent the “header” portion of a data file and are used for validation and processing purposes. All fields in this table are required.

 

Field Name

Definition

Domain

FileTitle

Name of digital file submitted to PTAGIS for loading. It is generated automatically based on when the file is created. Each distinct set of data must be in a file with a unique name.

SIT-YYYY-DOY-R-UDF.xml

 

SIT = 3-character site code

YYYY = 4-digit year of FileCreated

DOY = Day of year of FileCreated

UDF = 1-3 character user-defined to ensure unique file name

FileCreated

Date and time the file was opened for data collection

Date Time Offset. Must be earlier than FileClosed.

SiteCode

PTAGIS Site Code

Three alphanumeric characters

SiteLastModified

Date and time the site configuration was last modified.

Date Time Offset

MachineName

Name of the PC on which the file was created.

Text up to 50 characters

ProgramVersion

Name and version of software that created file.

Text up to 50 characters

DataRole

Indicates how the file should be processed

P = Primary, data will be loaded if valid and file will be stored

S = Secondary/backup, data will not be loaded and file will be stored

X = Patch, data will be loaded if valid and file will be stored

PtagisUserId

User name or email address of site steward or technical staff.

Text up to 255 characters

FileClosed

Date and time the file was closed data collection.

Date Time Offset. Must be later than FileCreated.

 

Each column in the MessageData table is described below. Some columns are optional depending upon message type.

Field Name

Definition

Domain

MessageKey

Unique record identifier (per site)

Integer

TimeStamp

Date and time the event occurred

Date Time Offset.  Must be between FileCreated and FileClosed.

MessageTypeVal

Indicates the type of record or message

Valid M4 Message Type value

MessageText*

Raw data or message recorded from equipment at the site (e.g. transceiver, PLC or other piece of equipment).

Text up to 4000 characters

AntennaGroup*

Optional antenna group name. This is for display in M4 only and is not loaded into PTAGIS. Antenna Group Name from the site configuration is used instead.

 

TransceiverId*

Unique identifier of the transceiver or other equipment that recorded the data.

Two character hexadecimal code

AntennaId*

Unique identifier of the antenna or other child piece of equipment that recorded the data.

Two character hexadecimal code

TransceiverBufferTimeStamp*

Timestamp if the record originated from the transceiver buffer.

Date Time Offset.

SbycActionTypeVal*

If MessageTypeVal = SbycTagMessage, or Field Data Type = SbyCTag, then this field records the SbyC action that was taken on that tag code

Valid Sbyc Action Type

SbycActionCode*

If MessageTypeVal = SbycTagMessage, then this field records the Action Code of the target group in which the tag is included.

integer

SbycGateActionTypeVal*

If MessageTypeVal = SbycTagMessage, then this field records the action or non-action of the physical SbyC gate for this tag

Valid Sbyc Gate Action Type

SbycProcessLatency*

Amount of time in milliseconds it took SbyC process to trigger gate action

Integer

*optional

Message Type Value

MessageTypeValue

VerboseDescription

None

Default: no message type.

RealTimeTag

Tag code captured from a reader device in real-time.

BufferedTag

Tag code downloaded from a readers internal storage.

DeviceAlarm

An alarm message generated from a reader device.

DeviceStatus

A status report generated from a reader device.

DeviceMessage

Information generated from a reader device.

SystemStatus

Information generated by the application or underlying system.

Error

An error message generated by the application or system.

StartMonitor

Data collection has started for the interrogation site.

StopMonitor

Data collection has stopped for the interrogation site.

DataUpload

One or more data files has been uploaded to PTAGIS.

DataExport

One or more data files have been exported to an external drive or folder.

DataMarker

Provides a user-defined marker within the data collection stream.

GPSCoordinate

A GPS coordinate.

DeviceNoiseReport

A noise report generated from a reader device.

DeviceBitCounterReport

A bit-counter report generated from a reader device.

SbycServiceStarted

The separation-by-code sevice has been started.

SbycServiceStopped

The separation-by-code sevice has been stopped.

DeviceExceptionError

An application error associated with a specific device.

DeviceConnectionStatus

The connection status with a device.

DeviceBufferedStatus

A status report generated and stored on a reader device.

DeviceIdMismatch

Device identifier reported from a reader device is different from the one configured.

DeviceTagCountReset

Tag counter has been reset on a reader device.

SequenceMismatch

BCC Reader message sequence is mismatched.

StartMonitorPending

Configuration is loaded and data collection is about to start.

StartMonitorFailed

Data collection failed to start.

SbycErrorMessage

An error occurred processing a separation-by-code request.

SbycTagMessage

A real-time tag resulted in a separation-by-code action.

ClusterStatus

Status generated by the the M4 cluster system.

ClusterError

Describes an error condition related to the M4 Failover Cluster.

DataUploadError

An error occurred uploading data files to the PTAGIS server.

DataExportError

An error occurred exporting data files to an external drive or folder.

SpuriousRealTimeTag

A spurious real-time tag code was detected.

SpuriousBufferedTag

A spurious tag code was downloaded from reader storage.

BufferedDeviceError

A reader error buffered and reported from the readers internal storage.

BufferedDeviceAlarm

A reader alarm buffered and reported from the readers internal storage.

BufferedDeviceMessage

Information from a reader that was buffered and reported from the readers internal storage.

PlcMessage

Data acquired from a PLC device.

PlcDiagnostic

Diagnostic data acquired from a PLC device.

PlcError

An error occurred connecting to or reading from a PLC device.

StartSbycPending

The configuration is loading and the separation-by-code service is about to be started.

StartSbycFailed

The separation-by-code service failed to start.

PlcSwitchState

The value of a logical switch monitored by a PLC device has changed.

PlcSampleState

The value of a facility sample monitored by a PLC device has changed.

SbycStateActive

The separation-by-code service is actively controlling the diversion gates.

SbycStatePassive

The separation-by-code service is not sending gate divert requests and is in stand-by mode.

SbycStateFaulted

The separation-by-code service cannot send divert requests due to a hardware or network-related communication fault.

SbycStateRecoverd

The separation-by-code service has recovered from a hardware or network-related communication fault.

 

SbyC Action Type

 

Type

Description

None

No action was triggered.

DefaultIgnore

Default action triggered because tag code is a timer or test tag.

DefaultNotFound

Action code associated with the tag code was not found in lookup table, so the default action was triggered.

DefaultAll

Divert by default, all tag codes trigger the same action.

Override

The override gate action was triggered based on the action code assigned to the tag code.

DefaultSkip

The default action was triggered because the override protocol instructed a skip (e.g. daily or seasonal limit has been reached or the protocol time period has been exceeded).

DefaultNA

The default gate action was triggered because the action code assigned to the tag code is not applicable at this diversion gate.

Ignore

No gate action was triggered because the tag is a timer tag.

Duplicate

No gate action was triggered because the tag code is a duplicate.

StandBy

No gate action was triggered because the SbyC service is in a stand-by state.

Failed

Indicates a divert request failed to trigger a PLC bit.

 

SbyC Gate Action Type

 

Type

Description

NoOp

Indicates the gate should take no action. This is often used to override a gate that opens by default for any PIT tag.

Open

Indicates the gate should open.

Close

Indicates the gate should close.

Left

Indicates the gate should open to the left side.

Right

Indicates the gate should open to the right side.

 

 

 


Version: 1.07

Published: 9/6/2023