Document revision date: 19 July 1999

Input operations terminated by a condition are indicated by the terminator codes SMG$K_TRM_CANCELLED, SMG$K_TRM_TIMEOUT, SMG$K_TRM_BUFFER_FULL, and SMG$K_TRM_UNKNOWN. If the input is from an OpenVMS RMS file, each input operation reads one record from the file; the terminator code is always the code for a Return. (The only exception is SMG$READ_KEYSTROKE, in which the terminator is the next character in the record.)

3.6.4 Key Name and Terminator Code Translation

The SMG$NAME_TO_KEYCODE routine translates the name of a key on the keyboard to its corresponding terminator code, while SMG$KEYCODE_TO_NAME translates the terminator code to the corresponding name of the key on the keyboard.

3.6.5 Symbolic Definitions of Terminator Values

Symbolic definitions of the terminator values are provided in Digital-supplied symbol libraries named $SMGDEF. For example, in a MACRO program you would issue a call to $SMGDEF to extract these definitions. The symbol names are of the form SMG$K_TRM_keyname, where keyname is the key name given in Table 3-1. For terminator codes 1 through 26, which correspond to the control sequences Ctrl/A through Ctrl/Z, the key names are CTRLA for Ctrl/A, CTRLB for Ctrl/B, and so on. The following synonyms are also defined:

Symbol	Synonym
SMG$K_TRM_BS	SMG$K_TRM_CTRLH
SMG$K_TRM_HT	SMG$K_TRM_CTRLI
SMG$K_TRM_LF	SMG$K_TRM_CTRLJ
SMG$K_TRM_CR	SMG$K_TRM_CTRLM
SMG$K_TRM_E1	SMG$K_TRM_FIND
SMG$K_TRM_E2	SMG$K_TRM_INSERT_HERE
SMG$K_TRM_E3	SMG$K_TRM_REMOVE
SMG$K_TRM_E4	SMG$K_TRM_SELECT
SMG$K_TRM_E5	SMG$K_TRM_PREV_SCREEN
SMG$K_TRM_E6	SMG$K_TRM_NEXTSCREEN
SMG$K_TRM_F15	HELP
SMG$K_TRM_F16	DO

3.7 Line Recall and the Recall Buffer

The Screen Management Facility allows you to access and change the contents of the application recall buffer. By default, the recall buffer stores the previous 20 commands or data lines entered by the user to the application.

The SMG$RETURN_INPUT_LINE routine lets you request a particular line from the recall buffer. You can either specify the appropriate line number for the line to be recalled, or you can specify a match string. If you use a match string, SMG$RETURN_INPUT_LINE searches for and returns the line that matches the specified string. This routine aids in the implementation of a DCL-style RECALL command.

The SMG$REPLACE_INPUT_LINE routine lets you replace the specified line or lines in the recall buffer with the specified string. The remaining lines of the recall buffer are deleted. This routine aids in processing line continuations.

3.8 Interaction of Input and Output

SMG$READ_COMPOSED_LINE, SMG$READ_KEYSTROKE, SMG$READ_STRING, and SMG$READ_VERIFY accept an optional display-id argument. If a display-id is supplied, it designates the virtual display in which the input operation should occur. By specifying display-id, you enable the Screen Management Facility to remain aware of the changes caused by character echoing. If you omit display-id, the Screen Management Facility assumes that screen management output is not being used.

Note that if the display-id argument is specified for any one of the above-mentioned input routines, then the length of the prompt string plus the input is limited to the number of columns in the display or, where specified, to the maximum number of characters to be read. (In the case of SMG$READ_KEYSTROKE, this restriction applies only to the length of the prompt string.)

The Screen Management Facility provides several advanced features to:

• Trap asynchronous events
• Create and execute commands in a subprocess
• Move the physical cursor
• Clean up at exit

The following sections describe these features.

The following types of asynchronous events can disrupt the screen image:

• Broadcast messages
• Unsolicited input
• Out-of-band asynchronous system traps (ASTs)

The following sections explain how to control these actions.

Normally, broadcast messages (for example, MAIL notifications or operator messages) can appear on the terminal screen at any time, destroying or distorting the screen image. The SMG$SET_BROADCAST_TRAPPING routine lets you trap messages broadcast to the specified terminal (pasteboard) and in addition, lets you specify an AST routine to be called whenever a broadcast message is trapped. The AST routine you supply can access the broadcast message by calling the SMG$GET_BROADCAST_MESSAGE routine.

