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

Following a call to SMG$PUT_LINE, the virtual cursor position is set to column 1 of the next line where output should occur. The next line where output should occur is determined by the line-advance and direction arguments; line-advance defaults to 1 so that subsequent calls to SMG$PUT_LINE do not cause overprinting.

Other SMG$ procedures that can be used to write lines of text to a virtual display are SMG$PUT_LINE_WIDE, SMG$PUT_LINE_HIGHWIDE, SMG$PUT_LINE_MULTI, and SMG$INSERT_LINE.


Condition Values Returned

SS$_NORMAL Normal successful completion.
SMG$_INVDIS_ID Invalid display-id.
SMG$_WILUSERMS Pasteboard is not a video terminal.
SMG$_WRONUMARG Wrong number of arguments.
LIB$_INVSTRDES Invalid string descriptor.

Examples

#1

C+ 
C This Fortran example program demonstrates the use of SMG$PUT_LINE. 
C- 
 
C+ 
C Include the SMG definitions. In particular, we want SMG$M_BORDER and 
C SMG$M_UNDERLINE. 
C- 
 
        IMPLICIT INTEGER (A-Z) 
        INCLUDE '($SMGDEF)' 
        CHARACTER*30 TEXT(3) 
 
C+ 
C Create a virtual display with a border. 
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 Create the pasteboard. 
C- 
 
        STATUS = SMG$CREATE_PASTEBOARD (PASTE1) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
 
C+ 
C Put data in the virtual display. 
C- 
 
        TEXT(1) = 'This virtual display has 7' 
        TEXT(2) = 'rows and 50 columns.' 
        TEXT(3) = 'Text entered by SMG$PUT_LINE.' 
 
C+ 
C After the first line of text is printed, call SMG$PUT_LINE to 
C advance two lines. 
C- 
 
        STATUS = SMG$PUT_LINE ( DISPLAY1, TEXT(1), 2 ) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
C+ 
C Now, use SMG$PUT_LINE to underline the next line of text. 
C Notice that 30 characters are being underlined. Advance one 
C line of text after displaying the line. 
C- 
 
        STATUS = SMG$PUT_LINE ( DISPLAY1, TEXT(2), 1, SMG$M_UNDERLINE ) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
C+ 
C Display the third line of text. 
C- 
 
        STATUS = SMG$PUT_LINE ( DISPLAY1, TEXT(3) ) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
C+ 
C Paste the 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 program is shown in Figure SMG-34.

Figure SMG-34 Output Generated by Fortran Program Calling SMG$PUT_LINE


This program uses the direction argument to SMG$PUT_LINE:
#2

C+ 
C This Fortran example program demonstrates the use of the DIRECTION 
C argument in the SMG$PUT_LINE routine. 
C- 
       INCLUDE '$SMGDEF' 
       IMPLICIT INTEGER*4 (A-Z) 
C+ 
C Call SMG$CREATE_PASTEBOARD to establish the terminal screen 
C as a pasteboard. 
C- 
       STATUS = SMG$CREATE_PASTEBOARD (NEW_PID) 
       IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) 
 
C+ 
C Call SMG$CREATE_VIRTUAL_DISPLAY to establish a virtual display region. 
C- 
       STATUS = SMG$CREATE_VIRTUAL_DISPLAY (5,80,DISPLAY_ID) 
       IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) 
C+ 
C Paste the virtual display to the screen, starting at 
C row 10, column 15, by calling SMG$PASTE_VIRTUAL_DISPLAY. 
C- 
       STATUS = SMG$PASTE_VIRTUAL_DISPLAY(DISPLAY_ID,NEW_PID,10,15) 
       IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) 
C+ 
C Define a scrolling region by calling SMG$SET_DISPLAY_SCROLL_REGION. 
C- 
       STATUS = SMG$SET_DISPLAY_SCROLL_REGION(DISPLAY_ID,1,5) 
       IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) 
C+ 
C Call SMG$PUT_LINE and SMG$ERASE_LINE to write three scrolling lines 
C to the screen: underlined, blinking, and reverse video. 
C- 
       DO I = 1,10 
       IF ((I/2) + (I/2) .EQ. I) THEN 
               DIR = SMG$M_UP 
       ELSE 
               DIR = SMG$M_DOWN 
       ENDIF 
 
       STATUS = SMG$PUT_LINE (DISPLAY_ID, 
     1     'This line is  underlined',,SMG$M_UNDERLINE,,,,DIR) 
       IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) 
 
       STATUS = SMG$ERASE_LINE(DISPLAY_ID) 
       IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) 
 
       STATUS = SMG$PUT_LINE (DISPLAY_ID,'This line is blinking', , 
     1      SMG$M_BLINK,,,,DIR) 
       IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) 
 
       STATUS = SMG$ERASE_LINE (DISPLAY_ID) 
       IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) 
 
       STATUS = SMG$PUT_LINE (DISPLAY_ID,'This line is reverse 
     1      video',,SMG$M_REVERSE,,,,DIR) 
       IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) 
 
       STATUS = SMG$ERASE_LINE (DISPLAY_ID) 
       IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) 
       ENDDO 
       END 
 
 
      


