OpenVMS RTL Screen Management (SMG$) Manual

Document revision date: 30 March 2001

OpenVMS RTL Screen Management (SMG$) Manual

Contents

Index

SMG$PUT_LINE_WIDE

The Write Double-Width Line routine writes a line of double-width text to a virtual display.

Format

SMG$PUT_LINE_WIDE 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

Specifies the virtual display 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.
text

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

Characters to be written to the virtual display. The text argument is the address of a descriptor pointing to the text.
line-advance

OpenVMS usage: longword_signed

type: longword (signed)

access: read only

mechanism: by reference

Specifies the number of lines to advance after output. The line-advance argument is the address of a signed longword integer that contains the number of lines to advance.
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 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.

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.

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$PUT_LINE_WIDE writes lines of double-width text to the virtual display. SMG$PUT_LINE_WIDE writes out the entire line, starting at the current virtual cursor position. If the caller's text does not span the entire line, the line is filled with blanks.
If the flags argument specifies wrapping, lines are scrolled line-advance times to make room for the overflow characters in the "next" line. If flags does not specify wrapping, excess characters are discarded.
Following a call to SMG$PUT_LINE_WIDE, 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 1 so that subsequent calls to SMG$PUT_LINE_WIDE will not cause overprinting.
Other routines that you can use to write text to a virtual display are SMG$PUT_LINE and SMG$PUT_LINE_HIGHWIDE.

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.

Example


C+ C This Fortran example program demonstrates the use of C SMG$PUT_LINE_WIDE. C C Include the SMG definitions. In particular, we want SMG$M_BORDER and C SMG$M_UNDERLINE. C- INCLUDE '($SMGDEF)' INTEGER SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD INTEGER SMG$PASTE_VIRTUAL_DISPLAY, SMG$PUT_LINE_WIDE INTEGER DISPLAY1, PASTE1, ROWS, COLUMNS, STATUS CHARACTER*34 TEXT(3) C+ C Create a virtual display with a border by calling C SMG$CREATE_VIRTUAL_DISPLAY. C- ROWS = 7 COLUMNS = 70 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 Use SMG$PUT_LINE to put data in the virtual display. C- TEXT(1) = 'This virtual display has 7' TEXT(2) = 'rows and 70 columns.' TEXT(3) = 'Text entered by SMG$PUT_LINE_WIDE.' C+ C After the first line of text is printed, advance two lines. C- STATUS = SMG$PUT_LINE_WIDE ( DISPLAY1, TEXT(1), 2 ) IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) C+ C Underline the next line of text. Notice that 34 characters are being C underlined. Advance one line of text after displaying the line. C- STATUS = SMG$PUT_LINE_WIDE ( DISPLAY1, TEXT(2), 1, 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_WIDE ( DISPLAY1, TEXT(3) ) IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) C+ C Paste the virtual display using SMG$PASTE_VIRTUAL_DISPLAY. C- STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 5 ) IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) END

    
C+ 
C This Fortran example program demonstrates the use of 
C SMG$PUT_LINE_WIDE. 
C 
C Include the SMG definitions. In particular, we want SMG$M_BORDER and 
C SMG$M_UNDERLINE. 
C- 
 
        INCLUDE '($SMGDEF)' 
        INTEGER SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD 
        INTEGER SMG$PASTE_VIRTUAL_DISPLAY,  SMG$PUT_LINE_WIDE 
        INTEGER DISPLAY1, PASTE1, ROWS, COLUMNS, STATUS 
        CHARACTER*34 TEXT(3) 
 
C+ 
C Create a virtual display with a border by calling 
C SMG$CREATE_VIRTUAL_DISPLAY. 
C- 
 
        ROWS = 7 
        COLUMNS = 70 
 
        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 Use SMG$PUT_LINE to put data in the virtual display. 
C- 
 
        TEXT(1) = 'This virtual display has 7' 
        TEXT(2) = 'rows and 70 columns.' 
        TEXT(3) = 'Text entered by SMG$PUT_LINE_WIDE.' 
 
C+ 
C After the first line of text is printed, advance two lines. 
C- 
 
        STATUS = SMG$PUT_LINE_WIDE ( DISPLAY1, TEXT(1), 2 ) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