Whether or not you specify an AST routine in the call to SMG$SET_BROADCAST_TRAPPING, you can check for the receipt of a broadcast message at any time by calling SMG$GET_BROADCAST_MESSAGE.

4.1.2 Unsolicited Input

The SMG$ENABLE_UNSOLICITED_INPUT routine detects the presence of unsolicited input. Note that this routine does not read any input characters; it merely calls an AST routine to notify the application that it should issue a read operation with SMG$READ_COMPOSED_LINE, SMG$READ_KEYSTROKE, SMG$READ_STRING, or SMG$READ_VERIFY. It is up to you to read the unsolicited input.

4.1.3 Out-of-Band ASTs

The SMG$SET_OUT_OF_BAND_ASTS routine provides a way to trap out-of-band characters such as Ctrl/Y, Ctrl/C, and Ctrl/O. This routine lets you specify which characters are to be treated as out-of-band characters and also lets you specify an AST routine to be called when one of these characters is typed.

4.2 Subprocesses

The Screen Management Facility lets you use a subprocess to execute DCL commands from an application. Only one subprocess is allowed per virtual display.

4.2.1 Creating a Subprocess

The SMG$CREATE_SUBPROCESS routine creates a subprocess. This routine creates a DCL subprocess and associates it with a virtual display you specify. The subprocess is initialized with the DCL commands SET NOVERIFY and SET NOON. The creating process requires an available BYTLM value of at least 5000 and an available PRCLM value of at least 1. The Screen Management Facility checks to make sure that you have sufficient resources before creating the subprocess.

4.2.2 Deleting a Subprocess

When you are done executing subprocess commands, you can delete the subprocess with the SMG$DELETE_SUBPROCESS routine. If you exit without first calling this routine, the Screen Management Facility includes an exit handler that deletes the subprocess for you. It is important to note, however, that under some circumstances these facility-supplied exit handlers are not executed. In that case, you must delete the subprocess with the following commands using your system-assigned process identifier (PID) code for xxxx:

$ SHOW PROCESS/SUB $ STOP/IDENT=xxxx

4.2.3 Executing Commands in a Subprocess

The SMG$EXECUTE_COMMAND routine executes a specified command in the created subprocess. If commands are being buffered, SMG$EXECUTE_COMMAND returns control after the specified command is buffered. The AST routine that you specify is invoked with the command status when the command completes execution. If commands are not being buffered, SMG$EXECUTE_COMMAND waits until the command has completed execution before returning the status of the command.

When you specify the command string to be executed, you must specify a dollar sign ($) as the first character of any DCL command. The Screen Management Facility assumes that any command string that does not begin with a dollar sign is input data for the previous command. The commands and their outputs are displayed on the specified virtual display as they are executed. Note that the commands SPAWN, GOTO, and LOGOUT are illegal to use as command strings and generate unpredictable results.

It is also important to note that since I/O is performed by means of mailboxes and not through the terminal driver, single-character commands such as Ctrl/C, Ctrl/Y, Ctrl/Z, and so on have no effect. Use SMG$M_SEND_EOF as the flags parameter in order to pass a Ctrl/Z to the subprocess.

4.3 Moving the Cursor

The Screen Management Facility lets you move the cursor to a specified location on the physical screen. It does so through the SMG$SET_PHYSICAL_CURSOR routine. However, if you attempt to move the cursor to a pasteboard position outside the screen boundaries, an error is returned.

4.4 Exit Handler

The Screen Management Facility supplies an exit handler, which is invoked before image termination. This handler deletes all pasteboards and virtual keyboards associated with the current image and resets the terminal characteristics. The Screen Management Facility's exit handler may or may not be invoked before any user-supplied exit handlers. Therefore, you should not delete pasteboards or virtual displays from inside a user-supplied exit handler because they may already have been deleted by the Screen Management Facility exit handler and their identifiers deassigned.

This chapter describes SMG$ support for foreign terminals. A foreign terminal is any terminal for which the device type is not one of the Digital terminals recognized by OpenVMS, or any terminal on which the ANSI_CRT characteristic is not set.

This support is used by the Screen Management Facility, but it can also be used by application programs that perform their own I/O to foreign terminals. Thus, if you use the Screen Management Facility, you need to concern yourself only with the definition of foreign terminal capabilities, and not with the details of calling the foreign terminal routines directly. Further, you need to define only a few terminal capabilities ("set absolute cursor position," "erase to end of display," and "erase to end of line") in order for the Screen Management Facility to effectively control the terminal screen. The routines used by the Screen Management Facility are presented here to allow you to do your own I/O to foreign terminals.

