![[OpenVMS documentation]](../../images/openvms_doc_banner_top.gif)
|
![[Site home]](../../images/buttons/bn_site_home_off.gif)
![[Send comments]](../../images/buttons/bn_comments_off.gif)
![[Help with this site]](../../images/buttons/bn_site_help_off.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs_off.gif)
![[OpenVMS site]](../../images/buttons/bn_openvms_off.gif)
![[Compaq site]](../../images/buttons/bn_compaq_off.gif)
|
|
Updated:
11 December 1998
|
OpenVMS RTL Screen Management (SMG$) Manual
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.
![[OpenVMS documentation]](../../images/openvms_doc_banner_bottom.gif)