Document revision date: 30 March 2001

## OpenVMS RTL Screen Management (SMG$) Manual

Previous | Contents | Index

In this Compaq Fortran example, the initial virtual display is copied to a second virtual display that has a viewport associated with it. When the second virtual display is pasted, only the portion of the virtual display that falls inside the viewport is visible. This is shown in Figure SMG-8.

Figure SMG-8 Output Generated by Creating a Viewport

## SMG$CREATE_VIRTUAL_DISPLAY

> The Create Virtual Display routine creates a virtual display and returns its assigned display identifier.

### Format

> SMG$CREATE_VIRTUAL_DISPLAY number-of-rows ,number-of-columns ,display-id [,display-attributes] [,video-attributes] [,character-set]

### RETURNS

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

### Arguments

> #### number-of-rows

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

> Specifies the number of rows in the newly created virtual display. The number-of-rows argument is the address of a signed longword that contains the desired number of rows.

> #### number-of-columns

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

> Specifies the number of columns in the newly created virtual display. The number-of-columns argument is the address of a signed longword that contains the desired number of columns.

> #### display-id

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

> Receives the display-id of the newly created virtual display. The display-id argument is the address of an unsigned longword into which is written the display identifier.

> #### display-attributes

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

> Receives the current default display attributes. The optional display-attributes argument is the address of an unsigned longword into which the current display attributes are written.

> Valid values for display-attributes are as follows:

> SMG$M_BORDER | Specifies a bordered display. If omitted, the display is not bordered.
> SMG$M_BLOCK_BORDER | Specifies a block-bordered display. If omitted, the display is not bordered.
> SMG$M_DISPLAY_CONTROLS | Specifies that control characters such as carriage return and line feed are displayed as graphic characters, if your terminal supports them.
> SMG$M_PROTECT_DISPLAY | Instructs the Screen Management Facility to return an error (SMG$_DSPIN_USE) if an SMG$ call is made from an AST routine that interrupted an SMG$ call on the same display.
> SMG$M_TRUNC_ICON | Specifies that an icon (generally a diamond shape) is displayed where truncation of a line exceeding the width of the virtual display has occurred.

> #### video-attributes

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

> Specifies the default rendition to be applied to all output in this virtual display unless overridden by a call to a specific output routine (for example, SMG$CHANGE_RENDITION). The video-attributes argument is the address of an unsigned longword that contains the video attributes mask.

> Valid values for this argument are as follows:

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

> #### 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 specifier. Valid values are SMG$C_ASCII (the default), and SMG$C_SPEC_GRAPHICS.

### Description

> SMG$CREATE_VIRTUAL_DISPLAY creates a new virtual display and returns its display identifier. Initially, the virtual display contains blanks, and the virtual cursor is positioned at row 1, column 1. The virtual scrolling region is the entire virtual display. To make the display visible, use the SMG$PASTE_VIRTUAL_DISPLAY routine.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> LIB$_INSVIRMEM | Insufficient virtual memory.
> SMG$_DSPIN_USE | An SMG$ call was made from an AST routine that interrupted an SMG$ call on the same display.
> SMG$_INVARG | Invalid argument. The video-attributes or display-attributes argument contains an unknown value.
> SMG$_WRONUMARG | Wrong number of arguments.

### Example

    C+
    C This Fortran example program demonstrates the use of
    C SMG$ERASE_PASTEBOARD.
    C-

            IMPLICIT INTEGER*4 (A-Z)
            CHARACTER*80    OUT_STR,TRIM_STR
            CHARACTER*18    PROMPT          /'Please enter data '/

            SMG$M_BOLD = 1
            SMG$M_REVERSE = 2
            SMG$M_BLINK = 4
            SMG$M_UNDERLINE = 8
    C+
    C Establish the terminal screen as a pasteboard using
    C SMG$CREATE_PASTEBOARD.
    C-

            STATUS = SMG$CREATE_PASTEBOARD (NEW_PID,,,)
            IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
    C+
    C Establish the terminal keyboard as the virtual keyboard
    C by calling SMG$CREATE_VIRTUAL_KEYBOARD.
    C-

            STATUS = SMG$CREATE_VIRTUAL_KEYBOARD(KEYBOARD_ID,,,)
            IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
    C+
    C Establish a virtual display region by
    C calling SMG$CREATE_VIRTUAL_DISPLAY.
    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.  To paste the virtual display, use
    C 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 Prompt the user for input, and accept that input using
    C SMG$READ_STRING.
    C-

            STATUS = SMG$READ_STRING(KEYBOARD_ID,OUT_STR,PROMPT,,,,,,,)
            IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
    C+
    C Clear the screen using SMG$ERASE_PASTEBOARD.
    C-

            STATUS = SMG$ERASE_PASTEBOARD (NEW_PID)
            IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
    C+
    C Trim any trailing blanks from the user input
    C by calling STR$TRIM.
    C-
            STATUS = STR$TRIM(TRIM_STR,OUT_STR,STR_LEN)
            IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

    C+
    C Display the data input by the user using SMG$PUT_CHARS
    C and SMG$PUT_LINE.
    C-

            STATUS = SMG$PUT_CHARS(DISPLAY_ID,'You entered: ',,,,,,)
            IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
            STATUS = SMG$PUT_LINE(DISPLAY_ID,TRIM_STR(1:STR_LEN),,
         1                               SMG$M_REVERSE,0,,)
            IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
            END