The support begins with a source file named TERMTABLE.TXT, which contains a list of terminal names and their associated capabilities. This file is processed by the SYS$SYSTEM:SMGBLDTRM.EXE program to create an image file called TERMTABLE.EXE. The following sections describe the creation and processing of the TERMTABLE database.

Note that the TERMTABLE support is used by the Screen Management Facility for all terminals, including Digital terminals. The definitions for Digital terminals are included in a file named SYS$SYSTEM:SMGTERMS.TXT, which is provided as part of the Screen Management Facility. The examples in this chapter show you how to use the foreign terminal package to define Digital terminals, because most users are familiar with them.

TERMTABLE.EXE is a database containing information about any number of different types of terminals. You extract information from this database with these steps:

1. Provide the terminal name to the database.
2. Retrieve the information about that terminal type (this step might be repeated any number of times).
3. End access to the database.

When using screen management routines to perform I/O to foreign terminals, you need only create the proper TERMTABLE entries for the foreign terminals you use. The steps listed above are necessary only when your program performs I/O directly to foreign terminals.

The first step can be performed in either of two ways. You can either pass a string that contains a terminal name (for example, "VT100") to the SMG$INIT_TERM_TABLE routine, or you can pass a value returned by the OpenVMS system service $GETDVI to the SMG$INIT_TERM_TABLE_BY_TYPE routine. The returned value may be a symbolic terminal type (for example, TT$_VT100 or TT$_VT52) or a value assigned by the SMG$ foreign terminal routines to designate a particular foreign terminal.

The second step requires that you call the SMG$GET_TERM_DATA routine. This routine extracts a command string (for example, an escape sequence) from TERMTABLE and stores it in a buffer you provide. It is then your responsibility to write the command string to the terminal. It may be necessary to call SMG$GET_TERM_DATA many times; each time you receive the command sequence you can perform a different operation. You should also call SMG$GET_TERM_DATA each time you want to use a capability string that requires a substitution or arithmetic operation for an argument. However, you may want to save the static capability strings in your program's local storage. These static capability strings can be retrieved once and used any number of times.

The third step is optional; it merely frees the virtual memory used to access the information in the database.

The DCL commands SET and SHOW TERMINAL recognize any name defined in TERMTABLE, as well as the current set of valid OpenVMS terminal names. If you use the SET TERMINAL/DEVICE=name command to specify a terminal that is unknown to the OpenVMS operating system, the TERMTABLE database is searched for the named terminal.

Two routines are provided to obtain the address of a specific terminal definition. SMG$INIT_TERM_TABLE accepts a terminal name as input; SMG$INIT_TERM_TABLE_BY_TYPE accepts a device type as input. Each maps to a specific terminal entry in the TERMTABLE.EXE section. These routines return this identifier to the caller for use in future calls.

SMG$GET_TERM_DATA accepts the identifier of the compiled TERMTABLE database and a request code. The request code is used as an index into the data to retrieve the appropriate escape sequence. Some sequences are static; they do not contain any variable information and are simply copied into the caller's buffer. Variable sequences, which include a ! or % directive, cause additional processing to take place. An example of a variable sequence is the VT300-series set cursor command: the required binary row and column numbers must be converted to ASCII for the set cursor sequence. SMG$GET_TERM_DATA uses the optional input arguments to do the conversion before copying the sequence to the caller's buffer.

If you do not provide any optional input arguments to SMG$GET_TERM_DATA, it uses a default of 1 for each argument that the capability requires. Nevertheless, you cannot supply some of the optional arguments and accept the default for others---you must supply all or none of them. SMG$GET_NUMERIC_DATA provides a simplified interface for users who wish to obtain numeric or Boolean data only.

When all terminal I/O has been completed, SMG$DEL_TERM_TABLE can be called to release the virtual memory used. This routine is useful only if you do not need TERMTABLE for the duration of your program; releasing virtual memory may make it available for reuse by your program.

A skeleton TERMTABLE.TXT is supplied in SYS$SYSTEM:. SMGTERMS.TXT, which defines Digital terminals, is also provided. The skeleton TERMTABLE.TXT uses the REQUIRE directive to include the separate source file SMGTERMS.TXT. Thus, only third-party terminals are actually defined in the TERMTABLE.TXT source file.

5.2 Capability Fields

If you have a foreign (third-party) terminal, the Screen Management Facility does not know what your terminal can and cannot do---in other words, what the terminal's capabilities are. Capability fields let you tell the Screen Management Facility what capabilities are supported for your foreign terminal. These fields let SMG$ use your terminal capabilities rather than emulate common terminal functions, which in turn improves SMG$'s performance.

