Appendix
D
Third Party Data Logger
Communication Details
It would be an extremely difficult task for UltraPIPE to provide communication drivers for all
available and potential third party data loggers. Therefore, a simple calling procedure has been
established to allow UltraPIPE to call third party applications software drivers and provide access
to sets of Eq/Circ ID data which may then be sent to or received from a third party device.
The key to achieving this communication through UltraPIPE is a driver program that you must
provide. The driver program is the interface between UltraPIPE and your data logger. The
driver program receives data from UltraPIPE and converts it to a format that can be understood
by the instrument.
UltraPIPE sends data by writing out the data file (or files) selected by the user, complete with
TMLs, locations, notes, and the most recent thickness, to a DataMate file (or files). UltraPIPE
then starts up a DOS session from which it invokes the driver program. The driver program is
executed and the data written in the DataMate file is downloaded to the third party device.
Upon termination of the driver program, UltraPIPE closes the DOS session and resumes
operation. If an error has occurred during transmission, a message will be displayed. Barring
errors, the third party device will now contain the UltraPIPE Eq/Circ ID information. The
driver program is responsible for deleting files after sending the data to the data logger.
UltraPIPE reads data by receiving Eq/Circ ID data from the driver program in a DataMate file
(or files). The data contained in the file(s) is placed into UltraPIPE’s database. UltraPIPE will
delete all DataMate files used to carry the data.
UltraPIPE places the same data in the DataMate file for all third party data loggers. It is the
responsibility of the driver program to send the needed data to the data logger.
This appendix explains in detail what a developer would need to know in order to create a driver
program that can be used by UltraPIPE to send and receive data to and from a third party data
logger.
D-1
Parameters Passed to the Driver Program
UltraPIPE will invoke driver programs in a DOS shell and pass several parameters. These
parameters will be the same for all third party driver programs and will be of the following
format:
<Program Name> <NG> <SR> <IM> <DISP> <PORT> <BAUD>
<DATADIR> <DATAFILE>
<Program Name> - The path and name of the driver program.
<NG> - Indicates the TML order for output of all Eq/Circ IDs selected to be transferred.
N - Indicates numeric ordering.
G - Indicates grid ordering. The available options are:
“R” - A Grid file which, in the event the data logger does not support grid
scrolling, should be downloaded so that readings are taken incrementing the
Row number after each reading. (i.e. A1, A2, A3, B1, B2, B3, C1, C2, C3).
“C” - A Grid file which, in the event the data logger does not support grid
scrolling, should be downloaded so that readings are taken incrementing the
Column letter after each reading. (i.e. A1, B1, C1, A2, B2, C2, A3, B3, C3).
The “R” or “C” in these cases comes from UltraPIPE where the user is asked
what to increment for each successive reading. If the user changes this in
UltraPIPE, this parameter will change the next time the driver program is
invoked.
<SR> - Indicates whether UltraPIPE is Sending or Receiving data.
<IM> - Indicates the units -- Inch or Millimeter -- which UltraPIPE is sending or receiving. If
data is received by the driver program is not in the correct units, it must be converted before
being written to the DataMate file.
<DISP> - Indicates the display mode of UltraPIPE. “C” for Color or “M” for Monochrome.
This parameter is passed so that any prompts or the transfer status message may be written in
the correct colors for the UltraPIPE screen being displayed.
<PORT> - Indicates the communication port.
<BAUD> - Indicates the transfer baud rate.
<DATADIR> - Indicates the driver and directory from which UltraPIPE will read and write
temporary DataMate files.
<DATAFILE> - The prefix of the DataMate files the driver program will access. Files written
by UltraPIPE or the driver program will contain this prefix and then a three digit sequential
D-2
number and the .DAT file extension. This field will usually contain the prefix “KBSOS”
meaning that if two files are being sent to the equipment their names will be “KBSOS001.DAT”
and “KBSOS002.DAT”. This prefix is also used for any resulting error messages generated by
the driver program. Error messages are written to a file with the specified prefix and then the
letters ERR and a .TXT extension. See the section on Handling Communication Errors for
more information.
The following is an example of a command line parameter:
C:\PIPE\MYPROG C S I C 1 9600 C:\PIPEDATA KBSOS
This will invoke the “MYPROG” driver program. UltraPIPE will expect to receive Grid
Eq/Circ IDs ordered by Column with readings in Inches. Status message to the screen will be
written by “MYPROG” in Color. Communications will be through COM1 at 9600 baud. The
received data will be written to the C:\PIPEDATA directory in a file called KBSOSnnn.DAT,
where nnn is a sequential numeric indicating the order of the files written.
DataMate File Format for a Numeric Eq/Circ ID
When a numeric Eq/Circ ID is specified, a Custom type DataMate file is used. The Custom
DataMate file will contain one reading per location. Please not that the readings for the Custom
file will be entered into the database for matching TML numbers only. That is to say, if a partial
Eq/Circ ID is contained in the DataMate file then only those readings with a TML numerically
equivalent to TMLs in the database will be updated.
For each TML in the UltraPIPE database, there will be a corresponding line in the DataMate file.
This line will be comprised of the following UltraPIPE information:
For Inch system units - 999.99LOCATIONnt 9.999
For Metric system units - 999.99LOCATIONnt 99.99
The 6 character DP number, the 8 character DP Location, the 2 character DP note, two spaces,
and the 6 character reading.
Although UltraPIPE sends the Location and Note information to the data logger software, it
does not expect to have them returned.
If a two character note is returned via the DataMate file it will be entered with the reading into
the new survey fields.
When sending the DataMate file to the driver program, UltraPIPE will determine the most
recent survey for each TML and will use this thickness and note in the DataMate file. As survey
dates may differ between TMLs , the receiving data logger should not attempt to calculate rates
from this data as no TML survey date is included in the file.
UltraPIPE writes the following header fields when sending data to the DataMate file:
D-3
File Name The 8 character Area name immediately
followed by a hyphen and the 16
character Equipment/Circuit name. This
field will be fixed length - 24 characters.
File Name “KBSOSnnn.DAT” a sequential file
number will replace nnn.
File Type “CUSTOM”
Date and Time Created The date and time this file is written
Date and Time Last Modified The date and time this file is written
File Description The first line of the equipment
description.
Allow Manual Readings “Y”
Number of Locations The number of locations in the file.
Characters for Location Code “16”
Readings/Location “1”
Operator ID This field will be left empty
Instrument ID This field will be left empty
Probe ID This field will be left empty
Material Velocity This field will be left empty
Inches or MM The units for Equipment/Circuit. Either
“I” (inches) or “M” (millimeters).
UltraPIPE reads the following header fields when receiving a DataMate file:
File Name The 8 character Area name immediately
followed by a hyphen and the 16
character Equipment/Circuit name. This
field will be fixed length - 24 characters.
File Type Must contain “CUSTOM”
Date and Time Last Modified UltraPIPE will use the date only.
D-4
Number of Locations The number of locations in the file.
Operator ID The three character initials of the
inspector.
Inches or MM The units for Equipment/Circuit. Either
“I” (inches) or “M” (millimeters).
Note: The data for the file must be written in the units specified by UltraPIPE when calling the
data logger. The driver program must perform any necessary conversion.
The following is an UltraPIPE to DataMate Numeric Eq/Circ ID example:
From the Equipment database:
Area: TestArea
Circuit TestCircuit
Description This is a sample description
From the TML database:
TML: 1.0 2.01 2.20
Location: Top PIPE Top PIPE Bottom
FNL_Note RP RP
FNL_Thick 3.05 3.08 4.00
DataMate Custom File:
FileName: TESTAREA-TESTCIRCUIT
DOS File Name: KBSOS001.DAT
FileType: CUSTOM
Date and Time Created: 04/14/96 12:00
Date and Time Last Modified: 04/14/96 12:00
FileDescription: This is a sample description
Allow Manual Readings: Y
Number of Locations: 3
D-5
Characters for Location Code: 16
Readings/Location 1
Operator ID:
Instrument ID:
Probe ID:
Material Velocity:
Inches or MM: I
Location Reading
001.00TOP PIPERP 3.050
002.01TOP PIPE 3.080
002.02BOTTOM RP 4.000
DataMate File Format for a Grid Eq/Circ ID
The Grid DataMate file will actually contain two grids. The first grid, which follows the header
information, will contain the TML readings. The second grid will contain 10 character
Location/Note blocks separated by a space. These blocks are fixed format with the first 8
characters containing the TML location and the last two characters containing the TML note.
Although UltraPIPE sends the Location and Note information to the data logger software it
does not expect to have them returned. If a TML note is returned via the DataMate file it will be
entered with the reading into the new survey fields. If a Location field is returned via the
DataMate file, the corresponding Location in the UltraPIPE database will be changed. The
exception to this is when a blank Location is returned. In this case, UltraPIPE will not edit the
UltraPIPE database as many instruments do not have the capability to use the Location field and
so will always return blank Location.
When sending the DataMate file to the driver program, UltraPIPE will determine the most
recent survey for each TML and will use this thickness and note in the DataMate file. As survey
dates may differ between TMLs , the receiving data logger should not attempt to calculate rates
from this data as no TML survey date is included in the file.
UltraPIPE writes the following header fields when sending data to the DataMate file:
File Name The 8 character Area name immediately
followed by a hyphen and the 16
D-6
character Equipment/Circuit name. This
field will be fixed length - 24 characters.
File Name “KBSOSnnn.DAT” a sequential file
number will replace nnn.
File Type “GRID”
Date and Time Created The date and time this file is written
Date and Time Last Modified The date and time this file is written
File Description The first line of the equipment
description.
Allow Manual Readings “Y”
Upper Left Location The upper left most ID
Lower Right Location The lower right most ID
Operator ID This field will be left empty
Instrument ID This field will be left empty
Probe ID This field will be left empty
Material Velocity This field will be left empty
Inches or MM The units for Equipment/Circuit. Either
“I” (inches) or “M” (millimeters).
UltraPIPE reads the following header fields when receiving a DataMate file:
File Name The 8 character Area name immediately
followed by a hyphen and the 16
character Equipment/Circuit name. This
field will be fixed length - 24 characters.
File Type Must contain “CUSTOM”
Date and Time Last Modified UltraPIPE will use the date only.
Operator ID The three character initials of the
inspector.
D-7
Inches or MM The units for Equipment/Circuit. Either
“I” (inches) or “M” (millimeters).
Note: The data for the file must be written in the units specified by UltraPIPE when calling the
data logger. Any necessary conversion must be performed by the driver program.
The following is a UltraPIPE to DataMate Grid Eq/Circ ID example:
From the Equipment database:
Area: TestArea
Circuit TestCircuit
Description This is a sample description
From the TML database:
TML: A1 A2 B1 B2
Location: Top PIPE Top PIPE Bottom Bottom Right
FNL_Note RP RP NT
FNL_Thick 3.05 3.08 4.00 0.00
DataMate Custom File:
FileName: TESTAREA-TESTCIRCUIT
DOS File Name: KBSOS001.DAT
FileType: GRID
Date and Time Created: 04/14/96 12:00
Date and Time Last Modified: 04/14/96 12:00
FileDescription: This is a sample description
Allow Manual Readings: Y
Upper Left Location: A1
Lower Right Location: B2
D-8
Operator ID:
Instrument ID:
Probe ID:
Material Velocity:
Inches or MM: I
Readings
3.050
3.080
4.000
0.000
Third Party Screen Access during Communications
Before invoking the driver program, UltraPIPE will display a message informing the user that the
program is being loaded. This message can be modified by entering a status message in the Data
Logger I/O window of the Setting Selections menu for sending and receiving data.
Handling Communication Errors
In the event of a communications error, the driver program should write a two line error
message to a text file, delete any received files, and terminate. The file name for the error
message will be the command line filename prefix followed by “ERR” and a .TXT file extension.
All DataMate files associated with the send or receive should be deleted, as the user will, most
likely, try to repeat the transmission after attending to the error.
D-9
