HP OpenVMS Systems Documentation

OpenVMS/Hanzi RTL Chinese Screen Management (SMG$) Manual

The Chinese 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 is intended to aid 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 is intended to aid in processing line continuations.

3.7 Interaction of Input and Output

SMG$READ_COMPOSED_LINE, SMG$READ_KEYSTROKE, and SMG$READ_STRING 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 Chinese Screen Management Facility to remain aware of the changes caused by character echoing. If you omit display-id, the Chinese Screen Management Facility assumes that Chinese 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 Chinese 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.

There are three types of asynchronous events that can disrupt the screen image:

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

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, or SMG$READ_STRING. 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 Chinese 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

You create a subprocess with the SMG$CREATE_SUBPROCESS routine. This routine creates a DCL subprocess and associates it with a virtual display you specify. The subprocess is initialized with the SET NOVERIFY and SET NOON DCL commands. 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 Chinese 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:

$ SHOW PROCESS/SUB
$ STOP/IDENT=xxxx

The SMG$EXECUTE_COMMAND routine lets you execute 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 "$" as the first character of any DCL command. The Screen Management Facility assumes that any command string that does not begin with a "$" 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 Chinese 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 Chinese 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 Chinese 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 Chinese 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 Chinese Screen Management Facility but it can also be used by application programs that need to do their own I/O to foreign terminals. Thus, if you use the Chinese 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. However, the routines used by the Chinese 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 Chinese 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 Chinese Screen Management Facility. The examples in the following section show you how to use the foreign terminal package to define Digital terminals, because most users are familiar with them. Note that you should not create your own definitions for Digital terminals, nor should you modify the definitions in SYS$SYSTEM:SMGTERMS.TXT.

5.1 TERMTABLE Interface Routines

TERMTABLE.EXE is a database containing information about any number of different types of terminals. You extract information from this database in three 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.

Note that when using Chinese 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 is doing 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. Note that 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. Note that 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.

Note that the DCL SET and SHOW TERMINAL commands 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.

Note that 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.

Note that SMGTERMS.TXT should not be modified by users.

5.2 Capability Fields

If you have a foreign (third party) terminal, the Chinese 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 Chinese 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 will 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.

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

The format for a Boolean capability field is as follows:

Following are the meanings of the elements:

Table 5-1 lists these Boolean capability fields.

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.