Search Rocket site

Rocket FlashConnect FAQ

1. What is Rocket FlashConnect?

Rocket FlashConnect, using a CGI, ISAPI, or Java interface, provides the ability to run Rocket D3 Database Management System applications from the Web.

Rocket FlashConnect consists of two components, the Web server component and the D3 component. While both components can reside on the same physical system, generally, for security reasons the Web server and the D3 component are usually on physically different systems.

Rocket FlashConnect components can be mixed and matched across Web servers and D3 platforms. One or more Web servers running the Rocket FlashConnect Web component can work with one or more D3 database servers. Each server can be running on a different hardware or O/S platform.


2. What are the Web Server Requirements?

Rocket FlashConnect is designed to work with any Web server which supports the CGI or ISAPI (on Windows Web servers only) interface. While there may be a few specialty Web servers which do not meet this criteria, we believe most, if not all current Web servers (Apache, IIS, ...) will run Rocket FlashConnect.

Whenever the Web server is started, a Rocket FlashConnect program must also be started. This program must be able to create and access a named pipe in the /tmp directory. This is usually not a problem if you host your own site. If you are using an independent ISP, you may need permission to do so.


3. What is installed for the Rocket FlashConnect Web server?

This is an overview of what is installed onto the Web server during the Rocket FlashConnect installation process and the files created while Rocket FlashConnect is running.

Programs:

fccgi.exe/fcisapi.dll

Run by the httpd server, fccgi.exe or fcisapi.dll pass to the D3 database server the request to the FCService process, then any reponse from the D3 server is passed back to the httpd server.

Regardless of the number of D3 database servers being supported, only one copy of fccgi.exe/fcispai.dll is needed on a Web server. fccgi.exe can be renamed (for example to fc.cgi) as needed to work with a Web server.

FCService.exe

Acts as a queuing and switching agent between the Web client requests and the D3 servers. Must be started before the first connection can be established and is generally done in a system startup script.

FCdebug/FCdebug.exe

Diagnostic program which provides detailed information about the state of Rocket FlashConnect and the state of each connection.

Files:

FC2000000, FC2*

Named pipes created by the FCService used to communicate with the fccgi.exe and fcisapi.dll programs. Location is configurable, however they are usually placed in /tmp.

/etc/flashconnect.conf

Contains the configuration of the Rocket FlashConnect Web server components.

FCDebug.txt, where are numeric digits.

Log file created in /tmp when the Rocket FlashConnect Web server component debugging is turned on.

w3library

Optionally installed account containing diagnostic tests and examples. It is best if this account is installed directly under the customers document root directory.


4. What ongoing administration is needed for the Web server component?

Unix:

  • Messages are written to the flashconnect.log file (usually found in /var/log). As with any log file, the file must be archived and cleared on an occasional basis. The directory in which the log file resides is administrator specified.
  • If debugging is enabled on any of the Web server components, the log files /tmp/FCdebug.txt are created and need to be deleted as appropriate. A directory other than /tmp may be specified in the FCDEBUG_PATH environment variable.
  • Optionally, the named pipes can be deleted when FCService is not running.

Windows:

  • Messages are written to the event log.
  • If debugging is enabled on any of the Web server components, the log files %TEMP%\FCdebug.txt are created and need to be deleted as appropriate. A directory other than %TEMP% may be specified in the FCDEBUG_PATH environment variable.

5. What resources does the Rocket FlashConnect Web server component consume?

Rocket FlashConnect is designed to consume minimal system resources. The following resource consumption is approximate:

Unix:

  • A shared memory segment (0xfc000000): The size depends upon the number of connections configured. It should not often exceed 1 MB.
  • Named pipes, one per connection to D3.
  • 5 typical or standard processes, plus one if the heartbeat is used, and one per connection to D3.
  • 1 semaphore per connection to D3.
  • 1 TCP/IP port, plus one TCP/IP port per connection to D3.

Windows:

  • 5 typical or standard threads, plus one if the heartbeat is used, and one per connection to D3.
  • 1 semaphore per connection to D3.
  • 1 TCP/IP port, plus one TCP/IP port per connection to D3.

6. What are the Web server configuration options?

The following Rocket FlashConnect Web server features can be configured:

