# Chapter 14

# Further Use of Internet Lingo

CONTENTS

- Multiple Operations
  - Identifying an Operation
  - GetLatestNetID()
- Targeting Frames with GoToNetPage
- External Parameters
  - Specifying the Parameters in the Embed Tag
  - Accessing the External Parameters
  - Valid Parameter Names
- Storing User Preferences
- Putting a Message in the Status Bar
- More Information about Network Operations
  - NetError()
  - NetMIME()
  - NetLastModDate()
- From Here…

The previous chapter introduced the main functions of Shockwave network Lingo. You learned how to navigate between movies and pages, how to retrieve text files from the Internet, and how to preload files to the user's cache. This chapter continues with those same functions, but expands them with a few additional commands.

- `GetLatestNetID` gives you a number to associate with a network operation. This allows you to perform more than one operation at a time.
- An additional parameter can target frames from a `GoToNetPage` command.
- External parameters can be passed to the movie from the embed tag.
- `SetPref` and `Getpref`-storing text information by writing to a file on the viewer's system.
- Use the `NetStatus` command to add a message to the browser status bar.
- `NetError()`, `NetMIME()`, and `NetLastModDate()` return more information about a recent network operation.

## Multiple Operations

Shockwave allows you to initiate up to four network operations at one time. Obviously, this is not used for `GoToNetPage` or `GoToNetMovie` because you can't look at four pages or four movies at the same time. But for `GetNetText` or `PreloadNetThing`, you may want to do multiple operations: four text files to load, four graphic images to preload, and so on. When one of the four operations is finished, you have a free "spot" to perform another operation, so you can continually perform network commands; however, no more than four can be initiated at once.

Note
Even though you can initiate four operations at one time, this doesn't mean they will all occur simultaneously. Only one file can be downloaded at a time, and it will be going as fast as possible given the speed of the connection. Initiating four commands may just be simpler for you to do than initiating one at a time.

### Identifying an Operation

Every time you issue a network command-`GetNetText` or `PreloadNetThing`-the operation is given a unique identifier. Fortunately, it's not a cryptic twelve-digit code number; instead, it starts at 1 and progresses up. Your first command is 1, your second command is 2, and so on. The number is reset to zero only when a new movie starts.

Remember those parentheses after `NetDone` and `NetTextResult`? Earlier examples left them empty. What goes into the parentheses is the identifying number for the operation. If you leave the parentheses empty, Shockwave assumes you are interested in the latest command, so if you are performing only one operation, you won't need a number. But if you are loading four text files, you need to be able to access all four, not just the last one.

By putting the identifier into those parentheses, you can access any of the last four operations. Suppose that you have initiated four `GetNetText` commands and you want to find out when they are all completed. You could use the following Lingo to check each one:

>     on exitframe
>      if netdone(1)=true then put nettextresult(1) into field "textone"
>      if netdone(2)=true then put nettextresult(2) into field "texttwo"
>      if netdone(3)=true then put nettextresult(3) into field "textthree"
>      if netdone(4)=true then put nettextresult(4) into field "textfour"
>     go to the frame
>     end

In the preceding example, if the particular operation is finished, the results are put into four different text fields. Note that the frame will continually loop, even after all four operations are finished, so you need a button that can jump to another part of the movie.

Caution
Remember, each operation has a unique identifier. The previous Lingo example will work only once! Any operations after the first four will have higher ID numbers, so your next four commands issued will have identifiers of 5, 6, 7, and 8. You'll soon learn how to determine the latest ID number by using `GetLatestNetID`. Also note that information for network operations will be discarded when new operations are started. Only the last four operations remain in memory, so when six operations have been completed, only ID numbers 3, 4, 5, and 6 will be able to return information.

### GetLatestNetID()

You may decide to keep track of the operation identifiers yourself, perhaps by using a global variable that you set to increment with every network command. But a better way to keep track of the current operation number is to use the `GetLatestNetID()` function.

Note
You will notice that there are parentheses after the `GetLatestNetID()` command, but the command doesn't take a parameter because it always returns the last operation number. The parentheses are necessary for Shockwave to understand that it's a network command, but it ignores anything you put into them.

Suppose that I want to set a local variable, x, equal to the last operation number. Then I want to check to see if the last operation is finished. Perhaps this is put into a handler named "checkdone" that I call periodically from another part of the movie. It could look like this:

>     on checkdone
>        set x=getlatestnetid()
>        if netdone(x) then put nettextresult(x) into field "results"
>     end checkdone

The preceding example isn't really useful because I could have just used `netdone()` with nothing in the parentheses to check the latest operation. But maybe you have issued four operations and want to check the last four. Instead of using specific numbers, you can use a variable. Your handler might look like this:

>     on checkdone
>        set x=getlatestnetid()
>           if netdone(x) then put nettextresult(x) into field "fourth"
>     if netdone(x-1) then put nettextresult(x-1) into field "third"
>      if netdone(x-2) then put nettextresult(x-2) into field "second"
>      if netdone(x-3) then put nettextresult(x-3) into field "first"
>      end checkdone

This is a bit more complex. If the last operation ID is 12, then the four statements will check using 12 (x), 11 (x-1), 10 (x-2), and 9 (x-3). If each is done, it will put the results into four separate text fields. This same handler could then be used no matter what the latest ID number is.

Note
You use only two commands in multiple operations: `GetNetText` and `PreloadNetThing`. They work slightly differently. When `PreloadNetThing` is finished downloading, you can issue another preload command immediately. But `GetNetText` requires that you use the `NetTextResult()` command before it releases its "spot" for a new operation. So if you issue four `GetNetText` commands but don't retrieve the text using `NetTextResult`, your four operations are still considered active. By issuing another `GetNetText` command, you will cause the latest ID number to increase; however, the operation will not occur. Therefore, you will have unretrieved information in ID locations 1, 2, 3, and 4, and your latest ID number will be 5. This can throw off your Lingo scripts and can be confusing. Be sure you use `NetTextResult` to retrieve the text information and allow a new operation.

## Targeting Frames with GoToNetPage

Certain browsers that allow separate scrollable windows on the same page use frames. You may have incorporated into your Web page design frames that you want to use with Shockwave's`GoToNetPage` command.

`GoToNetPage "url"` will leave your current page and load a new one. But with an extra parameter, you can target one particular frame on the page. So, your Shockwave movie could stay in one frame, while `GoToNetPage` switches the URL of another frame. Here is the syntax:

>     gotonetpage "http://www.server.com/page.html", framename

Let's look at an example from the CD-ROM. In Netscape or another frames-capable browser, load framed.html. In the left frame, there is an embedded Shockwave movie with three options. When you choose one, it causes a new HTML page to load into the right frame. The Shockwave movie stays in the left frame without changing. This is very useful for navigation movies so that you always have certain options in one frame, and the Web page content can change in a different frame.

Figure 14.1 shows the framed HTML document. You can see that we have named our two frames "left" and "right."

Figure 14.1 : The HTML setting up our framed page.

The movie is embedded into the HTML document called "left.html" that is put into the frame called "left."

In Director, we set up three buttons with Lingo scripts to call a new HTML page in the right frame. The second button, for example, looks like this:

>     on mouseup
>        gotonetpage "two.html", "right"
>     end

This button will load the HTML document called "two.html" and it will target the frame named "right." Our movie continues to run because the HTML document in the left frame has not changed. Figure 14.2 shows this example in the browser.

Figure 14.2 : Targeting a different frame using `GoTo NetPage`.

Note
Targeting frames with `GoToNetPage` is only recognized by the Shockwave version 5 plug-in. The version 4 plug-in will ignore the target and load the new page in the same frame that the movie is playing in.

## External Parameters

External parameters are strings of information that are passed to the Shockwave movie from the embed tag in the HTML document. External parameters were not an original feature of Shockwave, but are a valuable addition.

How are they used? Let's say you have a movie that uses the `GoToNetPage` command to switch Web pages. When you created the movie, your Web page to be loaded was named page2.html so you wrote the Lingo command as `GoToNetPage` "page2.html." However, you later changed your mind and renamed the HTML document for the second page to be newp2.html. Your Shockwave movie now does not work because the Lingo script uses the wrong file name for the new Web page. You have to go back into Director, change the Lingo command, save and Afterburn the movie, then upload the new version to your server.

Using external parameters, you can avoid problems like this that result from changing information. The solution to the above example would include an external parameter that is specified in the embed tag of the HTML document. You would pass a string to the movie that names the second Web page. Lingo reads the external parameter, knows what the name of the page is, and consequently puts the name into a variable used in the `GoToNetPage` command. By changing the name in the embed tag, the same Lingo script always uses the correct file name in the `GoToNetPage` command.

