Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS RTL Screen Management (SMG$) Manual


Previous Contents Index


SMG$DRAW_RECTANGLE

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



SMG$ENABLE_UNSOLICITED_INPUT

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


OpenVMS usage: user_arg
type: longword (unsigned)
access: read only
mechanism: by value

A value to be passed to the AST routine. The AST-argument argument contains the value to be passed to the AST routine.

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.


SMG$END_DISPLAY_UPDATE

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.

SMG$END_PASTEBOARD_UPDATE

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.

SMG$ERASE_CHARS

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



Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
5935PRO_017.HTML