Ingres CL TE
From Ingres Community Wiki
|
Ingres Compatability Library |
Compatibility Library Specification - TE
Abstract
This is the specification of the TE facility provided by the compatibility library.
Revision: 1.1, 8-Oct-96
Document History
- Revision 1.1, last modified 8-Oct-96.
- Formatted for HTML.
- Revision 1.0, last modified 29-Aug-91.
- TE_NULL_OUT was revoked in favor of a TE_CMDMODE argument to TErestore.
- Much explanatory material was added.
- Interaction of SI, TE and TR was described.
- Typos fixed.
- 14-Aug-90.
- After printing the 6.3/02 spec, TEtest was changed to take the TE_NULL_OUT flag.
Specification
Introduction
TE provides routines to get information about terminals and to handle Terminal Driver IO.
Library
CL
Intended Uses
TE routines are used for opening and closing the terminal, and for putting and getting characters. TE routines supply information about the terminal. TE routines also switches the terminal between normal and forms mode. TEtest is instrumental in testing INGRES forms-based systems.
SI, TE and TR files may be open and used in the same program. SI and/or TR may do i/o to the terminal when it is in the default TE_NORMAL mode, assuming flushes (SIflush, TEflush, TRflush) of pending output are done. When in TE_FORMS or TE_CMDMODE, operations by SI or TR to the terminal are undefined. Output may be mixed as long as flush calls are made before using a new interface and the terminal mode restrictions are obeyed. Mixing input from one file between SI and TR gives undefined results.
Definitions/Concepts
TE identifies three states of terminal operation and output placement, signified by the constants TE_NORMAL, TE_FORMS and TE_CMDMODE. The setting of these modes determines the mode that the terminal is placed in as well as whether the output from functions TEput(), TEwrite() and TEcmdwrite() goes to the terminal or is discarded.
TE_NORMAL mode is when the terminal is operating in line mode. Keystrokes are echoed by the operating system.
TE_FORMS mode is when the INGRES Forms Runtime System is controlling the terminal. Keystrokes are not echoed by the operating system - any echoing will be done by the FRS. Additionally, control characters are fielded by the FRS.
TE_CMDMODE mode is when the INGRES Forms Runtime System is using a smart user interface such as the MacWorkStation, and communicating with it through commands. The terminal is put in a communication mode.
The following table describes what happens to the output in different modes when TEput(), TEwrite() or TEcmdwrite() are called.
| TE Output Matrix Mode - TErestore ( which ) |
|---|
| Operation | TE_NORMAL | TE_FORMS | TE_CMDMODE |
|---|---|---|---|
| TEput, TEwrite | undefined | send | discard |
| TEcmdwrite | undefined | undefined | send |
TE facilitates the testing of INGRES forms-based systems by providing a mechanism to redirect terminal input and output. The following constants are used to indicate the type of input or output file:
| TE_SI_FILE | indicates the file is an SI file |
| TE_TC_FILE | indicates the file is a COMM_file (see TC chapter for more information). |
| TE_NO_FILE | indicates that no redirection will take place. |
Header File <te.h>
The header file <te.h> must be included before using any of the functions provided. It also defines the following.
TEENV_INFO - Terminal environment information
Terminal environment information. Used by TEopen to return information to the calling routine. Currently contains a delay constant and the number of rows and columns on the terminal screen. If rows (or cols) is zero (0), use the value obtained by looking up TERM_INGRES in the termcap file. If rows (or cols) is greater than zero, then use this value instead of the one obtained from termcap. If rows (or cols) is negative, then the absolute value is used to indicate the number of rows (or cols) made unavailable to the forms runtime system (i.e., subtract from termcap value).
Caveat: This structure is not intended to be used for dynamically re-sizing the forms system window size at runtime.
typedef struct
{
i4 delay_constant; /*
** A multiplier for determining the number
** of pad characters sent during terminal
** output. Value based on terminal baud rate.
*/
i4 rows; /*
** If positive, this is the number of rows
** to use for the terminal. If zero, use
** value in termcap. If negative, use
** absolute value to indicate number of
** rows made unavailable to the forms
** runtime system (subtract from value
** obtained from termcap).
*/
i4 cols; /*
** If positive, this is the number of
** columns to use for the terminal. If zero,
** use value in termcap. If negative, use
** absolute value to indicate number of
** columns made unavailable to the forms
** runtime system (subtract from value
** obtained from termcap).
*/
} TEENV_INFO;
Executable Interface
The following functions are provided.
TEclose - close the terminal
Close the terminal. TEclose() should flush the operating system's buffer(s). It does an implicit TErestore(TE_NORMAL).
Inputs:
| None |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS TEclose()
TEcmdwrite - conditionally write buffer to terminal
TEcmdwrite is used to output characters in the command mode. It efficiently moves many characters to the buffer and then to the terminal. It makes sure that all the characters are sent to the terminal so there is no need to call teflush subsequently. The buffer is discarded without being written to the terminal if command mode is not enabled.
Input:
| buffer | pointer to buffer |
| length | number of characters in the buffer |
Outputs:
| None |
Returns:
| None |
Definition:
VOID TEcmdwrite(buffer, length) char *buffer; i4 length;
TEflush - flush buffers to terminal
Flush the operating system's buffer(s) to the terminal. Normally called when the buffer is full or when the application decides that the screen should be updated.
Inputs:
| None |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS TEflush()
TEget - get a character
Return the next character. Return EOF on end-of-file or error condition. Note that the implementation does not require the use of a lookahead buffer.
If the parameter 'seconds' is greater than zero and there is a need to ask the operating system for a character, then only wait the number of seconds as specified in the passed in parameter. A timeout has occurred if no characters are returned within the timeout period (as specified by the passed in parameter). For the timeout case, the return value will be TE_TIMEDOUT (defined in <te.h>).
In all other cases, TEget will return the (first) character from the lookahead buffer or OS.
If the parameter 'seconds' is zero or negative, or in environments that do not support input timeout, TEget will simply wait forever for user input (as it currently does).
When obtaining characters from a file (as is the case when running in testing mode), TEget will ignore timeout.
Inputs:
| seconds | Timeout period in wallclock seconds, <1 means wait for input. |
Outputs:
| None |
Returns:
Character (cast to a i4) obtained from lookahead buffer or OS.
| EOF | on end-of-file or error condition. |
| TE_TIMEDOUT | when timeout occurs. |
Definition:
i4 TEget(seconds) i4 seconds;
TEinflush - flush input
Flush any type ahead input from the terminal. The assumption here is that this routine will NOT be called if a forms based front end is in test mode (i.e., input coming from a file). This will eliminate the possibility of doing a flush on input that comes from a file.
Inputs:
| None |
Outputs:
| None |
Returns:
| None |
Definition:
VOID TEinflush()
TEjobcntrl - set handlers for job control
This routine allows a user to specify routines to call just before a process is suspended (due to job control) and when a process is re-activated. It is a NO-OP on systems that do not have job control. Argument reset points to a user supplied routine that is called before the process suspends itself. Redraw points to another user supplied routine that will be called once the process is re-activated. Either argument or both may be NULL. This means that any program that wants to handle job control can call this procedure.
Inputs:
| reset | pointer to a user-supplied function called before the process is suspended |
| redraw | pointer to a user-supplied function called when the process is re-activated. |
Outputs:
| None |
Returns:
| None |
Definition:
VOID TEjobcntrl(reset, redraw) VOID (*reset)(); VOID (*redraw)();
TElock - allow/disallow screen modification by a cooperating process
This entry point is currently a stub for all environments but DG. It is used to bracket sections of code within which the terminal screen may not be modified by another cooperating process. For DG, the process being locked out is that used to update the Comprehensive Electronic Office (CEO) status line.
Screen modification by the cooperating process is disallowed until this routine is first called to unlock the terminal. At that time, the current cursor location is also specified. Multiple attempts to lock the terminal will be accepted, but the first call to unlock the screen will succeed.
Coordinate system is zero based with the origin at the upper left corner of the screen with the X coordinate increasing to the right and the Y coordinate increasing towards the bottom.
Locking is called only when the forms system is about to update the screen. Thus the forms system will set the lock when it is about to update the terminal screen and unlock when it is finished. It is assumed that if an INGRES application exits, the cooperating process also exits. There is also no danger of locking the terminal physically since the locking mechanism described here is only for a parent and cooperating process. No other processes are affected.
Usage is TElock(TRUE, (nat) 0, (nat) 0) to lock the screen, TElock(FALSE, row, column) to re-enable screen updates.
Inputs:
| lock | Specify whether the program is to lock out screen updates. |
| row | Specify the cursor's y coordinate; ignored if screen is locked. Possible values range from 0 to the screen length - 1. |
| col | Specify the cursor's x coordinate; ignored if screen is locked. Possible values range from 0 to the screen width - 1. |
Outputs:
| None |
Returns:
| None |
Side Effects:
| This is a stub for all non-DG systems. |
Definition:
VOID TElock(lock, row, col) bool lock; i4 row; i4 col;
TEname - name of your login terminal
This routine figures out the terminal you are currently logged in on. You must pass a buffer to this routine so it can fill in the terminal name. It is assumed that the passed buffer is big enough.
Inputs:
| buffer | pointer to buffer that will hold the terminal name |
Outputs:
| buffer | pointer to buffer that holds the terminal name |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS TEname(buffer) char *buffer;
TEopen - initialize the terminal
Open up the terminal associated with this user's process. Get the speed of the terminal and use this to return a delay constant. Initialize the buffering structures for terminal I/O. TEopen() saves the state of the user's terminal for possible later use by TErestore(TE_NORMAL). Additionally, return the number of rows and columns on the terminal. For all environments but DG, these sizes will presently be 0, indicating that the values obtained from the termcap file are to be used. Returning a negative row or column value also indicates use of the values from the termcap file, but additionally causes use of the returned size's absolute value as the number of rows (or columns) to be made unavailable to the forms runtime system. Both the delay_constant and the number of rows and columns are members of a TEENV_INFO structure.
Inputs:
| None |
Outputs:
| envinfo | Pointer to a TEENV_INFO structure filled in with description of the terminal. |
| .delay_constant | Constant value used to determine delays on terminal updates, based on transmission speed. |
| .rows | Indicate number of rows on the terminal screen; or no information if 0; or number of rows to reserve from the forms system if negative. |
| .cols | Indicate number of cols on the terminal screen; or no information if 0; or number of cols to reserve from the forms system if negative. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS TEopen(envinfo) TEENV_INFO *envinfo;
TEput - conditionally put a character
Put a character to the terminal. This is actually buffered to the terminal, so to force a change to the screen a TEflush() call is necessary. The character is discarded without being written to the terminal if command mode is enabled.
Inputs:
| char | character to be written to terminal buffer |
Outputs:
| None |
Returns:
| None |
Definition:
VOID TEput(c) char c;
TErestore - set/restore terminal characteristics
Restore the terminal to either forms or normal state depending on the value of which (TE_NORMAL, TE_FORMS, TE_CMDMODE).
Inputs:
| which mode to place terminal in, either TE_FORMS, TE_CMDMODE or TE_NORMAL |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS TErestore(which) i4 which;
TEtest - redirect terminal I/O for testing forms based subsystems
This routine redirects terminal input and output for testing forms-based subsystems. The routine takes four parameters: in_name, in_type, out_name, and out_type.
Input redirection affects the operation of TEget. When input redirection is in effect, TEget reads the file in_name. Legal values of in_type are:
This routine redirects terminal input and output, primarily for testing forms-based subsystems. TEtest also allows terminal output to be discarded.
Input redirection affects the operation of TEget. When input redirection is in effect, TEget reads the file in_name. Legal values for in_type are
TE_SI_FILE Get terminal input from the SI file in_name.
TE_TC_FILE Get terminal input from the TC file in_name.
TE_NO_FILE Don't redirect terminal input, in_name must be the null pointer.
Output redirection affects the operation of TEput and TEwrite, causing these routines to write to the file out_name. Legal values for out_type are: out_name or to discard output. Legal values for out_type are
TE_SI_FILE Write terminal output to the SI file out_file .
TE_TC_FILE Write terminal output to the TC file out_file .
TE_NO_FILE Don't redirect terminal output, out_name must be the null pointer.
Notes: TEtest may be called either before or after TEopen. The filename parameters to this routine are character string pointers because they come from the command line.
Inputs:
| in_name | filename containing test input, or NULL. |
| in_type | type of file, one of TE_SI_FILE, TE_TC_FILE or TE_NO_FILE. |
| out_name | filename for placing output, or NULL. |
| out_type | one of TE_SI_FILE, TE_TC_FILE, or TE_NO_FILE. |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS TEtest(in_name,in_type,out_name,out_type) char *in_name; i4 in_type; char *cut_name; i4 out_type;
TEvalid - check validity of a terminal name
This function returns FALSE if the given terminal name is not in a valid format. The terminal name should not have a path on the front of it. A valid terminal name on VMS looks like 'tty17:'; a valid name on UNIX looks like 'tty2' or 'ttyp2'.
Inputs:
| termname | pointer to buffer that holds the terminal name |
Outputs:
| None |
Returns:
| FALSE | if the terminal is not in a valid format. |
Definition:
bool TEvalid(termname) char *termname;
TEwrite - conditionally write buffer to terminal
When the application knows it is writing more than one character it should call this routine. TEwrite efficiently moves many characters to the buffer and then to the terminal. TEflush must subsequently be called to assure that the characters are displayed on the terminal. The buffer is discarded without being written to the terminal if command mode is enabled.
Inputs:
| buffer | pointer to buffer |
| length | number of characters to be written into the buffer |
Outputs:
| None |
Returns:
| None |
Definition:
VOID TEwrite(buffer, length) char *buffer; i4 length;
|
Ingres Compatability Library |
