SharedInfoServer

The Shared Info Server (SIS) is a service that provides a simple object database model designed to contain dynamic, ephemeral information. The server informs interested clients of changes to database values for which they previously registered. SIS provides a unique platform for prototyping awareness and other groupware applications on the Macintosh by providing easy-to-use push technology for both AppleScript and Java clients.

SharedInfoServer will run on any Macintosh or MacOS computer with a 68020 or better or a PowerPC processor. Use MacOS 7.6.1 or MacOS 8. SharedInfoServer needs sixteen megabytes of RAM. The application file is fat and runs on either 680x0 or PowerPC microprocessors.

Administrator's Guide

SIS is designed to run on a Macintosh designated for use as a server. While it is possible to run both the SIS and some of its clients on the same machine, you may experience timing-related problems with TCP/IP-based clients. Our current server is an 8150/110 with 40MB of RAM running MacOS7.6.1. We leave Virtual Memory turned off, in an attempt to prevent hard disk corruption in case of system crashes.

Launching SIS

You can launch the SharedInfoServer application by double-clicking on the application itself, or by opening one of its documents. If you launch the application directly, it will refuse to perform any operations until you open or create a database.

Our strategy has been to put an alias to our SIS document in the Startup Items folder in the system folder, so that SIS will start running whenever the machine restarts or powers up.

SIS Windows

When SIS first starts running, it immediately opens its log window. You will notice that the log window has some plotting irregularities, but it is reliable, and can serve as a valuable source of debugging information.

Upon opening or creating a database, SIS will perform several consistency checks on the database, and then attempt to establish TCP/IP communication. When TCP/IP connectivity is established, two additional windows will appear.

The Server Status Window shows statistics about TCP/IP communication -- how many connections to SIS have been established since the server started running, how many were rejected because the server was too busy, how many can be serviced at once. A separate section of the window provides statistics about "Persistent Connections," which are used to communicate with Java applets operating within the confines of the Java Applet Security Manager.

The Threads Window shows the status of all the running threads within SIS except the main application thread. You will see a new thread spawned for each incoming AppleTalk or TCP/IP request, and a new thread for each outgoing communication as well (multiple messages to the same client in a short amount of time can reuse the same TCP/IP connection). Each line of the display gives information about a single thread -- its name, the time its status was last updated, its current status (i. e., Running, Blocked, Suspended), and a short description of its current task. While most of this information is useful only for debugging the server, you may find it useful.

SIS Debugging Menu and Log File

When SIS launches it creates a file called "SharedInfoServer log" on your desktop. The SIS Logging Menu allows you to control how much information appears in the log window and whether that information is copied to the log file. There are several options on the menu, all of which may be toggled by selecting them with the mouse:

• Debug - The Debug flag is used to display messages pertinent to debugging the server. If you find a serious problem with SIS, please try to turn on Debug messages and save them to a log file -- it may be very useful in finding and fixing the problem.
• Information - The Information flag is used to display non-essential information about the server's operation, such as when TCP/IP connections time out. It is probably only useful for debugging the server, or when you need to see every detail about which records are being written to the database.
• Warning - The Warning flag is used to display non-fatal error messages about the SIS.
• Error - The Error flag displays error messages that SIS encounters during its operation. Most of them are prefixed by the C++ class that encountered the problem, many include a numeric error code or error string. The error codes are documented elsewhere. You should probably leave this flag turned on so you can confirm that the server is operating normally.
• Exception - The Exception flag reroutes low level Alert and Signal messages from PowerPlant to the log window. This includes a mix of both Exceptions that SIS is designed to accommodate and Exceptions that represent genuine error situations. You will probably not need to turn this flag on.

SharedInfoServer TCP/IP Protocol

The actual protocol used to send AppleEvents over a TCP/IP connection is very simple and is defined by the following grammar. Note that TCPDescList (an AEList) and TCPRecord (an AERecord) are recursive. While our goal in defining the protocol was to support communication between the Shared Information Server and Java, we believe that the protocol should be complete enough to be

used almost anywhere that AppleEvents are used.

