What are Tabriz AgentWare and Agent Tools?
AgentWare is general-purpose software that enables the creation and interaction of "processes" which are active, secure and persistant across the Internet, the World Wide Web and corporate intranets-processes that can be used to build a new, superior class of applications.
What do I need to have to use Tabriz?
Tabriz runs on the following platforms:
We recommend a minimum of 32MB of RAM for the Tabriz Agent Tools and 64 MB for operating Tabriz AgentWare, alone or with Tabriz AgentTools.
We recommend 200MB disk space for a full installation of the Tabriz Agent Tools including documentation, samples and demos, and 105MB for a minimum Tabriz AgentWare installation.
In addition, Tabriz software requires the following:
How do I get Tabriz?
To order Tabriz AgentWare or Tabriz Agent Tools you can:
NOTE: (If you're ordering free Tabriz software, please have a credit card handy to cover shipping and handling charges.)
Can I move Tabriz to a different location on the machine?
No. You must re-install Tabriz if you want it in a different location. It can't just be moved.
Where can I get sample code for Tabriz?
Samples can be obtained by logging in to General Magic's FreeAgent site.
I am experiencing Installation problems with Tabriz. What do I need to check to get this up and running?
You should verify the following:
NOTE: Please try to install from a normal user account. This account you install from does not need to match the web manager account.
NOTE: Although not specifically mentioned in the documentation, you need to have SOCKS available on the machine. Tabriz uses some of the SOCKS libraries even when talking to the machine Tabriz is installed on (itself). While the libraries for SOCKS need to be present on your system, SOCKS does not have to be running. This issue will be addressed in an upcoming release of the product.
SOCKS is available free of charge on the web if you don't already have it. For the latest socks libraries or more information on socks, connect to http://www.socks.nec.com. Exportable SOCKS S4
NOTE: Tabriz does some fancy footwork during installation that relies upon the host name information. It is not happy just using IP addresses like 10.1.33.22. So, somewhere in your network you need to have a DNS working to make the correct mappings.
There is a "-" in my domain name. Whenever I try to run
a sample application I receive an error in the eng.out log:
"String: <!! Cannot convert configuration file line to Telescript
objects: machinename_domain-name_or_country_TSToWebPort = 1603 !!>"
How can I avoid this problem?
Tabriz does not currently handle domain names with a "-" in them. This issue will be addressed in an upcoming release of the product.
I keep getting an error back from the server (500) when clicking on a hyperlink which maps to a clickable image, and the operation to handle the click (handleClick) never gets called. What is causing this?
There is no support inside the Tabriz for doing the coordinate-to-URL translation that's typically handled by cgi-bin programs such as imagemap (NCSA) and htimage (CERN).
If you have a clickable image where the hyperlink is
"/cgi-bin/telescript/ClickMap/operation/handleClick", the URL which gets sent to the server when you click on the image would be something like
"/cgi-bin/telescript/ClickMap/operation/handleClick?10,20" (where 10 is the x coordinate, and 20 is the y coordinate). The x/y coordinates are appended to the end of the URL and the webtots is not parsing the coordinates and sending them to Telescript correctly.
I tried to access a host and the browser hung/ timed out. What happened?
If you have an invalid host name in a string that is passed in to getHTML or getHTMLPage, such as "http://sigyy", the call to getHTML will time out if asked to parse a nonexistent page or inaccessable. You should verify that the host name and DNS entry are correct.
Developer's note: So that your application doesn't hang, you should put the getHTML/getHTMLPage operations inside a restrict clause which will force a timeout should this situation occur.
Can Tabriz retrieve VRML content?
Currently, Tabriz can only return content with the MIME type of "text/html" which means Tabriz cannot return VRML or some other type of content.
I can't seem to login with mainuserlogin. Why does this fail?
Currently, only lower-case letters and numbers are valid password characters. To change your password, rerun INSTALL (from webtools), and change your password to one with lower case letters and numbers.
I have an operation which requires a user to login before execution.
Can the user bypass security by changing the /login/ component to /cgi-bin/
?
The user can try to do this. It is up to your operation to validate whether or not the user has been authenticated.
To verify that the user has been authenticated, include the following in your code:
// see if user is really registered with Tabriz
ok:String|Nil=url.getCGIValue("IS_AUTHENTICATED");
if (ok != nil) && (ok == "YES") {
/* The user has logged in */
} else {
/* The user did not log in, so display an error message */
}
I keep receiving the message that my login name is invalid. What can I do?
Verify that your login name does NOT contain any embedded spaces, and or special characters. The current implementation does not handle spaces, reserved characters, and/or unsafe characters inside the login name and password.
What mechanism for Access controls is built-in in Tabriz ?
In Tabriz, you can use standard Telescript security/access control features (permits, etc.), or you can utilize login framework to build additional access control framework. The main idea would be to use the user's authority not only by agents (like it is done now), but also elsewhere in the application - that is up to the design.
Can I change my eMail address and password after registering on a Tabriz system (like freeagent)?
No. There is currently no way for you to alter your e-mail address once you have registered. You can, however, change is your password. Alternately, you can notify the administrator who can delete your account. You can then reregister with a different password.
I have just registered my Tabriz software with General Magic Support, can I change my eMail address and password?
Yes. You can send an eMail to csswebmaster@genmagic.com with the new information.
6)JAVA/ JAVA APPLETS
Can you include Java code in TELESCRIPT generated HTML page?
Yes. You can insert any string you'd like in a TELESCRIPT generated HTML page.
We also have some built-in support for Java - the HTMLApplet class, which uses the appropriate tags for Java applets. Also, Java UI can coexist with TELESCRIPT backend.
As far as a Java applet connecting to a Telescript application, the EAF can be used to do this. It is like setting up a socket connection between the agent and the TELESCRIPT application.
An example of a Java Applet running with Telescript is located on the General Magic Freeagent web site, to view it, select Java Example and Java Chat Example. To view the source files for the Java Example, select Java Example Source. To view the source files for the Java Chat Example, select Java Chat Telescript Source. To view additional sources for the Java Chat Example, select Java Chat Demo Sources
What is an asynchronous commit to a Telescript engine ?
A commit in this case means writing data to the database within an engine. Asynchronous commits utilize a new way to do engine database commits/updates. Instead of using the synchronous way (commits from the engine itself), there is now a separate external process called updater that does the database commit without involving the engine. Asynchronous commits can increase the engine duty cycle and reduce the duration of commits. This is only a strong benefit when commits are of long duration or when the system is under heavy load. This new mechanism is turned off by default.
What are the considerations before enabling asynchronous commit mode ?
The items to consider before enabling asynchronous commits include the available memory on the system and system performance.
For heavier loads on the system there is an improvement in performance, increasing with the load up to very heavy loads where the benefit is about 15%.
How do I enable asynchronous commits within Telescript?
Directions for enabling the asynchronous commit mode are located in the AgentWare Operator's Guide, which is a part of Tabriz Product Documentation (note: this document is in .pdf format) . Also, on page 62 of this document you can also find some suggestions on memory management under the asynchronous mode. You can also refer to webtools/release/cloud/logplace.cfg file for additional information and instructions.
I just cold booted and tstoweb is still running after a cold boot. How can I get rid of it?
Occasionally, Tstoweb is not restarted after a cold boot. You need to manually kill/restart tstoweb. You can kill/restart tstoweb by going to the "cloud status" panel in TDE (same goes for engine process, ezMail, httpd, etc.) and choosing the appropriate action.
I keep receiving "SessionConnectFailure" exceptions. What causes this?
One cause of this is the getHTML operation which can occasionally throw "SessionConnectFailure" exceptions when the OS runs out of sockets. When sockets become available again, getHTML/getHTMLPage will still throw this exception. To fix this you will need to restart tstoweb. You may also consider enabling more sockets through the OS if this occurs frequently. This problem may show up in a heavily loaded system.
The documentation for getHTMLPage says a nil is returned if an error occurs. This doesn't seem to happen. What is going on?
This is a rather confusing behavior of getHTMLPage. Currently, getHTMLPage returns an HTMLPage object that has an HTMLString as a child object that has the text of the error. In order to retrieve the error, you will have to parse the returned page to see if an error occurred.
How can I determine what port ID my debugger is running on?
There are a couple of ways to determine the debugger port number of your engine. You can look in cloud/region/ports.cfg. This will give you the MOCK_PORT values for all the engines.
You can look on the General Magic Web Page in Developer Services Area for the Backup and Restore Document .
The backup agent will go to each engine and backup the data.
Does Backup/Restore require stopping/suspending the engine? (Answers for the application backup and the whole site backup cases.)
You do not need to stop or suspend the engine to do either form of backup.
In the case of system backup, the engine is automatically quiescent during the backup. When the engine is quiesed, the CI thread will be stopped, therefore, no agent can be transferred into the engine. However, once the engine becomes available, the agent will be transferred into the engine. In other words, the agent sent in during a engine backup will be put on hold until the engine backup is completed. The backup is not an on-line backup process.
In the case of application backup, the engine needs not to be interrupted. However, the application should be written such that no data in the application place should be changed during the backup (so as to keep a consistent state database). This usually means that no agent can enter the place during backup, but in the case that the agent doesn't alter the data, it is up to the application to decide whether agent can come into the application place or not when it is backed up. It is possible that the browser is timed out when the agent is waiting for the engine backup. In such case, the user will get similar response when a web server is busy. Unfortunately, the agent will be transferred into the engine after backup, but there will be no way to return to the browser. Fortunately, this will not hurt the engine or application.
As a rule of thumb, the reason you would want to do application backup, though, is when the code for an application or for Tabriz itself is being updated. In this case, you would have to do the application backup, cold boot the engine to install the new code, and then do an application restore.
By using the "saveCheckpoint" operation provided by "ActiveWebCheckpointed " class, can we store ANY objects as "checkPointState" objects?
Yes. The saveCheckpoint operation once being executed, instantiates a CheckpointState Dictionary object for the object/data to be backed up, and then calls backupClassCheckpointData operation of the Checkpointable class. You can backup any object this way. Please note that when backing up more complicated object types than string, list, integer and Dictionary, you will need to back up its variables as a Dictionary [Identifier,Object,Equals]. Check General Magic's Developer Web site for
How do we restore/ recreate agents under Tabriz after executing a backup?
The backup mechanism for agents is the same as using the saveCheckpoint operation. In order to recreate agents, your implementation should store all the states of agents necessary for recreating it.
What happens to the applications processes when the application is being backed up?
When an application is being backed up, all the processes in the application are quiescent (the pending requests are NOT being killed/suspended; the application returns to them once it is back up -- the only bad thing that could happen is that the browser requests could time out).
My Checkpoint operation is failing silently. From the point of view of the WebManaged page interface, the operation appeared to complete normally. After selecting the backup option and giving a filename the engine then put up a page claiming that the data had been successfully saved to "xxxfile". The file does not exist. What happened?
The reason for the failure was that one of the objects which you were attempting to checkpoint was Nil. To correct this situation, you can check for Nil while in the backupClassCheckpointData() operation. The Checkpointing framework currently will fail ALL backups for a chosen place if it runs into a single Nil object.
What communication protocol does Tabriz use?
Tabriz communicates over TCP for general communication and for agent transport.
Is Magic going to support the Netscape Commerce Server for Tabriz ?
The only portion of the Netscape Commerce Server Tabriz does NOT support is the communication to an SSL server that does verification.
Therefore, if the verification level is turned up, then tstoweb will not be able to communicate with it (tstoweb does not support SSL, therefore it cannot provide the authentication information --loginname, password -- to the Netscape Commerce Server in such way that it accepts it).
However, you can set SSL verification level so that it does not do any verification (it still requires authentication, of course), and then tstoweb can still communicate to this server with no problems.
I am attempting to communicate with a C++ program using the External
Applications Framework.
I received a core dump on the computer (segment violation) when I use READ_TYPED_OBJECT()
as illustrated in the TDE Telescript Example.
What could be causing this?
This error comes from compiling against a set of our session/translation libraries that are not compatible with your toolset.
This crash is exactly what will happen if you are using the newer IRIX tools (4.x) with the libraries that shipped with Tabriz, which were compiled with IRIX 3.x tools.
You can always check our Developer Tools Website for additional sets of libraries that should work in this case.
According to the document "Tabriz AgentWare Operator's Guide",
the Multi-Engine environment requires a UNIX system running NFS in order
to make the cloud visible and accessible from other host machines.
Is NFS necessary only at the time of construction of the Multi-Engine environment
or is it necessary all the time?
It is required all the time, not just upon setup of the Multi-Engine environment.
How can I reduce the NFS traffic on my system?
To reduce NFS traffic, you want to put all the files belonging to an engine (or an application) on the same host where this engine (or application) resides. In this case, by the files belonging to engine or application, I mean engine configuration files, engine database, applications configuration files, application scripts, etc.
In fact, it is even recommended to do a Tabriz full install on every host that you are using in a multi-engine multi-host environment to reduce NFS traffic.
I am trying to use tstoweb, and it keeps timing out after 2 minutes. What's the problem?
This can be caused by a socks conflict.
The current tstoweb was compiled using a General Magic specific version of libsocks.a, set up for SOCKS 4.2.2 with gatekeep.genmagic.com acting as a DNS and SOCKS host.
Please note this is incompatible with SOCKS 4.1, SOCKS 5, and the new NEC SOCKS hardware, as well as with various non-SOCKS sorts of firewall.
In addition, if you do not have a properly configured socks.conf file and you have not set the SOCKS_SERVER and SOCKS_NS environment variables, then tstoweb will default to using gatekeep.genmagic.com as a SOCKS host and as a DNS server. Gatekeep will refuse accesses from outside our network, so this will fail from outside General Magic, and thus tstoweb will, and time it is used, wait 2 minutes and then time out.
You need to verify and edit the socks.conf file and change the SOCKS_SERVER and SOCKS_NS environment variables to reflect the appropriate gatekeep and DNS information.
This issue will be addressed in an upcoming Tabriz release.
How can Telescript programs can access entities which are outside the Tabriz engine?
The mechanism you are referring to is known as EAF, or the External Application Framework. With it, you do not have to setup any sockets yourself, that's handled by the EAF mechanism and the engine.
More information on it is in the Telescript Developer Libraries Reference.
You can basically set up your connection on a certain port, bind and send your TELESCRIPT object across. A method is then called on the C++ external process end which allows you to get at your object and act on it. If the connection was a "two-way" (as opposed to a one-way send only) the C++ process can return an object back to the TELESCRIPT process. All you need to have setup at both ends is the port and a knowledge of what the objects are that you will be transferring.
For more information on how to handle sockets and EAF look at the Java Chat Example. To view the Telescript source for the Java Chat Example, select Java Chat Telescript Source. To view additional sources for the Java Chat Example, select Java Chat Demo Sources . NOTE: These examples only show how to open a plain (text-only) sockets. These examples do not allow one to customize sending TS objects back and forth, only the raw octet data. You have to write a C++ external do get the benefits of EAF communications.
How can I move binary data through the cloud as an octet string without using ExternalHandle.receive()?
As far as using the sockets for communication, you should refer to the Java Chat Telescript Sources for hints. Additionally, you should look at the code used to set up the incoming way- it determines the format and is much easier to modify with than ExternalHandle.receive(). Generally, the data will come in as an octet already.
Use the following code to specify the inbound data type :
quoteWay = Way(Telename("service".asOctetString(), nil), TCPMeans(quoteHost,quotePort));
This will ensure the data is the format you are looking for without having to translate it later on.
Procedure ( << $proc do >> ) can, according to the Telescript Language Reference reference, return its contents asList, asString, and asOctetString. However, whenever I try to have it return it's data asOctetString() I get "feature unavailable". Why does this happen?
In general, when you do a $proc do, it returns its data in whatever form the procedure chooses to create it (which could be any valid Telescript data type). In the case of this special-mode use of EAF, it will always be an octet string, which you then may need to convert to whatever type you want. In this case, you are then trying to convert an octet string into an octet string. Since this is unnecessary (null operation), you will see the feature unavailable failure when calling asOctetString.
Procedure ( << $proc do >> ) can, according to the Telescript
Language Reference, return its contents asList, asString, and asOctetString.
However, whenever I try to have it return it's data asString() and subsequently
call asOctetString on it, I get "ConversionUnavailable".
Why does this happen?
In general, when you do a $proc do, it returns its data in whatever form the procedure chooses to create it (which could be any valid Telescript data type). In the case of this special-mode use of EAF, it will always be an octet string, which you then may need to convert to whatever type you want. In this case, the conversion is failing because some of the contents in the string are not directly convertible to octet string.
11)CERN and Sockets
Do I need CERN libraries and where can I get CERN libraries?
It depends on the application you are building. For some applications you build with the Tabriz AgentWare you may need to link against the CERN httpd library.
For those of you who don't have the whole CERN 3.0 release, we're providing the built libraries here for you. You will need to unzip the file, rename it to "libwww.a" and place it in $WDK/CERN/Library/[platform] or some other place in your link path.
For more information on CERN see their web site at http://www.w3. org/pub/WWW/Daemon/ .
While performing the "getHTML" operation, an error message appeared on the Web browser. The error message was "Error occurred in gateway: HTDoConnect(24)". What is the meaning of the error message ?
This is a networking related problem. HTDoConnect is a CERN library implementation function, defined in HTTCP.c; the error code 24 relates to a HTERR_NO_REMOTE_HOST error in HTError.h include file.
This problem would usually be related to a problem with the DNS server - either DNS server is unreachable, or DNS server cannot identify/connect to the host you specify.
So, the sequence of events is the following: Parse calls Webaccessing.getHTML (getHTMLPage), which calls tstoweb, which is trying to communicate with the external world using the CERN library functions it is linked with through libwww.a, and those (like HTDoConnect) go out to DNS server with the connection request. This happens even if the connection request is local. Remote host in this case means anything that is outside of the program.
You should verify the following:
How do I listen for inbound requests, handle socket connections, and call operations without tying up the thread?
One way to do it would be the following:
You have a place which has various operations that might be remotely requested. The place contains a server agent that listens for incoming connections; whenever it gets one it spawns a response agent, and hands the connection to the response agent, then goes back to listening. The response agent opens a socket on the connection, accepts input over the socket, makes here@MyPlace.operation() calls dependent upon the input, and returns output over the socket. When it's done it dies.
This gives you the following threads:
1) the place's live method, which is free to do anything it wishes (possibly serving webpages containing the client software?)
2) the server agent's live method, which blocks waiting for incoming connections
3) any number of response agents (as required), whose live methods are free to invoke methods belonging to the place. (They could also meet with each other or with the server agent and then invoke each other's methods, if required, or could register methods with some registry maintained by the place and then invoke each other's methods via that registry.)
You can also see the Java Socket Chat example for more information on how to make this work.
Are threads asynchronous in Tabriz/Telescript? (e.g. Is the calling method's thread is blocked waiting for the result of the called method, the end of the sponsored process, or can it keep going on asynchronously ?)
No, threads are synchronous and in this example, yes, the calling agent's thread is blocked until the sponsored operation returns.
Is there a way to get a free socket port in Telescript?
Yes. If you are connecting, the engine will allocate one for you. If you are listening, then typically some external process is trying to connect to you, so having the engine give you some random port is probably not very useful. Additionally, you can also select a port yourself, and then let the external process that is connecting know what the port is.
I have been receiving a WARNING: Unable to connect to host xxxx,
port xxxxx <WebSession::bind> failure when using the HelloAgent examples.
What does this mean, and what causes this?
HelloAgent is based on the InteractiveRequestAgent, which does not die, unless it is forced to die (if a certain parmeter which specifies if the process should continue is set to false). Therefore, if you have a number of HelloAgents running, each is taking up a socket connection. When the maximum allowed number of socket connections set in the kernel configuration parameters is exceeded, you cannot start anymore agents.
There are two ways to solve this problem:
1. Increase the maximum number of socket connections possible (this is set by kernel configurable parameter on IRIX and Solaris). NOTE: This operation is entirely system dependent. Please refer to your UNIX system manual for information on which parameter to modify and where it is located.
2. In the agent's code set the parameter to continue processing to false (the parameter is called "mycontinue"; in this case it should be set to false by HelloAgent, for instance).
Tabriz supports HTML version 2.0.
The eng#.out file keeps growing as the system is operating, is there a way to redirect its output to a separate directory so that my file system does not fill up?
Yes. To do this, before you start TDE, go into webtools/cloud/cloud.cld file and change the EngineOptions variable to -o filepath/filename; save the file, run TDE. Now you can look in cloud settings, and see that the options you specified have been read, and will be used once you start the cloud in TDE.
I deleted the eng#.out file and recreated a new one, but the TDE won't use it. Why?
As long as the engine is running, it holds the original file open. For
this reason, you should not delete the file while the engine is running.
You can safely delete it when the engine is down and generate a new one
at that time.You can also truncate the file rather than removing it.
Does the logging function provided by the class "WebManaged"
use EAF ?
No. The logging function provided by the class WebManaged is done with TestFile, which uses standard C file operation functions to open/read/write file on disk.
What are the files stored in the eng1 directory and what are they for?
One way to do this would be:
restrict Permit(process.age + timeout) {
...
str := *.getHTML(myURL);
...
}
My agent has visited a place and drops off some information which is stored in a list or Dictionary. Later, my place was performing a lookup on the collection, and it could not be found. What causes this?
This is caused by an ownership problem. The place in question does not having ownership of the piece of data which was entered into the collection. You need to make sure the place makes a copy of the collection inside of an owned block and stores it.
Can you send MIME (multimedia) mail via the Tabriz notification mechanism?
The "Tabriz notification mechanism" (ezMail Sample) is really a code sample - it was intended to show people how they could build their own notification mechanisms. While it can be extended or revised, Tabriz can only send data that is represented as a Telescript string. To do MIME, as well as digital signatures, you would need to write your own Mail handler within Telescript which includes handling for the for the common conventions for wrapping binary stuff in ASCII strings (such as uuencode) The ezMail consists of the Telescript part (ezMailMsg, ezMailSender classes),and the C++ part (the ezMail external process); both of which can be used as a beginning for writing this code.NOTE: The ezMail samples do not include the code to the ezmail external processf.
Can digital signature be embedded in the eMail and sent out by Telescript cloud transparently?
Yes. However, Tabriz can only send data that is represented as a Telescript string. To embed digital signatures, you would need to write your own Mail handler within Telescript which includes handling for digital signature.
Can Tabriz retrieve images from other web sites and store them locally?
Yes. You can retrieve web pages, images and all, from other web sites. However, the data is streamed back to the browser and is not written to disk. There is currently no method for saving images to disk from other web sites. We plan to address this in a future release.