uinhelp.asm

[随书类]Dos6.0源代码

cProc	GetNextNc,<PUBLIC,NEAR>
cBegin
	and	HelpFlags,NOT (HLP_FAILFNF OR HLP_FAILOOM); clear errors
	push	dx				; value to compare against
	push	dx				; push current context number
	push	ax
	cCall	HelpNcNext			; get next Context Num
	pop	bx
	cmp	bx,dx				; is it in a different file?
	jne	GetNextNc_Err			; yes, give error
	mov	cx,ax				; check if no more contexts
	or	cx,dx				; NZ & CX != 0 if no error
	jnz	GetNextNC_exit			; exit if success
GetNextNc_Err:
	mov	al,HELP_HANDLED 		; assume handled error
	test	HelpFlags,HLP_FAILFNF OR HLP_FAILOOM ; was it?
	jnz	GetNextNc_Err2			; yes, use this code
	mov	al,HELP_NF			; context not found
GetNextNc_Err2:
	xor	cx,cx				; set CX = 0, ZF
GetNextNc_exit:
cEnd


;***
;CreateContext - convert a number into a context string
;char *(NEAR CreateContext(iContextNumber ))
;
;Purpose:
;	This routine takes a number and an initial character and
;	creates a context string out of it. The context string will
;	be of the form	"-1234" were '-' is the character and "1234"
;	is an ASCII representation of the number.  The string is
;	returned in a static buffer.
;
;	The number must be 0 < iContextNumber < 32768
;
;Entry:
;	iContextNumber : integer which will be remaining digits
;
;Exit:
;	AX = pSz : near pointer to string with results
;
;Uses:
;	AX, BX, CX, DX.
;
;****

cProc	CreateContext,<NEAR,PUBLIC>
	parmW	HelpId			
cBegin
	mov	al,VT_I2		;Format an integer
	lea	bx,HelpId		; BX = ptr to number to format

	DbAssertRel [bx],g,0,UI,<CreateContext: Bad Help ID>

	call	B$IFOUT 		;BX = address of 0 terminated string

	mov	BYTE PTR [bx],PREFIX_MESSAGE ; Replace space with character
					; that belongs in first postion
	xchg	ax,bx			;return *sz in AX
cEnd

;***
;ShrinkHelp - Compress Help system memory usage
;
;Purpose:
;	Reduce the amount of memory that the help system uses without
;	impeeding the functionallity of the help system.
;
;	WARNING!!!
;	    Any time that this routine may be called (i.e. any time an alloc
;	    is done), you must either set fNoDelBufs or guarentee that
;	    numBuf = 0, or guarentee that oCurTopic, oFirstBuf and oLastBuf
;	    are correct.
;
;Entry:
;	None.
;
;Exit:
;	None.
;
;Uses:
;	Per C Convention.
;
;****
cProc	ShrinkHelp,<PUBLIC,FAR>
cBegin

	DbHeapMoveOff			; FH callback can't cause movement

	test	HelpFlags,HLP_NOSHRINK	; are we allowed to call HelpShrink?
	jnz	NoHelpShrink		; no, check for deleting buffers
	cCall	HelpShrink		; Tell help engine to shrink down
NoHelpShrink:


	cmp	fNoDelBufs,0		; Can we delete help buffers also?
	jnz	ShrinkHelp_Exit 	; no, just return

	xor	cx,cx
	mov	cl,numBuf		; cx = # buffers in use
	jcxz	ShrinkHelp_Exit 	; exit if there are none
	cmp	oCurTopic,0		; do we have a current topic?
	jz	NoCurrentTopic		; no, do not keep it in memory
	dec	cx			; do not delete the current topic
NoCurrentTopic:
	cCall	FlushBuffer		; delete CX buffers
ShrinkHelp_Exit:


	DbHeapMoveOn			; remove our lock on the heap
cEnd

;***
;CompressHelp - Close down the help system
;
;Purpose:
;	This routine is called before we execute any user code so that
;	the help system can release all the memory that it does not need.
;
;Entry:
;	None.
;
;Exit:
;	None.
;
;Uses:
;	AX,BX,CX,DX
;
;Preserves:
;	ES
;****

cProc	CompressHelp,<PUBLIC,FAR>,<ES>	
cBegin
	DbHeapMoveOff			; we are called from FHAlloc
					; not allowed to move heaps

	test	HelpFlags,HLP_GOTBUF	; Help system started?
	jz	NoFreeHelpBuffer	; brif not -- nothing to do

	cmp	fHelpAlloc,0		; doing a help alloc?
	jnz	NoFreeHelpBuffer	; yes, do not shut down help system

	xor	ax,ax			; Nc of 0 => close all files
	cCall	HelpClose,<AX,AX>	; Shut down the help engine

	; we will ignore any file errors on the close


	cCall	DiscardHelpBookMarks	; free bookmark ptrs into help