C+ 
C Underline the next line of text. Notice that 34 characters are being 
C underlined. Advance one line of text after displaying the line. 
C- 
 
        STATUS = SMG$PUT_LINE_WIDE ( DISPLAY1, TEXT(2), 1, 
     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_WIDE ( DISPLAY1, TEXT(3) ) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
C+ 
C Paste the virtual display using SMG$PASTE_VIRTUAL_DISPLAY. 
C- 
 
        STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 5 ) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
        END

The output generated by this Fortran program is shown in Figure SMG-35.
Figure SMG-35 Output Generated by Fortran Program Calling SMG$PUT_LINE_WIDE

SMG$PUT_PASTEBOARD

The Output Pasteboard Using Routine routine accesses the contents of a pasteboard.

Format

SMG$PUT_PASTEBOARD pasteboard-id ,action-routine [,user-argument] [,flags]

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

Pasteboard identifier. The pasteboard-id argument is the address of an unsigned longword containing the pasteboard identifier.
action-routine

OpenVMS usage: procedure

type: procedure value

access: read only

mechanism: by value

Pasteboard routine to be called. The action-routine argument is the address of the routine's procedure value. Because SMG$ cannot determine the resulting type of device, device-independent characters (plus sign [+], minus sign [-], vertical bar [|]) are used to draw lines.
The action-routine accepts two arguments:

A pointer to a string descriptor describing the line in the pasteboard.
The user argument, or 0, passed by value.

The action routine should return a success status (low bit set) as a return value, otherwise SMG$PUT_PASTEBOARD will terminate, and the status value will be returned as the return value for SMG$PUT_PASTEBOARD.
user-argument

OpenVMS usage: user_arg

type: longword (unsigned)

access: read only

mechanism: by value

The argument you supply to the action-routine. The user-argument argument is an unsigned longword that contains the value to be passed to the action routine. If user-argument is omitted, a 0 will be passed as the user argument.
flags

OpenVMS usage: mask_longword

type: longword (unsigned)

access: read only

mechanism: by reference

Optional bit mask that specifies whether a form feed is passed to the action routine. The flags argument is the address of an unsigned longword that contains the flag. Valid values for flags are as follows:

0 No form-feed line is sent.

SMG$M_FORM_FEED The first line passed to the action routine is a form feed.

Description

The SMG$PUT_PASTEBOARD routine accesses the contents of a pasteboard. The caller specifies an action routine that will be called once for each line in the pasteboard. The action routine should return a success status (low bit set) as a return value, or SMG$PUT_PASTEBOARD will terminate.

Condition Values Returned

SS$_NORMAL Normal successful completion.

Other Any error returned by the action routine.

SMG$PUT_STATUS_LINE

The Output Line of Text to Hardware Status Line routine outputs a line of text to the hardware status line.

Format

SMG$PUT_STATUS_LINE pasteboard-id ,text

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 containing the hardware status line. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.
text

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

The characters to be written to the hardware status line. The text argument is the address of a descriptor pointing to the text.

Description

The SMG$PUT_STATUS_LINE routine outputs a line of text to the terminal's hardware status line. Some terminals have a hardware status line at the bottom (25th line) of the screen. If this status line has been set as "host writable," you can use this routine to output a line of text to the status line. (If the hardware status line is not available, the error SMG$_OPNOTSUP is returned.) The text is output in reverse video.

Condition Values Returned

SS$_NORMAL Normal successful completion.

SMG$_INVPAS_ID Invalid pasteboard-id.

SMG$_OPNOTSUP No hardware status line available.

SMG$_WRONUMARG Wrong number of arguments.

LIB$_INVARG Invalid argument.

SMG$READ_COMPOSED_LINE

The Read Composed Line routine reads a line of input composed of normal keystrokes and equivalence strings.

Format

SMG$READ_COMPOSED_LINE keyboard-id [,key-table-id] ,resultant-string [,prompt-string] [,resultant-length] [,display-id] [,flags] [,initial-string] [,timeout] [,rendition-set] [,rendition-complement] [,word-terminator-code]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

keyboard-id

OpenVMS usage: identifier

type: longword (unsigned)

access: read only

mechanism: by reference

Specifies the virtual keyboard from which input is to be read. The keyboard-id argument is the address of an unsigned longword that contains the keyboard identifier.
The keyboard identifier is returned by SMG$CREATE_VIRTUAL_KEYBOARD.
key-table-id

