What's New in Director 8.5 > Using the Shockwave Multiuser Server and Xtra > Creating multiuser movies > Error checking

 

Error checking

It is essential to check for errors in your multiuser movies. Latency and stalled connections are common network problems. Servers may be temporarily unavailable because of power failures or other physical malfunctions. Error checking will let you detect and fix problems so that the end-user experience is not affected.

Because most of the commands used with the Shockwave Multiuser Server and Xtra are dependent on one another, it is important to verify that each command used is successful before executing the next one. Many multiuser commands can produce both synchronous and asynchronous results. A synchronous result is one returned immediately by the Xtra, which indicates whether the Xtra was able to correctly execute the command with the parameters you provided. An error code of 0 indicates success.

An asynchronous result is one that may be returned after some operation takes place on the server, such as when your connectToNetServer request is accepted or declined. This error code is provided as part of the contents of an incoming message and should be checked in each of your message callback handlers.

The following Lingo script sets the variable errCode to the number returned by the Xtra as the immediate result of the connectToNetServer command. If one or more of the parameters you provide is unacceptable to the Xtra, it will return a nonzero result and trigger an alert.

global gMultiuserInstance
errCode = gMultiuserInstance.connectToNetServer( \
"chatserver.mycompany.com", 1626, [#userID: "Bob", #password: \
"MySecret", #movieID: "Tech Chat"])
if errCode <> 0 then
	alert "Problem with connectToNetServer" & RETURN & 	\
	gMultiuserInstance.getNetErrorString(errCode)
end if

To check the asynchronous results returned from commands as the #errorCode property of incoming messages, use a Lingo script such as the following:

on defaultMessageHandler newMessage
	global gMultiuserInstance
	member("messageOutput").text = string(newMessage)
	if newMessage.errorCode <> 0 then
		alert "Incoming message contained an error."
	end if
end

You should keep checking the error codes in the messages you receive so that you are aware when conditions change in ways that will affect your movie. For instance, other movies on the network may disconnect, or other events may prevent them from communicating efficiently with your movie. When you receive a message containing an error, use getNetErrorString to convert the numeric error code into a useful description of the error that occurred.

For example, this handler contains statements that place the string returned by getNetErrorString() into a field for the user to see:

on defaultMessageHandler newMessage
	global gMultiuserInstance
	errCode = newMessage.errorcode
	member("errorText").text = \
	gMultiuserInstance.getNetErrorString(errCode)
end