### Specifying the Parameters in the Embed Tag

External parameters are listed just like the file name, height, width, and other information about the movie. For example, to use an external parameter named "sw1" that contains a string of information, you could use the following embed statement in your HTML document:

>     <embed src="movie.dcr" height=250 width=125 sw1="External
>      information goes here.">

The information contained in the sw1 parameter could then be used within the Shockwave movie. Perhaps you want to put it into a variable or display it in a text field. The next section describes the Lingo used to retrieve the information.

### Accessing the External Parameters

To access an external parameter in the movie, use the Lingo command `externalParamValue(n)`, where `n` is the name of the parameter. Continuing the example from above, the following Lingo handler would put the value of parameter sw1 into a text field named "mywords."

>     on getx
>        put externalParamValue("sw1") into field "mywords"
>     end

In the `externalParamValue(n)` statement, `n` could also be an integer instead of a string. As an integer, it returns the value associated with the nth parameter. So `externalParamValue(3)` would return the value of the third parameter.

#### Determining the Name of a Parameter

If you're not sure what parameters the embed tag uses, you can determine the name of a particular parameter by using another Lingo command: `externalParamName(n)`. So the following statement would put the name of the fifth parameter into a variable called "name5":

>     set name5=externalParamName(5)

If the embed tag had a fifth parameter called "swText," the above Lingo statement would set the variable "name5" equal to the string "swText."

#### Counting the Total Number of Parameters

To find out how many total parameters the embed tag contains, use the Lingo `externalParamCount()`. The parentheses are needed, though nothing is put in them. The following Lingo statement would set a variable called "ptotal" equal to the total number of parameters in the embed tag:

>     Set ptotal=externalParamCount()

### Valid Parameter Names

Macromedia has issued a list of possible parameter names that you may use. These are simply suggestions for useful parameters. You can make up any name for a parameter as long as it does not have another purpose (the "src" parameter for example). Here is the list Macromedia provides:

> swURL
> swText
> swForeColor
> swBackColor
> swFrame
> swColor
> swName
> swPassword
> swBanner
> swSound
> swVolume
> swPreloadTime
> swAudio
> swList
> sw1
> sw2
> sw3
> sw4
> sw5
> sw6
> sw7
> sw8
> sw9

Note
The above parameter names are merely names. You can pass any value you want using those parameters. If you want to use the swVolume parameter name to pass the URL of a Web page, that choice is up to you. The names were created by Macromedia to easily correspond to information you might be using.

You can use as many of the above parameters as you like. A possible embed tag could look like this:

>     <embed src="movie.dcr" height=300 width=400 swURL="http://www
>      pdgroup.com/" swName="audio.sw1" swText="A really great song." sw1="85" sw4="1">

Chapter 18, "Shockwave for Audio," uses external parameters in an example that plays streaming audio files. External parameters are ideal for situations where the same Shockwave movie could be used on different Web pages but performs differently-such as using the same movie to play different audio files depending on what Web page the user is viewing.

## Storing User Preferences

This is quite a powerful feature of Shockwave. Macromedia calls it storing "preferences," but it's basically just writing a text file to the user's hard disk. It's useful for storing information that can be retrieved by a different Shockwave movie or the same movie after the user has left and returned to the Web page. You could store information that the user enters the first time he or she loads the movie, then simply load that information automatically for subsequent visits to the Web page.

Note
The text file is not written to the Web server, it's written to the user's computer. You can never be sure how long it will remain there and it is always placed in the prefs folder within the Shockwave plug-in directory.

Two Lingo commands are used, one to store the information and one to retrieve it. To store the info use:

>     setpref filename, value

The file name is recommended by Macromedia to be eight characters or less. It can have the extension .txt and will automatically be given that extension if none is specified. For example, if I wanted to store the phrase "I like snakes" in a file named "reptile" I could use the following Lingo:

>     setPref "reptile", "I like snakes"

The above statement would create a text file named reptile.txt and place it in a directory named prefs within the Shockwave plug-in folder of their browser.

To retrieve the file name, use the Lingo `getpref(prefname)`. To retrieve the example from above and put it into a text field, you could use:

>     put getpref("reptile.txt") into field "presults"

