From:	CRDGW2::CRDGW2::MRGATE::"SMTP::CRVAX.SRI.COM::RELAY-INFO-VAX" 23-JUN-1989 09:13
To:	MRGATE::"ARISIA::EVERHART"
Subj:	SMG$READ_VERIFY example WITH comments

Received: From KL.SRI.COM by CRVAX.SRI.COM with TCP; Thu, 22 JUN 89 11:46:10 PDT
Received: from ucbvax.Berkeley.EDU by KL.SRI.COM with TCP; Thu, 22 Jun 89 11:34:43 PDT
Received: by ucbvax.Berkeley.EDU (5.61/1.37)
	id AA06371; Thu, 22 Jun 89 11:24:56 -0700
Received: from USENET by ucbvax.Berkeley.EDU with netnews
	for info-vax@kl.sri.com (info-vax@kl.sri.com)
	(contact usenet@ucbvax.Berkeley.EDU if you have questions)
Date: 22 Jun 89 17:10:29 GMT
From: bsu-cs!cfchiesa@iuvax.cs.indiana.edu  (Christopher Chiesa)
Organization: CS Dept, Ball St U, Muncie, IN, USA
Subject: SMG$READ_VERIFY example WITH comments
Message-Id: <7890@bsu-cs.bsu.edu>
Sender: info-vax-request@kl.sri.com
To: info-vax@kl.sri.com


;++
;
; SMG$READ_VERIFY example in Vax MACRO, by Chris Chiesa, 6/16/89
;
;   This program demonstrates a very simple usage of the SMG$READ_VERIFY
; routine.  A screen is presented with a prompt to "enter a telephone
; number; the user may then type digits (0-9), and SMG$READ_VERIFY automatically
; formats the input data and screen-echo as a phone number.  Simple editing
; with the DELETE key is supported.  Input terminates on any non-numeric-digit
; input character, OR on any character input beyond the size limit of the 
; "input field," in this case beyond the end of a 10-digit telephone number.
; When input terminates, the character string returned by SMG$READ_VERIFY is
; output to the screen to show what was received; this allows you to experi-
; ment with various combinations of invalid input, premature termination,
; etc.
;
;--
		$TRMDEF
		$SMGDEF

		.PSECT	DATA	WRT,NOEXE
;
; Data definitions.  SMG$ conveniently uses LONGWORDs for nearly everything:
;

PBID:		.BLKL		; Pasteboard ID
VDID:		.BLKL		; Virtual Display ID
KBID:		.BLKL		; Virtual Keyboard ID

STATUS:		.BLKL		; Status value (returned)

ROW:		.BLKL		; Row or Line number
COL:		.BLKL		; Column number

VDAT:		.BLKL		; Virtual Display "attributes" (borders, etc.)

;
; Just for laughs, I send a "title" string to the screen...
;

TITLE:		.ASCID	/- Enter a phone number -/

; 
; The following data items are SMG$READ_VERIFY parameters:
;
;---
; The string returned from the call, goes here:

OUT_STRING:	.ASCID	/              /	

;++
;
;  The IN-STRING parameter specifies two things: characters to be output to
; echoed to the display, in positions where PATTERN-STRING specifies a "mask" 
; character; and fill characters to be returned in the OUT-STRING in posi-
; tions where no valid input data was obtained.  You can observe this first
; function by simply typing numbers and watching the formatting take place,
; and the second function by typing several numbers and then a non-numeric
; character and noting the X's in the "received" string.
;
;--

IN_STRING:	.ASCID	/(XXX) XXX-XXXX/	

;++
;
;   The PIC-STRING parameter specifies, on a character-by-character basis, 
; the "classes" of characters ("NUMERIC," "UPPERCASE," "LOWERCASE,", "NUMPUNC"
; (numeric punctuation, e.g. "+" or "-"), etc. -- these may be ANDed together
; to allow more than one class per character position...  In this case, the
; "string descriptor" for the PIC_STRING points to a manually-constructed
; list of these "mask" values.  The pattern of mask values "lines up" with
; the formatting characters in the IN_STRING, to perform input verification
; and formatting.
;
;--

PIC_STRING:	.WORD	<MASK_END-MASK_LIST>
		.WORD	0
		.ADDRESS MASK_LIST

;
; The FILL-CHAR and CLEAR-CHAR work together: when editing (backspacing) input
; with the DELete key, if you remove a data character from a position where
; the FILL-CHAR appears in IN-STRING, the CLEAR-CHAR is displayed in that posi-
; tion; if input terminates before a new valid character is obtained, the 
; FILL-CHAR is returned in that position.
;

FILL_CHAR:	.ASCID	/X/
CLEAR_CHAR:	.ASCID	/./

;
; SMG$READ_VERIFY -- and even list-directed QIO itself -- conveniently allow
; for input prompting.  Just gotta love this OS !  :-)
;

