Updated: 11 December 1998

OpenVMS RTL Screen Management (SMG$) Manual

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.

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 Digital-supplied library $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.

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

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.

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.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

5935PRO_021.HTML