Document revision date: 30 March 2001

## OpenVMS RTL Screen Management (SMG$) Manual

Previous | Contents | Index

## SMG$INIT_TERM_TABLE_BY_TYPE

> The Initialize TERMTABLE by OpenVMS Terminal Type routine initializes the TERMTABLE database for the terminal named, so that subsequent calls to SMG$GET_TERM_DATA can extract information and command strings for that terminal.

### Format

> SMG$INIT_TERM_TABLE_BY_TYPE terminal-type ,termtable-address [,terminal-name]

### RETURNS

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

### Arguments

> #### terminal-type

> OpenVMS usage: | byte_signed
> type: | byte (signed)
> access: | read only
> mechanism: | by reference

> The device type of the terminal, as designated by an OpenVMS symbolic terminal type or by another value returned by the $GETDVI system service. The terminal-type argument is the address of a signed byte that contains the terminal type.

> #### termtable-address

> OpenVMS usage: | address
> type: | longword (unsigned)
> access: | write only
> mechanism: | by reference

> Address of the entry for a particular type of terminal in TERMTABLE.EXE. The termtable-address argument is the address of an unsigned longword into which is written the address of a terminal entry.

> Use this address when calling the SMG$GET_TERM_DATA procedure for the specified type of terminal.

> #### terminal-name

> OpenVMS usage: | device_name
> type: | character string
> access: | write only
> mechanism: | by descriptor

> A string into which is written the terminal name associated with the device type. The terminal-name argument is the address of a descriptor pointing to the string into which the terminal name is written.

### Description

> SMG$INIT_TERM_TABLE_BY_TYPE initializes the TERMTABLE database for the terminal type specified, so that subsequent calls to SMG$GET_TERM_DATA can extract information and command strings for that type of terminal. This routine should be used only when you perform direct (non-SMG$) I/O to terminals.

> SMG$INIT_TERM_TABLE_BY_TYPE first searches for TERMTABLE.EXE in the area logically named TERM$TABLOC. If TERMTABLE.EXE is not found there, the routine searches the global section SMG$TERMTABLE.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_GBLSECMAP | Successful completion. The definition was found in the global TERMTABLE.
> SMG$_PRISECMAP | Successful completion. The definition was found in a private TERMTABLE.
> SMG$_UNDTERNAM | Undefined terminal name.
> SMG$_UNDTERNOP | Undefined terminal. No definition was found for the terminal and no private TERMTABLE was found.
> SMG$_UNDTERNOS | Undefined terminal. No definition was found for the terminal and no system TERMTABLE was found.

## SMG$INSERT_CHARS

> The Insert Characters routine inserts characters into a virtual display.

### Format