Three types of capability fields are allowed in a TERMTABLE entry:

• Boolean
• Numeric
• String

The following sections describe these capability fields in detail.

Functions that are common to most terminals have been chosen as possible fields; not all functions of all terminal types are represented. (Specifically, there is no support for block mode, graphics, or typesetting composition functions.) Screen-oriented applications should be planned around typical terminal functions, and should not depend on features that exist on only one or a few models.

For applications that must support an unusual terminal, some generic capability names are reserved for user definition. Names of the form PRIVATE_BOO_n, PRIVATE_NUM_n, and PRIVATE_STR_n, where n is a number from 1 to 10, may be included as user-defined terminal definitions and returned by the TERMTABLE interface routines. Since meanings are assigned by the user, private capabilities vary between applications. Sites running several applications must guard against multiple definitions for a single private capability. (For example, you should include separate terminal entries for a terminal that requires PRIVATE_STR_1 to mean two different things, depending on the application program being run.) In general, you should not have to use private capabilities.

The following characters are used as delimiters in capability fields:

Delimiter	Meaning
!	Begins a comment
=	Separates a capability field name from its value
,	Separates capability fields
"	Delimits strings

5.2.1 Boolean Capability Fields

Boolean capabilities are either present or not present for a given terminal.

The format for a Boolean capability field is as follows:

BOOLEAN {Boolean-capability = binary-digit} [,...]

Following are the meanings of the elements:

• Boolean-capability --- One of the capability fields listed in Table 5-1
• Binary-digit --- Either 1 or 0

Table 5-1 Boolean Capabilities

Capability Field	Used by SMG	Meaning if Set
ADVANCED_VIDEO	N	The terminal has advanced video attributes and is capable of 132-column mode operation.
ANSI_COLOR	N	Terminal conforms to ANSI color programming standards.
ANSI_CRT	N	Terminal conforms to ANSI CRT programming standards.
AUTO_MARGIN	N	Terminal has automatic margins.
BACKSPACE	Y	Terminal can backspace with Ctrl/H.
BLOCK_MODE	N	Terminal can perform block mode transmission, local editing, and field protection.
CURSOR_REPORT_ANSI	N	Terminal uses the ANSI sequence to report the current cursor location.
DEC_CRT	N	Terminal conforms to Digital VT100 family standards.
DEC_CRT_2	N	Terminal conforms to Digital VT200 family standards.
DEC_CRT_3	N	Terminal conforms to Digital VT300 family standards.
DEC_CRT_4	N	Terminal conforms to Digital VT400 family standards.
DEC_CRT_5	N	Terminal conforms to Digital VT500 family standards.
EDIT	N	Terminal can perform ANSI-defined advanced editing functions.
EIGHT_BIT	N	Terminal uses 8-bit ASCII character code.
FULLDUP	N	Terminal operation mode is full-duplex (half-duplex if not set).
IGNORE_NEWLINE	N	Terminal ignores a newline after a wrap.
INSERT_MODE_NULLS	N	Insert mode distinguishes nulls on display.
LOWERCASE	N	Terminal has both uppercase and lowercase letters.
NO_ERASE	N	Standout (bolded) characters are not erased by writing over them.
NO_SCROLL	N	Terminal is not capable of scrolling.
OVERSTRIKE	N	Terminal is capable of overstriking.
PHYSICAL_FF	N	Terminal can accept form feeds (if not set, terminal driver must translate form feeds to multiple line feeds).
PHYSICAL_TABS	N	Terminal has hardware tabs (note that these tabs may need to be set with an initialization string).
PRINTER_PORT	N	Terminal has a printer port available.
PRIVATE_BOO_1 to 10	N	These fields denote user-defined capabilities 1 through 10.
REGIS	N	Terminal understands ReGIS graphics commands.
SCOPE	N	Terminal is a video terminal.
SET_CURSOR_COL_ROW	Y	Terminal uses column/row addressing.
SIXEL_GRAPHICS	N	Terminal can display graphics using the ReGIS-defined SIXEL graphics protocol.
SOFT_CHARACTERS	N	Terminal can load a user-defined character set.
UNDERLINE	N	Terminal has underlining capability (but not overstrike).

For example, the following TERMTABLE entry describes two characteristics of a VT300 series terminal:

NAME = "VT300_series" BOOLEAN ansi_crt = 1, dec_crt = 1

This entry specifies that the terminal conforms to ANSI CRT programming standards and to Digital VT300 series standards.

	privacy and legal statement
5935PRO_004.HTML