Server Commands

Server commands are one way to communicate with PopChart Server. They can be included in the query string of an HTTP request to PopChart Server, or in a separate server command file.

Server Command Format

All server commands begin with the characters @_. They are also all capitalized. Examples of server commands include @_FILE, @_PCSCRIPT, and @_GIF.

Each server command takes either zero or one arguments. If a command takes an argument, the argument should immediately follow the command. The argument should not be in parentheses, nor should there be a space or any other character between the command and the argument.

For example, the @_FILE server command takes one argument, a file name. If the filename is apfles/graph1.pcxml, the full server command with the argument would be:

Server Command Strings

Server commands are issued to PopChart Server via a server command string. The server command string consists of any number of server commands, all joined together in one long and unbroken line. In a URL or HTTP request, each command should follow the previous without any sort of interruption (i.e. no semi-colon, period, space, line-break, etc.). In a server command file, white space is not a problem. For example, if we wanted to issue the commands @_FLASH, @_SAVEimage1.swf, @_DONTCACHE, and @_PWpass, we could use the following command string:

Common Server Commands

The following is a list of common server commands. For a complete server command reference, refer to Chapter 6, "Server Commands," in the PopChart Server Reference manual.

Command	Purpose

@_FILEapfile	Specifies an appearance file.
@_FLASH	Specifies that the image format should be FLASH.
@_GIF	Specifies that the image format should be GIF.
@_HEIGHTheight	Specifies a height for the generated image.
@_LOADPCXMLfile	Instructs PopChart Server to load the specified PopChart XML file.
@_LOADREQUESTfile	Instructs PopChart Server to load the specified server command file.
@_PCSCRIPTpcscript	Specifies a PCScript command string.
@_SVG	Specifies that the image format should be SVG.
@_WIDTHwidth	Specifies a width for the generated image.

URL Encoding

Only alphanumerical [0-9, a-z, A-Z] characters, special characters such as $-_.,!*'(), and reserved characters used for their reserved purposes may be used unencoded within a URL. This means that if your HTTP request includes any of the following characters: ; / ? : @ = & space < > # % { } | \ ^ ~ [ ] `, it may not work properly.

Many of these characters are commonly included in the PCScript section of your server command string. To overcome this obstacle, you should make it a habit to URL encode your pcscript statements. When you do this, non-permissible characters are translated to permissible character sequences (e.g. %20 for the space character) so that the HTTP request remains valid. When PopChart Server receives the request, it will decode your server command string.

Note: If you are not yet familiar with PCScript, you should probably read "PopChart Script Review" in Chapter 7. PCScript is a very important aspect of dynamically generated PopChart images, especially when you don't have access to the PopChart Embedder.

Important: PopChart Embedder automatically URL Encodes your PCScript. You do not need to worry about URL Encoding with the PopChart Embedder.

You can URL encode your PCScript by hand, or you can pass it through a JavaScript function that will do this automatically for you. We recommend the latter.

Example 11.1 URL Encode Function

function urlEncode(str) {

var ms = "%25#23 20?3F<3c>3E{7B}7D[5B]5D|7C^5E~7E`60"

var msi = 0

var i,c,rs,ts

while (msi < ms.length)

{

c = ms.charAt(msi)

rs = ms.substring(++msi, msi +2)

msi += 2

i = 0

while (true)

{

i = str.indexOf(c, i)

if (i == -1) break

ts = str.substring(0, i)

str = ts + "%" + rs + str.substring(++i, str.length)

}

return str

}

</script>

If you were to include this function in the header of your HTML file, you could encode your PCScript by passing it through the urlEncode() function before attaching it to your server command string. Example 11.2 shows how you could do this.

Example 11.2 URL Encoding the PCScript

var pcscript = "Graph.Categories(Group 1, Group 2, Group 3)"

pcscript += "Graph.SetSeries(Item 1;54;75;85)"

pcscript += "Graph.SetSeries(Item 2;92;60;70)"

pcscript += "Graph.SetSeries(Item 3;69;87;37)"

document.write("<img src='http://www.yourserver.com:port/?")

document.write("@_GIF@_FILEapfiles/Untitled@_PCSCRIPT")

document.writeln(urlEncode(pcscript) + "'>")

</script>

Note: This embeds the HTTP Request in an image tag, a process that is discussed in the next section.