The M4 file format was in use between 2013 and 2023. 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 were used to create files of this type. M4 was primarily used at PTAGIS-maintained sites in the Columbia Basin.
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. |
|
|
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 |
|
|
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 |
|
|
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 |
|
|
SbycProcessLatency* |
Amount of time in milliseconds it took SbyC process to trigger gate action |
Integer |
*optional
|
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. |
|
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. |
|
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.08
Published: 11/12/2024