uinhelp.asm

Dos6.0

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
;
;****

cProc	CalcNc,<PUBLIC,NEAR>,<SI,DI>
parmW	npsz
localB	retVal				; value to return on error
cBegin
	mov	retVal,HELP_NF		; default error code is HELP_NF

	mov	cx,offset szHelpFileQhelp; cs:cx = ptr to file name
	call	fQhelpActive		; are we in the help viewer
	jnz	InQhelp 		; brif so, have proper file name
	mov	cx,offset szHelpFileEdit; cs:cx = ptr to file name
	call	fEditorActive		; are we in the editor
	jnz	InQhelp 		; brif so, have proper file name
	mov	cx,offset szHelpFileInterp ; use help file for interpreter
InQhelp:

	mov	dx,WORD PTR ncInitial	; dx = high word of ncInitial
	mov	ax,WORD PTR ncInitial+2 ; ax = low word of ncInitial

	mov	bx,npsz 		; get a ptr to the string
	cmp	Byte Ptr [bx],0 	; is it a local context?
	jne	NotLocalContext 	; no, check if we have to open file
DbAssertRel	oCurTopic,ne,0,UI,<CalcNc:oCurTopic invaid>
	mov	bx,oCurTopic		; get ptr to current topic
	mov	ax,Word Ptr [bx].ContextNum ; use current NC as the initial NC
	mov	dx,Word Ptr [bx].ContextNum+2

NotLocalContext:
	mov	bx,ax			; do we have a context #?
	or	bx,dx
	jnz	GotHelpFile		; brif so -- try the lookup

	cCall	HelpOpen,<cs,cx>	; try to open the file.
					; DX:AX = ncInitial, or 0:x if failure
	or	dx,dx			; was there an error?
	jnz	SaveInitialNc		; no
	cmp	ax,HELPERR_MAX		; check the low word
	jae	SaveInitialNc		; no error, continue processing

	.erre	HELPERR_MAX LT 256	; make sure all errors fit in a byte
	.errnz	HELPERR_FNF - 1 	; these two errors should be first
	.errnz	HELPERR_READ - 2

;HELPERR_READ => error already given
;HELPERR_FNF  => error already given
; error 7     => error already given
;HELPERR_LIMIT => assert that this doesn't happen (25 help files)
;HELPERR_BADAPPEND => give ER_BFM
;HELPERR_NOTHELP => give ER_BFM
;HELPERR_BADVERS => give ER_BFM
;others        => whatever is convenient

	mov	retVal,HELP_HANDLED	; set a new return value
DbAssertRel	ax,ne,HELPERR_LIMIT,UI,<CalcNC:HELPERR_LIMIT from HelpEngine>
	cmp	ax,HELPERR_READ 	; have we already informed user?
DJMP	jbe	CalcNcExit_Err		; yes, exit in error
	cmp	ax,7			; another error we told user about?
DJMP	je	CalcNcExit_Err		; yes, exit

DbAssertTst	HelpFlags,z,HLP_INHELP,UI,<HelpStart:Recursion lock set>
	or	HelpFlags,HLP_INHELP	; set recursion lock
	PUSHI	ax,MB_OK		; only an OK button
	PUSHI	ax,ER_BFM		; It must be a bad help file
	cCall	MsgBoxStd		; display error