PROMPT_STRING:	.ASCID	/Phone: /

; 
; There are a whole slew of modifiers.  It seems to be the case that QIO list-
; directed-I/O modifiers *NOT* present on the list of "valid modifiers" in the
; SMG$READ_VERIFY documentation *DO* have some effect here, but I haven't 
; investigated it.
;
; The modifier value currently here, TRM$M_TM_NOECHO, suppresses ONLY the echo
; of the character which TERMINATES the SMG$READ_VERIFY operation.  I found
; the additional-character echo made the display "messy."
;
; Note also that the program as presented currently performs "left justified"
; input.  Right-justified (it scrolls; really neat-looking) input is also
; possible, by ANDing in the TRM$M_TM_R_JUST modifier here, and changing the
; value used for INI-OFFSET (see code).
;

MODIFIERS:	.LONG	TRM$M_TM_TRMNOECHO

; 
; The explanation of this parameter in the manuals is ... well... not great,
; but I figured out how to use it.  Use '0' for a left-justified field, or
; length-of-in-string for a right-justified field.  (Don't forget the 
; TRM$M_TM_R_JUST modifier, for a right-justified field.)
;

INI_OFFSET:	.BLKL

;
; The SMG$K_TRM_'whatever' key value of the input-terminating character is
; returned by SMG$READ_VERIFY; I don't use it in this program.
;
TERMINATOR_CODE: -
		.BLKL

;
; The following list of "mask" values is what determines the validation of
; input on a character-by-character basis.  This is the 'string' part of the
; PIC-STRING parameter; for best results it should "line up" with the corres-
; ponding positions of the INI-STRING parameter.
;
; A value of 0 in the mask, indicates that the corresponding character posi-
; tion should be automatically filled-in from INI-STRING, rather than from
; input data, and should in effect be "skipped around" in all data-entry and
; editing operations while processing the SMG$READ_VERIFY call.
;
; Compare the pattern of 0's and TRM$M_CV_NUMERIC's in this mask, with the
; pattern of punctuation vs. fill-characters in the INI-STRING.
;

MASK_LIST:	.BYTE	0			; "Mask" character
		.BYTE	TRM$M_CV_NUMERIC	; Accept only 0-9
		.BYTE	TRM$M_CV_NUMERIC	;   .
		.BYTE	TRM$M_CV_NUMERIC	;   .
		.BYTE	0			;   .
		.BYTE	0			; etc...
		.BYTE	TRM$M_CV_NUMERIC	;   .
		.BYTE	TRM$M_CV_NUMERIC	;   .
		.BYTE	TRM$M_CV_NUMERIC	;   .
		.BYTE	0
		.BYTE	TRM$M_CV_NUMERIC
		.BYTE	TRM$M_CV_NUMERIC
		.BYTE	TRM$M_CV_NUMERIC
		.BYTE	TRM$M_CV_NUMERIC
MASK_END:		

;
; Believe it or not, that suffices for the data-declaration part of the 
; program.  The executable code follows.
;
		.PSECT	CODE	NOWRT,EXE

		.ENTRY	READ_VERIFY_TEST,^M<>
;
;  Standard SMG$ housekeeping...  Create pasteboard, create virtual display,
;    paste display onto pasteboard.
;
		MOVL	#24,ROW
		MOVL	#80,COL
		PUSHAL	COL
		PUSHAL	ROW
		PUSHL	#0
		PUSHAL	PBID
		CALLS	#4,G^SMG$CREATE_PASTEBOARD
		BLBS	R0,100$
		JMP	ERROR

;
; *I* don't need a Virtual Keyboard, but SMG$READ_VERIFY does, so I create
; one and never use it for anything special.
;

100$:		PUSHAL	KBID
		CALLS	#1,G^SMG$CREATE_VIRTUAL_KEYBOARD
		BLBS	R0,200$
		JMP	ERROR

200$:		MOVL	#9,ROW
		MOVL	#37,COL
		MOVL	#SMG$M_BORDER,VDAT	; "Bordered" display attribute
		PUSHAL	VDAT
		PUSHAL	VDID
		PUSHAL	COL
		PUSHAL	ROW
		CALLS	#4,G^SMG$CREATE_VIRTUAL_DISPLAY
		BLBS	R0,300$
		JMP	ERROR