Both Unix and Windows Web servers:

  • The maximum number of concurrent connections supported.
  • The names of environment variables passed to the D3 servers.
  • The amount of memory used to store the environment variables passed to the D3 server.
  • The TCP/IP port FCServer uses to communicate with the D3 servers.
  • Tuning parameters for available server search.
  • Redirection parameters for assorted error conditions.
  • The heartbeat period.

Unix Web servers only:

  • The directory where the named pipes will be kept.
  • The directory where the flashconnect.log file is placed.

7. Are there Security Issues?

All Rocket FlashConnect components are designed with security in mind, with the expectation that they will be run on a third-party system. FCService listens on an administrator specified TCP/IP port (usually 1505) for requests from the D3 servers. Access to this port should be limited to Rocket D3 Database Management System or Rocket mvBase Database Management System servers only.


8. What is the maximum number of connections allowed by Rocket FlashConnect?

When using Rocket FlashConnect, there are several points at which user limits can be reached.

  • The maximum number of D3 licenses purchased.
  • The maximum number of licenses supported on the D3 platform being used.
  • The throughput of the Rocket FlashConnect connector (fccgi.exe, Rocket D3 Java API, or fcisapi.dll) running on Web server.
  • The Web server CGI or ISAPI throughput.

Issues 3 and 4 can be controlled by hardware/software, i.e. faster O/S, Web server, faster hardware.


9. How are Rocket D3 Database Management System licenses consumed?

A Rocket FlashConnect license is consumed only during the time that the application holds a persistent connection to the database. The application developer determines this based on the selective use of persistence. Persistence can range from a fraction of the second to the length of an entire multi-page user session.

To illustrate the use of persistence, let us consider three different ways of designing an airline reservation and booking system. Any of these three designs are valid. However, depending on your goals, each design requires a different number of Rocket FlashConnect ports, thus a different number of D3 licenses.

Application description

Web page 1: Specify Route

The user specifies the date, time and location of both departure & arrival. This Web page does not contain any information from a database so a Rocket FlashConnect port is not needed to view it.

Web page 2: Select flight and payment

The user selects one flight from a list of flights that match the criteria, and enters their payment information.

Web page 3: Confirm payment

The user confirms the payment and flight information.

Web page 4: Completion message

The user is informed that their order is completed.

Design 1

Of the three designs, this design consumes a Rocket FlashConnect license for the longest period of time; however, the customer will always be able to book a seat on any flight offered. After page 1 is submitted, a tentative reservation is placed for each flight matching the user's criteria. One of the tentative reservations is finalized and the others released after payment is confirmed.

Design 2

Taking the middle ground, this design consumes a Rocket FlashConnect license for an amount of time less than design 1 but more than design 3. A final reservation is made when the user specifies a specific flight when submitting page 2 and confirmed after payment is confirmed. This design ensures the flight is available when the customer selects a specific flight; however, the flight could have filled sometime between the time the flight is first seen (Web page 2 loaded) and the time the payment is made (after Web page 2 submitted).

Design 3

This design consumes a Rocket FlashConnect license for the least amount of time. The final reservation takes place when the payment information is confirmed (page 3). The risk increases that their flight might fill while they are selecting a flight and entering payment information.


10. How do I determine the number of licenses to use?

The answer to this questions depends mostly upon how your Rocket FlashConnect application is designed and implemented.

For purposes of this discussion the following terms need to be defined:

  • Face time: The amount of time the user looks at a Web page before submitting the response. Included as a part of Face time is the time it takes to send and receive the Web page.
  • Processing time: The amount of time taken to generate a Rocket FlashConnect Web page. This time starts when FCService/w3Agent receives the Rocket FlashConnect request, and ends when FCService/w3Agent sends the reply back to the Web server.
  • Concurrent users: The desired number of concurrent users.
  • Fudge factor: An arbitrary amount by which to increase the number of licenses for unexpected peak use, growth, and errors in the estimate of Face and Processing time. Somewhere between 10% and 25% is a minimal value for the fudge factor.
  • Shared users: The number of users which can share one license.
  • Licenses: The number of D3 licenses required to support the specified level of concurrent users. We recommend rounding up to the next number of licenses.

