OpenVMS RTL Screen Management (SMG$) Manual

Document revision date: 30 March 2001

OpenVMS RTL Screen Management (SMG$) Manual

Contents

Index

SMG$ERASE_COLUMN

The Erase Column from Display routine erases the specified portion of the virtual display from the given position to the end of the column.

Format

SMG$ERASE_COLUMN display-id [,start-row] [,column-number] [,end-row]

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 affected. The display-id argument is the address of an unsigned longword containing this virtual display identifier.
start-row

OpenVMS usage: longword_signed

type: longword (signed)

access: read only

mechanism: by reference

Optional line number at which the erase operation begins. The start-row argument is the address of a signed longword that contains the specified line number. If this argument is omitted, the column-number argument is ignored and the erase operation begins at the current location of the virtual cursor for that virtual display.
column-number

OpenVMS usage: longword_signed

type: longword (signed)

access: read only

mechanism: by reference

Optional column number at which the erase operation begins. The column-number argument is the address of a signed longword that contains the specified column number. If this argument is omitted, the start-row argument is ignored and the erase operation begins at the current location of the virtual cursor for that virtual display.

end-row

OpenVMS usage: longword_signed

type: longword (signed)

access: read only

mechanism: by reference

Optional row number at which the erase operation ends. The end-row argument is the address of a signed longword that contains the specified row number.

Description

SMG$ERASE_COLUMN lets you erase a column of the virtual display from the specified position to the end of the column. If the position is not specified, the erase operation begins at the current position of the virtual cursor in the specified virtual display. After the erase operation has completed, this routine leaves the virtual cursor at the position of the first character erased.

Condition Values Returned

SS$_NORMAL Normal successful completion.

SMG$ERASE_DISPLAY

The Erase Virtual Display routine erases all or part of a virtual display by replacing text characters with blanks.

Format

SMG$ERASE_DISPLAY display-id [,start-row] [,start-column] [,end-row] [,end-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

Specifies the virtual display to be erased. 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.
start-row

OpenVMS usage: longword_signed

type: longword (signed)

access: read only

mechanism: by reference

Specifies the row at which the erase operation begins. The start-row argument is the address of a signed longword that contains the number of the row at which the erasure begins.
If the start-row argument is not specified, start-column is also ignored and the entire virtual display is erased. If you do not specify start-row and start-column, then end-row and end-column are ignored and the entire virtual display is erased.
start-column

OpenVMS usage: longword_signed

type: longword (signed)

access: read only

mechanism: by reference

Specifies the column at which the erase operation begins. The start-column argument is the address of a signed longword that contains the number of the column at which the erasure begins.
If the start-column argument is not specified, start-row is also ignored and the entire virtual display is erased. If you do not specify start-row and start-column, then end-row and end-column are ignored and the entire virtual display is erased.
end-row

OpenVMS usage: longword_signed

type: longword (signed)

access: read only

mechanism: by reference

Specifies the row at which the erase operation ends; that is, the last row to be erased. The end-row argument is the address of a signed longword that contains the number of the last row to be erased.
If the end-row argument is not specified, end-column is also ignored and all remaining rows in the display are erased.
end-column

OpenVMS usage: longword_signed

type: longword (signed)

access: read only

mechanism: by reference

Specifies the column at which the erase operation ends; that is, the last column to be erased. The end-column argument is the address of a signed longword that contains the number of the last column to be erased.
If the end-column argument is not specified, end-row is also ignored and all remaining columns in the display are erased.

Description

SMG$ERASE_DISPLAY causes all or part of a virtual display to be erased by replacing text characters with blanks. If omitted, the starting positions default to 1,1. The ending positions default to the last row or column in the display. Thus, to erase the entire virtual display, you need only pass the display-id. This routine leaves the virtual cursor at the start of the erased position. If the entire display is erased, the virtual cursor is left at position 1,1.

Condition Values Returned

SS$_NORMAL Normal successful completion.

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

SMG$_INVDIS_ID Invalid display-id.

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

SMG$_WRONUMARG Wrong number of arguments.

Example


C+ C This Fortran example program demonstrates the use of SMG$ERASE_DISPLAY. C- IMPLICIT INTEGER (A-Z) C+ C Call SMG$CREATE_VIRTUAL_DISPLAY to create the virtual C display. To give it a border, set BORDER = 1. C 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 Using SMG$CREATE_PASTEBOARD, create the pasteboard. C- STATUS = SMG$CREATE_PASTEBOARD (PASTE1) IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) C+ C Call 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 by calling 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$ERASE_DISPLAY to erase the display from row 2, C column 6, through row 4, column 28. C- STATUS = SMG$ERASE_DISPLAY ( DISPLAY1, 2, 6, 4, 28) IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) END

    
C+ 
C This Fortran example program demonstrates the use of SMG$ERASE_DISPLAY. 
C- 
 
        IMPLICIT INTEGER (A-Z) 
 
