![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to cache.3l CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10dc / 630 / man / src / p_man / man3|
Return to cache.3l CVS log | Up to [Research Unix] / researchv10dc / 630 / man / src / p_man / man3 |
1.1 root 1: .ds ZZ APPLICATION DEVELOPMENT PACKAGE
2: .TH CACHE 3L
3: .XE "cache()"
4: .SH NAME
5: cache \- put the calling application into the Application cache
6: .SH SYNOPSIS
7: .ft B
8: #include <dmd.h>
9: .br
10: #include <object.h>
11: .PP
12: .ft B
13: int cache (s, f)
14: .br
15: char \(**s;
16: .br
17: \f3int f;\f1
18: .ft R
19:
20: .SH DESCRIPTION
21: An application can put itself into the terminal's Application cache by calling
22: the function
23: .IR cache .
24: When this has been done, the window the application is running in can be
25: deleted by the user or the application can exit, but the
26: application itself is still resident in the
27: terminal's memory.
28: .PP
29: There are two ways to bring up a cached application. If the \fImenu name\fR of the
30: application shows up under the \fBMore\fR menu, the user can select
31: it and
32: open a new window to run the application. Otherwise, an
33: application can be booted from a
34: window running a 630 terminal emulator by
35: calling \fIdmdld(1)\fR with the \fItag name\fR of the application.
36: The cached application then replaces the terminal emulator in the window.
37: .PP
38: The \fItag name\fR of a cached application is the filename it is downloaded under
39: (i.e. \fIargv[0]\fR) stripped from any pathname prefix. For example the tag
40: name of \fI$HOME/dmda.out\fR is \fIdmda.out\fR. This name is used to
41: uniquely identify a cached application.
42: .PP
43: The \fImenu name\fR of a cached application is the name as appeared on the
44: \fBMore\fR menu. If the argument \fIs\fR is a null pointer, the default menu
45: name is the same as the tag name. If \fIs\fR is initialized
46: to some character string, that string will be the menu name of the cached
47: application.
48: .PP
49: The programmer can also specify how an application is cached and how it
50: will be subsequently invoked through the bit-vector argument \fIf\fR by
51: OR'ing these constant flags:
52: .IP \fBA_SHARED\fR
53: The application is cached as a shared application. A shared application
54: can have multiple copies of it running at the same time. All initialized
55: or un-initialized global and static variables of the application are also
56: shared between all the running copies, so shared applications must be
57: written accordingly. By definition the \fBA_SHARED\fR flag forces
58: the \fBA_DATA\fR and \fBA_BSS\fR flags.
59: .IP \fBA_NO_SHOW\fR
60: The application does not want to advertise itself through the \fBMore\fR
61: menu. Usually this type of application requires host support to run, thus
62: locally opening a window through the \fBMore\fR menu
63: is not sufficient. In this case, it is preferrable
64: to let the host side boot the terminal side
65: (i.e., the cached application) with \fIdmdld(1)\fR.
66: .IP \fBA_BSS\fR
67: The application does not want its un-initialized global and static variables
68: (\fI.bss\fR section) to be reset to null for subsequent invocations.
69: To conform with the default initialization rule of the C language which
70: states that un-initialized global and static variables are guaranteed to
71: be set to zero, the default for a cached application is to have its
72: un-initialized global and static variables to be cleared of all updates
73: made by previous runs before
74: a new invocation of the application starts to execute. However, for
75: shared applications or special applications that
76: want to keep data accumulated from previous runs, the \fBA_BSS\fR
77: flag can be set to prevent the \fI.bss\fR section from being cleared.
78: .IP \fBA_DATA\fR
79: The application does not want its initialized global and static variables
80: (\fI.data\fR section)
81: to be reset to the original values when the function
82: \fIcache\fR is called. By default, when the function \fIcache\fR is called,
83: an instant snapshot of the \fI.data\fR section is made and stored into memory.
84: Whenever the cached application is invoked again, the saved copy is used to
85: re-initialize the \fI.data\fR section with the original values. However, for
86: shared applications, or special applications that want to keep data
87: accumulated from previous runs, or applications that do not change the values
88: of the variables in the \fI.data\fR section and do not want memory wasted
89: for a snapshot, the \fBA_DATA\fR flag can be set to forgo the savings and copy.
90: .IP
91: \fBNOTE:\fR the original values of the variables in the \fI.data\fR section are
92: the values \fIat the time\fR the function \fIcache\fR is called. If any of these
93: variables are modified before \fIcache\fR is
94: called, the values remembered may not be the same as appeared in the source code.
95: .IP \fBA_NO_BOOT\fR
96: The application does not want to be booted from \fIdmdld\fR. Note that
97: if both \fBA_NO_BOOT\fR and \fBA_NO_SHOW\fR are set, there is no
98: way to access the cached application for invocation.
99: .IP \fBA_PERMANENT\fR
100: The applicaton cannot be removed by \fIdecache(3L)\fR or \fIucache(1)\fR.
101: ROM-resident applications are cached this way.
102: .PP
103: The default when the bit-vector argument \fIf\fR is null is to cache
104: the application as a non-shared text, which can be accessed from
105: the \fBMore\fR menu and from \fIdmdld(1)\fR, has its \fI.bss\fR section
106: cleared and its \fI.data\fR initialized before execution, and can be removed
107: from the application cache.
108: .PP
109: Besides the information supplied by the arguments, caching a downloaded
110: application requires other parameters. The most useful ones are:
111: .IP ""
112: - host connection
113: .IP ""
114: - capability to reshape
115: .IP ""
116: - default window size
117: .PP
118: The
119: .I cache
120: function
121: extracts the above information
122: from the current disposition of the application itself.
123: This relieves the programmer from supplying the many parameters,
124: and ensures a uniform user interface
125: among different cached applications.
126: .PP
127: The state of host connection of a cached application is the same as
128: of the application when the function \fIcache\fR is called. If the application is already
129: local (no host connection), the application will be cached as local; otherwise,
130: it will be cached as connected. When using the \fBMore\fR submenu to create a
131: connected cached application, the user has to select the host he wants the
132: application to be connected to through a Host submenu (like the one under the
133: item \fBNew\fR in the global menu).
134: On the other hand, when \fIdmdld\fR is used to bootstrap a local
135: cached application to replace the default terminal emulator, the previously
136: connected window will
137: automatically loose its connection (i.e. its border is changed to a checkered
138: pattern of a local window).
139: .PP
140: The capability to reshape a cached application depends on the \fINO_RESHAPE\fR
141: bit of the process state variable when the function \fIcache\fR is called.
142: If this bit is set, the application is cached as non-reshapable. When using
143: the \fBMore\fR submenu to create a non-reshapable cached application, the user
144: gets the
145: application's default window size without a sweep cursor. When \fIdmdld\fR is used
146: to bootstrap a non-reshapable cached application to replace the
147: default terminal emulator, the window is automatically reshaped
148: to the application's default window size.
149: .PP
150: The
151: cached application's default window size is determined by the \fIchar_to_bits\fR
152: function (see \fIbtoc(3R)\fR)
153: and the \fINO_RESHAPE\fR bit. If a function \fIchar_to_bits\fR is defined
154: for the application, the function \fIcache\fR will call it with three arguments:
155: 0, 0, and a pointer
156: to the application's process table to calculate the
157: default window size. The result will be stored in the Application cache, and
158: used by the terminal to generate the default outline if the application is
159: selected from the \fBMore\fR menu, or to reshape the window if the application
160: is not reshapable and is invoked from \fIdmdld\fR.
161: If the \fIchar_to_bits\fR function is not defined, but the \fINO_RESHAPE\fR bit is set, the
162: default window size will be taken as the current window size
163: of the application when the function
164: \fIcache\fR is called. If neither the function \fIchar_to_bits\fR is defined
165: nor the \fINO_RESHAPE\fR bit is set, no default window size will be displayed
166: when the user selects the application's name under the \fBMore\fR menu, and
167: the user will have to sweep a window to run the application.
168: .PP
169: All applications that are not cached with the \fBA_NO_SHOW\fR bit on, will
170: be shown on the \fBMore\fR menu. What happens when selected depends on how they are cached,
171: as explained below.
172: .PP
173: If an application is cached as shared and local, selection of the application's
174: name in the More submenu always results to the creation of a local window
175: running the chosen application.
176: .PP
177: If an application is cached as shared and connected, there will be always
178: a Host submenu connected to the application's name in the More submenu.
179: Selection will be effective only when an item in the Host submenu is picked.
180: Selection of the application's name in the More submenu is a null operation.
181: .PP
182: If an application is cached as non-shared and local, selection of the
183: application's name in the More submenu results in the creation of a local
184: window running the application, \fIif and only if\fR no other window is running
185: that application at the time. Otherwise the window running the application will
186: be made Top and Current.
187: .PP
188: If an application is cached as non-shared and connected, there will be
189: a Host submenu connected to the application's name in the More submenu,
190: \fIif and only if\fR no other window is running
191: that application at the time. Selection is effective only when an item
192: in the Host submenu is picked. If there is a window running the application
193: already, there will be no Host submenu, and selection of the application's
194: name in the More submenu results to the window running the application be
195: made Top and Current. \fI
196:
197: .SS Return Value
198: If the calling application is successfully cached, the \fIcache\fR
199: function returns a 1. Otherwise a 0 is returned.
200: .PP
201: A failure may be due to the following reasons. Another application
202: of the same \fItag name\fR is already in the cache, or the terminal
203: runs out of memory when saving the caching information.
204:
205:
206: .SH EXAMPLE
207: This is an example of a very crude terminal emulator that only
208: prints what it receives from the host.
209: This program, called \fIterm.c\fR is compiled as followed:
210: .br
211: dmdcc -o term term.c
212: .br
213: in order to have the name \fIterm\fR in the \fBMore\fR submenu.
214: .PP
215: .RS 3
216: .nf
217: .ft CM
218: .S -2
219: #include <dmd.h>
220: #include <object.h>
221:
222: main ()
223: {
224: register int c;
225: Point setsize();
226:
227:
228: P->ctob = setsize;
229: cache ((char *)0, A_SHARED);
230: /* cache as shared application */
231:
232: request (RCV);
233: while (1) { /* never ending loop */
234: wait (RCV); /* wait for a character */
235: while ((c = rcvchar()) != -1)
236: lprintf ("%c", c);
237: /* print anything received */
238: }
239: }
240:
241: Point
242: setsize () /* do not need the arguments 0, 0, P */
243: {
244: Point fPt();
245:
246: return (fPt(728, 344)); /* just a nice size */
247: }
248: .fi
249: .RE
250:
251: .SH SEE ALSO
252: dmdld(1), ucache(1),
253: btoc(3R),
254: cmdcache(3L), decache(3L),
255: local(3R), state(3R).
256:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.