For applications which exclusively use persistent connections, the number of shared users is 1. For applications which use some persistent connections, count the total time from when the persistent connection starts until it ends as processing time, regardless of the number of Web pages involved in the persistent connection.

Shared users = (Face Time + Processing Time) / Processing Time Licenses = Concurrent users/Shared Users * Fudge factor

Examples:

An average Web page takes 1 second to generate. Before replying, the user looks at the Web page for 9 seconds. Support for 100 concurrent users is needed; a 15% fudge factor is desired. Face time, 9 seconds; Processing time, 1 second; Concurrent users, 100 users/second; Fudge factor 15%; Shared users = (1+9)/1 = 10 Licenses = 100/10*1.15 = 11.5 = 12 rounded up.

An average Web page takes 2 seconds to generate. Before replying, the user looks at the Web page for 15 seconds. Support for 200 concurrent users is needed; a 10% fudge factor is desired. Face time, 15 seconds; Processing time, 2 seconds; Concurrent users, 200 users/second; Fudge factor 10%; Shared users = (2+15)/2 = 8.5 Licenses = 200/8.5*1.1 = 25.8 = 26 rounded up.

These equations are a suggestion from Rocket Software and may not be applicable to your site. Rocket Software assumes no responsibility for calculating the number of licenses needed for your site.


11. What development guidelines do you have?

While we cannot provide design information specific to any application, the following comments are available.

Web page design comments:

  • HTML goes in templates - not in the code.
  • One designer uses the technique of creating prototypes of my HTML pages, including using dummy data so the layout can be seen. Then hardcoded references to dynamic data are replaced with #unique# references. Many design issues are identified and resolved when looking at a page that resembles the final product. This process helps resolve Web page design issues before coding starts.
  • As part of your initial page design, decide how you are going to present errors. Be sure to present errors consistently throughout your application.

Program design comments:

  • Isolate your business rules from display logic. The programs which know about Rocket FlashConnect call subroutines which implement the business rules. The business rules should be unaware as to how the information will be presented. The Rocket FlashConnect programs should know nothing about file layout.
  • Create customized extensions to the Rocket FlashConnect API for building common HTML code segments.
  • Modularize the code that builds various segments of a web page. A single program that builds an entire page can get a little unwieldy at times, and debugging smaller routines is much easier.
  • While technically persistent connections work fine, they do tie up a license, so avoid persistence (using w3Input) unless it is required.
  • Try to design an application so inbound requests have a common entry point, or at least a minimum number of entry points (w3Apps entries). Doing so allows easy implementation of security and it also helps in cases where the user shouldn't execute program B unless they first execute A. This allows centralization of the navigation logic into the common routine instead of cluttering the application with this sort of housekeeping.

12. How can I use Rocket FlashConnect from within JavaScript to perform pre and post field processing?

The following line of JavaScript shows running a Rocket FlashConnect application and optioning the results from JavaScript. A line such as this can be embedded within JavaScript methods and used as needed within a Web page.

top.content.body.document.location = "http://"+ hostname +
"/cgi-bin/fccgi.exe?w3exec=&w3serverpool=
&formname= & ="


13. How can you start Rocket FlashConnect as an arbitrary user?

The following program starts a child program as a phantom running in a specified account as a specified user, then runs a specified command.

Usage: parent-program data
Parent program:

tclread indata

* Extract the first word which is the name
* of this program

indata = trim(indata)
word2start = index(indata, " ", 1) + 1

* Data follows this program name
indata = indata[word2start, 999999999]

* set up the user and account to use
user ="DM"
userpass=""
acct ="WWW"
acctpass=""
cmd = "test ":indata
line = ""

* set up the phantom start command
* pass in the user and account name and password

data user
data userpass
data acct
data acctpass
data cmd
data line
data ""
execute "z"

Program called test which exists in the target
account and is run there
the first word is this program's name

tclread indata
indata = trim(indata)

* data follows the program name
word2Start = index(indata, " ", 1) + 1
indata = indata[word2Start, 999999999999999]

cmd = "msg jack run from ":@account:" as ":@user:" data
":indata
execute cmd


14. Is there a Rocket FlashConnect customer support discussion forum?