SMG$PUT_LINE_HIGHWIDE

The Write Double-Height and Double-Width Line routine writes a line of text with double-height and double-width (highwide) characters.

Format

SMG$PUT_LINE_HIGHWIDE display-id ,text [,line-advance] [,rendition-set] [,rendition-complement] [,flags] [,character-set]


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

Display identifier. The display-id argument is the address of an unsigned longword that contains the display identifier of the virtual display.

text


OpenVMS usage: char_string
type: character string
access: read only
mechanism: by descriptor

Text to be output. The text argument is the address of the descriptor pointing to the output string.

line-advance


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

Number of lines to advance. The line-advance argument is the address of a signed longword that contains the number of lines to advance after the output. This argument is optional.

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

flags


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

Optional bit mask that specifies the action to be taken if the text does not fit on the line. The flags argument is the address of an unsigned longword that contains the flag. The flags argument accepts the following values:
0 Does not wrap (default).
SMG$M_WRAP_CHAR Wraps at the last character on the line.
SMG$M_WRAP_WORD Wraps at the last space on the line.

character-set


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

Specifies the default character set for all text in this virtual display. The character-set argument is the address of an unsigned longword that contains the character set code. Valid values are SMG$C_ASCII (default), and SMG$C_SPEC_GRAPHICS.

Description

SMG$PUT_LINE_HIGHWIDE is used to write lines of text with double-height and double-width characters to the virtual display. SMG$PUT_LINE_HIGHWIDE writes from the current virtual cursor position to the end of the line. If your text does not span to the end of the line, blank spaces are added.

Treatment of text that exceeds the rightmost bounds of the display depends on the flags argument. If flags specifies wrapping, lines are scrolled line-advance times to make room for the overflow characters in the "next" line. If wrapping is not specified, overflow characters are lost.

Following a call to SMG$PUT_LINE_HIGHWIDE, the virtual cursor position is set to column 1 of the next line where output should occur. The next line where output should occur is determined by the line-advance argument. Line-advance defaults to 2 so that subsequent calls to SMG$PUT_LINE_HIGHWIDE do not cause overprinting.


Condition Values Returned

SS$_NORMAL Normal successful completion.
SMG$_WILUSERMS Pasteboard is not a video terminal.
SMG$_WRONUMARG Wrong number (or combination of) arguments.
LIB$_INVSTRDES Invalid string descriptor.

SMG$PUT_LINE_MULTI

The Write Line with Multiple Renditions to Display routine writes lines with multiple renditions to the virtual display, optionally followed by cursor movement sequences.

Format

SMG$PUT_LINE_MULTI display-id ,text ,rendition-string [,rendition-complement] [,line-advance] [,flags] [,direction] [,character-set]


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

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

text


OpenVMS usage: char_string
type: character string
access: read only
mechanism: by descriptor

Text to be output. The text argument is the address of a descriptor pointing to the output string.

rendition-string


OpenVMS usage: char_string
type: character string
access: read only
mechanism: by descriptor

Optional bit mask string that controls the video attributes. The rendition-string argument is the address of a descriptor pointing to the bit mask string. Each attribute set causes the corresponding attribute to be set for the corresponding byte in the text string in the display. The following attributes can be specified for each byte using the rendition-string 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.

rendition-complement


OpenVMS usage: char_string
type: character string
access: read only
mechanism: by descriptor

Optional bit mask string that controls the video attributes. The rendition-complement is the address of a descriptor pointing to the bit mask string. Each attribute set causes the corresponding attribute to be complemented for the corresponding byte in the text string in the display.

If the same bit in the same byte is specified in both the rendition-string and rendition-complement arguments, rendition-string is evaluated first, followed by rendition-complement. By using these two parameters together, you can independently control each attribute in a single routine call. On a single-attribute basis, you 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

line-advance


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

Optional number of lines to advance after output. The line-advance argument is the address of a signed longword containing this number.

flags


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

Optional bit mask that specifies the action to take if the text does not fit on the line. The flags argument is the address of an unsigned longword that contains the flag. The flags argument accepts the following values:
0 Does not wrap (default).
SMG$M_WRAP_CHAR Wraps at the last character on the line.
SMG$M_WRAP_WORD Wraps at the last space on the line.

direction


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

Optional direction specifier. The direction argument is the address of an unsigned longword that contains the direction code specifying the scrolling direction, if scrolling is necessary. Valid values are SMG$M_UP (default) and SMG$M_DOWN.

character-set


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

Specifies the default character set for all text in this virtual display. The character-set argument is the address of an unsigned longword that contains the character set code. Valid values are SMG$C_ASCII (default) and SMG$C_SPEC_GRAPHICS.

