Document revision date: 30 March 2001

The Draw a Rectangle routine draws a rectangle.

Format

SMG$DRAW_RECTANGLE display-id ,start-row ,start-column ,end-row ,end-column [,rendition-set] [,rendition-complement]

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Arguments

display-id

OpenVMS usage:	identifier
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Specifies the virtual display on which the rectangle is to be drawn. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

start-row

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	read only
mechanism:	by reference

Specifies the row number of the top left corner of the rectangle. The start-row argument is the address of a signed longword that contains the row number of the top left corner of the rectangle.

start-column

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	read only
mechanism:	by reference

Specifies the column number of the top left corner of the rectangle. The start-column argument is the address of a signed longword that contains the column number of the top left corner of the rectangle.

end-row

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	read only
mechanism:	by reference

Specifies the row number of the bottom right corner of the rectangle. The end-row argument is the address of a signed longword that contains the row number of the bottom right corner of the rectangle.

end-column

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	read only
mechanism:	by reference

Specifies the column number of the bottom right corner of the rectangle. The end-column argument is the address of a signed longword that contains the column number of the bottom right corner of the rectangle.

rendition-set

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument:

SMG$M_BLINK	Displays blinking characters.
SMG$M_BOLD	Displays characters in higher-than-normal intensity.
SMG$M_REVERSE	Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display.
SMG$M_UNDERLINE	Displays underlined characters.
SMG$M_INVISIBLE	Specifies invisible characters; that is, the characters exist in the virtual display but do not appear on the pasteboard.
SMG$M_USER1 through SMG$M_USER8	Displays user-defined attributes.

The display-id argument must be specified when you use the rendition-set argument.

rendition-complement

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Attribute complement specifier. The optional rendition-complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All of the attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument.

The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, while rendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition-complement parameters, rendition-set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations:

Set	Complement	Action
0	0	Attribute set to default
1	0	Attribute on
0	1	Attribute set to complement of default setting
1	1	Attribute off

Description

SMG$DRAW_RECTANGLE draws a rectangle in a virtual display, given the position of the upper left corner and the lower right corner. Note that this routine does not change the virtual cursor position. The characters used to draw the lines making up the rectangle depend on the type of terminal. If possible, SMG$ uses the terminal's line-drawing character set. If that is not available, SMG$ uses the plus sign (+), minus sign (--), and vertical bar (|) to draw the lines.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
SMG$_INVCOL	Invalid column number. The specified column is outside the virtual display.
SMG$_INVDIS_ID	Invalid display-id.
SMG$_INVROW	Invalid row number. The specified row is outside the virtual display.
SMG$_WRONUMARG	Wrong number of arguments.

Example

    
C+ 
C This Fortran example program demonstrates the use of 
C SMG$DRAW_RECTANGLE. 
C 
C This routine creates a virtual display and uses SMG$DRAW_RECTANGLE 
C to draw a rectangle inside the bordered virtual display. 
C- 
 
C+ 
C Include the SMG definitions. In particular, we want SMG$M_BORDER. 
C- 
 
        INCLUDE '($SMGDEF)' 
        INTEGER SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD 
        INTEGER SMG$PASTE_VIRTUAL_DISPLAY, SMG$DRAW_RECTANGLE 
        INTEGER DISPLAY1, PASTE1, ROWS, COLUMNS, STATUS 
 
C+ 
C Create a virtual display with a border by calling 
C SMG$CREATE_VIRTUAL_DISPLAY. 
C- 
 
        ROWS = 7 
        COLUMNS = 50 
 
        STATUS = SMG$CREATE_VIRTUAL_DISPLAY 
     1                    (ROWS, COLUMNS, DISPLAY1, SMG$M_BORDER) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
C+ 
C Use SMG$CREATE_PASTEBOARD to create the pasteboard. 
C- 
 
        STATUS = SMG$CREATE_PASTEBOARD (PASTE1) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
C+ 
C Using SMG$DRAW_RECTANGLE, draw a rectangle inside the bordered region. 
C- 
 
        STATUS = SMG$DRAW_RECTANGLE (DISPLAY1, 2, 10, 6, 20) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
C+ 
C Paste the virtual display by calling SMG$PASTE_VIRTUAL_DISPLAY. 
C- 
 
        STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 15) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
        END 
 
      

