HP OpenVMS Systems Documentation

off-characteristics3

old-characteristics3

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

      

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.

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.

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.