Sybernet Utility

CONNECTIONS

Information about users connecting to and disconnecting from your Sybase data server. By default, this is the only option that is set for monitoring.

CTLIBERROR

Open Client Errors. Open Client errors are always sent to the browser, but this option allows you to send them to the log file.

OSLIBERROR

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.

CSLIBERROR

Client Server messages. Client Server messages are always sent to the browser, but this option allows you to send them to the log file.

RESPONSE

Result set sent to client. This can generate a tremendous amount of output!

POST

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.

DIRECT

The direct argument or extra path information.

SEARCH

Arguments to URL after the (?). In a URL request (method="get"), these are the parameters to your stored procedure and/or Sybernet reserved words.

SCRIPTNAME

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.

HTTP_HEADER

This option displays the entire HTTP header sent to Sybernet. This can generate a tremendous amount of output.

SYBERNET

This is Sybernet's home directory. If Sybernet is your web server, you can place Sybernet anywhere you want. If Sybernet is not your web server, you probably want to place Sybernet underneath your web server (somewhere in its CGI-BIN folder), but this is not required.

SYBASE

SYBASE is the full path and directory name of your Sybase directory.

ORACLE

ORACLE is the full path and directory name of your Oracle directory. This is the same thing as ORACLE_HOME.

DSQUERY

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.

LD_LIBRARY_PATH

LD_LIBRARY_PATH specifies your library search directories. This is a colon separated list. Although Sybernet sets this environment variable internally, LD_LIBRARY_PATH must be armed before you actually start Sybernet.

PATH

PATH specifies your binary search directories. This is a colon separated list.

NLS_DATE_FORMAT

This is the default date format used in Oracle. Any good Oracle programmer will tell you to never rely on this value; however, when used correctly, this option makes it possible to pass date values in your form screens as date parameters to your procedures.

HTDOCS

This is the path to your documents directory.

The default is ../htdocs.

CGIBIN

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.

PROCNAME

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.

PREFERENCES

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.

GUESTUSERNAME

GUESTUSERNAME represents the username that Sybernet will use when it detects a username of "guest" or "anonymous."

GUESTPASSWORD

GUESTPASSWORD is the password for the GUESTUSERNAME, of course.

PROXY

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.

ERRORFILE

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:

    <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:

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.

The following special strings are permitted in your standard error file:

• ^0

  This pattern is replaced either by the message generated by Sybase or a message generated by Sybernet when the former is not present.

• ^1

  This pattern is replaced by their username.

• ^2

  This pattern is replaced by their password.

• ^3

  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.

• ^4

  This pattern is replaced by their IP address or hostname.

• ^#

  This pattern is replaced by the ordinal number from the list below:

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:

1. There are too many user connections!
2. DSQUERY environment variable is not defined!
3. A username and password is required to access database!
4. Error allocating memory for this connection!
5. Unable to initialize context!
6. Unable to connect to Sybase!
7. Unable to allocate a command pointer!

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:

    <BODY onload="alert('^0');">

    <INPUT TYPE="TEXT" NAME="USERCODE" VALUE="^1">
    <INPUT TYPE="PASSWORD" NAME="PASSWORD" VALUE="^2">

COMMONERRORFILE

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:

    <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:

1. WRITING TO STREAM SOCKET FAILED
2. READING OK FROM STREAM SOCKET FAILED
3. UNABLE TO OPEN INTERNET STREAM SOCKET
4. UNABLE TO GET HOSTNAME CALLING GETHOSTNAME
5. INVALID SERVER NAME WHILE OPENING SOCKET
6. COULD NOT PROCURE SOCKET
7. SERVER NOT RUNNING. THE ATTEMPT TO START IT FAILED!
8. CONNECTION TO STREAM SOCKET FAILED
9. UNABLE TO READ CONTENTS OF CONFIGURATION FILE
10. REMOTE_HOST ENVIRONMENT VARIABLE IS UNDEFINED
11. CONNECTION TO SYBERNET SERVER TIMED OUT
12. MEMORY RESOURCES ARE RUNNING LOW
13. POST DATA IS TOO LARGE (MAKE IT SMALLER)
14. READING FROM WEB CLIENT FAILED
15. WRITING TO WEB CLIENT FAILED
16. ERROR READING RETURN RESULTS FROM SOCKET

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.

DEFAULTFORMAT

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.

SUMLOGFILENAME

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."

SERVERFILENAME

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."

STATISTICS

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.

    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."

CONFIGFILENAME

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:

    setenv SYBERNET_CONFIG $cwd"/config/Sybernet.config"

The default name is "Sybernet.config."

SENDMAIL

This is the name of your Unix sendmail program. It is called by Sybernet Sendmail.

The default name is "/usr/bin/sendmail."

ORGANIZATION

This value is included as the Organization name when sending mail.

COOKIE

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."

QUIT

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.<

USER

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.

GROUP

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.

DISALLOW

This variable contains a comma separated list of host names or IP addresses that are disallowed access to Sybernet. Sybernet will add entries to this list automatically whenever a client attempts to access too many invalid documents. This usually indicates someone attempting to compromise your site. Addresses can contain the usual wild-card character (*) to specify an entire node.

HELPDESK

You can use this option to display text whenever Sybernet generates a NOT FOUND or FORBIDDEN message. As its name implies, this might be contact information for your users when they are having problems.

EPILOGUE

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.

DOMAIN

This option allows you to run Sybernet in AF_INET or AF_UNIX domains.

SEPARATOR

This is also known as the explicit-path separator. It is used to separate the path to sybernet (or Sybernet.cgi) with the name of your stored procedure. The default is a dollar-sign ($) which must agree with the separator used by your web server if Sybernet is not your web server.

USERNAME

The username to connect to Oracle. This user must have the ability to alter a user's password if you use client certificates. If used as the username for Sybercron, this user must be able to do about just anything.

PASSWORD

The password to connect to Oracle. Password is stored encrypted in the configuration file, but is never displayed in the utility. You can, however, define or change this password with the utility.

VERSION

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.

VIRGIN

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.

REGISTER

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).

REGISTERED

This Boolean value (true or false) indicates whether or not Sybernet is registered for your system.

REGISTEREDNAME

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.

AUTHORIZATION

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.

LDAP

This node exists for each directory server you have defined. This is the only entry in the configuration file that is URI encoded.