Document revision date: 30 March 2001

## OpenVMS RTL Screen Management (SMG$) Manual

Previous | Contents | Index

#### off-characteristics3

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

Bit mask that specifies the terminal characteristics to be reset from $TT3DEF. The off-characteristics3 argument is the address of an unsigned longword that contains the bit mask.

#### old-characteristics3

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

Retrieves the current terminal characteristics in the third group. The old-characteristics3 argument is the address of an unsigned longword that contains the bit mask.

### Description

> SMG$SET_TERM_CHARACTERISTICS changes or retrieves the terminal characteristics for a given pasteboard. The characteristics are defined by the $TTDEF and $TT2DEF macro modules in system symbol libraries supplied by Compaq. A benefit of using this routine is that it allows you to control multiple terminal characteristics in a single routine call.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_NOT_A_TRM | Pasteboard is not a terminal.
> SS$_xyz | Errors from LIB$QIOW.

### Example

    10      !+
            ! This VAX BASIC program demonstrates the use of the
            ! SMG$SET_TERM_CHARACTERISTICS routine.
            !-

            OPTION TYPE = EXPLICIT
            OPTION CONSTANT TYPE = INTEGER

            %INCLUDE "$SSDEF"  %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"
            %INCLUDE "$TTDEF"  %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"
            %INCLUDE "$TT2DEF" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"

            DECLARE LONG S, PASTEBOARD_ID, ON_1, ON_2, OFF_1, OFF_2, OLD_1, OLD_2

            EXTERNAL LONG FUNCTION LIB$SIGNAL( LONG BY VALUE ),     &
                                   SMG$CREATE_PASTEBOARD( LONG ),   &
                                   SMG$SET_TERM_CHARACTERISTICS( LONG, LONG, &
                                    LONG, LONG, LONG, LONG, LONG )
            !+
            ! Create the pasteboard
            !-

            S = SMG$CREATE_PASTEBOARD( PASTEBOARD_ID )
            IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL( S ) END IF

            !+
            ! Terminal characteristics to be set
            !-

            ON_1 = TT$M_LOWER
            ON_2 = TT2$M_EDITING + TT2$M_EDIT

            !+
            ! Terminal characteristics to be reset
            !-

            OFF_1 = TT$M_WRAP + TT$M_MECHTAB
            OFF_2 = TT2$M_PASTHRU + TT2$M_INSERT

            !+
            ! Change the characteristics of the terminal line associated
            ! with the pasteboard.  They will be reset at image exit or when
            ! SMG$DELETE_PASTEBOARD is called. The previous characteristics
            ! are returned in OLD_1 and OLD_2.
            !-

            S = SMG$SET_TERM_CHARACTERISTICS( PASTEBOARD_ID, ON_1, ON_2, &
                                              OFF_1, OFF_2, OLD_1, OLD_2 )
            IF S <> SS$_NORMAL THEN CALL LIB$SIGNAL( S ) END IF

            IF (OLD_1 AND TT$M_WRAP) <> 0
            THEN
                PRINT "WRAP was set"
            ELSE
                PRINT "NOWRAP was set"
            END IF

            IF (OLD_2 AND TT2$M_ANSICRT) <> 0
            THEN
                PRINT "Pasteboard is an ANSI terminal"
            ELSE
                PRINT "Pasteboard is not an ANSI terminal"
            END IF

            END

## SMG$SNAPSHOT

> The Write Snapshot routine writes the current pasteboard buffer to the file or hardcopy terminal specified by the pasteboard identifier.

### Format

> SMG$SNAPSHOT pasteboard-id [,flags]

### RETURNS

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

### Arguments

> #### pasteboard-id

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

> Specifies the file or hardcopy terminal to receive the contents of the pasteboard buffer. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. The output device associated with pasteboard-id is specified by the output-device argument of SMG$CREATE_PASTEBOARD.

> #### flags

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

> Optional bit mask that specifies whether a form feed is passed. The flags argument is the address of an unsigned longword containing the flag. Valid values for flags are as follows:

> 0 | No form feed is passed.
> SMG$M_FORM_FEED | The first line passed is a form feed.

### Description

> SMG$SNAPSHOT is meant to be used when output to the pasteboard is controlled by OpenVMS RMS --- that is, when the output device is a file, a hardcopy terminal, or a terminal of unknown type. In this case, the pasteboard information is stored internally and is sent to either the file, hardcopy terminal, or the terminal of unknown type whenever SMG$SNAPSHOT is called. This allows you to capture pasteboard images in a file.

> Pasteboard batching does not affect the SMG$SNAPSHOT routine. If you enable pasteboard batching with the SMG$BEGIN_PASTEBOARD_UPDATE routine, a buffer is created that saves all output to a pasteboard until you disable batching with a call to SMG$END_PASTEBOARD_UPDATE. When you call SMG$SNAPSHOT, you get a snapshot of that current pasteboard buffer --- not what is possibly a stale screen image.

> This routine must be used if the SMG$_WILUSERMS error is returned by other SMG$ routines.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_NOTRMSOUT | Successful completion. No action was taken because output is not controlled by RMS.

Any condition value returned by RMS.

## SMG$SNAPSHOT_TO_PRINTER

> The Write Snapshot to Printer routine writes the current pasteboard buffer to the printer attached to the terminal.

### Format

> SMG$SNAPSHOT_TO_PRINTER pasteboard-id ,device-type [,flags]

### RETURNS

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

### Arguments

> #### pasteboard-id

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

> Identifier of the pasteboard whose snapshot will be sent to a printer. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

> #### device-type

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

> Specifies the type of printer to which the output associated with this pasteboard will be written. The device-type argument is the address of a descriptor that points to the name of the output device. Valid values for this argument (for example, LA50) are defined in SYS$SYSTEM:TERMTABLE.TXT.

> #### flags

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

> Optional bit mask that specifies whether a form feed is passed. The flags argument is the address of an unsigned longword containing the flag. The valid value for the flags argument is as follows:

> SMG$M_FORM_FEED | Output a form feed as the first record.

### Description

> SMG$SNAPSHOT_TO_PRINTER writes the current pasteboard buffer to the specified printer. This routine returns SMG$_OPNOTSUP if the output device (terminal) does not have a printer attached to its printer port.

> Pasteboard batching does not affect the SMG$SNAPSHOT_TO_PRINTER routine. If you enable pasteboard batching with the SMG$BEGIN_PASTEBOARD_UPDATE routine, a buffer is created that saves all output to a pasteboard until you disable batching with a call to SMG$END_PASTEBOARD_UPDATE. When you call SMG$SNAPSHOT_TO_PRINTER, you get a snapshot of that current pasteboard buffer --- not what is possibly a stale screen image.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_OPNOTSUP | Operation not supported.

Any condition value returned by LIB$GET_VM, LIB$FREE_VM, or $QIOW.

## SMG$UNPASTE_VIRTUAL_DISPLAY

> The Remove Virtual Display routine removes a virtual display from a pasteboard.

### Format

> SMG$UNPASTE_VIRTUAL_DISPLAY display-id ,pasteboard-id

### 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 to be removed from a pasteboard. 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.

> #### pasteboard-id

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

> Specifies the pasteboard from which the virtual display is removed. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

### Description

> SMG$UNPASTE_VIRTUAL_DISPLAY removes the specified display from the specified pasteboard, and thus from the screen associated with the pasteboard. This routine does not destroy the virtual display or its contents; it only removes its association with a particular pasteboard and its visibility on the screen. Any text occluded by the specified virtual display becomes visible again.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INVARG | Invalid argument. The specified virtual display is not pasted to the specified pasteboard.
> SMG$_INVDIS_ID | Invalid display-id.
> SMG$_INVPAS_ID | Invalid pasteboard-id.
> SMG$_NOTPASTED | The specified virtual display is not pasted to the specified pasteboard.
> SMG$_WRONUMARG | Wrong number of arguments.

Index | Contents

| privacy and legal statement |
5935PRO_038.HTML