---

NEW: Beam is Partially Available for Text Routing (5/22/97)

Q: My application doesn't support 'frame dataTypes. Why is Beam available in my Action picker in Newton 2.1 OS?

A: The Beam transport in Newton 2.1 OS supports the 'text dataType. If any routing formats for your data supports text export (a format.dataTypes array includes 'text), Beam will be available. Unfortunately, there is a bug in current Newton 2.1 OS devices such that Beam does not convert the target to text before sending it. Transports that support sending text should use the kItemToTextFunc function (in the Newton 2.x platform files), and that function calls the format's TextScript to convert the item to text. Since Beam does not do this, this gives the appearance that the item is being sent as 'frame, a dataType that may not be supported by your application's routing formats.

There are several workarounds (with the first choice recommended):
#1) Add support for the 'frame datatype. In your routing format, add 'frame to the dataTypes slot. This will allow all 'frame transports, including mail transports that can send attachments, to send mail with your application. This will allow your application to avoid text-specific bugs in Beam. For the best user interface, we recommend that you write stationery for your data so that users can view the item in the In Box or Out Box. See the Newton Programmers Guide and Reference for more information about writing and registering stationery. Note that you can test your application with Put Away, using the built-in Beam transport as well as the DTS sample "Archive Transport".

#2) Provide a text-only format that converts the item to text in the format:SetupItem(...) method. If you don't support overviews or other mechanisms that use multiple item targets, change item.body to be a new frame of the form {text: "the converted item to text", class: 'text}. Note that this format should not also support the 'frame dataType because you are destructively modifying the item.

If you do support multiple item targets, you have to do more work because the items are not split up into seperate items before your SetupItem method is called. You can use the code like the following in your SetupItem format after calling the inherited method:

// get a 'cursor' to iterate over the items.
// Note: this still returns a 'cursor' even if item.body wasn't real
local cursor := GetTargetCursor(item.body, nil);
local newArray := [];
local entry := cursor:entry();
while (entry) do
    begin
        // convert item to text in whatever way you normally do it...
        // For instance, you might call your format's textscript...
        entry := {
            text: "blah blah" && entry.a && entry.b,
            class: 'text
            }; 
        AddArraySlot(newArray, entry);
        entry := cursor:Next();
    end;
        
item.body := CreateTargetCursor(classof(item.body), newArray);

// remember to return 'item' from SetupItem
item
 

You might be wondering if you could route the 'frame data by hiding the data in extra slots in item.body. If you did that, the item would be much larger than necessary to route 'frame data, and will not be Put Away properly because the 'class slot is set to 'text, not your original data class). If you actually want to support 'text and 'frame dataTypes, use a single protoFrameFormat with dataTypes ['frame, 'text] and do not convert the item.body as illustrated above. (This is actually recommendation #1 above).

Note that 'text stationery must be registered in order to view the item in the In Box and Out Box. Such stationery is not necessarily installed on the receiving device. Some mail transport packages may have installed 'text stationery, but you may choose not to rely on this. If you are interested in writing text stationery, see the DTS sample "MinMail" and the Newton Programmers Guide and Reference for more information about writing and registering stationery.