The output generated by this Fortran example is shown in Figure SMG-18.

Figure SMG-18 Output Generated by Fortran Program Calling SMG$DRAW_RECTANGLE

The Enable Unsolicited Input routine detects unsolicited input and calls an AST routine in response.

Format

SMG$ENABLE_UNSOLICITED_INPUT pasteboard-id ,AST-routine [,AST-argument]

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Arguments

pasteboard-id

OpenVMS usage:	identifier
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Specifies the pasteboard for which unsolicited input is being enabled. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

The pasteboard identifier is returned by SMG$CREATE_VIRTUAL_PASTEBOARD.

AST-routine

OpenVMS usage:	ast_procedure
type:	procedure value
access:	read only
mechanism:	by value

AST routine to be called upon receipt of unsolicited input at the terminal. The AST-routine argument contains the routine's procedure value. SMG$ENABLE_UNSOLICITED_INPUT detects the presence of unsolicited input and calls the AST routine with six arguments: the pasteboard-id, the AST-argument, R0, R1, PC, and PSL (on VAX systems) or PS (on Alpha systems). The AST routine arguments are shown in Figure SMG-19.

Figure SMG-19 AST Routine Arguments

AST-argument

Description

SMG$ENABLE_UNSOLICITED_INPUT detects the presence of unsolicited input and calls an AST routine in response.

Note that this routine does not read any input characters; it merely calls an AST routine to "notify" the application that it should issue a read operation with SMG$READ_COMPOSED_LINE, SMG$READ_KEYSTROKE, SMG$READ_STRING or SMG$READ_VERIFY. It is up to you to read the unsolicited input.

SMG$ENABLE_UNSOLICITED_INPUT establishes a mailbox that receives messages when terminal-related events occur that require the attention of the user image. This mailbox carries status messages, not terminal data, from the driver to the user program. This status message is sent to the mailbox when there is unsolicited data in the type-ahead buffer. In this case, the user process enters into a dialogue with the terminal after an unsolicited data message arrives. Once this dialogue is complete, the Screen Management Facility reenables the unsolicited data message function on the last I/O exchange. Only one message is sent between read operations. (The SYSGEN parameters DEFMBXBUFQUO and DEFMBXMXMSG are used when creating the mailbox.)

Condition Values Returned

SS$_NORMAL	Normal successful completion.
SMG$_INVPAS_ID	Invalid pasteboard-id.
SMG$_WRONUMARG	Wrong number of arguments.

Any condition values returned by $QIOW.

Example

For an example using SMG$ENABLE_UNSOLICITED_INPUT, see the example for the SMG$DISABLE_BROADCAST_TRAPPING routine.

The End Display Update routine ends update batching for a virtual display.

Format

SMG$END_DISPLAY_UPDATE display-id

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Argument

display-id

OpenVMS usage:	identifier
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Specifies the virtual display to be affected. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

Description

SMG$END_DISPLAY_UPDATE and SMG$BEGIN_DISPLAY_UPDATE work together to control the batching of output operations on a given virtual display. Each call to SMG$BEGIN_DISPLAY_UPDATE increments a batch count. Each call to SMG$END_DISPLAY_UPDATE decrements this count. When the batch count reaches 0, the virtual display is updated with all operations done under batching, and written to the pasteboard if the virtual display is pasted.

Calling SMG$END_DISPLAY_UPDATE when the batch count is zero is a valid operation; therefore a success status is returned.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
SMG$_BATSTIPRO	Successful completion. Note that batching is still in progress.
SMG$_BATWASOFF	Successful completion. Note that batching was already off.
SMG$_INVDIS_ID	Invalid display-id.
SMG$_WRONUMARG	Wrong number of arguments.

The End Pasteboard Update routine ends update batching for a pasteboard.

Format

SMG$END_PASTEBOARD_UPDATE pasteboard-id

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Argument

pasteboard-id

OpenVMS usage:	identifier
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Specifies the pasteboard on which the batch count is to be decremented. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD. If the batch count reaches 0, all buffered output for the specified pasteboard is written out.

Description

SMG$END_PASTEBOARD_UPDATE and SMG$BEGIN_PASTEBOARD_UPDATE work together to control the batching of output operations on a given pasteboard. Each call to SMG$BEGIN_PASTEBOARD_UPDATE increments a batch count. Each call to SMG$END_PASTEBOARD_UPDATE decrements this count. When the batch count reaches 0, the pasteboard is written to the screen.

