![[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.