HP OpenVMS Systems Documentation

OpenVMS RTL Screen Management (SMG$) Manual

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.

Contents

Index