CACHE(3L)

NAME
cache - put the calling application into the Application cache

SYNOPSIS
#include <dmd.h>
#include <object.h>

int cache (s, f)
char *s;
int f;

DESCRIPTION
An application can put itself into the terminal's Application cache by calling the function cache. When this has been done, the window the application is running in can be deleted by the user or the application can exit, but the application itself is still resident in the terminal's memory.

There are two ways to bring up a cached application. If the menu name of the application shows up under the More menu, the user can select it and open a new window to run the application. Otherwise, an application can be booted from a window running a 630 terminal emulator by calling dmdld(1) with the tag name of the application. The cached application then replaces the terminal emulator in the window.

The tag name of a cached application is the filename it is downloaded under (i.e. argv[0]) stripped from any pathname prefix. For example the tag name of $HOME/dmda.out is dmda.out. This name is used to uniquely identify a cached application.

The menu name of a cached application is the name as appeared on the More menu. If the argument s is a null pointer, the default menu name is the same as the tag name. If s is initialized to some character string, that string will be the menu name of the cached application.

The programmer can also specify how an application is cached and how it will be subsequently invoked through the bit-vector argument f by OR'ing these constant flags:

A_SHARED
    The application is cached as a shared application. A shared application can have multiple copies of it running at the same time. All initialized or un-initialized global and static variables of the application are also shared between all the running copies, so shared applications must be written accordingly. By definition the A_SHARED flag forces the A_DATA and A_BSS flags.

A_NO_SHOW
    The application does not want to advertise itself through the More menu. Usually this type of application requires host support to run, thus locally opening a window through the More menu is not sufficient. In this case, it is preferrable to let the host side boot the terminal side (i.e., the cached application) with dmdld(1).

A_BSS
    The application does not want its un-initialized global and static variables (.bss section) to be reset to null for subsequent invocations. To conform with the default initialization rule of the C language which states that un-initialized global and static variables are guaranteed to be set to zero, the default for a cached application is to have its un-initialized global and static variables to be cleared of all updates made by previous runs before a new invocation of the application starts to execute. However, for shared applications or special applications that want to keep data accumulated from previous runs, the A_BSS flag can be set to prevent the .bss section from being cleared.

A_DATA
    The application does not want its initialized global and static variables (.data section) to be reset to the original values when the function cache is called. By default, when the function cache is called, an instant snapshot of the .data section is made and stored into memory. Whenever the cached application is invoked again, the saved copy is used to re-initialize the .data section with the original values. However, for shared applications, or special applications that want to keep data accumulated from previous runs, or applications that do not change the values of the variables in the .data section and do not want memory wasted for a snapshot, the A_DATA flag can be set to forgo the savings and copy.

    NOTE: the original values of the variables in the .data section are the values at the time the function cache is called. If any of these variables are modified before cache is called, the values remembered may not be the same as appeared in the source code.

A_NO_BOOT
    The application does not want to be booted from dmdld. Note that if both A_NO_BOOT and A_NO_SHOW are set, there is no way to access the cached application for invocation.

A_PERMANENT
    The applicaton cannot be removed by decache(3L) or ucache(1). ROM-resident applications are cached this way.

The default when the bit-vector argument f is null is to cache the application as a non-shared text, which can be accessed from the More menu and from dmdld(1), has its .bss section cleared and its .data initialized before execution, and can be removed from the application cache.

Besides the information supplied by the arguments, caching a downloaded application requires other parameters. The most useful ones are:

    - host connection

    - capability to reshape

    - default window size

The cache function extracts the above information from the current disposition of the application itself. This relieves the programmer from supplying the many parameters, and ensures a uniform user interface among different cached applications.

The state of host connection of a cached application is the same as of the application when the function cache is called. If the application is already local (no host connection), the application will be cached as local; otherwise, it will be cached as connected. When using the More submenu to create a connected cached application, the user has to select the host he wants the application to be connected to through a Host submenu (like the one under the item New in the global menu). On the other hand, when dmdld is used to bootstrap a local cached application to replace the default terminal emulator, the previously connected window will automatically loose its connection (i.e. its border is changed to a checkered pattern of a local window).

The capability to reshape a cached application depends on the NO_RESHAPE bit of the process state variable when the function cache is called. If this bit is set, the application is cached as non-reshapable. When using the More submenu to create a non-reshapable cached application, the user gets the application's default window size without a sweep cursor. When dmdld is used to bootstrap a non-reshapable cached application to replace the default terminal emulator, the window is automatically reshaped to the application's default window size.

The cached application's default window size is determined by the char_to_bits function (see btoc(3R)) and the NO_RESHAPE bit. If a function char_to_bits is defined for the application, the function cache will call it with three arguments: 0, 0, and a pointer to the application's process table to calculate the default window size. The result will be stored in the Application cache, and used by the terminal to generate the default outline if the application is selected from the More menu, or to reshape the window if the application is not reshapable and is invoked from dmdld. If the char_to_bits function is not defined, but the NO_RESHAPE bit is set, the default window size will be taken as the current window size of the application when the function cache is called. If neither the function char_to_bits is defined nor the NO_RESHAPE bit is set, no default window size will be displayed when the user selects the application's name under the More menu, and the user will have to sweep a window to run the application.

All applications that are not cached with the A_NO_SHOW bit on, will be shown on the More menu. What happens when selected depends on how they are cached, as explained below.

If an application is cached as shared and local, selection of the application's name in the More submenu always results to the creation of a local window running the chosen application.

If an application is cached as shared and connected, there will be always a Host submenu connected to the application's name in the More submenu. Selection will be effective only when an item in the Host submenu is picked. Selection of the application's name in the More submenu is a null operation.

If an application is cached as non-shared and local, selection of the application's name in the More submenu results in the creation of a local window running the application, if and only if no other window is running that application at the time. Otherwise the window running the application will be made Top and Current.

If an application is cached as non-shared and connected, there will be a Host submenu connected to the application's name in the More submenu, if and only if no other window is running that application at the time. Selection is effective only when an item in the Host submenu is picked. If there is a window running the application already, there will be no Host submenu, and selection of the application's name in the More submenu results to the window running the application be made Top and Current.

  Return Value
If the calling application is successfully cached, the cache function returns a 1. Otherwise a 0 is returned.

A failure may be due to the following reasons. Another application of the same tag name is already in the cache, or the terminal runs out of memory when saving the caching information.

EXAMPLE
This is an example of a very crude terminal emulator that only prints what it receives from the host. This program, called term.c is compiled as followed:
    dmdcc -o term term.c
in order to have the name term in the More submenu.

    #include <dmd.h>
    #include <object.h>
    main ()
    {
    	register int c;
    	Point setsize();
    	P->ctob = setsize;
    	cache ((char *)0, A_SHARED);
    	/* cache as shared application */
    	request (RCV);
    	while (1) {		/* never ending loop */
    		wait (RCV);	/* wait for a character */
    		while ((c = rcvchar()) != -1)
    			lprintf ("%c", c);
    			/* print anything received */
    	}
    }
    Point
    setsize ()		/* do not need the arguments 0, 0, P */
    {
    	Point fPt();
    	return (fPt(728, 344));	/* just a nice size */
    }

SEE ALSO
dmdld(1), ucache(1), btoc(3R), cmdcache(3L), decache(3L), local(3R), state(3R).