The MediNet Protocol
Structure
A message between Client and Server comprises a stream of Elements embedded in Segments embedded in Blocks.
In Phase 1, the client sends an Order File to the server. In Phase 2, the server sends an Outcome Report to the client. Phases 1 and 2 may then be repeated while the client has further orders.
GO.EXE offers a choice of four formats for the Outcome Report, as selected by the otype field in the Order File header segment. Use type T for directly presenting readable text to the user, or type P where you intend processing the report in your software. Types 3 and 2 are for backwards compatibility.
Element
An element is a variable length string of printable ASCII characters representing a single field such as a PIP-Code or a product description.
- Printable ASCII characters are those in the range CHR$(32) to CHR$(126).
- Leading zeros may be omitted from numeric elements. Trailing spaces may be omitted from alphanumeric elements.
- An element may be empty (zero length).
Segment
A segment is an ordered group of elements, such as a single order line.
- Elements within a segment are separated by the single ASCII byte RS (CHR$(30)).
- A segment is terminated by the single ASCII byte GS (CHR$(29)).
- Any empty elements at the end of a segment may be omitted.
- GO.EXE is backwards compatible with systems using the colon : (CHR$(58)) as the Element Separator and the plus sign + (CHR$(43)) as the Segment Terminator. Such systems will tolerate colons and plus signs within an element only if it is the last element of a segment.
Block
A block is a group of segments with the same structure, of suitable size for insertion into a transmission frame by the Data Link layer (say up to 120 bytes).
- A block should have a two byte prefix. The first byte is a printable character identifying the type of segments contained within the block. The second byte is the Segment Terminator.
- The block prefix may be omitted if its segments are of the same type as the preceding block.
- A single transmission frame can contain more than one block.
- The last segment of a transmission frame does not require the segment terminator.
- A block may contain empty segments (this provides padding if required for backwards compatibility).
The Order File
An order file comprises one Header Segment followed by any number of Detail Segments.
Order Header Segment (Block Prefix "H")
H+id:holder1:details:otype:holder2:holder3:holder4:cref
- id
- Alphanumeric, identifying the caller. GO.EXE expects id to be not less than ten characters comprising the caller's five digit Access Code and five character Password. If id is more than ten characters, GO.EXE discards the leading characters. If the password is incorrect GO.EXE disconnects (with code "C") immediately.
- holder1
- Reserved placeholder (leave empty).
- details
- Numeric, the number of Detail Segments following in the order file. No action is taken by GO.EXE if this does not match the actual number of Detail Segments received.
- otype
- Alphanumeric. A single character defining the type of Outcome Report required from the wholesaler in Phase 2. Specify:
"T" for Text Segments only,
"P" for Progress Segments,
"3" for Result Segments (without product descriptions),
"2" for Result Segments (with product descriptions). - holder2
- Reserved placeholder (leave empty).
- holder3
- Reserved placeholder (leave empty).
- holder4
- Reserved placeholder (leave empty).
- cref
- Alphanumeric, optional Customer's Reference. The wholesaler may print this on any documents ensuing from the order (it will be truncated if it exceeds the wholesaler's maximum length).
Order Detail Segment (Block Prefix "D")
D+item:qty:flags
- item
- Alphanumeric, the product's Item Code. Currently, GO.EXE supports:
PIP-Codes (numeric up to seven digits). - qty
- Numeric, the quantity ordered. Defaults to 1 if empty.
- flags
- Alphanumeric option flags. Option flags may be combined and may appear in any sequence. Specify:
"F" to request the item be placed on Back Order, to follow later, if out of stock.
"C" to indicate the qty element specifies cases (not units).
When combining Detail Segments within a single Block, only the Segment Terminator need separate the segments. It will usually be possible to omit flags (and qty too if the order quantity is 1). For example, the block:
D+6000285:6+698621+7510746:2+6009104:2+6009906:2+7510118+7510100:6
contains seven valid Detail segments (with a total order quantity of 20 units).
The Outcome Report (type T)
When otype="T" is specified in the Order Header, the report comprises only Text Segments ready for direct presentation to the user.
Text Segment (Block Prefix "T")
T+text
- text
- Alphanumeric, free format text.
The first Text Segment is sent immediately the wholesaler becomes line Master. It confirms the order has been safely received by the wholesaler, even if no further segments are sent. Additional Text Segments may be sent, each detailing an order line which cannot be delivered in full. These will be followed by the Order Outcome and finally the wholesaler's thanks. For example:
T+Fri 13 Jul 01 13:57. 8 lines expected, 8 taken by Station 2
T+006-1523 Ordered 12 regret 12 out of stock (N) Not on File
T+002-1626 Ordered 1 regret 1 out of stock (N) Not on File
T+040-1430 Ordered 9 regret 1 out of stock (T) SLINKY CONF BANDAGE 4M STRETCH 7.5CM PRE
T+103-2267 Ordered 1009 regret 1009 out of stock (N) Not on File
T+INVOICE 00000 #99999.99-
T+Thank you from J Wellington Wells
The Outcome Report (type P)
When otype="P" is specified in the Order Header, the report comprises one or more Progress Segments and one End Segment.
Progress Segments (Block Prefix "P")
The Initial Progress Segment is always present and is sent immediately the wholesaler becomes line Master. It confirms the order has been safely received by the wholesaler, even if no further segments are sent.
P+line:schema:count:station:time
- line
- Numeric, always value 0. Identifies this as the Initial Progress Segment.
- schema
- Numeric, always value 1. Allows for future modifications to the specification without loosing backwards compatibility.
- count
- Numeric, the number of lines (Detail Segments) detected in the Order File.
- station
- Numeric, allocated by the wholesaler to identify the equipment which handled the order.
- time
- Numeric (hhmmss according to the wholesaler's clock). Enables the wholesaler to find the order in the equipment's queue.
Additional Progress Segments are used to report shortages:
P+line:reason:QtyShort
- line
- Numeric, the Order Line Number of the item not being delivered in full.
- reason
- Alphanumeric (currently one character) as determined by the wholesaler. Reasons include (but may not be restricted to):
"N" Not stocked (or not an allocated item code),
"T" Temporarily out of stock (please reorder),
"B" Temporarily out of stock (will follow on Back Order),
"M" Manufacturer cannot supply. - QtyShort
- Numeric, the number of units (not cases) ordered but not being delivered.
It is possible for a progress Segment to be abbreviated to:
P+line
This indicates that the wholesaler's main computer has checked the stock up to order line line inclusive and there are no outstanding shortages to report. This is useful to reassure the customer that something is happening if the wholesaler's main computer is running slow (e.g. the information can be used to provide a % completion bar).
End Segment (Block Prefix "E")
The End Segment is always sent last and gives the Order Status and Outcome.
E+status:shorts:message
- status
- Alphanumeric, current values are:
"P" Pending. The wholesaler's main computer was unable to process the order, but it will be dealt with as soon as possible
"R" Rejected. The wholesaler's main computer rejected the order (see message for the reason).
"D" Done. The wholesaler's main computer completed processing the order (see message for the outcome). - shorts
- Numeric. The number of order lines (Detail Segments) for which shortages have been reported in Progress Segments.
- message
- Alphanumeric (currently not exceeding 24 characters).
When status="P", message="Stock not checked" if the wholesaler's main computer is off-line or message="Stock check abandoned" if it stops responding.
When status="R", message gives the reason as given by the wholesaler's main computer, e.g. "*** Invalid Access Code".
When status="D", message gives the details as given by the wholesaler's main computer, e.g. "INVOICE 12345 £123.45"
This is what the example Outcome Report shown for Type T looks like as Type P:
P+0:1:8:2:140258
P+1:N:12
P+2:N:1
P+3:T:1
P+5
P+6
P+7:N:1009
P+8
E+D:4:INVOICE 00000 #99999.99-
The Outcome Report (Type 3)
When otype="3" is specified in the Order Header, the report comprises one Text Segment acting as order acknowledgement, then one Result Segment for each order line the wholesaler is not going to deliver as requested, then one Summary Segment.
Result Segment (Block Prefix "R")
R+item:OrdQty:DlyQty:reason
- item
- Alphanumeric, the product's Item Code. Currently, GO.EXE supports:
PIP-Codes (seven digits). - OrdQty
- Numeric (four digits), the quantity ordered.
- DlyQty
- Numeric (four digits), the quantity being delivered.
- reason
- Alphanumeric (currently one character) as determined by the wholesaler. Reasons include (but may not be restricted to):
"N" Not stocked (or not an allocated item code),
"T" Temporarily out of stock (please reorder),
"B" Temporarily out of stock (will follow on Back Order),
"M" Manufacturer cannot supply.
Summary Segment (Block Prefix "S")
S+count:dcount:value:serial:message
- count
- Numeric, the number of lines (Detail Segments) detected in the Order File.
- dcount
- Numeric, the number of lines (Detail Segments) for which shortages have not been reported in Result Segments.
- value
- Numeric, GO.EXE always reports this as 0.
- serial
- Numeric. GO.EXE always reports this as 0.
- message
- Alphanumeric (currently not exceeding 24 characters).
If the wholesaler's main computer is off-line message="Stock not checked"
If the wholesaler's main computer stops responding message="Stock check abandoned"
If the wholesaler's main computer rejects the order, message gives the reason as given by the wholesaler's main computer (this will always begin with an asterisk), e.g. "*** Invalid Access Code".
Otherwise, message gives the order outcome as given by the wholesaler's main computer, e.g. "INVOICE 12345 £123.45"
This is what the example Outcome Report shown for Type T looks like as Type 3:
T+J Wellington Wells (Station 2)
R+0061523:0012:0000:N
R+0021626:0001:0000:N
R+0401430:0009:0008:T
R+1032267:1009:0000:N
S+008:004:0:0:INVOICE 00000 #99999.99-
The Outcome Report (Type 2)
When otype="2" is specified in the Order Header, the report is as for otype="3" except that the product description is added as an extra element at the end of each Result Segment.
This is what the example Outcome Report shown for Type T looks like as Type 2:
T+J Wellington Wells (Station 2)
R+0061523:0012:0000:N:Not on File
R+0021626:0001:0000:N:Not on File
R+0401430:0009:0008:T:SLINKY CONF BANDAGE 4M STRETCH 7.5CM PRE
R+1032267:1009:0000:N:Not on File
S+008:004:0:0:INVOICE 00000 #99999.99-