Calling SMG$END_PASTEBOARD_UPDATE when the batch count is 0 is a valid operation; a success status is returned.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
SMG$_BATSTIPRO	Successful completion. Note that batching is still in progress.
SMG$_BATWASOFF	Successful completion. Note that batching was already off.
SMG$_INVDIS_ID	Invalid display-id.
SMG$_WRONUMARG	Wrong number of arguments.

The Erase Characters routine erases characters in a virtual display by replacing them with blanks.

Format

SMG$ERASE_CHARS display-id ,number-of-characters ,start-row ,start-column

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Arguments

display-id

OpenVMS usage:	identifier
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Specifies the virtual display from which characters will be erased. The display-id argument is the address of an unsigned longword that contains the display identifier.

The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

number-of-characters

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	read only
mechanism:	by reference

Specifies the number of characters to be replaced with blanks. The number-of-characters argument is the address of a signed longword that contains the number of characters to be replaced with blanks.

start-row

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	read only
mechanism:	by reference

Specifies the row on which the erase operation begins. The start-row argument is the address of a signed longword that contains the number of the row at which the erasure is to begin.

start-column

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	read only
mechanism:	by reference

Specifies the column on which the erase operation begins. The start-column argument is the address of a signed longword that contains the number of the column at which the erasure is to begin.

Description

SMG$ERASE_CHARS erases characters in a virtual display by replacing them with blanks. The remaining text in the display is not moved. An erase operation is limited to the specified line. If number-of-characters is greater than the number of characters remaining in the line, all characters from the specified starting position to the end of the line are erased. This routine leaves the virtual cursor at the position of the first character erased.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
SMG$_INVCOL	Invalid column.
SMG$_INVDIS_ID	Invalid display-id.
SMG$_INVROW	Invalid row.
SMG$_WRONUMARG	Wrong number of arguments.

Example

   
 
C+ 
C This Fortran example demonstrates the use of SMG$ERASE_CHARS. 
C 
C Include the SMG definitions. In particular, we want SMG$M_BORDER. 
C- 
 
        IMPLICIT INTEGER (A-Z) 
        INCLUDE '($SMGDEF)' 
 
C+ 
C Create a virtual display with a border by calling 
C SMG$CREATE_VIRTUAL_DISPLAY. 
C- 
 
        ROWS = 7 
        COLUMNS = 50 
 
        STATUS = SMG$CREATE_VIRTUAL_DISPLAY 
     1          (ROWS, COLUMNS, DISPLAY1, SMG$M_BORDER) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
C+ 
C Call SMG$CREATE_PASTEBOARD to create the pasteboard. 
C- 
 
        STATUS = SMG$CREATE_PASTEBOARD (PASTE1) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
C+ 
C Using SMG$PUT_CHARS, put data in the virtual display. 
C- 
 
        STATUS = SMG$PUT_CHARS ( DISPLAY1, 
     1  ' This virtual display has 7 rows and 50 columns.', 2, 1) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
        STATUS = SMG$PUT_CHARS ( DISPLAY1, 
     1          ' This is a bordered virtual display.', 4, 1) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
        STATUS = SMG$PUT_CHARS ( DISPLAY1, 
     1  ' SMG$PUT_CHARS puts data in this virtual display.', 6, 1) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
C+ 
C Call SMG$PASTE_VIRTUAL_DISPLAY to paste the virtual display. 
C- 
 
        STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 15) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
C+ 
C Erase 4 characters on row 4 starting from character (column) 14 by 
C calling SMG$ERASE_CHARS.  This will remove the characters "rder" 
C from the word "bordered". 
C- 
 
        STATUS = SMG$ERASE_CHARS ( DISPLAY1, 4, 4, 14) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
        END 
 
 
      

The initial output generated by this Fortran example program is shown in Figure SMG-20.

Figure SMG-20 Output Before the Call to SMG$ERASE_CHARS

The output generated after the call to SMG$ERASE_CHARS is shown in Figure SMG-21.

Figure SMG-21 Output After the Call to SMG$ERASE_CHARS

	privacy and legal statement
5935PRO_017.HTML