> The output generated by this Fortran example is shown in Figure SMG-9.

> Figure SMG-9 Output of Fortran Program Calling SMG$CREATE_VIRTUAL_DISPLAY

## SMG$CREATE_VIRTUAL_KEYBOARD

> The Create a Virtual Keyboard routine creates a virtual keyboard and returns its assigned keyboard identifier.

### Format

> SMG$CREATE_VIRTUAL_KEYBOARD keyboard-id [,input-device] [,default-filespec] [,resultant-filespec] [,recall-size]

### RETURNS

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

### Arguments

> #### keyboard-id

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

> Receives the keyboard identifier of the newly created virtual keyboard. The keyboard-id argument is the address of an unsigned longword into which is written the keyboard identifier.

> #### input-device

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

> String containing the file specification or logical name of the file or terminal to be used for this virtual keyboard. The input-device argument is the address of a descriptor pointing to the file specification. If omitted, this defaults to SYS$INPUT.

> #### default-filespec

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

> String containing the default file specification. The default-filespec argument is the address of a descriptor pointing to the default file specification. If omitted, the null string is used.

> The default-filespec argument might be used to specify a default device and directory, leaving the input-device argument to supply the file name and type.

> #### resultant-filespec

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

> String into which the procedure writes the fully expanded file specification of the file used. The resultant-filespec argument is the address of a descriptor pointing to the string into which is written the file specification that was used.

> #### recall-size

> OpenVMS usage: | byte_unsigned
> type: | byte (unsigned)
> access: | read only
> mechanism: | by reference

> Number of input lines to be saved for later recall. The optional recall-size argument is the address of an unsigned byte containing the specified number of lines. A value of 0 turns off input line recall. By default, 20 lines are saved for later recall.

### Description

> SMG$CREATE_VIRTUAL_KEYBOARD creates the association between a file specification (terminal name or OpenVMS RMS file) and a virtual keyboard. The keyboard identifier is then passed to other SMG$ procedures in order to identify the input stream being acted upon.

> If your program also calls the routine SMG$CREATE_PASTEBOARD, be sure to call that routine before you call SMG$CREATE_VIRTUAL_KEYBOARD.

> If input-device does not refer to a terminal, the file is opened using RMS and all further access to that file is performed through RMS. If input-device is a terminal, this procedure assigns a channel to the terminal and sets the terminal's keyboard to application mode (if supported). These attributes are restored to their previous values when the virtual keyboard is deleted. The virtual keyboard is deleted automatically when the image exits and can also be deleted by a call to SMG$DELETE_VIRTUAL_KEYBOARD.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_FILTOOLON | File specification is too long (over 255 characters).
> SMG$_WRONUMARG | Wrong number of arguments.
> LIB$_INSEF | Insufficient number of event flags.
> LIB$_INSVIRMEM | Insufficient virtual memory.
> LIB$_INVSTRDES | Invalid string descriptor.

Any RMS condition values returned by $OPEN or $CONNECT.

Any condition values returned by $GETDVIW, $ASSIGN, or $DCLEXH.