Yes. Join the Rocket FlashConnect discussion group. Please see our forum Website to subscribe.


15. A Rocket FlashConnect port dies if the Rocket FlashConnect program isn't catalogued when it is used.

Problem

If the program that is being called from the browser is not cataloged in the www account, the browser hangs and evenually times-out, and the FC port is hung and must be restarted.

Answer

We previously discussed if we should check to make sure the program was cataloged every time it was run. Since we expect a system administrator to confirm the application works before announcing it to the public, this problem should be found and fixed before the application is released. The cost of checking the program each time it is used is too high for a setup issue.


16. How is caching of forms allowed? Or, sometimes when I go back to a Rocket FlashConnect generated Web page the browser presents a "Data Missing" message?

Discussion

To support state driven applications, Rocket FlashConnect informs the browser not to save (cache) any Rocket FlashConnect generated Web pages. Thus, when the user goes back to the page, it's not available in their cache. This can be a problem when writing event driven applications.

Solution

For Rocket FlashConnect releases 2.0 and after, the only change needed to enable caching of a Web page is to add an option to the w3HtmlInit API call:

call w3HtmlInit("background", w3HtmlFormCache)

For the Rocket FlashConnect 1.x releases, use w3HTMLPragma to change the form's pragma before using w3HTMLInit to initialize the background. For example:

Before

* use the default pragma of Content-type: text/html:
* Pragma: no-cache
call w3HTMLInit("demo")

After

call w3HTMLPragma("Content-type: text/html")
call w3HTMLInit("demo");* unchanged

Note: The 2.0 release has an option to w3HTMLInit to enable caching, however any existing code using the above features will continue to work.

Work around:

Rather than turning logging off, set the maximum number of entries to 1.

Solution:

Make the following change to the w3Log program in the wbp file:

Line: 59 if control.item<3> = "N" then return ;* nasty and brutial

Changes to:

if control.item<3> = "N" then
release f.log, filename ;* [05]
return ;* nasty and brutal
end


17. After I install Rocket FlashConnect the D3 programs don't start.

This problem has several causes:

Cause 1: Failure to update the www account md after doing the account-restore and before logging to the www account for the first time.

Symptom 1: The w3Logs,Rocket FlashConnect file does not exist after starting Rocket FlashConnect for the first time and "create-file w3Logs,Rocket FlashConnect 13" from the www account doesn't work.

Solution 1: Reinstall the www account, remembering to run "update-md www (n" after the restore and before the first time logging into the account.

Cause 2: Rocket FlashConnect is not activated.

Symptom 2: www-status shows an appropriate message. If the entire message isn't available, just use the instruction "ct w3ines" from the www account to see the entire message.

Solution 2: Purchase a copy of Rocket FlashConnect and activate the product, or obtain a temporary demonstration Rocket FlashConnect activation.

Cause 3: Insufficient D3 licenses.

Symptom 3: www-status shows an appropriate message. If the entire message isn't available, just use the instruction "ct w3ines" from the www account to see the entire message.

Solution 3: Purchase additional D3 licenses or obtain a temporary increase while you evaluate Rocket FlashConnect.


18. My Rocket FlashConnect connection dies after a period where it isn't being used.

All reported instances of this problem have been related to one or more the following:

  • Some cleanup process on a Unix Web server is deleting the named pipes in /tmp.
  • Solution: Reconfigure Rocket FlashConnect so the named pipes are no longer in /tmp.
  • A timeout setting in a firewall located between D3 and the Web server is killing the connections.
  • Solution: Reconfigure the firewall.
  • The D3 or Web server is being rebooted.

Solution: Check and if necessary restart the connections.


19. What are common administrative problems?

The most common problems can be resolved by:

  • Making sure the fccgi.exe (Unix and Windows) and fcisapi.dll (Windows only) programs are executable.
  • Making sure the directory containing fccgi.exe and fcispi.dll allows execution.
  • Reviewing the w3Apps, w3Groups, and w3Users files and remove any unneeded entries. For example, access to the D3Admin application is enabled by default using the default guest logon. The application allows management of the spooler and printer. This is probably not a desired feature on a live production system.
  • Until the site is stable, make sure there is at least one default server pool connection available.
  • Review and perform the diagnostics before making a support call.