NoHelpBuffer:
	xor	ax,ax			; get a convenient 0
	mov	iStaticHelpTopic,ax	; clear current search topic
	mov	oCurTopic,ax		; clear current topic ptr.
	mov	iCurRequestLine,ax	; clear GetHelpLine succeeded flag

	; zero the initial context number
	mov	WORD PTR ncInitial,ax	
	mov	WORD PTR ncInitial+2,ax

	or	HelpFlags,HLP_COMPRESS	; flag help has been compressed
	cCall	DrawDebugScr		; make sure screen is redrawn.

DbAssertRel	BdlHelpHist.BDL_Seg,ne,UNDEFINED,UI,<CompressHelp:HLP_GOTBUF is true, but no HistoryBuf Allocated>
	PUSHI	ax,<OFFSET DGROUP:BdlHelpHist>	; Free up the history buf
	cCall	BdlFree 		
	mov	cl,numBuf		; number of buffers to deallocate
	xor	ch,ch			
	cCall	FlushBuffer		; Delete all the help buffers
	and	HelpFlags,NOT HLP_GOTBUF ; indicate buffer unallocated

NoFreeHelpBuffer:
	DbHeapMoveOn			; remove our heap lock
cEnd



; ReWrote with [39]
;***
;GiveHelpOOM - Queue a message to give OOM for Help
;
;Purpose:
;	Indicate to the error handling code that an OOM error has occured
;	in the help system.  This routine may be called as many times as
;	desired before DisplayHelpOOM is called, and the error will only
;	be reported once.
;
;Entry:
;	None.
;
;Exit:
;	None.
;
;Uses:
;	By Convention
;
;****

cProc	GiveHelpOOM,<PUBLIC,NEAR>
cBegin
	or	HelpFlags,HLP_FAILOOM	; indicate We failed due to OOM
	mov	ax,MSG_HelpOOM		
	cCall	SetUiErr,<AX>		
cEnd

;Added with [39]
;***
;DisplayHelpOOM - Display an OOM error
;
;Purpose:
;	Displays an OOM error messages box for help, closes the help window,
;	and resets static variables.
;
;Entry:
;	None.
;
;Exit:
;	None.
;
;****

cProc	DisplayHelpOOM,<PUBLIC,NEAR>
cBegin

DbAssertTst	HelpFlags,e,HLP_INHELP,UI,<DisplayHelpOOM: Recursion lock already set>
	or	HelpFlags,HLP_INHELP	; set the recursion lock

	
	;We must save the HelpId in case the user does something like:
	;   Error 1	      -> displays a dialog box
	;   F1		      -> gets help, runs out of memory
	;   we call MsgBoxStd -> blows away iHelpId
	;   OK to message     -> back to original dialog box
	;   F1		      -> trys help again, iHelpId is invalid
	
	push	iHelpId

	PUSHI	ax,MB_OK		; Box has OK button
	PUSHI	ax,MSG_HelpOOM		; message to be displayed
	call	MsgBoxStd		; put up a dialog box
	and	HelpFlags, NOT HLP_INHELP ;remove recursion lock
	push	Word Ptr fHelpAlloc	; save the help alloc flag
	mov	fHelpAlloc,0		; zero it so CompressHelp will
	call	CompressHelp		; get help system out of the way
	mov	uierr,0 		; clear out the error condition
	pop	ax			; get fHelpAlloc back
	mov	fHelpAlloc,al		; and restore it.
	pop	iHelpId 		; restore HelpId
cEnd


;Rewritten with [38]
;***
;FlushBuffer - Deallocates buffers from HelpBuffer
;
;Purpose:
;	This routine will deallocate all buffers from (but not including)
;	the current topic to the end of the buffer.  If this is not enough,
;	it will start deleting buffers from the begining, until the specified
;	number has been reached.
;
;	If there is no current topic, we will just delete buffers from the
;	begining until we have freed enough.
;
;Entry:
;	CX = minimum # buffers to deallocate
;
;Exit:
;	None.
;
;Uses:
;	Per Convention
;****

cProc	FlushBuffer,<NEAR>,<SI,DI>
cBegin

	DbHeapMoveOff

DbAssertRelB	cl,be,MAX_HELPBUFS,UI,<FlushBuffer: Deallocating more buffers than exist>

	mov	di,cx			; DI = # buffers to delete
	cmp	oCurTopic,0		; is oCurTopic invalid?
	je	DelBegin		; yes, just delete from the begining
	mov	si,oLastBuf		; get pointer to last buffer