### Example

    C+
    C This Fortran example program demonstrates the use of
    C SMG$CREATE_VIRTUAL_KEYBOARD, SMG$CREATE_KEY_TABLE,
    C SMG$ADD_KEY_DEF, and SMG$READ_COMPOSED_LINE.
    C-

            INTEGER SMG$CREATE_VIRTUAL_KEYBOARD, SMG$CREATE_KEY_TABLE
            INTEGER SMG$ADD_KEY_DEF, SMG$READ_COMPOSED_LINE
            INTEGER SMG$DELETE_KEY_DEF, KEYBOARD, KEYTABLE, STATUS

    C+
    C Include the SMG definitions. In particular, we want SMG$M_KEY_NOECHO
    C and SMG$M_KEY_TERMINATE.
    C-

            INCLUDE '($SMGDEF)'

    C+
    C Create a virtual keyboard (using SMG$CREATE_VIRTUAL_KEYBOARD)
    C and create a key table (using SMG$CREATE_KEY_TABLE).
    C-

            STATUS = SMG$CREATE_VIRTUAL_KEYBOARD (KEYBOARD)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

            STATUS = SMG$CREATE_KEY_TABLE (KEYTABLE)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

    C+
    C Prompt the user with the following instructions.
    C-

            WRITE (6,*) 'When you see the prompt (->), strike the following'
            WRITE (6,*) 'keys (on the KEYPAD): '
            WRITE (6,*) '           PF1 '
            WRITE (6,*) '           5 '
            WRITE (6,*) '           PF3 '
            WRITE (6,*) ' '
            WRITE (6,*) 'When you have done this, the following sentence'
            WRITE (6,*) '(and nothing more) should appear following the'
            WRITE (6,*) 'prompt: '
            WRITE (6,*) '(PF3 should act as a carriage return.)'
            WRITE (6,*) ' '
            WRITE (6,*) 'NOW IS THE TIME FOR ALL TEXT TO APPEAR.'

    C+
    C Add key definitions by calling SMG$ADD_KEY_DEF.
    C-

            STATUS = SMG$ADD_KEY_DEF (KEYTABLE, 'PF1', , ,
         1  'NOW IS THE TIME FOR ')
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

            STATUS = SMG$ADD_KEY_DEF (KEYTABLE, 'KP5', , ,
         1  'TEXT TO APPEAR.')
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

            STATUS = SMG$ADD_KEY_DEF (KEYTABLE, 'PF3', ,
         1  SMG$M_KEY_NOECHO + SMG$M_KEY_TERMINATE ,
         1  'THIS SHOULD NOT BE ECHOED.  IF YOU CAN
         1  SEE THIS, AN ERROR EXISTS.')
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

    C+
    C Call SMG$READ_COMPOSED_LINE to read a line of input.
    C-

            WRITE(6,*) ' '
            STATUS = SMG$READ_COMPOSED_LINE (KEYBOARD, KEYTABLE, R_TEXT,
         1          '->')
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

            END

> Output session:

>     $ RUN example

>     When you see the prompt (->), strike the following
>     keys (on the KEYPAD):
>                PF1
>                5
>                PF3

>     When you have done this, the following sentence
>     (and nothing more) should appear following the
>     prompt:
>     (PF3 should act as a carriage return.)

>     NOW IS THE TIME FOR ALL TEXT TO APPEAR.

>     ->NOW IS THE TIME FOR ALL TEXT TO APPEAR.

>     $

## SMG$CURSOR_COLUMN

> The Return Cursor Column Position routine returns the virtual cursor's current column position in a specified virtual display.

### Format

> SMG$CURSOR_COLUMN display-id

### RETURNS

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

> SMG$CURSOR_COLUMN returns the current virtual cursor column position.

### Argument

> #### display-id

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

> The display for which the column position is returned. 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.

### Description

> SMG$CURSOR_COLUMN returns a longword containing the value of the current virtual cursor column position for the specified virtual display. If the display-id is omitted, this routine signals SMG$_WRONUMARG. If the display-id is invalid, this routine signals SMG$_INVDIS_ID.

### Condition Values Signaled

> SMG$_INVDIS_ID | Invalid display-id.
> SMG$_WRONUMARG | Wrong number of arguments.

## SMG$CURSOR_ROW

> The Return Cursor Row Position routine returns the virtual cursor's current row position in a specified virtual display.

### Format

> SMG$CURSOR_ROW display-id

### RETURNS

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

> SMG$CURSOR_ROW returns the current row position.

### Argument

> #### display-id

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

> The display for which the row position is returned. 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.

### Description

> SMG$CURSOR_ROW returns a longword containing the value of the current virtual cursor row position for the specified virtual display. If the display-id is omitted, this routine signals SMG$_WRONUMARG. If the display-id is invalid, this routine signals SMG$_INVDIS_ID.

### Condition Values Signaled

> SMG$_INVDIS_ID | Invalid display-id.
> SMG$_WRONUMARG | Wrong number of arguments.

Previous | Next | Contents | Index

| privacy and legal statement |
5935PRO_013.HTML