Document revision date: 30 March 2001

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

| privacy and legal statement |
5935PRO_028.HTML