[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

OpenVMS/Hanzi RTL Chinese Screen Management (SMG$) Manual

Contents

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

Note
An RMS file is not supported as an input device in Chinese Screen Management Facility.

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.
Default-filespec might be used to specify a default device and directory, leaving the input-device argument to supply the file name and type.

Note
An RMS file is not supported as an input device in Chinese Screen Management Facility.

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.

Note
An RMS file is not supported as an input device in Chinese Screen Management Facility.

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 zero turns off input line recall. By default, 20 lines are saved for later recall.

Description

SMG$CREATE_VIRTUAL_KEYBOARD creates the association between a terminal name 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.
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 condition values returned by $GETDVIW, $ASSIGN, or $DCLEXH.

Example


C+
C This DEC 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 write only

access by value

SMG$CURSOR_COLUMN returns the current virtual cursor column position.

Arguments

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

Arguments

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

SMG$DEFINE_KEY

The Perform a DEFINE/KEY Command routine performs the DEFINE/KEY command you provide.

Format

SMG$DEFINE_KEY key-table-id ,command-string

RETURNS

OpenVMS usage cond_value

type longword (unsigned)

access write only

mechanism by value

Arguments

key-table-id

OpenVMS usage identifier

type longword (unsigned)

access read only

mechanism by reference

Identification of the key definition table for which the DEFINE/KEY command is to be performed. The key-table-id argument is the address of an unsigned longword that contains the key table identifier.
Key-table-id is returned by SMG$CREATE_KEY_TABLE.
command-string

OpenVMS usage char_string

type character string

access read only

mechanism by descriptor

String containing the DEFINE/KEY command to be performed. The command-string argument is the address of a descriptor pointing to the command to be performed.
The valid qualifiers for the DEFINE/KEY command are as follows:

/TERMINATE
/NOECHO
/LOCK
/IF_STATE
/SET_STATE

The following two restrictions apply to the DEFINE/KEY qualifiers:

If you use the /LOCK qualifier, you must also use the /SET_STATE qualifier.
If you use both the /SET_STATE and /TERMINATE qualifiers, you may not use /LOCK.

Description

SMG$DEFINE_KEY parses and performs a DEFINE/KEY command. It can be used by programs that accept DEFINE/KEY commands but do not parse the commands themselves.
SMG$DEFINE_KEY calls CLI$DCL_PARSE to parse the command line and then makes the appropriate call to SMG$ADD_KEY_DEF. The original command is then restored with a call to CLI$DCL_PARSE. Use of this procedure requires that the image be run under the DCL Command Language Interpreter.

Condition Values Returned

SS$_NORMAL Normal successful completion.

SMG$_WRONUMARG Wrong number of arguments.

Any condition values returned by LIB$SCOPY_DXDX.

Any condition values returned by CLI$ routines.

Any condition values returned by SMG$ADD_KEY_DEF.

SMG$DEL_TERM_TABLE

The Delete Terminal Table routine terminates access to a private
TERMTABLE.EXE and frees the associated virtual address space.

Format

SMG$DEL_TERM_TABLE

RETURNS

OpenVMS usage cond_value

type longword (unsigned)

access write only

mechanism by value

Arguments

None.

Description

SMG$DEL_TERM_TABLE terminates access to a private TERMTABLE.EXE. Calling this routine is optional. This routine is useful in the case where a calling program might need to reuse the virtual address space used by a private TERMTABLE. This routine should be used only when you perform direct (non-SMG$) I/O to terminals.

Condition Values Returned

SS$_NORMAL Normal successful completion.

SMG$DELETE_CHARS

The Delete Characters routine deletes columns in a virtual display.

Format

SMG$DELETE_CHARS display-id ,number-of-columns ,start-row ,start-column

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

Identifies the virtual display from which columns are to be deleted. The display-id argument is the address of an unsigned longword that contains the display identifier.
Display-id is returned by SMG$CREATE_VIRTUAL_DISPLAY.
number-of-columns

OpenVMS usage longword_signed

type longword (signed)

access read only

mechanism by reference

Specifies the number of columns to be deleted. The number-of-columns argument is the address of a signed longword that contains the number of columns to be deleted.
start-row

OpenVMS usage longword_signed

type longword (signed)

access read only

mechanism by reference

Specifies the row position at which to start the deletion. The start-row argument is the address of a signed longword that contains the row number at which to start the deletion.
start-column

OpenVMS usage longword_signed

type longword (signed)

access read only

mechanism by reference

Specifies the column position at which to start the deletion. The start-column argument is the address of a signed longword that contains the column position at which to start the deletion.
In case that the start-column starts on the right portion of a Chinese character, the left portion of the character will become an undefined character.

Description

SMG$DELETE_CHARS deletes a specified number of columns, starting at a specified row and column position. Remaining columns on the line are shifted to the left to occupy the vacated space(s). Note that this routine deletes columns only on a single line.
If you specify more columns than are available for deletion, SMG$DELETE_CHARS deletes all columns from the specified column position to the end of the line.
In case Chinese language character set is used, and the start column begins on the right portion of a Chinese character, the left portion of the character will become an undefined character. Also, if the deletion terminates on the left portion of a Chinese character, the right portion of the character will become an undefined character.
This routine leaves the virtual cursor at the position of the first columns deleted.

Condition Values Returned

SS$_NORMAL Normal successful completion.

SMG$_INVARG Invalid argument. The number of columns specified extends outside the virtual display.

SMG$_INVCOL Invalid column position. The specified column is outside the virtual display.

SMG$_INVDIS_ID Invalid display-id.

SMG$_INVROW Invalid row position. The specified row is outside the virtual display.

SMG$_WILUSERMS Pasteboard is not a video terminal.

SMG$_WRONUMARG Wrong number of arguments.

Example

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

        INTEGER SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD
        INTEGER SMG$PASTE_VIRTUAL_DISPLAY,  SMG$PUT_CHARS
        INTEGER SMG$DELETE_CHARS, DISPLAY1, PASTE1
        INTEGER ROWS, COLUMNS, BORDER, STATUS
C+
C Create the virtual display be calling SMG$CREATE_VIRTUAL_DISPLAY.
C To give it a border, set BORDER = 1. No border would be BORDER = 0.
C-

        ROWS = 7
        COLUMNS = 50
        BORDER = 1

        STATUS = SMG$CREATE_VIRTUAL_DISPLAY
     1                                (ROWS, COLUMNS, DISPLAY1, 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 to the pasteboard using
C 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$DELETE_CHARS to delete 4 characters from row 4
C starting from character (column) 14, removing the characters
C "rder" from the word "bordered".
C-

        STATUS = SMG$DELETE_CHARS ( DISPLAY1, 4, 4, 14)
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

        END

The output generated by this FORTRAN program before the call to SMG$DELETE_CHARS is shown in Figure SMG-10.
Figure SMG-10 Output Generated Before the Call to SMG$DELETE_CHARS

The output generated after the call to SMG$DELETE_CHARS is shown in Figure SMG-11.

Figure SMG-11 Output Generated After the Call to SMG$DELETE_CHARS

Contents