![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to lqhhelp.c CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [OS/2 SDKs] / os2sdk / demos / apps / lqh|
Return to lqhhelp.c CVS log | Up to [OS/2 SDKs] / os2sdk / demos / apps / lqh |
1.1 root 1: /****************************************************************************
2:
3: PROGRAM: lqh.c
4:
5: MODULE: lqhhelp.c
6:
7: FUNCTIONS:
8: HelpSearch() - Retrieves a topic
9: PreLoad() - thread for preloading topics
10:
11:
12: ****************************************************************************/
13:
14: #include "lqh.h"
15:
16: BOOL fStructList = FALSE, fStructRequest = FALSE;
17:
18: /****************************************************************************
19:
20: FUNCTION:
21: HelpSearch(NPSZ, BOOL, NC)
22:
23: PURPOSE: Retrieves a topic from the database
24:
25: COMMENTS:
26: The first parameter of HelpSearch() points to a null-terminated
27: string that contains the name of the topic to retrieve. The second
28: paramater contains a flag. When this flag is TRUE, and the topic is
29: not found, a warning box is displayed indicating that the topic was
30: not found. In other words, TRUE means display a warning, and FALSE
31: means do not. The third parameter is an optional context number. If
32: ncContext is a nonzero value, then it is used instead of the
33: pszTopic parameter.
34:
35: The return value is TRUE if the topic was found.
36:
37: ****************************************************************************/
38:
39: BOOL HelpSearch(npszTopic, bWarn, ncContext)
40: NPSZ npszTopic;
41: BOOL bWarn;
42: NC ncContext;
43: {
44: CHAR chBuf[256];
45: NPSZ npszTmpPtr;
46: NPCH npchBuf;
47: PCH pchPtr, pchCellString, pchTmpPtr;
48: USHORT cbLen, usLines, i;
49: SHORT cbLine;
50: SEL selDeCompress; /* selector for current decompressed data */
51: NC ncRequest;
52: TOPICHDR FAR *tphdr;
53:
54: /* Call HelpNc to retrieve the context number of the topic requested
55: * in chBuf.
56: */
57:
58: if (!(ncRequest = ncContext))
59: if (!(ncRequest = HelpNc(npszTopic, ncHelp))) {
60: if (bWarn) {
61: Dstrcpy(chBuf, npszTopic);
62: Dstrcat(chBuf, " not found.");
63: BoxMessage(chBuf, atWARNING, THIN, hmou, TRUE);
64: }
65: fStructList = fBack = FALSE;
66: return FALSE;
67: }
68:
69: pchCellString = MAKEP(selStringTable, 0);
70: if (!fBack)
71: HelpNcRecord(selTable[usCurrent].ncContext); /* Save for back-tracing */
72: else
73: fBack = fStructList = FALSE;
74: if (fStructList)
75: fStructRequest = TRUE;
76: for (i = 0; i < MAXPRELOAD; i++)
77: if (selTable[i].ncContext == ncRequest)
78: break;
79:
80: /* If a selector is found that has been preloaded, then DosLockSeg is
81: * called to prevent the segment from being discarded. If DosLockSeg
82: * returns an error, then the memory was discarded. The entry in the
83: * selector table is then cleared and new memory is allocated.
84: */
85:
86: if (i < MAXPRELOAD)
87: if (DosLockSeg(selTable[i].sel)) { /* If it can't be locked, */
88: selTable[i].ncContext = (NC) 0; /* clears entry in table */
89: selTable[i].usHighLight = 0; /* no highlighting */
90: DosFreeSeg(selTable[i].sel); /* Frees the memory */
91: }
92:
93: if (i >= MAXPRELOAD || !selTable[i].ncContext) {
94:
95: /* Call HelpLook to place the compressed data into the StringTable
96: * buffer. This buffer will ultimately be used to store the
97: * character-attribute strings. HelpLook returns the amount of memory
98: * needed for the decompressed data.
99: */
100:
101: cbLen = HelpLook(ncRequest, MAKEP(selStringTable, 0));
102: if (DosAllocSeg(cbLen, &selDeCompress, SEG_DISCARDABLE)) {
103: BoxMessage(" Insufficient memory ", atWARNING,
104: THIN, hmou, TRUE);
105: return FALSE;
106: }
107:
108: /* Convert the selector to a pointer */
109:
110: pchPtr = MAKEP(selDeCompress, 0);
111:
112: /* Decompress the data */
113:
114: HelpDecomp(pchCellString, pchPtr, ncRequest);
115:
116: if (selTable[usCurrent].sel) /* unlock current selector */
117: DosUnlockSeg(selTable[usCurrent].sel);
118:
119: /* Find space in the table of selectors to store the current
120: * selector. Because the thread may be decompressing a file at the
121: * same time, the thread must be stopped until the usCurrent variable
122: * is set. The thread checks to make certain that it is not using the
123: * same usCurrent before writing data to the selTable strucutre.
124: */
125:
126: DosEnterCritSec();
127: usCurrent++;
128: if (usCurrent >= MAXPRELOAD)
129: usCurrent = 0;
130: DosExitCritSec();
131:
132: /* If the current selector is preloaded, free that selector
133: * before assigning a new one to it.
134: */
135:
136: if (selTable[usCurrent].sel)
137: DosFreeSeg(selTable[usCurrent].sel);
138: selTable[usCurrent].sel = selDeCompress;
139: selTable[usCurrent].usTopLine = 1;
140: selTable[usCurrent].usHighLight = 0;
141: selTable[usCurrent].ncContext = ncRequest;
142: }
143: else
144: usCurrent = i;
145: pchPtr = MAKEP(selTable[usCurrent].sel, 0);
146: tphdr = MAKEP(selTable[usCurrent].sel, 0);
147:
148: /* Databases are each allowed one special character that begins a line,
149: * and indicates it is a special line. QuickHelp specifies that lines
150: * beginning with a period are special lines and should be accepted.
151: */
152:
153: if (tphdr->appChar == '.') /* if control char is a period */
154: tphdr->lineChar = 0xFF; /* accept all lines */
155: else
156: tphdr->lineChar = tphdr->appChar; /* else accept none */
157:
158: usStructLine = usRefCount = 0;
159: fListDisplay = FALSE;
160:
161: /* It is necessary to keep two sets of line numbers. The variable
162: * usLines keeps track of the line number in the data file. This is used
163: * when requesting lines for pasting. The variable usTotalLines keeps
164: * track of the line numbers in the character-attribute string table.
165: */
166:
167: for (usLines = usTotalLines = 1;
168: (cbLine = HelpGetCells(usLines, 76,
169: pchCellString, pchPtr, bAttr)) != -1;
170: usLines++) {
171: if (*pchCellString == '.' && cbLine) {
172:
173: /* Lines that begin with a dot are special flags for use with
174: * QuickHelp. The following flags are accepted in lqh:
175: *
176: * .category name position
177: * Contains the category name that the current function is in,
178: * and its position in the list of functions.
179: *
180: * .ref topics
181: * Contains a list of space- or comma-separated topics
182: * (functions, structures, etc.) that will appear in
183: * the Reference menu, and that the PreLoad
184: * thread will preload.
185: *
186: * .structure
187: * Marks the beginning of a structure section.
188: *
189: * .list
190: * Means that the current topic contains a list of topics.
191: * This will cause a highlighted line to be displayed.
192: * The user may select a topic by moving the highlighted
193: * line over the desired topic and pressing the ENTER key.
194: * The first word of the line is used as the topic string
195: * to search for.
196: */
197:
198: HelpGetLine(usLines, sizeof(chBuf), chBuf, pchPtr);
199: npchBuf = chBuf + 1;
200:
201: /* .ref */
202:
203: if (chBuf[1] == 'r' && chBuf[2] == 'e' &&
204: chBuf[3] == 'f') {
205: npchBuf += 4;
206: while (*npchBuf == ' ')
207: npchBuf++;
208: npszTmpPtr = chReference;
209: MoreRef:
210: do {
211: npszRefTable[usRefCount++] = npszTmpPtr;
212: while (isalpha(*npchBuf))
213: *npszTmpPtr++ = *npchBuf++;
214: *npszTmpPtr++ = 0;
215: while (!isalpha(*npchBuf) && *npchBuf)
216: npchBuf++;
217: }
218: while (*npchBuf && usRefCount < MAXREF);
219: *chBuf = 0;
220: HelpGetLine(usLines + 1, sizeof(chBuf), chBuf, pchPtr);
221: if (strncmp(chBuf, ".ref", 4) == 0) {
222: usLines++;
223: npchBuf = chBuf + 5;
224: while (*npchBuf == ' ')
225: npchBuf++;
226: goto MoreRef; /* second reference line */
227: }
228: }
229:
230: /* .list */
231:
232: else if (chBuf[1] == 'l' && chBuf[2] == 'i' &&
233: chBuf[3] == 's' && chBuf[4] == 't') {
234: fListDisplay = TRUE;
235: if (chBuf[6] == 's')
236: fStructList = TRUE;
237: }
238:
239: /* .structure */
240:
241: else if (chBuf[1] == 's' && chBuf[2] == 't' &&
242: chBuf[3] == 'r' && chBuf[4] == 'u' &&
243: chBuf[5] == 'c')
244: usStructLine = usLines - 3;
245: }
246: else {
247: strTable[usTotalLines].addr = pchCellString;
248: strTable[usTotalLines++].cb = cbLine;
249: pchCellString += cbLine;
250: }
251: }
252:
253: /* Clear the semaphore to tell the thread to start preloading
254: * reference functions from the topic.
255: */
256:
257: usTotalLines--;
258: if (fListDisplay && !selTable[usCurrent].usHighLight)
259: selTable[usCurrent].usHighLight = 1;
260: if (usStructLine && fStructRequest) {
261: selTable[usCurrent].usTopLine = usStructLine;
262: fStructList = fStructRequest = FALSE;
263: }
264: DosSemClear((HSEM) &hsemNewRef);
265: return TRUE;
266: }
267:
268: /****************************************************************************
269:
270: THREAD: PreLoadThread
271:
272: COMMENTS:
273: In order to maximize response time, this thread preloads any
274: reference functions specified by the current function. First, it
275: waits until the hsemNewRef semaphore is cleared, which indicates
276: that a new function has been loaded. It then goes through the
277: reference table and preloads all the functions. If the hsemNewRef
278: semaphore is set before the thread completes its loop, it breaks
279: out of the loop, goes to its begining and waits for the semaphore
280: to clear.
281:
282: The thread is allowed to run only when the main process is waiting
283: for input. The Input function controls this by resuming thread
284: execution when it is called, and suspending thread execution before
285: it returns.
286:
287: This thread maintains its own pointer into the table of preloaded
288: selectors, and cycles through all selectors in a continuous loop.
289:
290: ****************************************************************************/
291:
292: USHORT usPreLoad = 10; /* Maintains preload position */
293:
294: VOID FAR PreLoadThread() {
295: USHORT cbLen;
296: INT i;
297: register INT j;
298: NC ncRequest;
299: SEL selDeCompress, selCompress;
300:
301: Loop:
302: for (;;) {
303:
304: /* Do not begin processing until the semaphore is cleared, indicating
305: * that a new topic has been loaded.
306: */
307:
308: while (DosSemWait((HSEM) &hsemNewRef, -1L));
309: DosSemSet((HSEM) &hsemNewRef);
310: if (!usRefCount)
311: continue;
312:
313: for (i = 0; i <= usRefCount; i++) { /* Preloads all references */
314: if (i == usRefCount)
315: ncRequest = HelpNcNext(selTable[usCurrent].ncContext);
316: else
317: ncRequest = HelpNc(npszRefTable[i], ncHelp);
318: if (ncRequest) {
319: for (j = 0; j < MAXPRELOAD; j++)
320: if (selTable[j].ncContext == ncRequest)
321: break; /* already preloaded */
322: if (j >= MAXPRELOAD) {
323: if (DosAllocSeg(HelpNcCb(ncRequest), &selCompress, 0))
324: break; /* Halts if allocation fails */
325:
326: cbLen = HelpLook(ncRequest, MAKEP(selCompress, 0));
327: if (DosAllocSeg(cbLen, (PSEL) &selDeCompress,
328: SEG_DISCARDABLE)) {
329: DosFreeSeg(selCompress);
330: break; /* Halts if allocation fails */
331: }
332: if (HelpDecomp(MAKEP(selCompress, 0),
333: MAKEP(selDeCompress, 0), ncRequest)) {
334: DosFreeSeg(selCompress);
335: DosFreeSeg(selDeCompress);
336: continue;
337: }
338: DosFreeSeg(selCompress);
339: while (usPreLoad == usCurrent)
340: if (++usPreLoad >= MAXPRELOAD)
341: usPreLoad = 0;
342:
343: /* It is crucial that the thread not change the
344: * selTable structure at the same time that HelpSearch is
345: * accessing it. The HelpSearch thread is suspended long
346: * enough to confirm that the table is safe, and
347: * is resumed only after writing to the table has
348: * been completed. The HelpSearch function has a
349: * similar critical section to prevent writing to the
350: * selTable structure at the same time as the thread.
351: */
352:
353: DosEnterCritSec(); /* Suspends other threads */
354: if (usPreLoad == usCurrent) {
355: DosExitCritSec();
356: goto Loop;
357: }
358:
359: if (selTable[usPreLoad].sel)
360: DosFreeSeg(selTable[usPreLoad].sel);
361: selTable[usPreLoad].sel = selDeCompress;
362: selTable[usPreLoad].usTopLine = 1;
363: selTable[usPreLoad].usHighLight = 0;
364: selTable[usPreLoad].ncContext = ncRequest;
365: DosUnlockSeg(selTable[usPreLoad].sel);
366: DosExitCritSec();
367: if (++usPreLoad >= MAXPRELOAD)
368: usPreLoad = 0;
369: }
370:
371: /* If the semaphore is cleared, a new topic was loaded,
372: * so the loop must start over again.
373: */
374:
375: if (!DosSemWait((HSEM) &hsemNewRef, 0L))
376: goto Loop;
377: }
378: }
379: }
380: }
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.