C+ 
C Call SMG$CREATE_VIRTUAL_DISPLAY to create the virtual 
C display. To give it a border, set BORDER = 1. 
C 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 Using SMG$CREATE_PASTEBOARD, create the pasteboard. 
C- 
 
        STATUS = SMG$CREATE_PASTEBOARD (PASTE1) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
C+ 
C Call 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 by calling 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$ERASE_DISPLAY to erase the display from row 2, 
C column 6, through row 4, column 28. 
C- 
 
        STATUS = SMG$ERASE_DISPLAY ( DISPLAY1, 2, 6, 4, 28) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
        END

The initial display output by this Fortran program is shown in Figure SMG-22.
Figure SMG-22 Initial Output of Fortran Program Calling SMG$ERASE_DISPLAY

This output displayed after the call to SMG$ERASE_DISPLAY is shown in Figure SMG-23.

Figure SMG-23 Output Displayed After the Call to SMG$ERASE_DISPLAY

SMG$ERASE_LINE

The Erase Line routine erases all or part of a line in a virtual display.

Format

SMG$ERASE_LINE display-id [,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

Specifies the virtual display to be affected. 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.
start-row

OpenVMS usage: longword_signed

type: longword (signed)

access: read only

mechanism: by reference

Specifies the line at which the erase operation starts. The start-row argument is the address of a signed longword that contains the number of the row at which the erasure starts. If omitted, start-column is also ignored and the current cursor position is used.
start-column

OpenVMS usage: longword_signed

type: longword (signed)

access: read only

mechanism: by reference

Specifies the column at which the erase operation starts. The start-column argument is the address of a signed longword that contains the number of the column at which the erasure starts. If omitted, start-row is also ignored and the current cursor position is used.

Description

SMG$ERASE_LINE erases a line from the specified starting position to the end of the line. If you do not specify a starting position, SMG$ERASE_LINE erases text from the current virtual cursor position to the end of the line. This routine leaves the virtual cursor at the start of the erased portion.

Condition Values Returned

SS$_NORMAL Normal successful completion.

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

SMG$_INVDIS_ID Invalid display-id.

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

SMG$_WRONUMARG Wrong number of arguments.

Example


C+ C This Fortran example program demonstrates the use of C SMG$ERASE_LINE. C- IMPLICIT INTEGER (A-Z) INCLUDE '($SMGDEF)' C+ C Use SMG$CREATE_VIRTUAL_DISPLAY to create a virtual display C with a border. C- ROWS = 7 COLUMNS = 50 STATUS = SMG$CREATE_VIRTUAL_DISPLAY 1 (ROWS, COLUMNS, DISPLAY1, SMG$M_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 Put data in the virtual display by calling SMG$PUT_CHARS. 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 Use SMG$PASTE_VIRTUAL_DISPLAY to paste the virtual display. C- STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 15) IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) C+ C Call SMG$ERASE_LINE to erase line 2, and then again to C erase the last 4 words on line 4. C- STATUS = SMG$ERASE_LINE ( DISPLAY1, 2, 1) IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) STATUS = SMG$ERASE_LINE ( DISPLAY1, 4, 9) IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) END

    
C+ 
C This Fortran example program demonstrates the use of 
C SMG$ERASE_LINE. 
C- 
 
        IMPLICIT INTEGER (A-Z) 
        INCLUDE '($SMGDEF)' 
 
