Book Contents Previous Chapter Next Chapter
This chapter describes the relationship between Magic Cap and Telescript and provides an overview of how to use Telescript in your Magic Cap packages. The information in this chapter is intended to familiarize you with some basic Telescript concepts, but it doesn't provide details about Telescript.
Creating Telescript-based services requires the Telescript Developer Kit or Telescript Service Provider Kit, additional software kits from General Magic which are available through a special license. For more information about programming in Telescript, contact General Magic to obtain the Telescript White Papers.
Telescript technology provides a software foundation for electronic messaging and distributed processing with personal communicators, computers, telephones, and the networks that link them together. Telescript networks are platforms for developers that support the creation of communicating applications, software packages that use Telescript as the foundation for communication-based services.
Telescript uses remote programming, in which complete programs are transported from one network device to another and then executed by the receiving device. An interpreter called a Telescript engine running on each device provides the environment for executing these programs. Typically, one device is a Magic Cap platform, such as a personal communicator or Magic Cap for Windows, while the other device is a communication service, such as AT&T PersonaLink Services.
A cloud is a group of Telescript engines and their supporting applications.
Telescript and Magic Cap are designed to be compatible in many ways and to work together tightly to enable a wide variety of communicating applications. Magic Cap includes the ability to execute Telescript programs, and many Telescript classes are also available in Magic Cap.
Telescript performs much of its work by means of Telescript programs called agents. For example, the programs that traverse the network are agents representing users or other entities. When agents arrive at their destination, they interact with other agents representing services. The venues for these interactions among agents are places.
Every agent and place defines a method named live (the verb, rhymes with "give"). When an agent or place is created, its live method is executed.
Every agent also defines a method named go. When an agent executes its go method, the agent suspends execution, saves its state, and prepares for transmission to its destination. When the agent is received at the destination, it resumes execution at the instruction following go. A trip is an agent's journey from one place to another.
When an agent is about to be transported to another place, it is converted to a special form conducive to transmission. This special form for transmission is called the agent's wireline encoding, also known colloquially as the bag of bits, a reference to the generic nature of this form. When the agent reaches its destination, the Telescript engine converts it back to its usual form.
General Magic provides various class libraries and frameworks that you can use when creating communicating applications. The most important of these are the Telescript Application Library, Magicmail Framework, and Publishing Applications Library.
The Telescript Application Library provides high-level classes that are needed by most applications, such as access control, event handling, exception handling, external methods, localization, logging, administration, and rules.
The Magicmail Framework is a set of classes used by network operators as the foundation for commercial messaging services. AT&T PersonaLink Services is an example of a Magicmail-based service. Magicmail includes classes for the network as well as for Magic Cap.
The Publishing Applications Library classes can be used to implement basic information publishing services, such as online newspaper delivery. This library includes provisions for creating a broadcast place, a Telescript place for sending information to subscribers.
The Telescript Application Library, Magicmail Framework, and Publishing Applications Library are fully described in the Telescript Developer Kit.
Telescript is designed to be very portable, and Telescript engines can be present on many different kinds of computing systems. Telescript engines are available in the following:
Although Magic Cap and AT&T PersonaLink Services are the initial hosts for Telescript engines, Telescript does not depend fundamentally on either of these hosts and will be available in other venues. Specifically, Telescript engines may be available on other, non-Magic Cap personal communicator and personal computer platforms in the future. In addition, Telescript-based services other than AT&T PersonaLink Services may appear in the future.
Magic Cap also provides features that support communication without using Telescript. Many of these features are described in this book's Electronic Mail chapter. However, because Magic Cap provides the only client access to Telescript at present, creating a Telescript-based application without using Magic Cap is currently impractical.
To create a Telescript-based communicating application, you must take the following steps:
There are two forms of Telescript: High Telescript and Low Telescript. You can create Telescript programs using either or both of the two forms, although you'll typically write your Telescript programs in High Telescript. Low Telescript is the form that is read and interpreted directly by Telescript engines. Low Telescript is a stack-based language that uses Reverse Polish Notation, like PostScript and Forth.
High Telescript was created to simplify programming in Telescript. High Telescript has a function-oriented syntax and is more like C or Pascal, making it easier to read and use than Low Telescript. Every High Telescript element maps directly to Low Telescript, and the build process provides tools that translate High Telescript to Low Telescript.
You create communicating applications using Magic Cap and Telescript. Communicating applications have two parts, one that runs on the Magic Cap platform and the other that runs on the Telescript network.
When you create a communicating application, you must install both the Magic Cap- and network-resident parts. The Magic Cap part is represented by a Magic Cap software package and can include any of the usual elements of a Magic Cap package. You introduce Telescript code by installing class definitions in one or more Telescript places, such as the engine place or places created by your application. Telescript network operators provide procedures for installing your Telescript code.
The rest of this section describes a few of the many possible kinds of communicating applications that can be created with Magic Cap and Telescript. Note that these kinds of applications, like all communicating applications, require the cooperation of the operator of the Telescript-based network that hosts them.
You can create a communicating application that provides information on request from a remote database to the Magic Cap platform. For example, your service in the Telescript network might have access to a large database of detailed street maps, and users could request particular maps from Magic Cap. You might also create a service that publishes information on a regular basis, such as a daily electronic newspaper customized to the user's particular interests or a daily horoscope provider.
Telescript allows you to create arbitrary agents that execute in the network and perform tasks on behalf of the user. You can create an application that sends agents to watch some value, such as the price of a stock, or waits for some event, such as a particular model of car being advertised for sale below a certain price. Once sent, these agents continue to operate in the network without further intervention by the Magic Cap user. Then, when the appropriate event occurs, they can send the appropriate signal back to the Magic Cap platform.
You can create communicating applications that provide users with an interactive catalog of products, customized to follow each user's interests. These catalogs could allow users to browse, evaluate, and order all kinds of products from the service. Software products could be delivered directly by the service, while physical goods would be shipped according to the preferences indicated by the user when the order was placed.
Every subscriber to AT&T PersonaLink Services has a mailbox that accumulates mail before it is sent to Magic Cap. You can use Telescript to create custom mailboxes that perform specialized tasks. For example, you might create a customer support mailbox that automatically routes inquiries to the appropriate support representative, based on when the message is received and what expertise is required.
Magicmail services such as AT&T PersonaLink allow users to customize their mailboxes by setting up various rules in the AT&T building downtown in Magic Cap. The set of rules available in Magic Cap is fairly small: in general, users can set rules to automatically forward or delete telecards that meet certain criteria, or to automatically signal the user's pager when certain telecards arrive. You could create a communicating application that adds new kinds of rules to the user's mailbox. For example, you could create a rule to automatically inform some senders that you're on vacation when they send telecards to you.
Magicmail uses portals to transmit telecards to and from other kinds of mail systems. For example, AT&T PersonaLink Services includes portals for exchanging text with internet addresses, fax machines, and pagers. You could use Telescript to create an internet portal that can exchange data types other than text, such as MIME enclosures, or to create a portal that reads Netnews. Portals are sometimes called gateways.
Magic Cap provides users with access to Telescript networks. Every Magic Cap platform includes Telescript agent classes that can travel to and communicate with the agents and places in Telescript networks. This section describes some of the common agents and places provided by Magic Cap.
Magic Cap includes two Telescript places. The in box place receives agents bearing telecards from the service and corresponds to the Magic Cap in box that users see. The customization place hosts agents that prepare custom rules (also known as customizations) for the user's mailbox in the service, such as auto-forward and auto-delete rules.
Magic Cap also includes many agent classes. When the user collects mail, a mail collector agent goes from Magic Cap to the user's mailbox in the Telescript network to check for mail. The network creates and sends back a mail summary agent that lists the contents of the mailbox. As the telecards themselves are collected, the network sends a mail escort agent to Magic Cap with the messages. The mail escort agent is received by the in box place in Magic Cap.
When the user creates a new customization rule for mail, Magic Cap creates and sends an edit customization agent to the user's mailbox in the network. When the user wants to look up an address in the network's directory, Magic Cap sends a directory inquiry agent to the directory place in the network. Standard telecards are sent to the network with a courier agent.
Other agent types used by Magic Cap include download data agents, which are used to transmit various kinds of data including registration forms, and register agents, used to carry filled-out registration forms to the network.
In addition to these built-in places and agents, your communicating application will likely create its own places and agents in Magic Cap and in the Telescript network. The Magic Cap part of your application will create agents that are sent to the network, and the network will execute your agents and return agents to Magic Cap if appropriate.
The information in this section is particularly applicable to the most common kinds of communicating applications, information services. Although the details and examples are presented in the context of information services, most of the techniques are applicable to all kind of communicating applications.
Your communicating application will probably create a building downtown in Magic Cap. Inside the building downtown, you should provide the appropriate user interface for starting communication with the service. Alternately, you might provide a telecard in the in box that can be used to register with the service.
When the user starts communicating with the service, either by taking some action in your building or by touching a button on a card in the in box, your application will probably create a new agent and ask Magic Cap to send it to the service. When Magic Cap is ready to send the agent, it executes the agent's live operation, which eventually calls go. Magic Cap then translates the agent to its wireline encoding and sends it to the service.
When the encoded agent arrives at the service, the service reconstitutes the agent as a Telescript object and routes it to the appropriate place in the service. Usually, this place will be an application place that was previously created and installed by the application itself. The agent then resumes execution with the instruction immediately following go.
Once executing in the network, the agent then performs its task, which may consist of retrieving information or waiting for a particular event to take place. When the agent has completed its task in the network, it prepares for a return trip to the Magic Cap platform. The original agent itself might make the return trip, but more typically, the original agent will create a new agent, perhaps of a different class, for the return trip.
When the returning agent is received, Magic Cap routes it to the appropriate place, usually a place created by the application. Once the agent is in its place, it can take whatever action is necessary to finish its job.
Every Telescript agent and place has a telename, an object that indicates the entity that owns the agent or place. As described in this book's Software Packages chapter, Magic Cap packages include a telename. Any agents or places created by your application will bear this telename.
Every Telescript place also has a teleaddress, an object that identifies the place. The place's teleaddress indicates its location by referring to its enclosing place. A place's teleaddress also includes a string chosen by its creator when the place is created. The place's teleaddress allows the Telescript network to route appropriate agents to that place.
The rest of this section describes the various parts of a communicating application and provides information on some of the details of creating these parts.
A communicating application contains two parts, one part that runs on the Magic Cap platform and the other that runs on the Telescript network. The part that runs on Magic Cap is made up of the usual pieces of a Magic Cap package: C source, a class definition file, and an instance definition file. The Magic Cap package defines the application's user interface, Telescript agents and other custom classes, and a Telescript place in Magic Cap if appropriate.
In addition, the Magic Cap part sometimes includes a small amount of Telescript that implements code for classes that must execute in the Telescript network.
The part of a communicating application that runs in the Telescript network consists of Telescript code, organized as classes. Any classes whose objects will execute code in both the Magic Cap platform and the Telescript network must be defined in both places.
Because your agent's live method will execute in the Telescript network, it must be implemented in Telescript. You can implement your agent's live method in Telescript by including a Telescript source file with the .ts suffix with the other source files for your Magic Cap package. When you use CodeWarrior Magic to build your Magic Cap package, the Telescript source file will be compiled by ObjectMaker and its code will be associated with the appropriate class and method.
You'll probably create your Magic Cap package's Telescript source file by writing and debugging Telescript code with the Telescript Developer Kit, then using that kit's htm tool to convert the Telescript source code to a form that can be used by CodeWarrior Magic.
When you define any agents or other classes in your communicating application that must exist both on the Magic Cap platform and in the Telescript network, you must make sure the class definitions are present at both ends - the class definitions will not be sent along with the classes. In particular, your application will probably create agents in Magic Cap that will be transmitted to the Telescript network and execute there.
When your communicating application creates an agent in Magic Cap and sends it to the Telescript network, that particular object is encoded and sent, but its class definition is not sent. This limitation is expected to be removed in the future, but must be dealt with in Magic Cap 1.0.
In order for a sent object to function when it reaches the Telescript network, the object's class definition must be available in the network. When your application creates and sends its own custom agent classes, the agent's class definition must be available in the Telescript service so that the service can execute the agent's live method when the agent arrives.
In order for the agent to function correctly, its definition in Magic Cap must match its definition in the Telescript network. Specifically, the following elements of the class definition must match:
The usual strategy for ensuring that class definitions are identical is to create them in Telescript, then use the htm tool provided in the Telescript Developer Kit to convert the definitions to Magic Cap form. By using this tool to automate the conversion, you minimize the possibility of translation errors, which can be hard to debug.
Magic Cap and Telescript use different capitalization conventions for method names. Magic Cap method names are always capitalized, while Telescript method names are never capitalized. When you define a Telescript method in your Magic Cap package, you should capitalize its name when you use it on the Magic Cap platform, but never on the Telescript network.
Remember that some Telescript methods must be defined and executed in both the Magic Cap and Telescript environments. When you define these Telescript methods, you should observe the following rules:
The htm tool follows these naming conventions by assuming initial lower case for methods running in Telescript and capitalization for methods running under Magic Cap.
You can see examples of these method conventions in the sample code that appears later in this chapter.
When you send an agent on a trip from one place to another, the agent refers to a ticket that defines the trip by identifying the agent's destination. When you create an agent and prepare to send it on its trip, you'll also create an accompanying ticket that the agent refers to.
Telescript defines address cards to represent entities available in the network. Every Magic Cap name card includes an address card to provide information about its entity. The address card includes a list of facilities, which are features provided by the address card's entity, such as registration or directory lookup. Address cards provide the FacilityTicket operation for creating a ticket to that facility.
In addition to the destination, tickets also indicate the way that the agent will get to the destination. The way includes an authenticator, which defines the security that will be used to communicate with the destination, and a means, which specifies the physical connection to be used, such as wireline modem, wireless modem, local area network, and so on.
Once the agent is created and ticketed, you can send it by calling the Telescript electronic mail client's EnqueueAgent operation in Magic Cap. For more information on name cards and Telescript address cards, see this book's Name Cards chapter.
You create an agent in Magic Cap just as you would any other object, by calling NewTransient or a similar operation. When you create a new agent, its live operation is not executed. Instead, you'll usually create an agent, ticket it for its destination, then call the post office to ask an electronic mail client to handle it. When the post office sends the agent, it calls the agent's live operation, which includes a Telescript go call that sends the agent on its trip.
This following example, which creates and sends an agent from Magic Cap to the Telescript network, demonstrate many of the concepts described so far in this chapter:
ObjectID agent, ticket, means, serviceProvider; // Create an agent, an instance of our // application's own agent class. agent = NewTransient(CustomAgent_, nil); // Make the agent's ticket and assign it // to the agent, and also get the service's address // card as the function result. The MakeCustomTicket // method is shown and discussed below. serviceProvider = MakeCustomTicket(agent); // Now we must get the ticket and the means, because the // call to EnqueueAgent requires them. // First, get the ticket. Although we previously // created the ticket by calling MakeCustomTicket, // we don't have a reference to it handy, so we get // it from the agent. ticket = Destination(agent); // Then, get the ticket's way by calling WayOut. // Finally, get the means from the way. means = Means(WayOut(ticket)); // The agent is made and ticketed, and the ticket is // all filled out. Now we're ready to ask the Telescript // service client to send the agent to the network. // Calling EnqueueAgent will put the agent in the out box // and ask the post office to handle it when appropriate. // The parameters are as follows: // iTelescriptService The electronic mail service // object that will handle // sending the agent. You should // always use iTelescriptService. // agent The agent to be sent. // serviceProvider Address card for the service. // ticket The ticket for the trip. // means How the connection will be // made (modem, radio, etc.). EnqueueAgent(iTelescriptService, agent, serviceProvider, ticket, means); }
The MakeCustomTicket method creates a ticket for the agent's trip, as shown above. The rest of this section shows the code for MakeCustomTicket. The first part of this method actually creates the ticket object and points it at the desired facility in the network.
Method ObjectID
CustomAgent_MakeCustomTicket(ObjectID self)
{
ObjectID ticket;
ObjectID customFacilityName;
ObjectID way;
ObjectID serviceProvider;
// The ticket directs the agent to a particular facility's
// place in the network. To start making the ticket,
// we'll make a text object with the facility's name -
// in this case, the facility is called "NewsUpdate")
customFacilityName = LiteralToText(self,"NewsUpdate") ;
// Next, we'll create the ticket object by calling the
// FacilityTicket method of our application's address card.
// Calling FacilityTicket requires that we have a reference
// to our package's provider address card. This reference
// is made via package indexical. For information on
// package indexicals, see this book's Software Packages
// chapter.
ticket = FacilityTicket(iOurAddressCard, customFacilityName);
// The next step is to get the address card for the
// Telescript service provider; that is, the entity that
// operates the Telescript network. We'll need this for
// several purposes later.
// We can get the service provider by calling HostingService
// on the ticket.
serviceProvider = HostingService(ticket,nil);
// Next, we ensure that the user is registered with the
// service provider that hosts our application's
// service. We do this by calling the address card's
// MakeReadyToCommunicate operation. This operation
// checks to see if the user is registered with the
// given service provider. If not, Magic Cap asks the
// user to take the next step in registering.
if(!MakeReadyToCommunicate (DirectID(iCurrentUser), serviceProvider))
return nil;
// When the agent goes on its trip, Magic Cap destroys
// the objects that the agent took with it. But we got
// the ticket from the address card, and it
// would be bad to destroy it -- it wouldn't be
// available for the next agent.
//
// To avoid having Magic Cap destroy the original ticket
// we'll make a copy of the ticket.
ticket = CopyNear(ticket, self);
// Next, we'll set up the ticket's way, which indicates
// what hardware will be used for the connection
// when the agent goes on its trip. The address card's
// PreferredWay operation provides the way. As with
// the ticket, we'll copy the way and use the copy
// to prevent the original way from being destroyed when
// the agent goes.
way = CopyNear(PreferredWay(serviceProvider), ticket);
// Now that we have the way, we'll set the ticket to use
// that way.
SetWayOut(ticket, way);
// We finish getting the agent ready for its trip
// by setting its destination to the ticket we've
// created.
SetDestination(self, ticket);
// This operation returns the address card of the
// service provider, which the caller will use
// when it calls EnqueueAgent.
return serviceProvider;
}
Following is the agent's live method as specified in High Telescript. This code is skeletal and incomplete. It is only presented here to give you a rough idea of what a live method does as it moves from place to place.
live: sponsored magiccap op(cause: Exception|Nil) = {
stub: TicketStub;
// When the enqueued agent gets its turn, the
// Magic Cap post office calls the agent's live
// operation, and this method is executed.
// The first thing the live method does is
// call Telescript's go operation, which sends
// agent on its trip to the network.
stub = self.go(self.destination);
// Now the agent is running in the network. // The next lines of code would perform the
// agent's task in the network.
// At some point, the agent may be ready to
// return. You could program this to take place
// immediately, at some future time, or in
// response to some future event.
// To send the agent back, we'll create a
// ticket in another operation (not shown),
// then start the trip by calling go.
self.destination = *.makeReturnTicket(stub);
self.go(self.destination);
// Once back, the agent should call an operation
// of its place to report that it has returned.
here@MCPlace.agentHasReturned();
};
When you send an agent on a trip from Magic Cap, the connection that sends the agent usually terminates after the agent is sent. However, if you expect one or more agents to return immediately, you can ask Magic Cap to keep the connection open until the specified number of agents returns. To do this, override the agent's ExpectedIncoming operation to reflect the expected number of returning agents.
If you override ExpectedIncoming, Magic Cap will wait for the number of seconds specified by the agent's MaximumWait operation. By default, this operation waits up to 10 minutes for the returning agent. If you want to change the maximum waiting time, you can override MaximumWait in your agent subclass to return the maximum number of seconds to wait.
Magic Cap defines class AgentCard as a subclass of telecard that sends agents to a Telescript network. Because agent cards are telecards, they provide a familiar and convenient user interface for agent communication. You can set your agent cards to use any class of agent, including your own custom classes.
When the user touches the send button or puts the card in the out box, Magic Cap handles the card by calling its GetOrMakeAgent operation, which creates an agent and its ticket, then enqueues the agent for its trip.
When you use agent cards in your communicating application, you should declare several related objects in your instance definition file:
You'll probably create your own custom subclass of agent card to use in your application. In your agent card subclass, you can override PrepareAgent to perform any action you want on the agent card before Magic Cap sends it. If you want to perform an action just as the agent is about to be created, you can override its GetOrMakeAgent operation.
You can override IsReadyToSend to perform some verifying action on the card before sending it, such as confirming that it contains the appropriate data or that the user is properly registered with the service.
You should declare an object of class SpecialAgentForm to use as the agent card's form in its view hierarchy. If each card sends only one class of agent, you should set the special agent form's agentClass field to the class of agent you want the agent card to create. If each card can send more than one class of agent, you should override the card's GetOrMakeAgent operation to create the agent as appropriate.
This agent class can be a standard one defined by a Telescript library, such as a download data agent, upload data agent, or standard courier, or it can be a custom agent class defined by your application.
To use agent cards in your communicating application, you'll specify a stationery object in your instance definition file. You should set the stationery's card field to refer to an instance of the agent card class you want it to use.
When you send objects from Magic Cap to a Telescript service, you must ensure that the objects' classes are defined in the service as well as in Magic Cap. Many of Telescript's classes are also defined in Magic Cap, including Telescript's built-in classes as well as classes in common Telescript libraries, such as the Telescript Application Library and the Magicmail Framework.
If you want to send objects of a class not supported by Telescript, including any subclass defined by your communicating application, you should begin by defining the class in Telescript. Then, use the htm tool in the Telescript Developer Kit to translate the class to its corresponding Magic Cap syntax. You should examine the output of the htm tool to determine if any changes or corrections are necessary. You can also add attributes to get and set any fields in the Magic Cap class definition.
You should avoid sending objects of unknown classes to the Telescript network. If the network receives an object of an unknown class, or a class with a definition that doesn't match its own version of that class, the object will be frozen. A frozen object can be sent to other places, but its data can't be accessed and its operations can't be called. A frozen object can be thawed if its definition is available at another place in the network.
To send objects of your subclasses to the Telescript network and ensure that they are not frozen when they arrive, you should specify the class in Telescript, as described above, and also override the class's CloudKnowsClass operation to return true. This informs Magic Cap that the network has the class's definition and so the object should be sent as an object of its class, rather than a frozen object. If you fail to override CloudKnowsClass to return true, the object will be sent frozen even if its class definition is available in the Telescript network.
The Telescript network and the Magic Cap platform each define various Telescript places that can receive agents. This section briefly describes the standard places built into the Telescript network and Magic Cap.
The Telescript network includes the engine place, which is an all-encompassing place that represents the engine itself. Other places occupy the engine place. The directory place provides a service that allows users to look up subscriber information. The broadcast place lets you send information to a large number of subscribers at once, after obtaining permission from the network operator. The Internet portal place provides services for exchanging electronic mail with Internet addresses. The registration place is used when a new subscriber registers for the service.
In addition to these built-in places, your communicating application will probably provide its own application places in the Telescript network. You can direct your agents to your application places or to standard places to perform their action.
The directory place, Internet portal place, and registration place are defined by the Magicmail Framework. The broadcast place is defined by the Publishing Application Library.
As described earlier in this chapter, Magic Cap includes two built-in Telescript places. The in box place receives agents bearing telecards from the Telescript network and corresponds to the Magic Cap in box that users see. The customization place hosts agents that prepare custom rules (also known as customizations) for the user's mailbox in the service, such as auto-forward and auto-delete rules.
As with Telescript places, your communicating application can add custom places to Magic Cap. You can then route your agents to these custom places on Magic Cap platforms.
This section briefly describes a typical communicating application by listing the files that contain the application's source code, describing the process for creating the parts of the application, and how those parts are handled in order to install the application.
One part of the application is designed to run on the Magic Cap platform. The Magic Cap part typically consists of these files:
The Magic Cap part of the application is built with CodeWarrior Magic like any other package. The build process results in a standard Magic Cap package, which can be placed on a PC card, mailed, beamed, or transferred with a personal computer link product.
The other part of the application runs in the Telescript network. This part typically includes the following files:
The network part of the application is built with the make tool and the Telescript Developer Kit. The build process results in compiled Telescript programs which can be submitted to the network using the procedures described in the Telescript Developer Kit.
For more information, see these topics in Magic Cap Class and Method Reference and in the documentation provided with the Telescript Developer Kit:
class Agent
operations and attributes:
Destination ExpectedIncoming Go MaximumWait
class AgentCard
operations and attributes:
GetOrMakeAgent IsReadyToSend PrepareAgent
class SpecialAgentForm
fields:
agentClass
class Place
operations and attributes:
Live
class AddressCard
operations and attributes:
FacilityTicket HostingService
class TelescriptService
operations and attributes:
EnqueueAgent
class Ticket
operations and attributes:
WayOut
Book Contents Previous Chapter Next Chapter