> SMG$INSERT_CHARS display-id ,character-string ,start-row ,start-column [,rendition-set] [,rendition-complement] [,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.

> #### character-string

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

> The character string to be inserted. The character-string argument is the address of a descriptor that points to the string to be inserted.

> #### start-row

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

> The row position at which to begin the insertion. The start-row argument is the address of a signed longword that contains the row number.

> #### start-column

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

> The column position at which to begin the insertion. The start-column argument is the address of a signed longword that contains the column number.

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

> #### 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 (the default) and SMG$C_SPEC_GRAPHICS.

### Description

> SMG$INSERT_CHARS inserts the specified character string at the start-row and start-column positions specified. Characters to the right of the insertion are shifted to the right. Any characters that do not fit on the current line are discarded. The virtual cursor remains at the character position following the last character inserted.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INVARG | Unrecognized rendition code.
> SMG$_INVCOL | Invalid column.
> SMG$_INVDIS_ID | Invalid display-id.
> SMG$_INVROW | Invalid row.
> 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 SMG$INSERT_CHARS.
    C-

            IMPLICIT INTEGER (A-Z)
            INCLUDE '($SMGDEF)'

    C+
    C Use SMG$CREATE_VIRTUAL_DISPLAY to create a virtual display
    C 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 Call SMG$CREATE_PASTEBOARD to 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 by calling SMG$PUT_CHARS.
    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 Use 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 Call SMG$INSERT_CHARS to add a row 1 of text, starting at column 6.
    C Underline these characters.
    C-

            STATUS = SMG$INSERT_CHARS ( DISPLAY1,
         1          'This is a new row.', 1, 6, SMG$M_UNDERLINE )
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

    C+
    C Calling SMG$INSERT_CHARS again, add text to row 6.
    C Note that there will be some characters that will no
    C longer fit on the line. They will be discarded. The
    C new text will be bolded.
    C-

            STATUS = SMG$INSERT_CHARS ( DISPLAY1,
         1          'to this bordered display.', 6, 28, SMG$M_BOLD )
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

            END

> The output generated by this Fortran program before the call to SMG$INSERT_CHARS is shown in Figure SMG-27.

> Figure SMG-27 Output Generated by Fortran Program Before the Call to SMG$INSERT_CHARS

The output generated by this Fortran program after the call to SMG$INSERT_CHARS is shown in Figure SMG-28.

Figure SMG-28 Output Generated by Fortran Program After the Call to SMG$INSERT_CHARS

## SMG$INSERT_LINE

> The Insert Line routine inserts a line into a virtual display and scrolls the display.

### Format

> SMG$INSERT_LINE display-id ,start-row [,character-string] [,direction] [,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.

> #### start-row

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

> Specifies the row number at which the string is inserted and at which scrolling begins. The start-row argument is the address of a signed longword that contains the row number.

> #### character-string

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

> The character string to be inserted by SMG$INSERT_LINE. The character-string argument is the address of a descriptor pointing to this string.

> #### direction

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

> Specifies the scrolling direction. The direction argument is the address of a longword bit mask that contains the direction code. Valid values are SMG$M_UP and SMG$M_DOWN. SMG$M_UP is the default.

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

> #### 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. Valid values for flags are as follows:

> 0 | Does not wrap (the 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 (the default) and SMG$C_SPEC_GRAPHICS.

### Description

> SMG$INSERT_LINE lets you insert a line into a virtual display at a location other than the first or last line. Existing lines are scrolled in the specified direction to create an open space. If you specify a character-string argument, that string is written in the space created; otherwise, the new line remains blank. If the string does not span the width of the display, it is padded with blanks.

> If the value of flags is SMG$M_WRAP_WORD or SMG$M_WRAP_CHAR and the specified character-string is longer than the width of the virtual display, SMG$INSERT_LINE scrolls another line and writes the excess characters in the created space. If flags is 0, any excess characters are discarded. The virtual cursor remains at the character position following the last character written.

> See SMG$PUT_LINE to add lines and scroll at the first or last line in a virtual display.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INVARG | Invalid argument. The specified direction is not up or down.
> SMG$_INVCOL | Invalid column.
> SMG$_INVDIS_ID | Invalid display-id.
> SMG$_INVROW | Invalid row.
> SMG$_WILUSERMS | Pasteboard is not a video terminal.
> SMG$_WRONUMARG | Wrong number of arguments.

### Example

    C+
    C This Fortran example program demonstrates the use of SMG$INSERT_LINE.
    C
    C Include the SMG definitions. In particular, we want SMG$M_BORDER,
    C SMG$M_UNDERLINE, and SMG$M_UP.
    C-

            IMPLICIT INTEGER (A-Z)
            INCLUDE '($SMGDEF)'

    C+
    C Use SMG$CREATE_VIRTUAL_DISPLAY to create a virtual display
    C 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 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_CHARS to 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 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))

    C+
    C Call SMG$INSERT_LINE to add a line of text after line 6 and scroll
    C the display. Also, underline the new characters.
    C-

            STATUS = SMG$INSERT_LINE ( DISPLAY1, 7,
         1          'This is a new line.', SMG$M_UP, SMG$M_UNDERLINE )
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

            END

> Previous | Next | Contents | Index

> | privacy and legal statement |
> 5935PRO_022.HTML