C+ 
C Use SMG$CREATE_VIRTUAL_DISPLAY to create a virtual display 
C with a border. 
C- 
 
        ROWS = 7 
        COLUMNS = 50 
 
        STATUS = SMG$CREATE_VIRTUAL_DISPLAY 
     1          (ROWS, COLUMNS, DISPLAY1, SMG$M_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 Put data in the virtual display by calling SMG$PUT_CHARS. 
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 Use SMG$PASTE_VIRTUAL_DISPLAY to paste the virtual display. 
C- 
 
        STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 15) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
C+ 
C Call SMG$ERASE_LINE to erase line 2, and then again to 
C erase the last 4 words on line 4. 
C- 
 
        STATUS = SMG$ERASE_LINE ( DISPLAY1, 2, 1) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
        STATUS = SMG$ERASE_LINE ( DISPLAY1, 4, 9) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
        END

The initial output generated by the Fortran program is shown in Figure SMG-24.
Figure SMG-24 Initial Output Generated by Fortran Program Calling SMG$ERASE_LINE

The output generated after the call to SMG$ERASE_LINE is shown in Figure SMG-25.

Figure SMG-25 Output Generated After the Call to SMG$ERASE_LINE

SMG$ERASE_PASTEBOARD

The Erase Pasteboard routine erases the contents of a pasteboard.

Format

SMG$ERASE_PASTEBOARD pasteboard-id

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Argument

pasteboard-id

OpenVMS usage: identifier

type: longword (unsigned)

access: read only

mechanism: by reference

Specifies the pasteboard to be erased. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.
The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

Description

SMG$ERASE_PASTEBOARD erases the contents of a specified pasteboard. The physical cursor is left at position 1,1. If there are any virtual displays pasted to the pasteboard, they will be redrawn the next time the Screen Management Facility is used to output to the pasteboard.

Condition Values Returned

SS$_NORMAL Normal successful completion.

SS$_xxxx Any status from $QIOW.

SMG$_BATWAS_ON Pasteboard is batched.

SMG$_INVPAS_ID Invalid pasteboard-id.

SMG$_WRONUMARG Wrong number of arguments.

Example


C+ C This Fortran example program demonstrates the use of C SMG$ERASE_PASTEBOARD. C- IMPLICIT INTEGER4 (A-Z) CHARACTER80 OUT_STR,TRIM_STR CHARACTER*18 PROMPT /'Please enter data '/ SMG$M_BOLD = 1 SMG$M_REVERSE = 2 SMG$M_BLINK = 4 SMG$M_UNDERLINE = 8 C+ C Establish the terminal screen as a pasteboard using C SMG$CREATE_PASTEBOARD. C- STATUS = SMG$CREATE_PASTEBOARD (NEW_PID,,,) IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) C+ C Establish the terminal keyboard as the virtual keyboard C by calling SMG$CREATE_VIRTUAL_KEYBOARD. C- STATUS = SMG$CREATE_VIRTUAL_KEYBOARD(KEYBOARD_ID,,,) IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) C+ C Establish a virtual display region by C calling SMG$CREATE_VIRTUAL_DISPLAY. C- STATUS = SMG$CREATE_VIRTUAL_DISPLAY (5,80,DISPLAY_ID,,,) IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) C+ C Paste the virtual display to the screen, starting at C row 10, column 15. To paste the virtual display, use C SMG$PASTE_VIRTUAL_DISPLAY. C- STATUS = SMG$PASTE_VIRTUAL_DISPLAY(DISPLAY_ID,NEW_PID,10,15) IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) C+ C Prompt the user for input, and accept that input using C SMG$READ_STRING. C- STATUS = SMG$READ_STRING(KEYBOARD_ID,OUT_STR,PROMPT,,,,,,,) IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) C+ C Clear the screen using SMG$ERASE_PASTEBOARD. C- STATUS = SMG$ERASE_PASTEBOARD (NEW_PID) IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) C+ C Trim any trailing blanks from the user input C by calling STR$TRIM. C- STATUS = STR$TRIM(TRIM_STR,OUT_STR,STR_LEN) IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) C+ C Display the data input by the user using SMG$PUT_CHARS C and SMG$PUT_LINE. C- STATUS = SMG$PUT_CHARS(DISPLAY_ID,'You entered: ',,,,,,) IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) STATUS = SMG$PUT_LINE(DISPLAY_ID,TRIM_STR(1:STR_LEN),, 1 SMG$M_REVERSE,0,,) IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) END

