Ingres CL TC
From Ingres Community Wiki
|
Ingres Compatability Library |
Contents |
Compatibility Library Specification - TC
Abstract
This is the specification of the TC facility provided by the compatibility library.
Revision: 1.1, 15-Nov-1997
Document History
- Revision 1.1, last modified 15-Nov-1997.
- Converted to HTML.
- Revision 1.0, last modified 2-Jan-91.
- Superfluous return codes undocumented.
Specification
Introduction
The TC module is used to read data from and write data to COMM-files. COMM-files are files that can be shared by processes. They provide a mechanism for interprocess communication.
Library
CL
Intended Uses
TC routines will provide testing tools a more flexible way of providing INGRES modules with input and getting the corresponding output. INGRES modules currently have the capability of taking input from a given text file and placing the corresponding results in an also indicated text file\**. .(f \** Although the frontend systems can generate two output files, the RES file and the SCR file, only the SCR file is used for comparison of results. .)f This is accomplished in the frontend systems by invoking them with the -Z and -D flags, and in the terminal monitor by invoking it with the < and > redirection indicators (these indicators may vary in some environments). This capability is the main feature used to test INGRES products. However, new testing tools being developed require a more effective and efficient way of communicating with INGRES modules.
TC routines will allow testing tools to provide INGRES modules with input during execution and monitor the output as it is being generated. This functionality will allow testing tools to ( among other things ):
- Detect problems as soon as they occur (i.e. keystroke file out of sync, server is down, test attempting to deal with nonexisting INGRES objects, etc.).
- Increase precision of test runs. Since it is possible to obtain the output generated by each instruction, only significant output will be compared against expected results. The current methodology demands comparison of the entire output file.
- Working with small output segments allows for easier debugging and test analysis.
Assumptions
The rules and characteristics that govern the use of COMM-files were designed to answer testing needs and may not be suitable for other uses. Since improper use of these files might lead to deadlock, it is up to applications using this new functionality to use it in a way (as testing tools will) that prevents deadlock from occurring.
While interacting with testing tools, INGRES modules will get input data from an input COMM-file and write SCR data to an output COMM-file. Testing tools will communicate with the user via TE routines and with INGRES modules via TC routines.
Concepts
COMM-files can be opened for reading or writing.
COMM-files are byte stream oriented, data can be read or written to these files in any size chunks, there is no concept of a record within these files.
COMM-files do not support random access.
When two processes share a COMM-file, one of the processes writes data to the file, and the other one reads data from it. These roles cannot be changed during process execution. Once a process opens a COMM-file for reading, it cannot append data to the file. When a process opens a COMM-file for writing, it cannot read from it.
Synchronization between processes sharing a COMM-file will be accomplished by writing special characters to the file. For example, processes writing output to a COMM-file will use the Beginning Of Session (TC_BOS) character to indicate that the COMM-file was successfully opened. These processes will subsequently use the End of Query Result (TC_EQR) character to delimit pieces of output written to the file. Processes writing input to a COMM-file will use the End of Query (TC_EOQ) character to delimit pieces of input written to the file.
Data written to a COMM-file is sequenced in order of arrival. The preferred behavior is for the data to be immediately appended to the file. If implementation of this behavior results in poor performance, the data will be buffered and then appended to the file when the TC flush routine, TCflush, is called. If the preferred behavior is implemented, TCflush will be a NO-OP.
Client code may make no assumptions about when and whether the TCputc routine will block. An implementation is free to make TCputc block on the second TCputc call if the previous character has not been read. However, throughput of the client will obviously be lower under such an implementation. It is recommended that processes reading from a COMM-file constantly monitor the COMM-file to make sure all available data is read as soon as possible, to lessen the likelihood of blocking the writer. The TCempty call is provided for this purpose.
Data is read from a COMM-file in order of arrival, just as it was written. Once read, data can't be reread or put back. Normally, if the COMM-file is empty, the TC read routine, TCgetc, will wait until at least one byte of data is available. If the process writing to the COMM-file closes the file, TCgetc will return a TC_EOF code, indicating end of file.
The TCgetc routine supports a timeout feature. If the passed in seconds parameter is greater than 0, and if the TCgetc routine must block waiting for a character to arrive, it should only wait the number of seconds as specified in the seconds parameter. A timeout has occurred if no characters arrive within the timeout period, and the TCgetc routine should then return TC_TIMEDOUT. If the seconds parameter is 0 or negative, TCgetc will simply wait forever.
A process reading data from a COMM-file can use the TCempty routine to check if data has been appended to the COMM-file that has not yet been read.
TC declares a single data type TCFILE that is always used by applications as a pointer to a COMM-file. All the routines in TC use a TCFILE pointer to refer to the COMM-file.
TC makes no guarantee of consistency in the event of system failure. If the system experiences some type of fault while a process is reading from or writing to a COMM-file, no assumptions can be made as to the state of the file.
Header File <tc.h>
The header file <tc.h> must be included before using any of the functions provided. The following are also defined.
/* Special characters and suggested values for ASCII environments: */ #define TC_EOF (i4)-1 /* end of file */ #define TC_TIMEDOUT (i4)-2 /* timed out on TCgetc */ #define TC_EOQ 034 /* end of query */ #define TC_EQR 035 /* end of query results */ #define TC_BOS 036 /* beg. of session */
Note: non-ASCII environments will need to settle on designated characters for this purpose. They must be non-printable and preferably something that cannot be entered from the keyboard.
This means that TC files do not allow the transmission of these characters. We understand that this may become an unacceptably limiting factor in the future. At that time, we should consider other alternatives, such as a new escape character for this particular use.
Executable Interface
The following functions are provided.
TCclose - close connection to TC file
Closes a COMM-file.
Inputs:
| desc | file pointer |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS TCclose(desc) TCFILE *desc;
TCempty - is the file empty?
Check if there is unread data in a COMM-file.
Inputs:
| desc | - file pointer |
Outputs:
| None |
Returns:
| FALSE | There is unread data in the file. |
Definition:
bool TCempty(desc) TCFILE *desc;
TCflush - flush output to file
Flush a COMM-file.
Inputs:
| desc | file pointer |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS TCflush(desc) TCFILE *desc;
TCgetc - read character from a TC file
Reads a character from a COMM-file. If the COMM-file is empty, it will wait until at least one byte of data is available. If the process writing to the file closes it, TCgetc will return TC_EOF. The TCgetc routine supports a timeout feature. If a given number of seconds has passed while the TCgetc routine is waiting for data to be available, the TC_TIMEDOUT code will be returned by TCgetc. If the given number of seconds is < 0, TCgetc will wait until data is available.
Inputs:
| desc | file pointer |
| seconds | number of seconds to wait for data |
Outputs:
| None |
Returns:
| Next character available in the COMM-file, | |
| or | |
| TC_EOF | if process writing to the file closes it, |
| or | |
| TC_TIMEDOUT | if TCgetc has been waiting for a given number of seconds and still no data is available. |
Definition:
i4 TCgetc(desc,seconds) TCFILE *desc; i4 seconds;
TCopen - open a TC file
Opens a COMM-file. COMM-files are files that can be shared by processes. They provide a more flexible communication mechanism between Ingres modules and testing tools.
Inputs:
| location | location of the file |
| mode | access mode of the file. Possible values are: w, open file for writing and r, open file for reading. |
Outputs:
| desc | value to get file pointer |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS TCopen(location, mode, desc) LOCATION *location; char *mode; TCFILE **desc;
TCputc - write a character to a TC file
Writes a character to a COMM-file. Data written to a COMM-file is sequenced in order of arrival. It is not buffered and will be immediately appended to the file. No need for a flush routine. Client code may make no assumptions about when and whether the TCputc routine will block. An implementation is free to make TCputc block on the second TCputc call if the previous character has not been read.
Inputs:
| achar | char to be written to COMM-file |
| desc | file pointer |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS TCputc(achar,desc) i4 achar; TCFILE *desc;
|
Ingres Compatability Library |