300$:		MOVL	#7,ROW
		MOVL	#20,COL
		PUSHAL	COL
		PUSHAL	ROW
		PUSHAL	PBID
		PUSHAL	VDID
		CALLS	#4,G^SMG$PASTE_VIRTUAL_DISPLAY
		BLBS	R0,400$
		JMP	ERROR

;
;  Just for "niceness," I display a title ...
;

400$:		MOVL	#1,ROW
		MOVL	#7,COL
		PUSHAL	COL
		PUSHAL	ROW
		PUSHAQ	TITLE
		PUSHAL	VDID
		CALLS	#4,G^SMG$PUT_CHARS
		BLBS	R0,500$
		JMP	ERROR
;
;  The documentation for SMG$READ_VERIFY notes that "... batching must be OFF.."
;  for the Pasteboard and Virtual Display in which the SMG$READ_VERIFY call
;  takes place, for proper operation.  SMG$END_DISPLAY_UPDATE and 
;  SMG$END_PASTEBOARD_UPDATE perform this function.  Note that in a more
;  intricate environment, one would need to call these functions repeatedly 
;  until a successful status OTHER THAN "SMG$_BATSTIPRO" ("Batching still in
;  progress") is returned.  In this program, batching was NEVER ON, but I 
;  wanted to show you this anyway.
;
500$:		PUSHAL	VDID
		CALLS	#1,G^SMG$END_DISPLAY_UPDATE
		BLBS	R0,700$
		JMP	ERROR

700$:		PUSHAL	PBID
		CALLS	#1,G^SMG$END_PASTEBOARD_UPDATE
		BLBS	R0,900$
		JMP	ERROR
;
;  If I don't explicitly move the cursor to a different row and column, 
; SMG$READ_VERIFY attempts to perform its input (prompt, input field, etc.)
; at the "last cursor position" in the specified Virtual Display.  In this
; case, that would be at the end of the "title" I displayed, so I explicitly
; set a "good" cursor position.  (Note - SMG$READ_VERIFY will fail if the
; cursor position, prompt length, and input-field length combine to try to
; "go beyond the right edge" of the virtual display.)
;

900$:		MOVL	#6,ROW
		MOVL	#2,COL
		PUSHAL	COL
		PUSHAL	ROW
		PUSHAL	VDID
		CALLS	#3,G^SMG$SET_CURSOR_ABS
		BLBS	R0,1350$
		JMP	ERROR

;
; And now, what you've all been waiting for...  
;

;
; Set INI-OFFSET to 0 for left-justified field.  This would've been a 
; "MOVZWL  IN_STRING,INI_OFFSET" -- giving INI-OFFSET the "length of the
; input field" -- if I were doing a right-justified field.  (Try it your-
; self and see! -- don't forget the right-justification MODIFIER flag.)
;

1350$:		CLRL	INI_OFFSET		

;
; And now, everything is set up properly, so go do the SMG$READ_VERIFY !
;
		PUSHAL	VDID			; Virt. Display in which to read
		PUSHAW	TERMINATOR_CODE		; Receives terminating keycode
		PUSHAL	INI_OFFSET		; See above
		PUSHL	#0			; "TERMINATOR-SET" OMITTED
		PUSHL	#0			; "TIMEOUT" OMITTED
		PUSHAL	MODIFIERS
		PUSHAQ	PROMPT_STRING	
		PUSHAQ	CLEAR_CHAR
		PUSHAQ	FILL_CHAR
		PUSHAQ	PIC_STRING
		PUSHAQ	IN_STRING
		PUSHAQ	OUT_STRING
		PUSHAL	KBID
		CALLS	#13,G^SMG$READ_VERIFY		; DO IT!!!  :-)
		BLBS	R0,1400$
		JMP	ERROR

;
; The string has been obtained, formatted and all, but since there's a 
; FILL-CHAR that's different from the CLEAR-CHAR displayed so far, it's
; nice to get a look at the actual string that came back.
;

1400$:		MOVL	#8,ROW			; put it lower on the display
		MOVL	#2,COL
		PUSHAL	COL
		PUSHAL	ROW
		PUSHAQ	OUT_STRING		; resulting from SMG$READ_VERIFY
		PUSHAL	VDID
		CALLS	#4,G^SMG$PUT_CHARS	; display it
		BLBS	R0,1500$
		JMP	ERROR
1500$:						; that be all!
		RET

;
; I probably ought to unpaste the virtual display and so on, but I didn't
; take the time.  What the heck, it's only a demo...  ":-)
;

ERROR:
		$EXIT_S	R0			; error messages if something
						;   fails

		.END	READ_VERIFY_TEST
-- 
UUCP: <backbones>!{iuvax,pur-ee,uunet}!bsu-cs!cfchiesa 
cfchiesa@bsu-cs.UUCP                                           

