Occasionally Connected Computing (OCC)

Summary:
  • Occasionally Connected Computing enables the application user to access your application when not connected to the Web server.
  • An OCC application creates a replica of itself on the user machine.
  • The user controls whether to use an application's OCC feature and can put shortcuts into the Start Menu or on the desktop.
The Curl language and the Curl RTE support Occasionally Connected Computing (OCC). OCC enables the end user of your application to store a copy of the application on the local hard disk and access it when not connected to the Web server. The OCC application runs locally in the Curl RTE using the stored Curl source and other application data.

Using an OCC Application

Note: Before 7.0, the prefix for OCC URLs was curl://occ/ instead of the current curl://offline/ syntax described below. The curl://occ/ URL syntax is deprecated now, but retained to be consistent with prior Curl releases. Please don't use curl://occ/ with new applications.
This is the OCC scenario from the end user's point of view:
The end user can access an application by putting the special Curl URL prefix curl://offline/ before the network URL for the application. For example, the simple OCC application http://www.curl.com/developers/occ2/app1.curl, can be referred to in the location bar and hyperlinks as curl://offline/http://www.curl.com/developers/occ2/app1.curl, and the application will offer to install itself, or redirect the user to the local copy if it is already installed.
The actual URL of the local copy depends on the platform, and the username, and possibly the hostname, or various user settings, but may be determined programmatically by replacing the http:// or https:// prefix of the normal network URL of the application with curl://user-data/local-root-for/, and then canonicalizing the result using Url.canonicalize. For the example above, this would involve canonicalizing curl://user-data/local-root-for/www.curl.com/developers/occ2/app1.curl. The following example shows this value for you (the user looking at this documentation right now).


Example
{{url "curl://user-data/local-root-for/www.curl.com/developers/occ2/app1.curl"}.canonicalize}


Applications should not depend on this location and should not use curl://user-data/local-root-for/ URLs inside any application code except to inform end users about the explicit location of the local copy of the OCC application.

Writing an OCC Application

There are several points you must consider when writing an OCC application.

Planning for OCC

As described by process-get-curl-root, the curl-root for an applet defines the root of the tree of files "related" to the applet. This affects many things, including OCC replication, since during OCC installation, the entire tree of files rooted at the applet's curl-root (or at least the portion of this tree for which the user has expressed an interest) will be replicated to the user's machine.
By default, for a network applet, the curl-root is assumed to be the root of the webserver, but the curl-root declaration, inside the applet statement, will override this. This is normally only necessary if the root of the webserver contains several totally unrelated subtrees. For example, the directory http://www.curl.com/developers/occ2 is totally unrelated to any other files at http://www.curl.com, and so the two examples below use an explicit curl-root to enforce this.
For example, the applet http://www.curl.com/developers/occ2/app1.curl contains a curl-root = "." declaration in its applet statement, and thus its resulting "curl root" is http://www.curl.com/developers/occ2.
Continuing the previous example, the applet http://www.curl.com/developers/occ2/subdir/app2.curl contains a curl-root = ".." declaration in its applet statement, and thus its resulting "curl root" is also http://www.curl.com/developers/occ2.
Since the two example applets mentioned above share a common curl-root, browsing either will cause both of them to be replicated to the user's machine, enabling either one to be browsed later, while disconnected. In a sense, they are thus both considered to be part of the same application, and would normally be developed, and deployed, together, using a single project. This simple situation is supported by occ-root-installer (see below).
In a more complex situation, an application, or set of applications, may want to break out common code into libraries, possibly shared among the applications, with all of the applications and libraries being developed, and deployed, separately. Since they all may need the ability to use one another, and/or to share local data, they must have a common curl-root, but it may be easiest for them to each have their own project, and to be deployed separately. In this case, each of the applications and libraries may be thought of as a module, with a given application actually being made up of several such modules. In addition, it is often desirable that any modules not actually needed by a given user not be replicated to that user's machine. This more complex situation is supported by occ-module-installer (see below).

Writing for OCC

An OCC application may use a variety of techniques for creating and/or updating a local copy of itself on the end user's machine. All of them involve the use of the occ-install-or-update procedure, in combination with an appropriate installer procedure.
A very simple installer is occ-root-installer, as used by this very simple applet, as well as by the example applets mentioned above.
{curl 8.0 applet}
{applet
    manifest = "manifest.mcurl",
    curl-root = "."
}
{do {occ-install-or-update occ-root-installer}}
...
The applet above will attempt to install or update a local copy of itself every time it is browsed, before continuing with its normal execution.
The occ-install-or-update procedure first verifies that the application has permission to install itself locally. If the calling applet's local root directory already exists on the user's machine, occ-install-or-update assumes that permission was granted in the past and calls the installer procedure to install or update the application. If the applet does not already have a local root directory, then occ-install-or-update raises a user dialog to request permission to install the application. Unless the application uses keyword arguments to provide more information occ-install-or-update will call request-local-data-permission to raise a simple yes-or-no dialog. If the application specifies the install-filename keyword argument, the permission dialog will be more elaborate and a successful installation will register the application with the host operating system like a native application, including launcher icons and an uninstallation option on platforms that support them.
The applet above uses occ-root-installer, which assumes that a curl-timestamp.txt file, as well as an appropriate curl-contents.txt or curl-archive.car file, are present in the curl-root directory on the Web server. The IDE can generate these files (see below). If there is no local copy, or the curl-timestamp.txt file indicates that the local copy is out of date, then the files listed in the curl-contents.txt file are acquired, or the files contained in the curl-archive.car file are extracted, and the curl-timestamp.txt file is copied, yielding a new local copy of the application.
Note that there are, in fact, curl-timestamp.txt and curl-archive.car files in the example directory http://www.curl.com/developers/occ2, which do, in fact, enable the contents of that directory to be copied to a users local machine, when any of the applets inside that directory, such as those mentioned above, are browsed.
A more complex installer is occ-module-installer, for which no example is available at this time.

Special URLs

OCC applets are always run from the local file system, whether connected to the network or not, so the base url of the applet will always be a local filesystem url. The root of the application on the server from which it was installed, and whose hostname is used for security purposes, can also be accessed through curl://http-root when there is a network connection. Local application data should be accessed through curl://local-data.

Deploying for OCC

As described above, occ-root-installer depends on the server having special curl-timestamp.txt and curl-archive.car files at the curl-root of the applet. The occ-module-installer also depends on these files, and it also uses a special curl-modules.txt file to indicate inter-module dependencies. The deployment tools available through the IDE can generate these files, and manage other aspects of OCC deployment.

Checking Connection Status

An application can use the procedure network-disconnected? to determine the current connection status of the local computer, and can use this information to handle appropriately any actions that require a network connection, such as access to Internet resources.
Copyright © 1998-2019 SCSK Corporation. All rights reserved.
Curl, the Curl logo, Surge, and the Surge logo are trademarks of SCSK Corporation. that are registered in the United States. Surge Lab, the Surge Lab logo, and the Surge Lab Visual Layout Editor (VLE) logo are trademarks of SCSK Corporation.