A number of new properties have been added to the Request object. These allow developers to simplify code while maintaining or adding functionality.
Request.Accept - Contains the value of the Accept header included with the request. If an Accept header was not included in the request, the value will be blank. Previously, this property would not exist if the header was not included, requiring additional Xbasic code to test for its existence first.
Request.AcceptCharset - Contains the value of the Accept-Charset header included with the request. If an Accept-Charset header was not included in the request, the value will be blank. Previously, this property would not exist if the header was not included, requiring additional Xbasic code to test for its existence first.
Request.AcceptEncoding - Contains the value of the Accept-Encoding header included with the request. If an Accept-Encoding header was not included in the request, the value will be blank. Previously, this property would not exist if the header was not included, requiring additional Xbasic code to test for its existence first.
Request.AcceptLanguage - Contains the value of the Accept-Language header included with the request. If an Accept-Language header was not included in the request, the value will be blank. Previously, this property would not exist if the header was not included, requiring additional Xbasic code to test for its existence first.
Request.Cookie - Contains the value of the Cookie header included with the request. If a Cookie header was not included in the request, the value will be blank. Previously, this property would not exist if the header was not included, requiring additional Xbasic code to test for its existence first.
Request.IfUnmodifiedSince - Contains the value of the If-Unmodified-Since header included with the request. If an If-Unmodified-Since header was not included in the request, the value will be blank. Previously, this property would not exist if the header was not included, requiring additional Xbasic code to test for its existence first.
Request.UserAgent - Contains the value of the User-Agent header included with the request. If a User-Agent header was not included in the request, the value will be blank. Previously, this property would not exist if the header was not included, requiring additional Xbasic code to test for its existence first.
A number of new methods and properties have been added to the Response object in order to extend the functionality of the Application Server.
Response.AddCookie() - This method supercedes Response.Add_Cookie(), adding support for Http-Only and Secure cookies.
Set a simple cookie with a 15 minute lifetime:
Response.AddCookie("MyCookie","MyValue",900)
Set an Http-Only cookie:
Response.AddCookie("MyCookie","MyValue",900,.t.)
Set a Secure cookie:
Response.AddCookie("MyCookie","MyValue",900,.f.,.t.)
Set a Secure and Http-Only cookie:
Response.AddCookie("MyCookie","MyValue",900,.t.,.t.)
Response.AddHeader() - This method supercedes Response.Add_Header(), extending the supported syntax to be familiar to ASP programmers while maintaining the previous Xbasic syntax.
Set a header using "classic" syntax:
Response.AddHeader("MyHeader: abc123")
Set a header using ASP-like syntax:
Response.AddHeader("MyHeader","def456")
Response.Charset - This is a new property that indicates to the client which character set it should use to display the response.
Response.Charset = "UTF-8"
Response.Expire() - This is a new method to control the client-side caching of the response.
To expire the response in 5 minutes:
Response.Expire("5 minutes") 'supports seconds, minutes, hours, days, and weeks
To expire the response at a specific time:
Response.Expire("3/29/12 03:07")
'or
Response.Expire("Thu, 29 Mar 2012 07:07:00 GMT")
To expire the response immediately:
Response.Expire("-1")
Response.Mime_Type - This is a new property that indicates the MIME type of the response to the client.
Response.Mime_Type = "application/pdf"
Response.NoCache() - This is a new method that sets a number of response headers which indicate to the client, and any proxy servers, that this response should never be cached. This method simplifies previous techniques that required multiple lines of Xbasic to accomplish the same result. This is recommended for use in any page that displays sensitive data that should not remain in a client or proxy cache due to security concerns.
Response.Redirect() - This method has been extended to support permanent (301) redirects using an optional second argument. If left unspecified or set to .F., the redirect is a temporary (302) redirect, while setting the second argument to .T. results in a 301 redirect. The end result is generally the same in most clients, but 301 and 302 redirects are typically handled differently by search engines and caches.
To redirect the client, using a permanent redirect:
Response.Redirect("/newpage.a5w",.t.)
Response.SendFile() - Response.SendFile() is a new method to send a file from outside the server's document root to the client. This was previously possible using several lines of Xbasic to send the file, set the proper MIME type, etc. which is now greatly simplified.
To send the file c:\invoice.docx to the client:
Response.SendFile("c:\invoice.docx")
To send the file c:\invoices\customer0023.docx to the client and have the client receive it as invoice.docx:
Response.SendFile("c:\invoices\customer0023.docx","invoice.docx")
A number of changes have been made to the session management mechanisms of the Application Server to further enhance security and functionality.
Session Cookie Lifetime - The cookie used to track session state is now a "session" cookie. This means that it is never stored on the client's disk and it will be removed when the client browser is closed.
Session Cookie is Http-Only - The cookie used to track session state is an Http-Only cookie. This protects the cookie from being accessed by unauthorized scripts.
Session Cookie is "Secure" - If SSL is in use by the server, the cookie used to track session state is a Secure cookie. This ensures that the cookie is only sent across an encrypted connection secured by SSL and never in plain text.
Session IDs - Session ID management and assignment have been made more robust. Only session IDs that have been generated by the server are useable. Additionally, session IDs cannot be recycled (reused). If the client attempts to access a non-existent session, a new session ID will be assigned.
Session.BrowserId - A new browser ID cookie provides an equivalent long-lifetime browser identifier as the previous session ID did. This is similar to older session IDs in that it does not change across sessions and can be used to uniquely identify a client across sessions. The name and lifetime of this cookie are configurable by the server administrator.
Failed Startup - A failed server startup is now logged to error log. This condition was previously not recorded.
Thread Transition Log - The new thread transition log records all thread transitions and critical code execution while the Application Server is running. This option quickly generates a large amount of data which is not of much use to users, so it is recommended that this log be left off. However, the log is of use to Alpha Software when helping customers troubleshoot specific problems so you may be asked to temporarily enable this by Technical Support.
Xbasic Error Stack Log - The new Xbasic error stack log records the Xbasic execution stack at the time of any Xbasic error. This can be very helpful in debugging errors, as it typically gives a much clearer picture of what was going on when an error occurred than does the simple error message sent back to the client and recorded in the standard error log.
IP Address Binding - The Application Server can now bind to a single specific IP address instead of always binding to all addresses available on the host machine. This allows multiple servers on the same system to use the same port as long as they each use a different IP address. Running multiple servers enables the hosting of distinct web sites or applications.
Header Read Timeout - The period allowed for all request headers to be received is now configurable by the server administrator. This was previously hard-coded to 1.5 minutes.
Request Read Timeout - The period allowed for the full request (headers and body) to be received is now configurable by the server administrator. This was previously hard-coded to 8 minutes.
Keep-Alive Timeout - The period which the server waits on a previously used connection to receive another request from the same client is now configurable by server administrator. This was previously hard-coded to 15 seconds.
Maximum Keep-Alive Requests Per Connection - The maximum allowed requests per Keep-Alive connection before using a new connection is now configurable by the server administrator. This was previously hard-coded to 100.
Maximum URI Length - The maximum length of a URI that the server can receive is now configurable by the server administrator. This was previously hard-coded to 8192 bytes.
Disable Built-in Functionality - Each of the following built-in server features can be individually enabled or disabled. They are all enabled by default.
Socket Performance - Sockets used by the server are now read from and written to more efficiently, allowing the actual transfer of data between client and server to happen more quickly.
Optimized Request Parser - The parser used to receive the incoming request, validate it, and ensure that it is appropriately processed has been optimized for performance to minimize server overhead.
Application Cache - Application-specific information is now cached by the server to make request processing more efficient. This includes the application root, aliases, connection strings, and any variables created in a5_application.a5i. Any changes to a5_application.a5i, such as updated aliases or connection strings, now require the server to be restarted before taking effect.
Gzip Caching - Gzip is a compression technique used by many application servers to reduce the amount of data that must be sent to a client. This improves delivery speed of the response, but it adds some processing overhead on the server as the compression takes place. To negate that overhead, the server now caches gzipped copies of static content, eliminating the processing required to duplicate the compression. This cache is automatically cleared when the Application Server is shut down, or it can be cleared at any time while the server is running by using Server.ClearGzipCache().
More Responsive Server Shutdown - General processing optimizations allow the Application Server to be more responsive to shutdown requests.
Error Pages - Custom error pages now support executing A5W code in addition to simply serving static files. This allows for custom handlers that email an administrator, attempt to fix up a mistyped URL, or take just about any other action that can be written in Xbasic.
Server.ClearGzipCache() - This method clears the gzipped versions of static resources that have been cached by the server. This is useful when static content on the server has been updated but a server restart to clear the cache is not desirable.
Version 9 Compatibility Server - While Version 10 adds new functionality, provides greater security, and greatly enhances performance, some may wish to temporarily run the older Version 9 server for testing or debugging. This removes all new Version 10 functionality by running the Version 9 server within Version 10.
Response.Add_Cookie() is deprecated and has been superseded by Response.AddCookie(). It will continue to work in Version 10 but will be removed in a future version. Any new code should use the replacement Response.AddCookie() and it is recommended that existing code be updated when convenient.
Response.Add_Header() is deprecated and has been superseded by Response.AddHeader(). It will continue to work in Version 10 but will be removed in a future version. Any new code should use the replacement Response.AddHeader() and it is recommended that existing code be updated when convenient.
Alpha Five and the Application Server each store server settings in a configuration file on the computer's hard drive. The location of the file being used by an instance of Alpha Five or the Application Server can be determined using the function a5_GetAppServerConfigFile(). For example:
?a5_GetAppServerConfigFile()
= "C:\AppServer\ServerConfig.xml"
Typically, you would execute this function from the Interactive Window to ascertain the location of the configuration file in use for creating an application shortcut.
The Application Server allows for an alternate configuration file to be specified. This is done through the use of a command line option, CONFIGFILE. For example, to launch the Application Server using a configuration file named TestConfig.xml in the root of the server's C drive:
A5ApplicationServer.exe -CONFIGFILE="C:\TestConfig.xml"
A command line such as this example could be run from a command prompt directly, saved as a shortcut, or used with third-party tools that launch and/or manage programs.
If the specified configuration file is not found, a warning will be displayed and startup will be aborted. To create a new configuration file, you may either create a new, empty file which the Application Server will then populate with defaults, or you may make a copy of an existing configuration file, start the Application Server, and then modify settings as desired.
Note: CONFIGFILE is only supported by the Application Server (A5ApplicationServer.exe). If specified when starting Alpha Five (Alpha5.exe), it will be ignored. The Alpha Five server configuration file cannot be changed.
The Application Server configuration file is an XML based text file, with all settings stored as attributes of the ApplicationServer element. The file may be modified using any XML or plain text editor as desired.
By editing the Application Server configuration file (see above), it is possible to create arbitrary attributes of the ApplicationServer element. When the Application Server reads and processes the configuration file, these attributes will become constant properties of the ServerSetting global object in the A5W environment. This is useful for creating custom server-wide constants for use in your applications.
For example, if an attribute CompanyName is added to the configuration file, ServerSetting.CompanyName will then be available throughout all of your applications running on the server and across all sessions. The value will not be changeable by Xbasic. To change the value, the configuration file would need to be modified and then the server would need to be restarted.
Global constants created using this mechanism will always be of type Character.
A limitation of the Application Server is that it can only run on one TCP port at a time. This means that a single Application Server cannot provide both HTTP and SSL support. Nonetheless, HTTP and SSL services can be provided for a given application by using two instances of the Application Server, each using a different configuration file. To do so,
The result is 2 running Application Server instances, making the entirety of your application available via both HTTP and SSL.
SSL enhances the security of your application by encrypting data while it is in transit, but performing this encryption adds additional load to your CPU and impacts the overall performance of your application. In many cases, only a portion of your application will work with sensitive data, so it may be desirable to use SSL for only that portion of your application. The previous example provides the basic HTTP and SSL services, which can then be enhanced with the addition of some fairly simple Xbasic.
By creating an A5W page with just the following code and using a5w_include() to make sure it is included on all of your other pages, all access to the /store/checkout/ folder will be forced to use SSL, while all other access will be forced to not use SSL.
<%a5
dim StandardUrl as c = "http://www.myserver.com"
dim SslUrl as c = "https://www.myserver.com"
if left(Request.SCRIPT_NAME,16) = "/store/checkout/"
if .not. ServerSetting.SSL_Enabled
Response.Redirect(SslUrl + Request.SCRIPT_NAME,.t.)
end if
else
if ServerSetting.SSL_Enabled
Response.Redirect(StandardUrl + Request.SCRIPT_NAME,.t.)
end if
end if
%>
Traditionally, Application Server administrators provide service for multiple applications by using a single instance of the Application Server, placing each distinct application within a different subfolder under the document root. While this is quite effective, it results in cluttered URLs, such as http://www.server.com/application1 and http://www.server.com/application2, and shares sessions between sites. By using multiple instances of the Application Server, each to provide service for only one specific application or site, sessions are no longer shared and URLs may be further customized. This configuration requires 1 IP address per application or site.
The Application Server creates an icon in the Windows Systray to access the Control Panel and indicate the server's state. Each icon is visually identical when running multiple instances of the Application Server, so it becomes difficult to associate each icon with the correct server instance. However, setting a Systray Caption on the Advanced tab of the Application Server Control Panel makes it much easier to determine which icon is associated with which server instance. When hovering your mouse over the icon, Windows shows a popup bubble which includes the caption and the server state, as shown below. The caption is also reflected in the window title of the Application Server Control Panel, when visible.
Note: In order for the caption to be updated after making a change, the Application Server must be exited and restarted.
Firewalls control network access to your server in order to provide a layer of security from malicious attacks. In the process of blocking undesirable access though, they can also block access to your server that you want to allow. If your Application Server appears to start correctly but clients cannot connect to it, it is quite likely that a firewall is blocking network access to your Application Server.
Most versions of Windows include Windows Firewall, a built-in firewall to control what incoming connections are allowed, and also which programs may accept incoming connections and initiate outgoing connections. It is important to be aware that Windows Firewall exceptions (connections which will be allowed) can be set by the TCP port number, but also by the specific application. This means that it is possible that you may have previously configured Windows Firewall to allow an older version of the Application Server to function properly, but a new version does not work as expected because it is a totally different application with respect to Windows Firewall. In this case, you need to add a new exception to the firewall rules.
In addition to Windows Firewall, many common security software packages, such as McAfee Total Protection and Norton Internet Security, include a firewall for additional protection. If you have software such as this installed, you should review its accompanying documentation and ensure that it is not blocking access to your Application Server.
In addition to software-based firewalls discussed above, many networks also use hardware firewalls to restrict network access. These are dedicated devices that provide similar access control to that of a software firewall, but across an entire network instead of on a single PC. You should consult your network administrator to find out if there is a hardware firewall in use and if it may need to be specially configured for your Application Server.
Network services use TCP ports to "listen" for incoming requests from remote clients and service them. The combination of IP address and TCP port is what provides the unique address for your service, so only one process can use a given port at a time. When you attempt to start the Application Server, it will warn you if there is already some other program using the port it is configured to use and it will then abort starting. If this happens, you can either use a different port for the Application Server, or you can determine what other program is using the port and stop it.
Changing the port used by the Application Server is the easiest solution - simply change the port number designation in the Application Server Control Panel and start the server. However it is also typically less desirable, because it means that clients must now modify the URL they use to access your server. If you specify a port other than 80 (or 443 in the case of an SSL-enabled server), the client must then know the port number you are using, and include it as part of the URL that they access, e.g. http://www.server.com:8080
The Application Server cannot determine what other process is using a port on your computer for you, but the procedure to determine this is included in the Alpha Five documentation. Once you know the other process involved, you can determine whether it is providing a critical service, in which case you will possibly want to change the port used by the Application Server, or if it is safe to disable.
Version 10 also provides another remediation option. With the new ability for the Application Server to bind to a specific IP address, it is possible to have multiple processes on the same computer use the same port number as long as they use different IP addresses. Consult with your network administrator regarding using multiple IP addresses for your computer.
The Application Server can record a variety of useful information in different log files. The value of these log files in detecting and troubleshooting any problems is immeasurable. Many times, application users will not report what they presume to be minor errors, or they may not even be aware of something like a missing image which, if present, would enhance the usability or appearance of the application.
The primary server log is the Access log. This file contains an entry for every resource that was requested and, along with other information, an HTTP status code to indicate the result of the request. A regular review of the Access log with reveal any recurring problems, such as missing files (status code 404) or pages that generally generate errors (typically status code 500).
The Error log also records each error, and usually contains some more specific information on what the problem was. For example, the Access log may record that a specific request resulted in a 500 status, while the corresponding entry in the Error log may reveal that it was an Xbasic error, with the specific error text and line number.
The Xbasic Error Stack log records the execution stack any time an Xbasic error occurs. This means that it will not record anything for a non-Xbasic error such as if a file is not found. When there is an Xbasic error, additional information about the execution state of your code will be logged. During normal operation this log will have nothing to record, so it is recommended that this log be left enabled in order to capture as much debugging information as possible in the event an error does occur.
The Raw HTTP Traffic log records the raw data sent on the connection between the server and the client. The information in this log can be used to verify that the server is receiving a complete request as expected and sending a proper response to the client. This generally results in a large amount of data being logged very quickly, and it potentially saves sensitive data in an unencrypted format, so it is best not to enable this log unless a specific error condition is being debugged.
Web applications depend on accurate time keeping. Sessions are managed using a cookie, and the server sets a lifetime for that cookie based on what it thinks is the current time. The client then receives the cookie and acts on it based on its own clock. Additionally, the server will direct the client to store responses that it sends in a cache until a specified time.
For these reasons, it is important that both the server and the client have accurate system clocks. In many situations, it is not possible to directly verify or control the system clock on the client, but it is something to be aware when trying to determine the cause of unexpected behavior. On your server, you can use a utility to automatically synchronize your clock with an authoritative time source.
Most versions of Windows have the ability to synchronize the clock using an Internet time source, but third-party utilities are typically more reliable. The NTP Pool Project is a reliable time source that is available for general use.