Document revision date: 30 March 2001

## OpenVMS RTL Screen Management (SMG$) Manual

Previous | Contents | Index

## SMG$GET_PASTING_INFO

> Provided that the specified virtual display is currently pasted, the Return Pasting Information routine returns the row and column of the pasting.

### Format

> SMG$GET_PASTING_INFO display-id ,pasteboard-id ,flags [,pasteboard-row] [,pasteboard-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

> Identifier of the virtual display to be examined. The display-id argument is the address of an unsigned longword containing the identifier of this virtual display.

> #### pasteboard-id

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

> Identifier of the pasteboard on which the virtual display is pasted. The pasteboard-id argument is the address of an unsigned longword containing the identifier of this pasteboard.

> #### flags

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

> Bit mask indicating the status of the specified virtual display with respect to the specified pasteboard. The flags argument is the address of an unsigned longword that contains the flag. Valid values for flags are as follows:

> 0 | The virtual display is not pasted to the specified pasteboard.
> SMG$M_DISPLAY_PASTED | The virtual display specified by display-id is pasted to the pasteboard specified by the pasteboard-id argument.

> #### pasteboard-row

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

> Row of the pasteboard that contains row 1 of the specified virtual display. The optional pasteboard-row argument is the address of a signed longword containing the number of the pasteboard row that contains the first row of the virtual display.

> #### pasteboard-column

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

> Column of the pasteboard that contains column 1 of the specified virtual display. The optional pasteboard-column argument is the address of a signed longword containing the number of the pasteboard column that contains the first column of the virtual display.

### Description

> SMG$GET_PASTING_INFO first checks to see if the virtual display specified by display-id is pasted to the pasteboard specified by pasteboard-id. If this virtual display is pasted to this pasteboard, SMG$GET_PASTING_INFO returns the row and column numbers of the pasteboard that correspond to row 1 and column 1 of the pasted virtual display.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_ILLBATFNC | Display is batched.
> SMG$_INVDIS_ID | Invalid display-id.
> SMG$_INVPAS_ID | Invalid pasteboard-id.
> SMG$_WRONUMARG | Wrong number of arguments.

## SMG$GET_TERM_DATA

> The Get Terminal Data routine accesses TERMTABLE.EXE and returns the character sequence that causes a terminal to perform a specified operation.

### Format

> SMG$GET_TERM_DATA termtable-address ,request-code ,maximum-buffer-length ,return-length ,capability-data [,input-argument-vector]

### RETURNS

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

### Arguments

> #### termtable-address

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

> Specifies the address of the TERMTABLE entry for the desired terminal. The termtable-address argument is the address of an unsigned longword that contains the address of the terminal capabilities table (TERMTABLE).

> The TERMTABLE address is returned by SMG$INIT_TERM_TABLE or SMG$INIT_TERM_TABLE_BY_TYPE.

> #### request-code

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

> Longword constant of the form SMG$K_code, where code is the name of the desired capability field. The request-code argument is the address of a signed longword that contains the request code. The SMG$K_code constants can be found in the library supplied by Compaq, $SMGTRMPTR.

> See Table 5_1 , Table 5_2 , Table 5_3 , and Table 5-4 for valid capability fields.

> #### maximum-buffer-length

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

> Maximum length of the buffer into which the requested capability data is written. The maximum-buffer-length argument is the address of a signed longword that contains the maximum number of bytes that can be written into the buffer.

> #### return-length

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

> Receives the number of bytes actually written into the buffer. The return-length argument is the address of a signed longword into which is written the number of bytes transferred into the buffer.

> #### capability-data

> OpenVMS usage: | unspecified
> type: | unspecified
> access: | by reference, array reference

> Address of the first byte of the buffer which is to receive the capability data. The capability-data argument contains the address of the buffer.

> #### input-argument-vector

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

> Address of a list of longwords used for capabilities that require a variable number of arguments, and for those that require substitution or arithmetic operations on an argument. The input-argument-vector argument is the address of an array of unsigned longwords that contains capability arguments. The first longword must contain the number of arguments that follow.

### Description

> SMG$GET_TERM_DATA should be used only when you perform direct (non-SMG$) I/O to terminals. It accesses the TERMTABLE.EXE entry for the specified type of terminal and returns the character sequence that performs the specified operation. It is up to you to send this character sequence to the terminal.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INVREQCOD | Invalid request code.
> SMG$_INVTERTAB | Invalid terminal table address.

## SMG$GET_VIEWPORT_CHAR

> The Get Characteristics of Display Viewport routine returns the characteristics of the specified viewport.

### Format

> SMG$GET_VIEWPORT_CHAR display-id [,viewport-row-start] [,viewport-column-start] [,viewport-number-rows] [,viewport-number-columns]

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

> Identifier of the virtual display associated with the viewport. The display-id argument is the address of an unsigned longword containing this identifier.

> #### viewport-row-start

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

> Optional argument that receives the starting row number of the viewport. The viewport-row-start argument is the address of a signed longword that receives this row number.

> #### viewport-column-start

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

> Optional argument that receives the starting column number of the specified viewport. The viewport-column-start argument is the address of a signed longword that receives this column number.

> #### viewport-number-rows

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

> Optional argument that receives the number of rows in the specified viewport. The viewport-number-rows argument is the address of a signed longword that receives this number.

> #### viewport-number-columns

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

> Optional argument that receives the number of columns in the specified viewport. The viewport-number-columns argument is the address of a signed longword that receives this number.

### Description

> SMG$GET_VIEWPORT_CHAR returns the requested characteristics of the specified viewport.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INVDIS_ID | Invalid display-id.
> SMG$_NO_WINASSOC | No viewport associated with the virtual display.
> SMG$_WRONUMARG | Wrong number of arguments.

### Example

    C+
    C This Fortran example demonstrates the use of SMG$GET_VIEWPORT_CHAR.
    C The viewport created will start at row 3, column 4. It will consist of
    C 7 rows and 29 columns. Note the parameters used in the SMG$CREATE_VIEWPORT
    C routine. I request 26 rows and 55 columns, but my viewport is truncated
    C to fit.
    C-
     IMPLICIT INTEGER (A-Z)
     INCLUDE '($SMGDEF)'

    C Create the virtual display. Give it a border.

     ROWS = 4
     COLUMNS = 34

     STATUS = SMG$CREATE_VIRTUAL_DISPLAY
         1         ( ROWS, COLUMNS, DISPLAY1,SMG$M_BORDER )
     IF (.NOT. STATUS) CALL LIB$SIGNAL(%val(STATUS))

    C Create the pasteboard.

     STATUS = SMG$CREATE_PASTEBOARD (PASTE1)
     IF (.NOT. STATUS) CALL LIB$SIGNAL(%val(STATUS))

    C Put data in the virtual display.

     STATUS = SMG$PUT_CHARS ( DISPLAY1,
         1  'This is row number 1 of 4, you see', 1, 1 )
     IF (.not. STATUS) CALL LIB$SIGNAL(%val(STATUS))

     STATUS = SMG$PUT_CHARS ( DISPLAY1,
         1  'This is row number 2 of 4, you see', 2, 1 )
     IF (.not. STATUS) CALL LIB$SIGNAL(%val(STATUS))

     STATUS = SMG$PUT_CHARS ( DISPLAY1,
         1  'This is row number 3 of 4, you see', 3, 1 )
     IF (.not. STATUS) CALL LIB$SIGNAL(%val(STATUS))

     STATUS = SMG$PUT_CHARS ( DISPLAY1,
         1  'This is row number 4 of 4, you see', 4, 1 )
     IF (.not. STATUS) CALL LIB$SIGNAL(%val(STATUS))

    C Paste the virtual display.

     STATUS = SMG$COPY_VIRTUAL_DISPLAY(DISPLAY1,DISPLAY2)
     IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

     STATUS = SMG$LABEL_BORDER (DISPLAY1, 'Full Display',,,SMG$M_BOLD)
     IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

     STATUS = SMG$LABEL_BORDER (DISPLAY2,'Viewport',,,SMG$M_BOLD)
     IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

     STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 2, 2 )
     IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

     STATUS = SMG$CREATE_VIEWPORT ( DISPLAY2, 1, 5, 26, 55 )
     IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

     STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY2, PASTE1, 8, 2 )
     IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

     CALL SMG$SET_PHYSICAL_CURSOR(PASTE1, 16, 1)
     TYPE *, ' '
     TYPE *, LIB$SIGNAL(%VAL(STATUS))

     STATUS = SMG$GET_VIEWPORT_CHAR ( DISPLAY2, A, B, C, D )
     IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

     TYPE *, ' '
     WRITE(5,7) A,B
    7 FORMAT(1X,'Row start = ',I2,8X,'Column start = ',I2)
     TYPE *, ' '
     WRITE(5,8) C,D
    8 FORMAT(1X,'Number of rows =',I2,4X,'Number of columns =',I3)

     END