Description

SMG$PUT_LINE_MULTI lets you write lines to the virtual display with multiple renditions, optionally followed by cursor movement sequences. SMG$PUT_LINE_MULTI writes from the current virtual cursor position to the end of the line. If the text does not span to the end of the line, the remaining portion of the line is filled with blanks.

The treatment of text that extends beyond the rightmost bounds of the virtual display depends on the value of the flags argument. If flags specifies wrapping, lines are scrolled line-advance times to make room for the overflow characters in the "next" line. The "next" line is determined by the scrolling direction. If flags does not specify wrapping, excess characters are discarded.

Following a call to SMG$PUT_LINE_MULTI, the virtual cursor position is set to column 1 of the next line where output should occur. The next line where output should occur is determined by the line-advance and direction arguments; line-advance defaults to 1 so that subsequent calls to SMG$PUT_LINE_MULTI do not cause overprinting.


Condition Values Returned

SS$_NORMAL Normal successful completion.
SMG$_INVARG A negative value for line-advance was specified.
SMG$_WILUSERMS Pasteboard is not a video terminal.
SMG$_WRONUMARG Wrong number (or combination of) arguments.
LIB$_INVSTRDES Invalid string descriptor.

Example


10 
     !+ 
     !This VAX BASIC example demonstrates the capabilities of the 
     !SMG$PUT_LINE_MULTI routine. 
     !- 
 
     OPTION TYPE = EXPLICIT 
 
     EXTERNAL SUB LIB$STOP (LONG BY VALUE) 
     EXTERNAL LONG FUNCTION SMG$CREATE_PASTEBOARD (LONG) 
     EXTERNAL LONG FUNCTION SMG$CREATE_VIRTUAL_DISPLAY (LONG, LONG, & 
                             LONG, LONG) 
     EXTERNAL LONG FUNCTION SMG$PASTE_VIRTUAL_DISPLAY (LONG, LONG, & 
                             LONG, LONG) 
     EXTERNAL LONG FUNCTION SMG$PUT_LINE (LONG, STRING) 
     EXTERNAL LONG FUNCTION SMG$PUT_LINE_MULTI (LONG, STRING, STRING, & 
                             STRING, LONG, LONG) 
 
 
     DECLARE LONG pasteboard_id, display_id, display2_id, & 
                   index, ret_status 
 
     MAP (rend) STRING dummy = 32 
     MAP DYNAMIC (rend) BYTE i_rend(15), STRING rendition 
     REMAP (rend) i_rend(), rendition 
 
     EXTERNAL BYTE CONSTANT SMG$M_BOLD 
     EXTERNAL BYTE CONSTANT SMG$M_REVERSE 
     EXTERNAL BYTE CONSTANT SMG$M_BLINK 
     EXTERNAL BYTE CONSTANT SMG$M_UNDERLINE 
     EXTERNAL LONG CONSTANT SMG$M_BORDER 
 
     FOR index = 0 TO 3 
         i_rend(index) = SMG$M_REVERSE 
     NEXT index 
 
     FOR index = 4 TO 7 
         i_rend(index) = SMG$M_BOLD 
     NEXT index 
 
     FOR index = 8 to 11 
         i_rend(index) = SMG$M_UNDERLINE 
     NEXT index 
 
     FOR index = 12 TO 15 
         i_rend(index) = SMG$M_BLINK 
     NEXT index 
 
 
     REMAP (rend) rendition = 16, i_rend() 
 
     ret_status = SMG$CREATE_PASTEBOARD (pasteboard_id) 
     IF (ret_status AND 1%) = 0% THEN 
        CALL LIB$STOP(ret_status BY VALUE) 
     END IF 
 
     ret_status = SMG$CREATE_VIRTUAL_DISPLAY (4,10,display_id, & 
                   SMG$M_BORDER BY REF) 
     IF (ret_status AND 1%) = 0% THEN 
        CALL LIB$STOP(ret_status BY VALUE) 
     END IF 
 
     ret_status = SMG$PASTE_VIRTUAL_DISPLAY (display_id, pasteboard_id, & 
                   2 BY REF, 30 BY REF) 
     IF (ret_status AND 1%) = 0% THEN 
        CALL LIB$STOP(ret_status BY VALUE) 
     END IF 
 
     ret_status = SMG$PUT_LINE_MULTI (display_id, '1234567890123456', & 
                   rendition,,,1) 
     IF (ret_status AND 1%) = 0% THEN 
        CALL LIB$STOP(ret_status BY VALUE) 
     END IF 
 
END 
 
      

This example shows the use of SMG$PUT_LINE_MULTI. In the first line of output, the characters "1234" appear in reverse video. The characters "5678" are highlighted, and the characters "90" are underlined. In the second line of output, the characters "12" are underlined and the characters "3456" are blinking.


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_028.HTML