The Graphic Counter Language - Frequently Asked Questions
This is a work in progress. I realize a program, no matter how powerful, will do only as much for you as you know how to use it. That is why I am trying to take a break from programming occasionally, and add to this FAQ.
Luckily, the beauty of GCL is in being a programming language. That means even if you have not mastered all nuances of the language, you can still put it to a good use, and learn more later.
Is GCL a compiler or an interpreter?
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:
GCL will combine all layers before sending the image out as a GIF graphic.
How do I add digits to the counter? You need a separate graphic file for each digit in version 1.00 of GCL (in version 2.00 you can combine them in one file, called array graphic, and in version 2.10 you can compile your own defaults directly into the binary executable). They need to be in the GIF, Xbm, or GD format. You then add them to your GCL program by using the #0 - #9 keywords followed by the file path and name, followed by either gif, xbm, or gd. The file path and name should be in double quotes unless they contain nothing but alphabetic characters. For more information, see page 2 of the Introductory Tutorial.
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:
Now you need to tell GCL which part of the array graphic represents which digit, comma, etc. You will use the same commands as you do when listing individual graphic files, i.e., #0 for digit 0, etc. But instead of listing the file name, you will list an array of the following values:
Note that the upper left corner is at coordinates (0, 0). You need to place the array values in brackets ([ ]), and separate them by commas (,).
I have created a sample, called g.gcl which uses an array graphic in g.gd. You can download g.gcl.tar.gz and study it yourself. This is how it declares all of its graphic elements:
So, for example, the image for the dash (#-) starts at x = 182, y = 12. It is 11 pixels wide and 2 pixels high.
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.Why is optimization not the default? It is based on the assumption that in most cases counters will be created from graphics which do not combine to more than 256 colors. Optimization adds some overhead, which means it slows the interpreter somewhat. It has no influence on the speed of the compiler. How do I add a comma? See page 3 of the tutorial. How do I align and kern the digits, commas, and everything else? See page 3 of the tutorial.
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:
The background graphic will appear centered behind your counter.
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:
Because of that, the digits appear 24 pixels above the center of the background.
How do I determine the background color? Use the bkg keyword followed by the red, green, and blue, components (0 - 255). For example to have a white background, use:
This is the default.Can I make the background transparent? Yes, if you are not using a frame. Use the trans keyword. You also determine the color of the transparency by using the invis keyword followed by the red, green, and blue, components. This color should be different from any color used in your source graphics, and from the background color specified above. Otherwise, any pixel that uses that color would be transparent. The default is:
I have chosen this default as an unlikely color to appear in a graphic, but you can change it to any color you want.
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.
What is head and tail? They are graphics that appear to the left and to the right of the counter respectively. Or, in a vertical counter, they appear above and below the counter. For example, the abacus counter to your left uses the head and tail keywords for its frame. For more information, see page 5 of the Introductory Tutorial.
How do I create a vertical counter? By using the vertical keyword. See page 6 of the tutorial.
How do I count visitors without showing the counter? Create a transparent counter without declaring any GIF digits. It will “display” a one-pixel transparent counter. You can read the counter value by viewing the source file at the command line or in an editor, or by writing a program for that purpose. As of version 2.00 of GCL, you can also view the counter by running it in text mode.
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).
Ask them to click on the yes counter to vote yes, and on the no counter to vote no. Create two separate links, one for the people who voted yes, one for the people who voted no. On the yes link display yes.gcl without the -n option, but use the option on no.gcl. On the no page do the opposite.
Can I force the counter to show a minimum number of digits? Yes, you can do it in several ways. First of all, you can use the mindigits keyword followed by a number. For example, mindigits 4 will always display at least four digits, left padding with zeros as necessary. You can choose any number between 1 - 63 (of course using 1 does nothing since the counter is always at least one digit wide). If 63 is not enough, change the value of MAXDIGITS in gcl.h and recompile.
Secondly, you can use a command line override. This is, however, limited to 1 - 9 digits. Place a dash immediately followed by a digit on the command line. For example, if your counter is counter.gcl and you want it to display at least seven digits, the appropriate command line is counter.gcl -7. Of course, if you are listing it in an HTML page, you must use the proper way of passing command line parameters to a CGI program (see my CGI tutorial for details). Anyway, in this case, you would use the following HTML code (assuming your URL is www.mysite.com and your counter is in cgi-bin directory of your site:
The question mark is what you use to separate the program name from its command line.
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:
(You will remember from the CGI tutorial that individual command line parameters of a CGI program must be separated by plusses, not by spaces.) See the result on the left.
Copyright © 1999 G. Adam Stanislav
How do I change the count from the command line?Are you sure you want to be able to do that? Remember, anyone can enter the URL of your counter and a command line to their browser location bar! That means that if you can change the count via URL, so can anyone else. Nevertheless, it’s your counter, and if you still think it is a good idea to be able to change the count via URL, append secure none to your source file. Assuming your counter is in unsafe.gcl, you can do it by using this Unix command:
By default, GCL operates each counter in a secure mode, unless you explicitly turn it off. Now that you have turned security off, calling your counter with a number on the command line will change the count to that number. Note this is the same command line option we used above with a secure counter to display a specific number without setting the count to it.
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:
Note that in version 2.00 you can add or subtract a constant to/from the current count by appending commands such as count += 10000, count -= 100, count++, and count--.
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:
from your Unix command line.
Can I use GCL to display current time or date? Yes, as of version 2.00. Detailed description is on a separate page.
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:
This tells the browser to cache the GIF for 1800 seconds, or 30 minutes. Thus, in theory, if someone comes to your page, leaves, and returns within 30 minutes, he will not rerun your counter, and thus will not increase the count for the second time. I said in theory because if the browser ignores the expiration date and time, there is nothing anyone can do about it. But most modern browsers follow the rules of RFC 2068.
Note that you can use a negative value with the expires keyword. Also, if you use a value greater than the number of seconds in a year (31536000), GCL parser will chop it down accordingly to conform with RFC 2068 which states that no document should expire later than one year from the time it is being sent to the browser.
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.
As a matter of fact, GCL is perfectly suited for remote counters. For example, you can use a suitable background graphic to advertise your business on such a remote counter. You may also use the cookie keyword to keep track of whatever information you need (e.g., the name and email address of the client).
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:
You can have anything in the cookie as long as it is a valid quoted string. You can use your own software to read and write the cookie any way you need. Note that this is not an HTTP cookie. It is not saved on caller’s system but in your own GCL source code.
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:
Then use HTML code like this to send your users there:
Each time your users click on that link two things will happen:
You can easily check the count by calling somedomain.gcl with the -r (no redirection) command line option. Unless you choose uninhibited redirection, this will automatically inhibit the counter (i.e., the count will not increase when viewed). If your web site is at www.mydomain.com and somedomain.gcl is in its cgi-bin directory, you can view the count by entering the following in your browser location bar (or in a link in a private page):
This is very useful for tracking various associate programs you participate in, among other things.
What is unihibited redirection? Uninhibited redirection works just like regular redirection with one exception: When you view the counter using the -r command line switch, the count will be increased by one. You can still override that by using the -i switch.
To instruct GCL redirection should be uninhibited, add an exclamation point (!) after the string with the URL. Note that the exclamation point must be past the closing double quote. Example:
Can my GCL counter perform statistical analysis? Your GCL counter can do anything. While you cannot write your statistical analyzer directly in GCL, you can write a separate program and have your counter fork it in the background. This is based on Unix philosophy of having a separate program for each different task. It also offers unlimited flexibility: Rather than me deciding what kind of statistics you should get, you can create a statistical analysis program geared toward your specific needs.
Incidentally, if you write a statistical analysis program for GCL, or any program to be forked by GCL, and make it available for people on the web, let me know. I will be glad to create a directory for GCL extension programs.
How do I fork a script? Starting with version 2.00, you can fork an external script or program from within your counter. Use the fork keyword followed by a quoted string which contains the script name and command line parameters, if any.
Let’s suppose you have written a Perl script for statistical analysis of your web site visitors, and named it stats.pl Let’s further suppose you want to run it with -a -b -c command line parameters from within your counter. You would add this line to your GCL program:
This is quite a realistic scenario because GCL will pass some information to the script through the use of environment variables.
Note that the forked script or program will run in the background (as a separate process) and will, therefore, not slow down the creation of your counter output.
What environment variables does the forked script receive? The forked script will have available all environment variables that GCL received from the system. That includes your standard environment and any CGI environment variables passed to it by the web server.
Additionally, GCL will pass the following environment variables:
The above environment variables will always be available to your forked script. The rest may or may not be there as follows:
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:
Note that a warning is most likely to happen only once. After GCL compiler has rewritten the source code, it will contain no errors. (If it does, there is a bug in GCL, and I want to hear from you! My email address is at the beginning of gcl.c and at the bottom of the home page.)
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:
This will produce your own version of files gcldefaults.h and gcldefaults.c (it will rename their old version to gcldefaults.h.old and gcldefaults.c.old). Make sure the new files are in the same directory with the rest of your source code, then run make. This will build a new, customized, version of the gcl executable.
Install the new executable in /usr/bin (or wherever you want to install it).
Create a test source file, e.g. test.gcl, with only one line of code:
Now run a local test with the debug switch, like this:
Voilà, you have a custom gif which gcl created without having to read ten gif files!
Of course, you can always override your defaults by explicitly listing new values in your source files.
And if you want to create a counter which does not contain a default graphic, list that graphic as nodefault. For example, if you have created a default background graphic, but want to create a counter without it, enter the following in your source file:
Your counter will now contain all the default graphics, except the default background.
Note that using default graphics speeds everything up considerably, and saves on your disk wear and tear. It is of particular use to web sites with very high traffic.
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.GCL is not for me. What other counters are there? There are many counter programs available. Take a look at www.pageresource.com/counters.htm for a list.
I want to consult my astrologer about this. Just when and where were you born? Whatever. I was born 1950-04-23T00:30+01 in Bratislava. If you cannot interpret that, read ISO 8601.