C+ 
C This Fortran example program demonstrates the use of 
C SMG$ERASE_PASTEBOARD. 
C- 
 
        IMPLICIT INTEGER*4 (A-Z) 
        CHARACTER*80    OUT_STR,TRIM_STR 
        CHARACTER*18    PROMPT          /'Please enter data '/ 
 
        SMG$M_BOLD = 1 
        SMG$M_REVERSE = 2 
        SMG$M_BLINK = 4 
        SMG$M_UNDERLINE = 8 
C+ 
C Establish the terminal screen as a pasteboard using 
C SMG$CREATE_PASTEBOARD. 
C- 
 
        STATUS = SMG$CREATE_PASTEBOARD (NEW_PID,,,) 
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) 
C+ 
C Establish the terminal keyboard as the virtual keyboard 
C by calling SMG$CREATE_VIRTUAL_KEYBOARD. 
C- 
 
        STATUS = SMG$CREATE_VIRTUAL_KEYBOARD(KEYBOARD_ID,,,) 
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) 
C+ 
C Establish a virtual display region by 
C calling SMG$CREATE_VIRTUAL_DISPLAY. 
C- 
 
        STATUS = SMG$CREATE_VIRTUAL_DISPLAY (5,80,DISPLAY_ID,,,) 
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) 
C+ 
C Paste the virtual display to the screen, starting at 
C row 10, column 15.  To paste the virtual display, use 
C SMG$PASTE_VIRTUAL_DISPLAY. 
C- 
 
        STATUS = SMG$PASTE_VIRTUAL_DISPLAY(DISPLAY_ID,NEW_PID,10,15) 
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) 
C+ 
C Prompt the user for input, and accept that input using 
C SMG$READ_STRING. 
C- 
 
        STATUS = SMG$READ_STRING(KEYBOARD_ID,OUT_STR,PROMPT,,,,,,,) 
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) 
C+ 
C Clear the screen using SMG$ERASE_PASTEBOARD. 
C- 
 
        STATUS = SMG$ERASE_PASTEBOARD (NEW_PID) 
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) 
C+ 
C Trim any trailing blanks from the user input 
C by calling STR$TRIM. 
C- 
        STATUS = STR$TRIM(TRIM_STR,OUT_STR,STR_LEN) 
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) 
 
C+ 
C Display the data input by the user using SMG$PUT_CHARS 
C and SMG$PUT_LINE. 
C- 
 
        STATUS = SMG$PUT_CHARS(DISPLAY_ID,'You entered: ',,,,,,) 
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) 
        STATUS = SMG$PUT_LINE(DISPLAY_ID,TRIM_STR(1:STR_LEN),, 
     1                               SMG$M_REVERSE,0,,) 
        IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS)) 
        END

This Fortran program calls Run-Time Library Screen Management routines to format screen output, and to accept and display user input.