OpenVMS usage: identifier

type: longword (unsigned)

access: read only

mechanism: by reference

Specifies the key definition table to be used for translating keystrokes. The key-table-id argument is the address of an unsigned longword that contains the key definition table identifier.
The key definition table identifier is returned by SMG$CREATE_KEY_TABLE.
resultant-string

OpenVMS usage: char_string

type: character string

access: write only

mechanism: by descriptor

String into which SMG$READ_COMPOSED_LINE writes the complete composed line. The resultant-string argument is the address of a descriptor pointing to the string in which the composed line is written.
prompt-string

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

String used to prompt for the read operation. The prompt-string argument is the address of a descriptor pointing to the prompt string.
resultant-length

OpenVMS usage: word_unsigned

type: word (unsigned)

access: write only

mechanism: by reference

Receives the number of characters read or the maximum length of resultant-string, whichever is less. The resultant-length argument is the address of an unsigned longword into which SMG$READ_COMPOSED_LINE writes the number of characters read.
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. This argument is optional only if you are not using the Screen Management Facility's output routines.
If you are using the Screen Management Facility input and output routines, this argument specifies the virtual display in which the input is to occur. The virtual display specified must be pasted to the same pasteboard as specified by keyboard-id and must not be occluded. You cannot accept input from an occluded area of the virtual display.
In the case of multiple virtual displays, each virtual display has an associated virtual cursor position. At the same time, there is a single physical cursor position corresponding to the current location of the physical cursor. If the display-id argument is specified, the read begins at the current virtual cursor position in the specified virtual display. If the display identifier is omitted, the read begins in the current physical cursor position. The length of the prompt-string plus the key entered is limited to the number of visible columns in the display.

Note
This virtual display must be pasted in column 1 and may not have any other virtual displays to its right. This restriction is necessary because otherwise any occurrence of Ctrl/R or Ctrl/U would blank out the entire line, including any output pasted to the right. To circumvent this restriction, you can use SMG$REPAINT_LINE whenever a Ctrl/R or Ctrl/U is encountered.

flags

OpenVMS usage: mask_longword

type: longword (unsigned)

access: read only

mechanism: by reference

Optional bit mask that specifies enabled keys. The flags argument is the address of an unsigned longword that contains the flag. Valid values for flags are as follows:

0 Line editing is enabled and function keys (F6 to F14) cannot be used.

SMG$M_FUNC_KEYS Function keys (F6 to F14) may be used and line editing is disabled.

SMG$M_NOKEEP Lines entered in the recall buffer are not saved.

SMG$M_NORECALL Line recall is disabled for this I/O only.

Because the OpenVMS terminal driver uses the function keys (F6 to F14) for line editing on some terminals, you cannot have function keys and line editing enabled at the same time.
initial-string

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

Optional string that contains the initial characters of the field. The initial-string argument is the address of a descriptor pointing to the string. The string is written to the display in the input area, as if it had been entered from the keyboard. It may be edited in the usual way (provided that the SMG$M_FUNC_KEYS flag is not set).
timeout

OpenVMS usage: longword_signed

type: longword (signed)

access: read only

mechanism: by reference

Optional timeout count. The timeout argument is the address of a signed longword containing the timeout count. If the timeout argument is specified, all characters entered before the timeout are returned in the buffer. If the timeout argument is omitted, characters are returned in the buffer until a terminator is encountered.
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.

Previous Next Contents Index

privacy and legal statement

5935PRO_029.HTML

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

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

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

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

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

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.

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.

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

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.

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

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

0	No form-feed line is sent.
SMG$M_FORM_FEED	The first line passed to the action routine is a form feed.

SS$_NORMAL	Normal successful completion.
Other	Any error returned by the action routine.

SS$_NORMAL	Normal successful completion.
SMG$_INVPAS_ID	Invalid pasteboard-id.
SMG$_OPNOTSUP	No hardware status line available.
SMG$_WRONUMARG	Wrong number of arguments.
LIB$_INVARG	Invalid argument.

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by reference

0	Line editing is enabled and function keys (F6 to F14) cannot be used.
SMG$M_FUNC_KEYS	Function keys (F6 to F14) may be used and line editing is disabled.
SMG$M_NOKEEP	Lines entered in the recall buffer are not saved.
SMG$M_NORECALL	Line recall is disabled for this I/O only.