The Graphic Counter Language - Frequently Asked Questions

Is GCL a compiler or an interpreter? It is both. When you run it, the compiler rewrites the source code with the new value of the counter, and with any modifications you have appended to it. Then the interpreter creates the graphic counter.

What if someone calls my web site while the compiler is running? Will I lose count? No. GCL never loses count because it locks the source file while it is processing it.

Will file locking not slow my server down? No. The compiler is the first thing that is run, and it is very fast. Once the compiler is finished working, GCL unlocks the file. That means the counter for your next web user may be processed while the interpreter is running for the previous one. Of course, if you have a million people calling at the same time, you need a fast server anyway. :-)

What is an “active” counter? Once you use a GCL counter on a web page, it is considered “active.” You should never modify an active counter with a text editor. Why? Because in the time you do your editing hundreds of users may have accessed your web page. When you are done editing, you will set the counter back to the value it had just before you started editing.

How do I modify an active counter? GCL has a built-in mechanism which makes it easy to modify an active counter without using a text editor. All you need to do is append the modifications to the active counter.

You can append to the counter in one of two ways:

How many layers does GCL use? Internally, GCL works with three layers:

• The Counter Layer is the top layer. It contains the digits, the commas, the head and the tail of the counter;
• The Background Layer is in the middle. It contains the background graphic if one is defined;
• The Frame Layer is at the bottom. It cosists of the frame and the tile graphic if you define one.

GCL will combine all layers before sending the image out as a GIF graphic.

How do I use an array graphic? Simply combine all your graphic elements into a single graphic file. Suppose you create it in the gd format and name it array.gd. You will add the following line to your source file:

Do all digits have to be of the same size? No, they can all be of different sizes, they can use different color palettes (but remember, GIF only allows for 256 colors altogether), and they can be in different file formats.

What if my graphics combine to more than 256 colors? GCL will use the first 256 colors (including the invisible one, if you make the result transparent). It will use the closest match for the rest. This is done separately for each layer.

How does it combine colors of layers? Again, if there are more than 256 colors, GCL will use the first 256, then match the rest. You can control the order in which this happens with the optimize keyword.

How does optimization work? Without the use of the optimize keyword (default), GCL will first copy the frame layer to the output, then the background layer, and finally the counter layer. That means the colors of the frame layer have top priority, while the colors of the counter layer have least priority. This is probably not what you want.

If you use the optimize keyword, the colors of the counter layer have the highest priority, and the colors of the frame layer have the least priority. The result looks much better.

It works by first copying the counter layer to the output, then the bakground layer, then the frame layer. This, unfortunately, hides the background and counter layers. Therefore, the background layer is copied again, then the counter layer. It optimizes the quality of the image sacrificing some speed.

How do I add a background graphic? Use the #$ keyword. For example, if your background graphic is bkg.gif, and it is located in /usr/pix, add the following line to your source code:

What if I do not want the background centered? You can shift the counter up or down, and left or right, for a specified number of pixels. For example, the counter to the left contains this line:

Why do I need to choose the transparent color if it is invisible? Because GIF files require it. It has nothing to do with GCL.

How do I show the counter without increasing the count? Use the -i or the -n command line option. The -i option “inhibits” the counter. That means the compiler will write a new version of your source file using the same count as before. The -n option (“no compile”) takes it one step further: No compilation takes place with this option. This option is generally preferable since it is faster. Please remember to use a question mark to separate the command line from the program name when used as a CGI program. For example:

How do I use a counter to count and display the results of a poll or survey? Use the same counter for both. When you are displaying the results of the poll, use it with the -i or -n option. When you are accepting input from the poll, use the counter without the option.

For example, if you are taking a poll with people answering either yes or no, you could create two counters, yes.gcl and no.gcl (with appropriate background graphics, of course!). On your main poll page, show both using the -n option. This will tell viewers how many people have voted yes, and how many no (even showing a zero if no one voted).

Can I force the counter to show a specific number? Yes, simply place the number on the command line. Usually, you will probably also want to use the -n or -i switch to prevent the counter from increasing its count. Note that you can combine any command line options that start with a dash. Let's suppose we want to use the marble.gcl counter from our tutorial to display the number 7, showing three digits (i.e., 007), and not increase the count. We need the -3 switch to show three digits, the -n switch to prevent compilation (which prevents the counter from increasing) and a 7 option to show the number seven. We can combine the first two switches, and do something like:

How do I change the count from the command line?

How do I change the count safely? By telneting to your account and appending count = followed by a number. For example, to change the count of cheat.gcl to 10000, enter:

Can I create counter based on a time period? Yes. Use the reset keyword followed by one of the following: daily, weekly, monthly, yearly, or annualy. Note that you need version 2.00 or later for this to work. Also note that yearly and annualy are two ways of doing the same thing. There is only one l in annualy, which is a mistake I made. In version 2.10 it will be changed to annually. That version will also accept annualy and correct it automatically.

But my counter always stays at zero! You need to set your file permissions to let everyone read from, write to, and execute, your counter. If your counter is in counter.gcl, enter:

Could you summarize how the GCL software works? It follows these steps:

How do I control caching? RFC 2068 allows CGI programs (and web servers) to send out expiration information to the browser, which tells the browser to cache or not to cache whatever we send to it. By default, GCL tells the browser its GIF output expires “now.” In other words, the expiration date and time is set to current date and time.

You can change this default by using the expires keyword followed by the number of seconds from “now.”

Suppose you add the following line to your source code:

Can I use GCL to provide a remote counter service? Yes. The counter does not have to run on the same system as the web page it counts.

What’s in a GCL cookie? Anything you put there. GCL compiler will simply copy your cookie to the new source file. Other than that, GCL will not touch it, nor use it in any way. To create a cookie, place the cookie keyword in your source file, follow it by an equal sign (=) and a quoted string. For example:

What is a valid quoted string? In GCL, a quoted string starts and ends with a double-quote character ("), not to be confused with the opening and closing double quotes (“”). It consists of a single line of text up to 1023 characters long (if this is not enough for you, change the definition of LBSIZE in gcl.h to one more than you need, and recompile).

Characters may be escaped with a backslash (\) if necessary. Generally, the only two characters that must be escaped are the double quote and the backslash itself. Escaped characters count as one character as far as the maximum length of the string goes. If your editor does not let you enter the entire string on one line, you can end the line with a backslash, and continue on the next line, or even several lines below: Whenever GCL lexical analyzer (called by GCL parser) encounters a backslash followed by one or more newline characters, it skips to the first non-newline. Finally, any tab is converted to a single space.

The GCL compiler will always put the quoted string on one line even if you originaly used backslashes to spread it over several lines.

Note to C programmers: Unlike in C, there are no special characters in GCL. A backslash followed by a character simply means that the character comes next in the string. So, for example, \n is the same as n, it does not denote a newline character!

How do I use redirection? By using the redirect keyword (you need GCL 2.00) followed by the desired URL in double quotes. For example, suppose your web site contains a link to www.somedomain.com and you want to know how many of your users clicked through to that link. Create a GCL counter, let’s say somedomain.gcl containing the following line:

How does GCL handle errors in my code? As gracefully as it can. That means it will use defaults whenever possible, and it will generally not complain unless you ask it to. The reason for it is that GCL is designed to work with CGI. If GCL simply quit when it encounters an error, the user’s browser would be waiting for data that never comes. Nor can it send out an error page to the user because its output is a graphic, not an HTML page. I suppose it could create a graphic stating something like “Tell the webmaster to fix his counter,” but why tell your users something is wrong with your code? You will see that the output is not right.

A related reason works for the not complaining part. When running on the web, typically there is no one there to see error messages. Your web server can of course redirect error messages to a log. But many major web hosts do not let their customers see the logs. If you run your own web server and have access to error logs, you can use several command line switches to override GCL’s shyness:

The -w switch turns on warnings.

The -d switch turns on the debugging mode which makes GCL work like a Starfleet Officer constantly muttering what it is about to do.

The -v switch will display the progam version and copyright information.

The -e switch tells GCL compiler to place extra information (comments) in the source file it creates.

Generally, you will not want to use these switches (especially -e and -d) because they slow everything down. However, -w only produces warnings when there is something wrong. So, if you have access to your logs, you may want to append this switch at the end of the first line of the source file, like this:

How do I compile my own defaults into the executable? You need version 2.10 to do this:

Create a source file containing any defaults you want: graphic files, kerning, shifts, alignment, etc.

Run it with the -k command line switch. For example, if you use defaults.gcl:

Why are you giving it away? Well, I have been programming, off and on, since 1965. I have seen the trends. Proprietary software comes and goes. It tends to develop slowly, be full of bugs, stagnate progress, and eventually die. Its motivation is economic gain, not technological advance.

Shareware? Been there, done that. People take it for granted, very few pay for it. It usually leads to a total programmer burnout.

Free software without the source code? Tends to be better. The programmer really does not expect to get paid for it, so his motivation tends toward technological advance. Or in some cases ego boost, but the result seems the be the same. :-) Unfortunately, when the programmer dies, so does the program.

Open source has historically helped move technology forward. The Internet would not exist without it, at least not at the grand scale we see these days. Many open-source programs have been around for decades. That, in computer history terms, is infinity! And when the original programmer dies, or is disabled, or loses interest, or whatever, someone else will take over.

The only way to achieve true technological progress seems to be giving the source code away, and letting anyone use it for free, without imposing limitations.

Secondly, I am a very independent-minded person. I will certainly listen to suggestions about the program, but I do not want to have a boss (that includes paying customers) telling me what to do and what not to do. I hope you can see the difference.

Having grown up in a Communist country, I value freedom above food. This way I am free to write software any way I want. You are free to use it any way you want. You are also free to donate any resources if you wish, and only if you wish. I will gladly accept any donations, again, as long as I can stay free—that is to say, as long as there are no strings attached.