SMG$EXECUTE_COMMAND

The Execute Command in a Subprocess routine executes the specified command in the subprocess created with the SMG$CREATE_SUBPROCESS routine.

Format

SMG$EXECUTE_COMMAND display-id ,command-desc [,flags] [,ret-status]

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

Display identifier of the virtual display with which the subprocess is associated. The display-id argument is the address of an unsigned longword containing this identifier.
command-desc

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

Command string. The command-desc argument is the address of a descriptor pointing to the command string.
flags

OpenVMS usage: mask_longword

type: longword (unsigned)

access: read only

mechanism: by reference

Optional bit mask that specifies optional behavior. The flags argument is the address of an unsigned longword that contains the flag. The valid values for flags are as follows:

SMG$M_DATA_FOLLOWS Input data follows. The next call to SMG$EXECUTE_COMMAND contains input data for the currently executing command. Do not specify this value if this is the last input data item. If you do specify this value, ret-status is not returned.

SMG$M_SEND_EOF Send end-of-file marker. The end-of-file marker is sent to the subprocess.

ret-status

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by reference

Optional status of the executed command, provided that the commands are not being buffered. The ret-status argument is the address of an unsigned longword containing this status.

Description

SMG$EXECUTE_COMMAND lets you execute the specified command in the subprocess created with SMG$CREATE_SUBPROCESS. If commands are being buffered, this routine returns control after the command has been buffered, and the user-specified AST routine is invoked when the command completes. If commands are not being buffered, SMG$EXECUTE_COMMAND waits until the command has completed execution before returning the status of the command.
When specifying the command string, you must specify a dollar sign ($) as the first character of any DCL command. Any command string that does not begin with a dollar sign is assumed to be input data for the previous command. SMG$EXECUTE_COMMAND outputs the commands and their output to the specified virtual display as they are executed. Do not perform I/O to the specified virtual display. Note that the commands SPAWN, GOTO, and LOGOUT are illegal to use as command strings and generate unpredictable results.
Since I/O is performed using mailboxes and not through the terminal driver, command prompts and single-character commands such as Ctrl/C, Ctrl/Y, Ctrl/Z, and so forth have no effect. You should specify SMG$M_SEND_EOF for the flags argument in order to send a Ctrl/Z to the subprocess. For more information on mailboxes, see the mailbox driver section of the OpenVMS I/O User's Reference Manual.

Condition Values Returned

SS$_NORMAL Normal successful completion.

SS$_xxxx Any status from $QIO, $DCLAST, or $SYNCH.

SMG$_INPTOOLON Input is longer than 255 characters.

SMG$_INVDIS_ID Invalid display-id.

SMG$_NOSUBEXI No subprocess exists.

SMG$_xxxx Any status from SMG$PUT_LINE.

LIB$_xxxx Any status from LIB$ANALYZE_SDESC.

Contents

Index

privacy and legal statement

5935PRO_018.HTML

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

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

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

SS$_NORMAL	Normal successful completion.
SMG$_INVCOL	Invalid column number. The specified column is outside the virtual display.
SMG$_INVDIS_ID	Invalid display-id.
SMG$_INVROW	Invalid row number. The specified row is outside the virtual display.
SMG$_WRONUMARG	Wrong number of arguments.

SS$_NORMAL	Normal successful completion.
SS$_xxxx	Any status from $QIOW.
SMG$_BATWAS_ON	Pasteboard is batched.
SMG$_INVPAS_ID	Invalid pasteboard-id.
SMG$_WRONUMARG	Wrong number of arguments.

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

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

SMG$M_DATA_FOLLOWS	Input data follows. The next call to SMG$EXECUTE_COMMAND contains input data for the currently executing command. Do not specify this value if this is the last input data item. If you do specify this value, ret-status is not returned.
SMG$M_SEND_EOF	Send end-of-file marker. The end-of-file marker is sent to the subprocess.