Configuration and Preferences
The configuration file consists of NAME=VALUE pairs. Entries are case-insensitive and free format, but are written in upper-case when Sybernet rewrites this file. Each entry occupies a single line.
Editing this file manually is not encouraged, but it is possible. Sybernet
will validate entries in this when it is loaded, and those entries that it
does not understand or agree with are ignored; for example, you could
incorrectly set HTMLLIMIT as follows:
Since HTMLLIMIT cannot be less than 32K when it
is non-zero, Sybernet will ignore this entry.
When the configuration file was different between the Mac and Unix, changes
or options to Sybernet were difficult to add. This common format now
eliminates this problem. The change was so successful, in fact, a lot of
internal "constants" have been removed from Sybernet and placed in this
configuration file. These are constants you may never need to change, but
now you have the ability to do so; for example, it is now possible to change
the Guest username and password, or you may wish to change the default idle
timelimit that disconnects users after they have been idle for too long.
SERVERS represents the number of Sybernet Servers
that are available to the Sybernet CGI.
It is not possible to tell you how many servers you will need. This is
dependent on how much traffic you expect as well as how efficient your
stored procedures are.
As of version 2.05, now that neither Solaris nor Linux are single threaded,
one server may be sufficient. You'll appreciate that at one time this was
not the case and having multiple servers was a convenient way to
distribute the load.
The minimum is 1; the maximum is 32; the default is 4.
SOCKETS determines the starting socket or port number.
Socket numbers are contiguous.
If you specify the default HTTP socket at port 80, you will
need to be root to start Sybernet. You will also want to specify a user and
group name that Sybernet runs from so that Sybernet does not run as root.
The minimum is 1; the maximum is 65536-SERVERS; the
default is 6666.
MEMORY determines that maximum kilobytes of memory
that a server can allocate.
Linux ignores this setting and it's probably my fault, but
the exact same code works fine under Solaris. Go figure!
There is a real difference in memory requirements in Client-Library between
a select on a tera-byte table and a while loop that does a select. The former
is very efficient because it results in one result set; the latter is not
because it results in several result sets. Each result set requires more
memory. This is Client-Library's doing, not mine.
Surprisingly enough, the Linux libraries return this memory after all result
sets have been processed so the MEMORY limit is not
as critical. On Solaris, however, this memory is not relinquished. My
suspicion is that this was designed this way and not a memory leak because
Client-Library will reuse this memory. Personally, I prefer the way it's
done on Linux.
Still, a stored procedure can generate so many result sets as to cause
your system to hang. And that is the purpose of this option. My experience
is that the procedure is at fault and any procedure that returned that much
data would have crashed the browser way before it ever ate up all your memory.
MEMORY is specified in kilobytes. If non-zero, the
minimum value allowed is 3,000 kilobytes. A value of zero means there is no
limit.
RESPONSE size is essentially the amount of data that
is buffered by Sybernet before it is sent to the web server. The default is
32K which has worked well. Lower values would cause Sybernet to stream output
results to the browser sooner giving the illusion of faster response times.
RESPONSE is specified in kilobytes.
The default is 32K.
POST size if the maximum size of any single post
request. Post requests occur when an HTML form
page is submitted with an action value of Post.
POST is specified in kilobytes.
The default is 32K.
STACKLIMIT represents the maximum number of simultaneous
forked processes a server can initiate. When this limit is reached, future
request are denied (not queued), so you'll want to specify a value that
makes sense. 1 or 2 does not make sense; something like 30 does.
Each child process spawned by Sybernet will show up in a Unix
Sybernet may be safely killed from the Unix command line using kill -QUIT pid,
where pid is the process ID of the main process. The QUIT signal will be caught by
Sybernet, and Sybernet will kill all of its children, disconnect every user, and
then terminate itself; for example,
If you kill the main Sybernet process without -QUIT, spawned processes are
not terminated and they will have to be terminated individually.
Specifying a value of 0 for this option essentially turns off the ability
to fork requests and requests will be single-threaded in each server. That is,
everyone waits their turn while someone else is executing a stored procedure.
It is possible for the Sybernet utility to report that the total active
time of a server is greater than the total elapsed time of that server. Hardly
likely, but is possible. Active time, however, still only reports the active
time while doing something in Sybase. Child processes waiting their turn are
not included in this calculation.
NOTE: Setting STACKLIMIT to the same
value as CLIENTLIMIT means Sybernet will not attempt to impose
any limits. This doesn't mean Unix won't, however.
The default is 10 (0 means requests are single-threaded).
Previously, this benign statement would hang you and all connections attached to this
server until it completed. Now, only you are affected by this statement.
Subsequent requests submitted by other users will continue normally. Subsequent
requests submitted by you are queued (up to a maximum of FRAMELIMIT)
while this statement runs.
FRAMELIMIT is a configurable value that can be changed with the
Sybernet utility. This value determines the maximum number of queued requests that
may be submitted to Sybernet. It's called FRAMELIMIT because
a stored procedure that creates frames will cause your browser to submit each frame
source asynchronously. Previously, this was not a problem because the server would
only do one request at a time. Now it is a problem because Sybernet only allocates
one handle per user connection and must therefore queue any requests for the same
connection. The question then arises how many simultaneous requests for the same
handle represents a problem? The answer is that this can't be conveniently determined.
FRAMELIMIT is currently set to 6. This means your stored procedure
can generate as many as 6 frames before connections are denied. In reality, you could
actually create more frames if Sybernet and Sybase are fast enough to keep up with these
requests. In the tests I've done (generating 4 frames at once), I've only seen 1 or 2
frame requests become queued.
When FRAMELIMIT is exceeded, a very unfriendly message is generated
by Sybernet. This message indicates that system resources have temporarily become
unavailable. This is the same message that is generated when Sybernet is forbidden
by Unix when it attempts to spawn another process. At the bottom of that message is
hyper-text link that will allow you to disconnect in case you are the culprit that
caused the problem. Clicking this link will terminate all active and queued requests
that you may have submitted and disconnect you from Sybase.
You don't have to wait to exceed FRAMELIMIT. If you submitted the
above example and wish to disconnect, simply click the Log Out button on
the menu bar or (if that is not available) submit a "quit" to Sybernet using a URL;
for example,
The default is 6.
This value defines the maximum number of simultaneously open connections. The total number
of connections allowed is this value times the number of servers.
Changing this value in any server is ignored if there are already open connections. To
be absolutely sure the change takes effect, make sure no connections are active or stop
the servers before submitting this change.
If you are running with AUTOSHUTDOWN set to TRUE,
the change will take effect the next time a server is initialized.
The default is 25 connections.
TIMELIMIT determines the number of minutes a connection
may remain idle before it is disconnected.
TIMELIMIT is specified in minutes. The default is
120 minutes. A value of zero means there is no limit.
This option determines the number of kilobytes that can be retrieved from a
Text or Image column. Sybase's default is 32K.
TEXTLIMIT is specified in kilobytes.
Sybernet's default is 100K.
HTMLLIMIT determines the maximum
number of bytes Sybernet can send to a client browser in any single request.
If this limit is exceeded, output to the client is stopped and a "gratuitous"
message is displayed indicating that this limit has been exceeded. Sybernet
does NOT terminate the result set, however. Instead,
the result set is completely processed and the total number of bytes is also
displayed.
Some browsers are better than others at handling large amounts of data. The
worst case is it dies--sometimes you even get a message--and takes your PC
with it. Setting a value here can prevent this problem.
HTMLLIMIT is specified in kilobytes. A value
of zero means unlimited output. A non-zero value must be greater than or equal
to 32K.
READTIMEOUT determines the maximum number of seconds Sybernet will
wait while reading from the browser.
READTIMEOUT is specified in seconds. The default is 60 seconds.
WRITETIMEOUT determines the maximum number of seconds Sybernet
will wait while writing to the browser. If you're running with
CTCANCEL turned on, this value is critical in determining what Sybernet
does when the user clicks the STOP button or when they
submit any request to Sybase while a stored procedure is running.
When CTCANCEL is TRUE, Sybernet will
cancel all result sets after this time out has expired and proceed to the
next request, if any. It's really a question of how long do you want to wait
after clicking the STOP button, but it isn't quite that
easy. You'll also want to specify a value that makes sense for your system
and for your users. If the value is too small, requests might be terminated
when you don't want them to be.
It is important to point out that just because you specify a small value for
this option, doesn't mean Sybernet is going to respond in that many seconds
every time you click the STOP button. This time out applies
only to writes to the browser. If your stored procedure is looping or otherwise
taking a long time and not creating any result sets for Sybernet to send, the
time out will not occur. Using the <SEND_PARTIAL> tag
will help with the latter, but probably won't help with the former, however.
WRITETIMEOUT is specified in seconds. The default is 10 seconds.
BACKLOG determines the maximum number of clients that can concurrently
wait for a connection to Sybernet.
Do not confuse this with the maximum number of simultaneous open connections that
are specified with CLIENTLIMIT. Instead, this parameter
defines the maximum length the queue of pending connections may grow to when
requests are made to the Sybernet application server.
The default is 16. Although a value of 0 is allowed, this is probably a bad idea.
Options/Send Partial determines if Sybernet will use
the Send Partial facility of WebSTAR. This option must be set if Sybernet
is an asynchronous CGI and reset if Sybernet is a synchronous CGI.
Forcing Sybernet to run as a synchronous CGI has its limitations. Any
context-type other than text/html greater than 32K will not be delivered
correctly. And the temporary file that is created when output exceeds
32K (and is unique for each client) is not removed!
Running Sybernet as a synchronous CGI is NOT
recommended.
This option causes Sybernet to terminate after all users have disconnected
from Sybase. On the Mac, TIMELIMIT is enforced
and Sybernet terminates automatically after all connections (idle or otherwise)
are closed. On Unix, TIMELIMIT is not enforced
unless the server is pinged (with the utility) or it receives a request
from the Sybernet.cgi.
Setting AUTOSHUTDOWN to TRUE
under Solaris might be a good way to relinquish memory since
Client-Library will not do this when a connection is closed.
I don't use the Thread Manager. The last time
I did, it worked fine except that GIFs appeared to be "broken." I think
this is a problem with WebSTAR so I haven't investigated it much. To see
the Thread Manager working, you'll want to turn on Monitor/ConnectionID.
This option should be checked if connections will
occur from behind a fire-wall. When checked, this option will append a unique
string to the end of all remote host addresses. This is necessary to uniquely
identify users having the same address. It uses NetScape cookies to do this
so you are limited to non-cookie challenged browsers if you want to use this option.
CTCANCEL allows Sybernet to issue a ct_cancel to
Sybase when the user clicks the STOP
button on their browser. This option is now set by default. Prior to
version 2.05 it was reset.
If you are running Sybernet through an Open Server, CTCANCEL
must not be set. When reset, Sybernet does not issue ct_cancel and
instead throws the result sets away itself. Depending upon your stored procedure,
this can take a long time. Also, the value for WRITETIMEOUT
(although not ignored) is meaningless because the result sets are manually
discarded.
If you are not using Open Server, you will want to set this option so that
result sets can be discarded immediately. In conjunction with the value for
WRITETIMEOUT, this option determines how Sybernet is going
to respond when the user clicks the STOP button.
Prior to version 2.05, Sybernet was not gracefully recovering after a call
to ct_cancel. This problem has been corrected.
Information about users connecting to and disconnecting from your Sybase
data server. By default, this is the only option that is set for
monitoring.
Open Client Errors. Open Client errors are always sent to the browser,
but this option allows you to send them to the log file.
Error messages and print statements from the Sybase server. Server
messages are always sent to the browser, but this option allows you
to send them to the log file.
Client Server messages. Client Server messages are always sent to
the browser, but this option allows you to send them to the log file.
Result set sent to client. This can generate a tremendous amount of output!
Post Request received from client. Actually, Sybernet will create two entries
in the sumlog file for this option. The first entry will be the entire post
request in its URI Encoded form. The second (and possibly subsequent) entries
are the post request after URI decoding.
Subsequent POST requests are possible when the original
post request is separated by GO's or you are
using FILTER=CGI and result sets are separated by
<GO>'s.
The direct argument or extra path information.
Arguments to URL after the (?). In a URL request (method="get"), these are the
parameters to your stored procedure and/or Sybernet reserved words.
Tells whether GET or POST
was specified. That is, a form screen is usually sent with
METHOD="POST" while URL requests are sent with
the GET method.
Name or IP address of the client.
This is the E-Mail address where these results should be sent.
EMAIL is valid only if
Sybercron is installed.
This is an obsolete option.
This is an obsolete option.
Name or IP address of your web server.
TCP/IP port number being used by your Web server.
This used to represent the URL name of script that invoked the stored procedure.
This value (if specified) is now the name of the disk file where the results
of your stored procedure are written.
Setting this option tracks the Script Name sent to Sybernet and the Script
Name that is set in a URL or POST request. For documents and scripts, you
will see script name change as Sybernet attempts to locate this file.
The URL of the page referencing this document.
The name and version of the WWW client software.
MIME Content type.
ConnectionID is used only by WebSTAR. This is a unique number
generated by WebSTAR so that it can keep track of its clients. CGI's must
cooperate by returning this value back to the server. Sybernet also uses this
value when running with the Thread Manager.
Type of formatting to perform on result set.
The Hostname of the Sybase data server. This value is normally specified
when a user is being connected to Sybase. It can be specified at anytime,
but doing so causes the current connection to be closed and a new connection
to be opened at the specified server.
Sybernet, by the way, is smart enough to detect the same username, password,
and hostname and will not disconnect and then reconnect the same user when
this is not necessary.
Database name requested. This option, when specified, causes an implicit
USE statement. While useful in some circumstances (such as changing the
database context in the Stored Procedure Editor), this can leave a user
in a database in something other than they might expect.
The actual process name of the Sybernet CGI. Technically, you can call
Sybernet anything you'd like, but why would you do so?
NetScape Cookies.
Type of filtering to perform on result set.
From address when E-Mail address is used.
Subject in mail message.
If you're running through SSL, this option will display user certificates.
SYBERNET is the name of the directory where the
Sybernet tar files were decompressed.
SYBASE is the full path and directory name of
your Sybase directory.
The default is "/sybase."
DSQUERY represents the default host name of your Sybase
SQL server. On Unix, this value was used to set the DSQUERY
environment variable. On the Mac, an entry called DSQUERY
needed to exist in your interfaces file. This value is now used instead.
If this option is not changed, Sybernet will continue to work as before.
LD_LIBRARY_PATH specifies library search directories to the
runtime linker.
The default is $SYBASE/lib:$LD_LIBRARY_PATH or $SYBASE/lib:/usr/ucblib.
This is the path to your htdocs directory.
The default is "../htdocs."
This is the path to your cgi-bin directory. Since version 2.05, Sybernet is now
a true HTTP web server and can execute C programs in your cgi-bin directory. If
you are familiar with Script Alias, this is essentially the same thing except
the implementation is completely different.
Whereas Script Alias might define X to be Y, the usual convention would be to
define cgi-bin as /usr/home/http/cgi-bin. CGIBIN can be
either a relative or absolute path name. Your CGI's (including Sybernet.cgi)
may refer to all or any part of this name; for example, if
CGIBIN was defined as /usr/home/http/cgi-bin, your stored procedure
could refer to Sybernet as /Sybernet.cgi, /cgi-bin/Sybernet.cgi, or
/http/cgi-bin/Sybernet.cgi.
Like HTDOCS, no CGI's will be executed outside of this
scope, even though the naming rules are different from what you might be
used to.
The default is NULL, which means it defaults to the
current working directory of Sybernet.
This is NetScape's home directory.
This is NetScape's root directory.
GUESTUSERNAME represents the username that Sybernet will
use when it detects a username of "guest" or "anonymous."
The default is "anonymous."
GUESTPASSWORD is the password for the
GUESTUSERNAME, of course.
The default is "anonymous."
NOTE: The guest password is displayed and stored in
clear text. That is its purpose: to allow anonymous access to your server,
should you desire.
PROCNAME is the name of the stored procedure Sybernet will
use when signing a user on to Sybase. Normally, this is not needed since the form
request specifies the name of the procedure; however, a URL request that points to
Sybernet and does not specify a procedure name will be directed to the procedure
indicated by this value.
If you've written your own default home page (and well you should), don't call it
sp_html_login. Instead, use this attribute to point it to the name of your stored
procedure. The purpose here is so that you don't lose your procedure when
you install the latest scripts (my latest scripts).
The default is "sp_html_login."
PREFERENCES is the name of the stored procedure that
retrieves user preferences. This procedure is called only when in the Interactive
SQL procedure, or more specifically when FORMAT is
ISQL, TEXTAREA, or TABLE.
These are undocumented formats by the way, which is why only the Interactive SQL
procedure uses this option.
The default is "http..sp_html_preferences."
PROXY identifies the name of your proxy server. You can
use this option instead of the COOKIES option to uniquely
identify client addresses that originate from behind a firewall. This is necessary
because Sybernet needs to differentiate between each user connection.
The default value of PROXY is the name of our proxy server.
Sybernet now lets you define your own error file which is invoked automatically
when a user fails to connect to Sybase. In addition, this file can contain
special strings embedded anywhere in this file that are replaced with
real text before this file is displayed; for example, the special string ^1
causes Sybernet to insert the user's login name. Consider the following
example:
The following special strings are permitted in your standard error file:
This pattern is replaced either by the message generated by Sybase or a message
generated by Sybernet when the former is not present.
This pattern is replaced by their username.
This pattern is replaced by their password.
This pattern is replaced by the name of the server (HOSTNAME) that they
are attempting to connect to. If none was specified, this will be the
value for DSQUERY.
This pattern is replaced by their IP address or hostname.
This pattern is replaced by the ordinal number from the list below:
The message "Unable to connect to Sybase" will almost always be replaced by
a message created by Sybase.
Currently, we use this feature to display the exact same page back to the user with
the username and password fields already filled in. In addition, a JavaScript alert
is sent when the form is loaded using the onLoad event handler.
I was unable to actually use the exact same HTML page
because JavaScript didn't permit me to assign the value for password. Instead, I
copied the standard signon screen and made the following changes:
In the <BODY> tag I added the following onLoad command:
If no error file is defined, Sybernet will continue to create the error messages
as it used to.
The COMMONERRORFILE definition can be used to specify a
default HTML file that is displayed when the Sybernet
CGI detects an error while communicating with the Sybernet
Server. These are errors you never want to see and possibly indicate something
is seriously wrong. To cushion the user from such errors, you may wish to
define your own HTML screen.
Do not confuse this definition with the ERRORFILE variable
described above. That file is the HTML file that is
displayed when a user fails to connect to Sybase while this file is displayed
when a CGI error is detected.
Special characters may be embedded in the COMMONERRORFILE;
for example, the special string ^# is replaced by the error number corresponding
to one of the errors below, and ^1 is the actual text corresponding to that
error number. Here's an example:
NOTE: 14, 15, and 16 are never sent to the client's
browser, but they are written to the log file.
The default COMMONERRORFILE name is undefined, and Sybernet
will generate its own HTML page.
This setting allows you change the default value for FORMAT
when no value is specified. Prior to version 1.78, the default was
NONE. Now the default value may be explicitly
specified as either NONE or
SUPPRESSED.
This value is the name of the log file. Prior versions of Sybernet required that
the log file be in the same directory as the binaries. You now may wish to place
this file in your web servers logs directory, for example.
The servers must be cycled for the change to take place.
The default log file name is "Sybernet.sumlog."
This value is the name of the Sybernet server. Prior versions of Sybernet
required that the servers reside in the same directory as the Sybernet cgi.
This is no longer true. Changing its name is safe; changing its location is
a bit more tricky because the configuration file is, by default, suppose to
reside in the same directory as all Sybernet software.
If you change its name, make sure Sybernet is not running. Ideally, you
should disable access to Sybase while this occurs.
If you change its location, then you must set the SYBERNET_CONFIG
environment variable for your web server's username to point to the configuration file.
A relative path name is not going to work. The complete path is required because
once you set this environment variable, all software will use that name.
The default name is "Sybernet."
This binary file is used by Sybernet and its child processes to accumulate statistics
about each connection. This is the information (sans the number of hits) that is
displayed when you click the Server Status link in the utility. The information
is reset each time the server is started.
The name of the configuration file is not stored in the configuration
file; however, its name may be specified with a real Unix environment variable
that is set for your web server. The name of this environment variable is
called SYBERNET_CONFIG.
In a shell script, for example, you might define it this way:
This value determines the name of the Sybernet Sendmail program. This is what
gets called when EMAIL is specified in a URL or POST
request. Sybernet sendmail calls the Unix sendmail.
If you change the location of Sybernet Sendmail, then you must set the
SYBERNET_CONFIG environment variable for your web server's
username to point to the configuration file.
The default name is "Sybernet.sendmail."
This is the name of your Unix sendmail program. It is called by Sybernet Sendmail.
The default name is "/usr/bin/sendmail."
This value is included as the Organization name when sending mail.
The default is null.
This defines the actual name of the cookie that is set when IP addresses are not
unique because you are using a proxy server or because the COOKIES option is set.
Do not change this name if you are currently using cookies and there are open
connections.
The default is "CUSTOMER."
This option defines the URL that a user is directed to when
they disconnect from Sybase. The QUIT command is the one
URL path name that Sybernet recognizes as a request to
disconnect. All other path names represent Sybase stored procedures.
Prior to version 1.97 this option was not configurable and QUIT
requests were redirected to the URL of your home page.
As of version 1.97 this option may be any valid (or invalid) URL.
Be sure to append a slash (/) if the URL represents a folder
or directory; be sure to omit the slash if the URL represents
a static HTML page.
The default is "http://" + ServerName + "/" where ServerName is
the name of your web server.
If you start Sybernet as root, this attribute determines the username that you
want Sybernet to run as. You have to start Sybernet as root if you specify a
port number less than 1024. This is the SOCKETS option.
The default is NULL.
If you start Sybernet as root and USER is not
NULL, this option specifies the group name to run Sybernet from.
The default is NULL.
This variable defines the name of a stored procedure that is automatically
called whenever an idle connection has timed out. Its purpose is to allow
your epilogue procedure to perform whatever cleanup is needed when a user
is disconnected.
If defined, you want to make sure that execute permission has been granted
to public and that the procedure either resides in sybsystemprocs or its
name is fully qualified.
This string value corresponds to the current version of Sybernet running on your
system. This value will be used to help you update to newer versions of Sybernet.
This Boolean value (set to true) is present only if Sybernet is being installed
for the first time. Its name and value is removed after a successful
installation.
This is your Sybernet registration number. Registration numbers are decrypted
and matched to the host name of your Web Server. As of version 1.65, this value
can be either the name of your Web Server (single user license) or a site name
(site license).
This Boolean value (true or false) indicates whether or not Sybernet is registered
for your system.
This string value represents the decrypted host name or site name from your
registration number. If Sybernet is saying your version is still unregistered,
then the problem is the name submitted for registration is not the same name
sent by your server to Sybernet.
When TRUE, this option will enable a command line interface
to Unix from the utility. It's a very dangerous option and should never be set,
but if you do, make sure the utility is protected by your web server with a
username and password.
Commands are entered in the lower window. Output is sent to the upper window.
You can change directories in this mode (using cd) and it will be remembered.
Text in the output window (perhaps from a cat on a file) can be saved by clicking
the Save as... button.
UNSAFE mode may not be set from the utility.
The default value is FALSE.
This uuencoded string is the username and password you submitted to password
protect the utility when using Sybernet as your web server. Only basic
authorization is supported. If Sybernet is not used as your web server,
authorization is accomplished with Netscape cookies.
This node exists for each directory server you have defined. This is the
only entry in the configuration file that is URI encoded.
You can start Sybernet by double-clicking on its icon. This is not necessary. WebSTAR invokes it
automatically whenever a request for Sybernet is received.
Sybernet was originally developed on the Mac and where I do most of my development work. The window
that appears is primarily for this development, but it does provide some useful features.
If you don't want to see the window, simply click on its close box or select File/Close from the menubar.
Select File/New to make it appear.
If you never want to see this window, select Options/Auto Shut Down until Auto Shut Down is not
selected, then select File/Save. Note: the window will reappear when Sybernet is restarted.
The three LED's on Sybernet's window indicate what is happening between
WebSTAR, Sybernet, and Sybase:
Magenta while processing a request from WebSTAR.
Red when logging a user on to Sybase.
Green when writing result sets to disk.
The Sybernet.cgi is started automatically by your web server. They connect
to the Sybernet server with an internet stream socket
It's the servers that hold connections and state information between the CGI
and Sybase. The servers get all their configuration parameters from the file
Sybernet.config in your cgi-bin directory except for the socket number that
they are suppose to listen at. The socket number is passed as a parameter
to the Sybernet server. It is the only parameter that it accepts; for
example,
will start a Sybernet server that listens at socket 5555. Make sure that if
you start the servers in this manner that the socket numbers are valid.
NOTE:
The utility program is the safest way to start the Sybernet servers because
it will not start a server on an invalid socket number.
NOTE:
As of version 1.71 and above the Sybernet CGI will automatically start the
Sybernet Server if it is not running.
A non-zero return result indicates one of the following errors:
NOTE: The term point means to set the Location
field to the URL of your web server's cgi-bin directory or to use the
Edit menu to Open Location in Navigator. Do not use
Open Page in Navigator.
You are attempting to reload the stored procedures, but you are getting
connection errors when the procedures are submitted to Sybase. This is
a bug recently discovered in the Sybernet utility. You have
COOKIES turned on, but the utility does not know how to pass
Netscape cookies to Sybernet. Turn COOKIES off
while the update takes place and turn it back on when finished.
The installation went fine, but now you receive a server error when you
execute one of the stored procedures. It looks like the URL is wrong,
and it is. This will occur if the Utility thinks you have a Netscape
server and you told it to install ntrans.so. Go back to the installation
and when it asks, "Do you want to install Netscape's ntrans.so?" answer
no, continue with the remaining questions (again), and reinstall the
stored procedures. The database and tables are fine and do not need to
be reloaded.
Some of the more notorious messages are documented here as well. It
is a good idea to always check the log file when you suspect something
is wrong.
You are probably trying to start Sybernet on a port number less than
1024, and you are not root.
Make sure that the sockets at SOCKETS through SOCKETS+SERVERS-1
are not in use by some other application.
Earlier versions of Sybernet would require a minute or two before
they could bind to their socket. This has since been corrected.
A call to "getsockname" failed. This too is another question for
your Unix Admin.
Check the security on the file "Sybernet.sumlog" in your cgi-bin
directory. The Sybernet server appends log information to this.
Check the security on the file "Sybernet.config" in your cgi-bin
directory. The Sybernet CGI server needs to read this file.
A user pressed the STOP button on
their browser. Sybernet will either issue a ct_cancel at this point
or continue to process the remaining results sets and throw them
away.
If a server is hung and this is the last message you see, turn off
CTCANCEL and restart the servers.
If CTCANCEL is already turned off, then
your stored procedure is looping.
Sybernet's attempt to fetch a result set has failed. The exact reason
for this failure will not be evident unless you are also monitoring
CTLIBERROR, CSLIBERROR and
OSLIBERROR. Terminating a process with the Sybase
kill command can cause this error, for example.
In most cases Sybernet is able to gracefully recover from this. Sometimes
the client is disconnected and must reconnect.
This message can also occur if Client Library (Unix and MacOS both) has run
out of memory. Things can quickly start to deteriorate and you may need
to restart the server. Increasing the amount of memory can alleviate many
of these conditions. In general, however, it's the stored procedure
that caused this condition so start pointing your finger there first.
Sybernet has hit your MEMORY limit. This will
close all open connections to Sybase (for this server) and terminate
Sybernet. Versions 1.71 of the Sybernet CGI will detect this condition
and automatically restart this server.
Version 1.78 and above allows Sybernet to fork requests to a separate
process. Although forked processes can exceed the defined memory
limit, they will not affect the main process and this message will not
occur.
This message occurs if Client Library is unable to find the file
ctlib.loc in your SYBASE directory;
for example, /sybase/locales/us_english/iso_1/ctlib.loc.
Check the security on the file "Sybernet.config" in your cgi-bin
directory. The Sybernet CGI needs to read this file.
Check that the Servers are alive and well by selecting Server Status
from the utility program.
See if the problem reoccurs. If it does, bring down the servers
(or if you know which server is having trouble, that server) and
restart them.
The handshake that occurs between the Sybernet CGI and the
Sybernet server failed. Check that the servers are alive, and
restart them if necessary.
The version of the Sybernet CGI or Sybernet utility is different
from the version of the Sybernet server. Make sure that the creation
dates are similar.
This message no longer occurs. If something exists in the configuration file
that Sybernet does not understand, it now ignores it!
A call to the system function "socket" failed. Contact your Unix
administrator.
Your web server is not passing SERVER_NAME to Sybernet.
The SERVER_NAME environment variable is invalid. Either your web server
is getting this wrong or you need to contact your Unix administrator.
Make sure the "hosts" entry in /etc/nsswitch.conf is correct.
Make sure that "named" is running and that its zone file is valid.
Increase the number of Sybernet CGI servers. You can change the
number of servers with the Utility program, but the servers must
be stopped before you can change this number.
Versions 1.71 and greater will automatically start a stopped server.
This probably does not mean anything serious is wrong. All it
means is that the Sybernet server did not respond to a status
request. Most likely, it's busy processing another request. If
this does not clear up in a reasonable amount of time (say, 5
minutes?) you might try checking in Sybase (using sp_who) and
see if there is perhaps a process running that will not quit.
With version 1.78 and above, Sybernet can spawn forked processes
for each request. If you are running Sybernet with STACKLIMIT
greater than 0, this message should not occur.
It is safe to kill, by the way, a process that is running in Sybase via Sybernet
that will not quit on its own.
Invoking Sybernet Sendmail is easy to accomplish. All you need to do is specify
the Sybernet reserved word EMAIL in either a post or URL
request; for example,
will send the output of the stored procedure sp_html_login to your E-Mail address.
Sendmail will force content-types of "text/plain" and "text/html" to be displayed
in-line in the body of the message. For content-type text/html you will want to
be using an HTML capable mail program such as Netscape Communicator.
All other content-types are included as an attachment; however, Sybernet Sendmail
does need to know if your mail attachment is actually HTML because it must break
up long lines. This can be accomplished by setting content-type to application/html.
This works because Sybernet actually ignores content-type, so your HTML output can
be included as an attachment with this special string.
The Sybernet utility allows you to change the name and location of Sybernet Sendmail.
Changing the name is safe, but changing its location requires you to set the
environment variable SYBERNET_CONFIG in your web server's .cshrc file. For more
information on how to do this, please refer to the section on
CONFAGFILENAME under Configuration and Preferences in this document.
Sybernet Sendmail calls sendmail (a Unix utility) to actually send your email.
The name and location of your Unix sendmail program must be specified with the
Sybernet Utility. See the entry for SENDMAIL under
Configuration and Preferences in this document.
Server Settings
This section discusses the various server settings. Settings are different
from options because they impose limits on how Sybernet is going to work.
ps request. The
one with the lowest process ID is actually running in Sybase. Those with higher
process ID's are waiting to run. Killing any one of these children will cause
Sybernet to terminate all children belonging to that user and disconnect that user
from Sybase. It is not possible to tell from ps, however, which children belong to
whom.ps -elf | grep 8888
8 S www 21169 20267 0 41 20 f64f6018 610 f64f61e8 12:59:26 ? 0:00 Sybernet 8888
8 S www 21171 20267 0 41 20 f62ea320 610 f62ea4f0 12:59:35 ? 0:00 Sybernet 8888
8 S www 21175 20267 0 41 20 f6583680 610 f6583850 12:59:41 ? 0:00 Sybernet 8888
8 S www 21177 20267 0 41 20 f5967cd0 610 f5967ea0 12:59:43 ? 0:00 Sybernet 8888
8 S www 20267 1 0 39 20 f62b4cd8 610 f6588066 07:05:17 ? 0:03 Sybernet 8888
8 S www 21173 20267 0 41 20 f63a49a0 610 f63a4b70 12:59:38 ? 0:00 Sybernet 8888
In this example, the main Sybernet server is 20267 and
21169 is a child process running in Sybase. The remaining
processes may be waiting for 21169 to complete, or they
might be separate user connections with no children waiting. It's impossible to
tell. kill -QUIT 20267
will safely kill the Sybernet server listening at socket 8888 from the above
example. waitfor delay "1:01"
select 'done'
In about an hour this waitfor statement will complete. By that time, your browser will
have timed out. http://Sybernet.sri.com/cgi-bin/Sybernet.cgi$quit
will also terminate all pending and active processes and disconnect you from Sybase.Option Settings
This section discusses the various options that can be set in Sybernet. The normal
defaults are the recommended values for these options.
Monitor Settings
This section discusses the various monitor options that can be set and written
to the Sybernet sumlog file. This is information passed from the Web server to
Sybernet. Note too that everything after CSLIBERROR
are also Sybernet reserved words.
Environmental Settings
This section discusses the various environmental settings that can or should be defined
for your system. Some of these are used to install or update
Sybernet while others are required to get the whole thing going. Other settings allow
you to tailor Sybernet for your particular environment.
<HTML>
<BODY>
<H3 ALIGN=CENTER>Sorry ^1, please try again</H3>
</BODY>
</HTML>
causes the following text to be displayed when user Charlie enters the wrong
password:
Sorry Charlie, please try again
The standard error file can be defined from the preferences dialog box
on the Mac or with the utility program under Unix. Although relative path
names are allowed, you may not use Sybernet's environment variables to specify
a path; for example, $HTDOCS/errorfile.html is not allowed. The proper way
to specify this name would be ../htdocs/errorfile.html.
As mentioned, the special string ^0 is normally the message generated by Sybase, but
if no message is available or the message was created entirely by Sybernet, then that is
the message you will see. The following are the messages Sybernet could produce:
<BODY onload="alert('^0');">
And for the two input fields (usercode and password) I added the following
VALUE statements: <INPUT TYPE="TEXT" NAME="USERCODE" VALUE="^1">
<INPUT TYPE="PASSWORD" NAME="PASSWORD" VALUE="^2">
I definitely prefer this over what I used to do, and if you don't, you can now create
your own page that is more suitable to your environment. That is the purpose. <HTML>
<BODY>
<H1>Don't Panic!</H1>
Sybernet detected the following error: ^1<P>
Please attempt to resubmit your request. If this message appears again,
you should call the help desk at x1234.<P>
</BODY>
</HTML>
If you include JavaScript to parse the error number or error string, make sure
you account for new values that might be added in a future release. The following
errors are currently defined:
struct statistics
{
int fd; // Self Reference.
unsigned long version; // myVersion.
off_t offset; // Offset in statistics file for this row.
unsigned long hits; // Total hits.
unsigned long bytesReceived; // Total bytes read.
unsigned long bytesTransmitted; // Total bytes written.
unsigned long minConnections; // Number of current connections.
unsigned long maxConnections; // Max connections at one time.
unsigned long activeTime; // Total time server was active (in seconds).
unsigned long elapsedTime; // Total time server was running (in seconds).
} ;
The default name is "Sybernet.statistics." setenv SYBERNET_CONFIG $cwd"/config/Sybernet.config"
The default name is "Sybernet.config."Everything Else...
This section contains a description of information contained in the configuration file
that is normally not shown to anyone. It is documented here for completeness.
Sybernet as a Web Server
Sybernet Utility
Running Sybernet (MacOS)
The other indicators on Sybernet's window should be obvious enough. They track the current number of
connections, the maximum simultaneous connections, the number of bytes sent to and received from
Sybase, and the amount of time this all took.
Magenta when sending a command to Sybase.
Magenta when sending result sets to WebSTAR.
Running Sybernet (Unix)
so the servers must
be up and running at all times.Sybernet 5555 9. CANTREADCONFIGFILE
18. SYNTAXERROR
19. CANTCREATESOCKET
20. CANTBINDSOCKET
21. CANTGETSOCKETNAME
22. CANTOPENLOGFILE
23. FORKFAILED
24. ASSERTFAILED
These errors are explained in more detail in the section on trouble shooting
(below).
Trouble Shooting
Trouble Shooting the Installation
When you point your browser to the Sybernet Utility, all you get is garbage
on your screen. This means your web server is simply reading the utility
and dumping its contents to your browser and means the server has not been
configured to execute CGI's in your cgi-bin directory. Documentation on
how to correct this problem can be found at the following URL:
http://hoohoo.ncsa.uiuc.edu/docs/tutorials/cgi.html
In particular, note the section on specifying ScriptAlias.Trouble Shooting the Sybernet Server
The following are error messages you might see when starting a server.
Once the servers have successfully initialized, future errors are written
to the log file: Sybernet.sumlog.
Trouble Shooting the Sybernet CGI
In all cases, see if there are any entries in the log file: Sybernet.sumlog
in your cgi-bin directory. If there are none and the servers are alive,
the problem usually points to the client: either the Sybernet CGI or the browser.
It read the configuration file fine, but it found entries it did
not understand. Rebuild the configuration file with the Sybernet
utility by selecting Configuration from the main
menu and click on submit.A Sybernet server is not running. Start it.
Sybernet Sendmail
Sybernet Sendmail
Sybernet Sendmail is new to version 1.85. This programs makes it possible to
send the output of your stored procedures to an E-mail address. Sybernet Sendmail
is actually an integral part of
Sybercron. Sybercron is available to registered users on both Solaris and Linux platforms.