TCPAppleEvent:

AppleEvent Suite (4 bytes)
AppleEvent Code (4 bytes)
Number of parameters for event (4 bytes)
TCPParameter
...

TCPParameter:

Parameter Keyword (4 bytes)
TCPDescriptor &brkbar; TCPDescList &brkbar; TCPRecord

TCPDescriptor:

Descriptor Type (4 bytes)
Descriptor Size (4 bytes)
Descriptor Value ('Descriptor Size' bytes)

TCPDescList:

'list' (4 bytes)
Number of Elements (4 bytes)
TCPDescriptor &brkbar; TCPDescList &brkbar; TCPRecord
...

TCPRecord:

'reco' (4 bytes)
Number of Elements (4 bytes)
TCPParameter
...

Communication between SIS and any client over TCP/IP is simple:

1. A connection is established.
2. Repeat any number of times:
   1. Client sends an TCPAppleEvent.
   2. SIS sends an TCPAppleEvent as the reply.
3. Connection is destroyed.

Since establishing and destroying the connection can easily take as long as sending a short message, the client can keep the connection open for a period of time and send several messages to the server (this is different than the AppleEvent interface to SIS in which a connection is established and destroyed by the system for each AppleEvent). Since SIS can only support a limited number of connections at once, the client should disconnect from the server as soon as it's finished sending a batch of messages. The Java client classes can be set up to timeout and drop the connection after a user-definable

amount of time.

When a TCP/IP-based client registers interest in a particular entity/attribute, it must also include a port number as a parameter of the register TCPAppleEvent. When the given entity/attribute changes (or new entities/attributes are created), the server will attempt to establish a connection with a "server" on the given port number at the client's address. It will then send one or more TCPAppleEvents to the client and expect an TCPAppleEvent as a reply for each of them. The TCP/IP support in SIS leaves the connection open for a user-defined amount of time so that multiple entity/attribute/value changes can be sent to a client without the overhead of repeatedly opening/closing a connection.

The Descriptor Value can be any sequence of bytes and SIS is capable of storing any arbitrary block of bytes. The Java support classes are also capable of storing any arbitrary block of bytes -- for convenience, several data types are treated specially:

'TEXT'

a string value, supported by the Java class 'TCPDescString' and corresponding to the Java type 'String'. Since AppleEvents on the Macintosh don't support Unicode characters, this type currently ignores the upper byte on all of the unicode characters.

'long'

a four byte signed integer, supported by the Java class 'TCPDescInteger'

'doub'

an eight byte floating point number corresponding to the 'C and Java double type. Supported by the Java class TCPDescDouble.

'GifP'

a GIF encoded picture. Supported by the Java class AEDescImage and corresponding to the Java type Image.

'JPEG'

a JPEG encoded picture. Supported by the Java class AEDescImage and corresponding to the Java type Image.

SharedInfoServer Error Messages and Codes

These are the error codes and string used by the Shared Info Server and other C++ clients based on the same C++ sources.

Server-Only Errors

-24000 "No database attached"

The Shared Info Server has no currently open database, and thus cannot process incoming events

-24001 "Database has bad version number"

The Shared Info Server is trying to open a database whose format is too old or too new for this version of the Shared Info Server

-24002 "Database item not found"

The Shared Info Server was unable to find an Attribute or Reader client in its database

-24004 "Reader Application Invalid"

The Shared Info Server got an error while communicating with a Shared Info Client

-24005 "Another database is already open"

The Shared Info Server has a database open, and thus cannot open another database

-24007 "Redundant request ignored"

A Shared Info Client made a redundant request of the Shared Info Server, such as adding an Entity that is already present in the server

Client-Only Errors

-24003 "Server Application Invalid"

A Shared Info Client got an error while communicating with the Shared Info Server

General Errors

-24008 "Internal Error"

The Shared Info Server is experiencing difficulty and may need to be restarted

Related Articles

• Rapid Prototyping of Awareness Services using a Shared Information Server
• SharedInfoServer AppleEvent Suite

See Also

• Apple Advanced Technology Group
• Apple Computer