> The output for this program is shown in Figure SMG-26.

> Figure SMG-26 Output Generated by SMG$GET_VIEWPORT_CHAR

## SMG$HOME_CURSOR

> The Home Cursor routine moves the virtual cursor to the specified corner of a virtual display.

### Format

> SMG$HOME_CURSOR display-id [,position-code]

### 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 in which the virtual cursor is moved. The display-id argument is the address of a longword that contains the display identifier.

> The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

> #### position-code

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

> Specifies the point to which the virtual cursor moves. The position-code argument is the address of a longword that contains the position code.

> Valid codes for position-code are as follows:

> Code | Meaning
> --- | ---
> SMG$C_UPPER_LEFT | Row 1, column 1 (the upper left corner). This is the default if position-code is not specified.
> SMG$C_LOWER_LEFT | Row n, column 1 (where n is the number of rows in the display). That is, the lower left corner. It is useful to specify this position when accepting input for an upward-scrolling virtual display.
> SMG$C_UPPER_RIGHT | Row 1, column m (where m is the number of columns in the display). That is, the upper right corner.
> SMG$C_LOWER_RIGHT | Row n, column m (where n is the number of rows and m is the number of columns in the display). That is, the lower right corner.

### Description

> SMG$HOME_CURSOR moves the virtual cursor to a corner of the specified virtual display, according to the code specified in the position-code argument. You do not need to know the dimensions of the virtual display, or the virtual cursor location. If you omit the position-code argument, SMG$HOME_CURSOR moves the virtual display cursor to the upper left corner of the virtual display.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INVARG | Invalid argument.
> SMG$_INVDIS_ID | Invalid display-id.
> SMG$_WRONUMARG | Wrong number of arguments.

## SMG$INIT_TERM_TABLE

> The Initialize Terminal Table 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 terminal-name, termtable-address

### RETURNS

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

### Arguments

> #### terminal-name

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

> Specifies the name of the terminal. The terminal-name argument is the address of a descriptor pointing to the terminal name. The name must be an entry in TERMTABLE.EXE.

> #### 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 that contains the address of the terminal capabilities table.

> You use this address when calling the SMG$GET_TERM_DATA procedure for the specified type of terminal. The TERMTABLE address is also returned by SMG$INIT_TERM_TABLE_BY_TYPE.

### Description

> SMG$INIT_TERM_TABLE 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. This routine should be used only when you perform direct (non-SMG$) I/O to terminals.

> SMG$INIT_TERM_TABLE 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.

Previous | Next | Contents | Index

| privacy and legal statement |
5935PRO_021.HTML