General comments

• The RETDAT protocol is transmitted as the data of an ACNET packet.  RETDAT protocol structures use the ACNET network representation.
• The Front-end process which services RETDAT requests connects to ACNET with the rad-50 handle RETDAT .
• In the description of the packet formats below all fields in the packets abut.

RETDAT request list packet

 

Length(bytes)	Field Description	Type
2	Maximum length of reply in bytes	2-byte unsigned integer
2	Number of entries in request list	2-byte unsigned integer
2	Frequency-Time-Descriptor(FTD)	2-byte unsigned integer
16	Request structure 1	structure see below
---	---	---
16	Request structure N	structure see below

 
•  The request is a one-shot if and only if the FTD is zero.  Note the console software also uses bit 14 to indicate a one-shot but such FTDs are transmitted over the network.  The ACNET multiple reply flag will also be clear for a one-shot.  MOOC determines if a request is a one-shot by looking at the multiple reply flag not the FTD.
• For a multiple reply FTD, the most-significant bit indicates whether the FTD is a tclk event or a frequency.   When the bit is set the event is a tclk event and the event number is in the least-significant byte.  When it is not set the 14 least-significant bits contain the frequencies period in 60 Hz ticks.

Request structure

 

Length(bytes)	Field Description	Type
4	Property-device index pair	4-byte unsigned integer
8	SSDN	array of 8 1-byte unsigned integers
2	Number of bytes requested from property data (ILEN)	2-byte unsigned integer
2	Offset in bytes to requested property data (usually)	2-byte unsigned integer

 
• The property index in a property-device index pair is placed in the most-significant byte of the integer.
• The device index in a property-device index pair is contained in the least-significant 20 bits.  The most-significant 4 bits may be used for flags of various sorts.
• Please refer to the  Property Notes  for information about property indices and there meanings.

RETDAT reply packet

 

Length(bytes)	Field Description	Type
2	Error status for request list entry 1	2-byte signed integer
ILEN (1)+ ILEN(1) mod 2	Data for request list entry 1	unknown to RETDAT
---	---	---
2	Error status for request list entry N	2-byte signed integer
ILEN(N) + ILEN(N) mod 2	Data for request list entry N	unknown to RETDAT

 
• The ILEN(n) mod 2 term in the length of the data insures that everything is word aligned.  The data in the packet should be left-justified, i.e., should be in the bytes with the lowest offsets from the start of the packet.   However, since the data in the packet is in network representation the data will not be left-justified on the wire.   On the wire the data will be word-wise byte-swapped, which causes among other things the padding byte to be the next to last byte on the wire.   Note that Charlie's Acnet implementation does not perform the word-wise byte-swap so the user's methods must use the network represenation justification when assigning values to the memory area passed to the method by MOOC.
• The error status contains an error byte and a facility byte.  The facility byte is an unsigned 1-byte integer.  The error byte is a signed 1-byte integer.  The error byte is in the most-significant byte of the error status.   A zero error status indicates success.  A negative error indicates failure, a positive error indicates partial success, e.g., a pending.   The facility indicates what returned the error.

Other Comments

• A RETDAT request is cancelled with an ACNET cancel.   An ACNET cancel is a dataless USM with the cancel flag set.   The host address of the requester and the message stamp, aka request id, which are specified in the ACNET header identify what RETDAT request is to be cancelled.
• MOOC looks at the F_RTL flag from ntcreq().  This flag is set when a user-supplies a buffer which is too small for the ACNET packet.  Since MOOC uses ACNET-supplied buffers it does not need to check this.   When not using user-supplied buffers ACNET will allocate appropriately sized buffers dynamically, and thus it will never set F_RTL.  Whether to use ACNET or user buffers is specified by arguments to ntrreq().