DelEnd_Next:

	cmp	si,oCurTopic		; have we reached the current topic?
	je	DelBegin		; yes, start deleting from begining

	lea	ax,[si].bdlHelpText	; ax = ptr to BDL in first buffer
	cCall	BdlFree,<ax>		; get rid of it

	dec	numBuf			; indicate it is no longer in use
	sub	si,BUFSIZE		; point at the last buffer
	cmp	si,OFFSET DGROUP:HelpBuffer ;did we go off the end?
	jae	NoWrap5 		; no
	add	si,BUFFERSIZE		; wrap around
NoWrap5:
	mov	oLastBuf,si		; update oLastBuf
	dec	di			; one more buffer deleted
	jmp	short DelEnd_Next	; go try again

DelBegin:
	or	di,di			; is it 0 or negative
	jle	EndFlushBuffer		; yes, exit
	mov	si,oFirstBuf		; get pointer to first buffer
DelBegin_Next:
	lea	ax,[si].bdlHelpText	; ax = ptr to BDL in first buffer
	cCall	BdlFree,<ax>		; get rid of it

	dec	numBuf			; indicate it is no longer in use

	add	si,BUFSIZE		; Point SI at next buffer
	cmp	si,BUFFEREND		; did we go off end of buffer?
	jb	NoWrap1 		; no, continue
	sub	si,BUFFERSIZE		; wrap around to begining
NoWrap1:
	dec	di			; one less to do
	jnz	DelBegin_Next		; loop again
	mov	oFirstBuf,si		; restore ptr to first buffer

EndFlushBuffer:
	DbHeapMoveOn			; reeanble heap movement

cEnd


;Reorganized with [43]
;***
;StartHelp : make sure the help system is initialized (or reinitialized)
;
;Purpose:
;	This routine is called before any references to the help buffers
;	or the help engine are made.  It makes sure the help engine is
;	activated, the help file exists, and the buffers for the virtual
;	line system are initialized.
;
;Entry:
;	None.
;
;Exit:
;	AX = 0	if all OK
;	AX = HELP_HANDLED if an error occured (will be handled).
;
;Uses:
;	Per Convention
;
;****

cProc	StartHelp,<PUBLIC,NEAR>
cBegin
DbAssertRelB	fHelpAlloc,ne,0,UI,<StartHelp:fHelpAlloc not set>

	test	HelpFlags,HLP_GOTBUF	; do we have the buffers?
DJMP	jnz	StartHelp_Success	; yes, exit with return code

	
	;Try to start help engine
	
StartHelpEngine:

DbAssertRel	BdlHelpHist.BDL_Seg,e,UNDEFINED,UI,<StartHelp:History Buffer Valid without HLP_GOTBUF>
	PUSHI	ax,<OFFSET DGROUP:BdlHelpHist>
	PUSHI	ax,HELPHIST_END 	; # bytes to allocate
	cCall	BdlAlloc		; allocate the memory
	or	ax,ax			; did we get the memory?
	jnz	InitHistBuff		; yes, go initialize it
	cCall	GiveHelpOOM		; queue an OOM error

	mov	ax,sp			; return a non-zer value
	jmp	short StartHelp_Exit

InitHistBuff:
	GETSEG	es,BdlHelpHist.BDL_Seg,bx,SIZE	; get segment
	xor	bx,bx
	mov	ES:[bx].HH_Used,bx	; initialize # elements in use
	mov	WORD PTR ES:[bx].HH_First,HELPHIST_BEGIN ; initialize ptr
	
	;Initialize HelpBuffer
	
	push	di			; Save register
	push	ds			; Set ES=DS=DGROUP
	pop	es
	mov	ax,UNDEFINED		; value to initialize buffers with
	mov	cx,BUFFERSIZE/2 	; number of words in buffer
	mov	di,OFFSET DGROUP:HelpBuffer   ; start of buffer
	mov	oFirstBuf,DI		; initialize buffer pointers
	mov	oLastBuf,DI
	rep	stosw			; initialize buffer
	mov	numBuf,CL		; initialize num in use (=0)

	pop	di			; Restore register
	or	HelpFlags,HLP_GOTBUF

StartHelp_Success:
	xor	ax,ax			; return code of success

StartHelp_Exit:
cEnd


;Rewritten with revision [57]
;***
;CalcNc - Calculate a Context Number from a Context string
;
;Purpose:
;	Go though our list of help files, calling HelpNc with the
;	initial context number for each one.  If a help file is not
;	opened, then try to open it before calling HelpNc.
;
;	If the context number is not found and there have been any
;	dialog boxes displayed (or OOM), then return HELP_HANDLED.
;	Otherwise return HELP_NF.
;
;Entry:
;	npsz - Near pointer to context string
;
;Exit:
;	if (CX <> 0)
;	    DX:AX = Context Number
;	else
;	    AL = Error Code (HELP_NF, HELP_HANDLED)
;
;Uses:
;	Per Convention
;
;****