Ingres CL UT
From Ingres Community Wiki
|
Ingres Compatability Library |
Compatibility Library Specification - UT
Abstract
This is the specification of the UT facility provided by the compatibility library.
Revision: 1.2, 9-May-1997
Document History
- Revision 1.2, 9-May-1997
- Converted to html.
- Added UTcompile_ex().
- Revision 1.1, 30-Jul-94
- Errata: UTcompile is missing a CL_ERR_DESC at the end.
- UTprint can take NULL title and destination arguments (26-jun-92).
- Revision 1.0, last modified 29-Aug-91.
- UTcompile got outfile and pristine arguments.
- UTexe's interface changed substantially.
- UTlink got outfile and pristine arguments.
- UTprint no long interprets ING_PRINT, got additional arguments for deletion, copies, title and destination, and no longer prints errors to the screen.
- To support unbundled Window s/4GL, the following were added:
- UTcompile's interaction with the new NMsetpart and NMgetpart are documented.
- UTdeffile was added, allowing callers to get the LOCATION of the active UTexe definition file.
- Additionally, the following cleanup was done:
- UTcom.def and UTexe.def are now correctly lowercase utcom.def and utexe.def.
Specification
Introduction
UT provides a way of calling utility programs and chaining to other INGRES susbsystems, maintaining a database connection.
These routines are system dependent.
Library
CL
Header File <ut.h>
The header file <ut.h> must be included before using any of the functions provided.
Executable Interface
The following functions are provided.
UTcompile - compile a file
UTcompile compiles the source file srcfile and places the resulting object code into the object file objfile.
UTcompile first looks for the default compile script in II_COMPILE_DEF. If this logical is not set, UTcompile constructs a filename of the form utcom.XXX, where XXX is the first three characters of the partname given to NMsetpart and returned by NMgetpart. This file should be in the `ingres' subdirectory files. (If NMsetpart wasn't called or if the file was missing, the filename utcom.def is used as a default.) This file contains the operating system specific part of UTcompile. This file uses the extension of srcfile to decide how to compile srcfile.
If the output file is specified, it will be deleted and as much compilation output as possible will be redirected there. If the compilation succeeds, the file will be deleted.
If there is any chance that compilation messed up the screen, then the variable pointed to by 'pristine' will be set to FALSE, otherwise it will be set to TRUE.
The format of utcom.def is:
<extension>
<command line>
<command line>
... Each extension begins at the first character. On succeeding lines, indented with a tab, are commands which are processed and then passed to PCcmdline. The commands can be any operating system commands with the following special arguments.
| %E | The following in an INGRES executable. | |
| %N | The name of srcfile minus the extension. | |
| %I | The full pathname of srcfile minus the extension. | |
| %O | The full pathname of objfile. |
The following fragment might be used to compile ".qc" files on UNIX:
qc
cd `dirname %I`; %Eeqc -A %N.qc
cd `dirname %I`; cc -c %N.c
if [ %I.o != %O ];then mv %I.o %O;fi
rm %I.c
Inputs:
| srcfile | LOCATION containing name of source file to process. |
| objfile | LOCATION containing name for resultant object file. |
| outfile | if non-NULL, file to delete and to which error output should be redirected. |
Outputs:
| pristine | Set to TRUE if the redirection is guaranteed to work; to FALSE if there's any possibility that output leaked onto the screen. |
| err | Set if there was any error. |
Side Effects:
| Object file is created (in objfile). |
Returns:
| OK | if operation succeeded |
| UT_CO_FILE | compiler definition file, "utcom.def", not found |
| UT_CO_IN_NOT | input source file not found |
| otherwise system specific error status. |
Definition:
STATUS UTcompile(srcfile, objfile, outfile, pristine, err) LOCATION *srcfile; LOCATION *objfile; LOCATION *outfile; /* Text output by compiler */ bool *pristine; /* (output) was screen untouched ? */ CL_ERR_DESC *err;
UTcompile_ex - compile a file with extra parameters
UTcompile_ex function's exactly like UTcompile, except it takes an additional parameter of optional flags that will replace the '%F' flag in the compilation script.
| %E | The following in an INGRES executable. |
| %N | The name of srcfile minus the extension. |
| %I | The full pathname of srcfile minus the extension. |
| %O | The full pathname of objfile. |
| %F | Any additional parameters passed verbatim to the script. |
Inputs:
| srcfile | LOCATION containing name of source file to process. |
| objfile | LOCATION containing name for resultant object file. |
| outfile | if non-NULL, file to delete and to which error output should be redirected. |
| parms | a null-terminated array of character pointers containing additional compiler flags passed verbatim to the script. |
Outputs:
| pristine | Set to TRUE if the redirection is guaranteed to work; to FALSE if there's any possibility that output leaked onto the screen. |
| err | Set if there was any error. |
Side Effects:
| Object file is created (in objfile). |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS UTcompile_ex(srcfile, objfile, outfile, parms, pristine, err) LOCATION *srcfile; LOCATION *objfile; LOCATION *outfile; /* Text output by compiler */ char **parms; /* null-terminated array of char ptrs */ bool *pristine; /* (output) was screen untouched ? */ CL_ERR_DESC *err;
UTdeffile - locate UTexe definition file for access by caller
Set the LOCATION pointed to by ploc to the UTexe definition file for the program "progname". This file contains descriptions of the arguments for "progname"; see the UTexe section for the file layout.
First, the deffiles subdirectory of the FILES directory (as returned from NMloc) is checked for the file "prog.def", where "prog" is "progname" lowercased and truncated, if necessary, to 8 characters. If this file exists, the LOCATION "ploc" is set to point to it. If not, "ploc" is pointed to the default UTexe definition file: "utexe.def" in the FILES directory.
The files are not read; the caller is not guaranteed that the file returned contains argument definitions for the program passed in. The file may also contain argument definitions for other programs.
Inputs:
| progname | The program name. |
| buffer | The buffer for the LOCATION. This must be at least MAX_LOC bytes. |
Outputs:
| ploc | A pointer to the LOCATION to be filled in. |
| clerror | An error return block |
Returns:
| OK | if the operations suceeded, otherwise system specific error status. |
Prototype:
STATUS UTdeffile(char *progname, char *buf, LOCATION *loc, CL_ERR_DESC *clerror);
Example:
An example use of the routine UTdeffile is shown here. In this example, the caller wants to get a LOCATION filled in with the location of the UTexe definition file for qbf.
whatever()
{
STATUS rval;
char buf[MAX_LOC];
LOCATION qbf_def_file;
FILE *ct_file;
CLERROR clerror;
if ((rval = UTdeffile(ERx("qbf"), buf,
&qbf_def_file, &clerror)) != OK))
{
/*
** There was an unexpected error
*/
SIprintf("Unexpected error %d from UTdeffile\n", rval);
return(FAIL);
}
/*
** qbf_def_file now contains location of the UTexe definition
** file for QBF. The caller must assume that the UTexe
** definition file might contain entries for programs other
** than QBF as well as QBF. He must also be prepared not to
** find QBF at all.
*/
rval = SIfopen(&qbf_def_file, "r", SI_TXT, (longnat)0,
&ct_file);
...
}
UTedit - edit a file
Edit the file f with the editor e. If the editor can't be found or is NULL, use the default text editor, which may be ING_EDIT.
On VMS, e must be a DCL command or symbol that points to an executable, not a symbol that points to a command file.
Inputs:
| e | name of editor or edit command to use. |
| f | LOCATION containing name of file to edit. |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS UTedit(e, f) char *e; LOCATION *f;
UTexe - execute an INGRES subsystem or module
UTexe executes the INGRES subsystem or module program with the argument list arglist. UTexe is largely system independant.
Arglist is a special list, something like a format list in SIprintf. Arg1 to argN are the arguments to substitute into arglist. N is the number of arguments. The arglist is of the following form:
"<argument name> = %<argument specifier>, ..."
The argument name is the name of the argument. Argument names are specific to a subsystem. The specifier is one of
| S | The argument is a string. |
| L | The argument is a location. |
| N | The argument is an integer. |
| F | The argument is a double float pointer. |
UTexe uses the file "utexe.def" in the FILES directory (as determined by NMloc) to build a command line that it executes. The file contains all the argument names and what flags to pass. The format of utexe.def is as follows. Fields are separated with TAB characters; spaces are significant.
<subsystem> <executable> <moduletype> <reserved> <usage>
<argument name> <flag spec> <id> <prompt> <format>
<reserved>, <usage>, <id>, <prompt> and <format> are used by a frontend utility, and must be ignored by UTexe. If <executable> is % then the executable to run will be one of the arguments (see C and E below). The flag spec can be any string of characters. '%' has a special meaning and tells what type of argument is needed. The different types are
| S | string. |
| N | number. |
| C | The argument is the name of the executable. |
| E | The argument is the full path name of the executable. |
The C and E types are only valid if <executable> is %. For example, an abbreviated version of the SQL entry on looks like:
sql
sql PROCESS
database '%S'
equel -X%S
user -u'%S'
flags %S
connect +c%S
A complete list of argument names for the different subsystems can be found in the utexe.def file in ~ingres/files.
The mode argument controls how UTexe calls the subsystem or module. It is a bit mask with the allowed values:
| UT_WAIT | wait for the called subsytem to terminate |
| UT_NOWAIT | do not wait for the called subsytem to terminate |
| UT_STRICT | enable strict argument checking |
UT_STRICT may be or-ed ("|") in if strict argument checking is desired. With strict argument checking enabled, if the arglist contains an argument name that is not present in utexe.def then an error will be returned, otherwise it will ignore that argument.
For different platforms, creating two simultaneous processes may not be possible. In this case, UT_WAIT = UT_NOWAIT. Control will always return to the calling routine after the subsytem has terminated. Calling routines may check if UT_WAIT == UT_NOWAIT to determine if subprocesses are possible. In the future other values for mode will be possible.
dict is an obsolete parameter that must always be NULL.
DsTab is an obsolete parameter that must always be NULL.
err_code will return information describing the error status returned from UTexe.
Inputs:
| mode | a flag indicating whether or not strict argument checking is desired; should return before the subsytem has terminated |
| err_log | location where ourput and errors will be redirected if possible. If UT_WAIT is set, may be NULL. |
| dict | Must be NULL. |
| dsTab | Must be NULL. |
| program | name of subsystem to execute. |
| err_code | CL_ERR_DESC pointer |
| arglist | special argument list, described above, that appears in the form: "<argname>=%<argspec>,...". |
| N | number of arguments. |
Outputs:
| err_code | pointer to a variable used to return operating system errors. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS UTexe(mode, err_log, dict, dsTab, program, err_code, arglist, N, ...) i4 mode; LOCATION *err_log; PTR dict; /* always NULL */ PTR dsTab; /* always NULL */ char *program; CL_ERR_DESC *err_code; char *arglist; i4 N; ... variable number of arguments
Examples:
To call qbf as if doing:
qbf mydb myform -f
the call to UTexe would be:
STATUS
UTexe(UT_WAIT, NULL, (PTR) NULL,
(PTR) NULL, "qbf", &err_code,
"database = %s, entry = %s",
2, "mydb", "myform");
UTlink - link an executable
Link an executable from the list of object modules in the NULL terminated array objs.
Also included in the link are system dependent arguments to the linker in the NULL terminated array usrlist.
The resulting executable is placed in the file exe.
If the output file is specified, it will be deleted and as much compilation output as possible will be redirected there. If the compilation succeeds, the file will be deleted.
If there is any chance that compilation messed up the screen, then the variable pointed to by 'pristine' will be set to FALSE, otherwise it will be set to TRUE.
Inputs:
| objs | array of LOCATIONS containing names of object files. |
| usrlist | array of other strings to pass to the linker. |
| exe | LOCATION containing name for resultant executable. |
| outfile | if non-NULL, file to delete and to which error output should be redirected. |
Outputs:
| pristine | Set to TRUE if the redirection is guaranteed to work; to FALSE if there's any possibility that output leaked onto the screen. |
Side Effects:
| Executable file is created (in exe). |
Definition:
STATUS UTlink(objs, usrlist, exe, outfile, pristine) LOCATION *objs[]; /* Object files (inputs to link) */ char *usrlist[]; /* other strings to pass to linker */ LOCATION *exe; /* Executable to create */ LOCATION *outfile; /* Text output by linker */ bool *pristine; /* (output) was screen untouched ? */
UTprint - print a file
Print 'n' copies of the file 'filename' with the printer 'destination' using the command 'printer_cmd'. If 'printer_cmd' is NULL, then the default command is used. If 'destination' is NULL, the default printer is used. If set, 'title' is sent as the jobname. Note on VMS, the jobname is printed on the burst page only if the queue has been initialized to print the job burst page rather than the file burst page. If 'delete' is TRUE, then delete the file after it has been printed.
On VMS, e must be a DCL command or symbol that points to an executable, not a symbol that points to a command file.
UTprint no longer interprets ING_PRINT which must be done by the calling code, if desired, and passed to UTprint in 'printer_cmd'.
Should the print command fail for any reason, no error message will be sent to the screen and error status is returned.
Inputs:
| printer_cmd | print command to use |
| filename | LOCATION containing name of file to print |
| delete | flag indicating whether to delete the file after it's printed (TRUE) or not (FALSE) |
| copies | number of copies to be printed |
| title | jobname, may be NULL. |
| destination | printer (queue) to send file |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS UTprint(printer_cmd, filename, delete, copies, title, destination) char *printer_cmd; LOCATION *filename; bool delete; i4 copies; char *title; char *destination;
|
Ingres Compatability Library |