On the CD-ROM, load pref.html to see an example of how this works. If it is the first time loading the Shockwave movie (prefs.dir), it will ask you a few questions. The responses will be stored in a text file within the plug-ins folder. When the movie is loaded again later, it will retrieve the file and display a message showing the information. Figures 14.3 and 14.4 show the two possible options of the sample movie.

Figure 14.3 : Questions are asked the first time the movie is played.

Figure 14.4 : At any later time when the movie is loaded, the text file retrieves the stored information.

## Putting a Message in the Status Bar

The `netStatus` command is a simple Lingo function that puts a single line of text into the status bar at the bottom of the browser window. The syntax is:

>     netstatus msg

For example, to display "This site is Shocked!" in the status bar, you could use the following script:

>     on exitframe
>        netstatus "This site is Shocked!"
>     end

Currently, this function does not work with Internet Explorer, though it may change in future versions.

## More Information about Network Operations

You can use three other commands to retrieve information about recent operations. These commands probably will not be used as often as `NetDone()` or `NetTextResult()` but may be useful in certain cases. On the CD-ROM, load GetNet.dir or GetNet.dcr to see some of these commands used. Of course, it won't run from Director, but you can see how it is set up. You can load the HTML document, Getnet.html, to view the Shockwave movie also.

Getnet.dir is the same as the gethttp.dir file from chapter 16, but it not only loads a text file (or HTML source file), it also displays the ID number, date, error, and done state of each operation (see figure 14.5).

Figure 14.5 : A simple Shockwave movie using various network Lingo commands.

### NetError()

`NetError()` allows you to check whether an operation was successful or not. There are several different responses you can receive from this command as seen in table 14.1.

Table 14.1 NetError() Responses

NetError Response | Meaning
None | No operation has been started.
OK | Operation completed successfully.
(nothing) | Operation is not finished yet.
Error | Particular error is identified if the operation fails.

The syntax is just like `NetDone()`. The following Lingo handler puts the error response into a field called "`error`."

>     On checkerror
>        put neterror() into field "error"
>     end checkerror

You could also specify a parameter in the parentheses to identify one of the four last operation ID numbers.

Note
You may be expecting an error message if a file is not found on the server. However, many servers send a message that says something like "file [file name] could not be found on the server…" This is sent as an HTML document, so your `GetNetText` command will receive this and think it is the text that you requested. `NetError()` will return "OK" thinking the file was loaded properly. But when you use `NetTextResult` to view the results, you will see the HTML code for the message "`<body>The file could not be found…`"and so on.

### NetMIME()

The `NetMIME()` function is used to identify the MIME type of a recent operation. MIME stands for Multipurpose Internet Mail Extension. Every file type has its own extension: Graphics can be .GIF or .JPEG, Shockwave files can be .DCR or .DIR, text might be .TXT, and so on. The server and browser need to know how to view or use each MIME type. So for Shockwave, any file that has the extension .DCR or .DIR has the MIME type of "Application X / Director."

You may wish to check with Macromedia on using this function. At the time this book was published, `NetMIME` continually reported "`Application X / Director`" as a MIME type for any operation, whether it was loading a Shockwave file or another file type. This could be a bug, or it could simply be reporting the MIME type of the movie that is playing, which will always be "Application X / Director."

### NetLastModDate()

Each file on the server has a date and time attached to it when it was last modified. By using `NetLastModDate()`, you can view the last modified time of a file used in a recent network operation.

For example, if you were loading a text file using `GetNetText` that contained information that changed daily, you could have the Shockwave movie display the date and time that the text file was updated so users would know how recent the information is.

The syntax follows the same pattern as `NetDone()`, `NetError`, and the others. An identifier can be put in the parentheses or left out for the most recent operation. To put the date into a global variable called "lastdate," you could use the following script:

>     On exitframe
>        global lastdate
>        set lastdate=netlastmoddate()
>     end

As an example, the returned value put into the variable, "lastdate" could be "Tue, Jun 25, 1996 6:31:44 PM GMT." GMT means the time was converted to Greenwich Mean Time.

## From Here…

You have now learned how to use multiple operations, external parameters, and several other Internet Lingo functions. Be sure to watch for updates and new information about Shockwave development on Macromedia's Web site (http://www.macromedia.com).

- Chapter 18, "Shockwave for Audio": The basics of using Shockwave Audio.
- Chapter 19, "Shockwave for Authorware": Learn all about Authorware versus Director.
- Chapter 20, "Shockwave for Freehand": Find out about using high-quality vector graphics on your Web Pages.