'\" t
.\" Uil.sgm /main/11 1996/09/08 21:42:50 rws $
.de P!
.fl
\!!1 setgray
.fl
\\&.\"
.fl
\!!0 setgray
.fl			\" force out current output buffer
\!!save /psv exch def currentpoint translate 0 0 moveto
\!!/showpage{}def
.fl			\" prolog
.sy sed -e 's/^/!/' \\$1\" bring in postscript file
\!!psv restore
.
.de pF
.ie     \\*(f1 .ds f1 \\n(.f
.el .ie \\*(f2 .ds f2 \\n(.f
.el .ie \\*(f3 .ds f3 \\n(.f
.el .ie \\*(f4 .ds f4 \\n(.f
.el .tm ? font overflow
.ft \\$1
..
.de fP
.ie     !\\*(f4 \{\
.	ft \\*(f4
.	ds f4\"
'	br \}
.el .ie !\\*(f3 \{\
.	ft \\*(f3
.	ds f3\"
'	br \}
.el .ie !\\*(f2 \{\
.	ft \\*(f2
.	ds f2\"
'	br \}
.el .ie !\\*(f1 \{\
.	ft \\*(f1
.	ds f1\"
'	br \}
.el .tm ? font underflow
..
.ds f1\"
.ds f2\"
.ds f3\"
.ds f4\"
.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n 
.TH "Uil" 3
.SH "NAME"
\fBUil\fP \(em Invokes the UIL compiler from within an application
"Uil"
"uil functions" "Uil"
"uil compiler"
.SH "SYNOPSIS"
.PP
.nf
#include <uil/UilDef\&.h>
.sp \n(PDu
\fBUil_status_type \fBUil\fP\fR(
\fBUil_command_type *\fBcommand_desc\fR\fR,
\fBUil_compile_desc_type *\fB*compile_desc\fR\fR,
\fBUil_continue_type (*\fBmessage_cb\fR) ()\fR,
\fBchar *\fBmessage_data\fR\fR,
\fBUil_continue_type (*\fBstatus_cb\fR) ()\fR,
\fBchar *\fBstatus_data\fR\fR);
.fi
.SH "DESCRIPTION"
.PP
The \fBUil\fP function provides a callable entry point for the UIL
compiler\&. The
\fBUil\fP callable interface can be used to process
a UIL source file and to
generate UID files, as well as return a detailed description of the
UIL source module in the form of a symbol table (parse tree)\&.
.IP "\fIcommand_desc\fP" 10
Specifies the \fBuil\fP command line\&.
.IP "\fIcompile_desc\fP" 10
Returns the results of the compilation\&.
.IP "\fImessage_cb\fP" 10
Specifies a callback function that is called when the compiler
encounters errors in the UIL source\&.
.IP "\fImessage_data\fP" 10
Specifies user data that is passed to the message callback function
(\fImessage_cb)\fP\&. Note that this argument is not interpreted by UIL, and is
used exclusively by the calling application\&.
.IP "\fIstatus_cb\fP" 10
Specifies a callback function that is called to allow X applications to service
X events such as updating the screen\&. This function is called
at various check points, which have been hard coded into the UIL compiler\&.
The \fIstatus_update_delay\fP argument in \fIcommand_desc\fP
specifies the number of
check points to be passed before the \fIstatus_cb\fP function is invoked\&.
.IP "\fIstatus_data\fP" 10
Specifies user data that is passed to the status callback function
(\fIstatus_cb)\&.\fP
Note that this argument is not interpreted by the UIL compiler
and is used exclusively by the calling application\&.
.PP
Following are the data structures \fBUil_command_type\fP and
\fBUil_compile_desc_type\fP:
.PP
.nf
\f(CWtypedef struct Uil_command_type {
char *source_file;
    /* single source to compile */
char *resource_file; /* name of output file */
char *listing_file; /* name of listing file */
unsigned int *include_dir_count;
    /* number of dirs\&. in include_dir */
char *((*include_dir) []);
    /* dir\&. to search for include files */
unsigned listing_file_flag: 1;
    /* produce a listing */
unsigned resource_file_flag: 1;
    /* generate UID output */
unsigned machine_code_flag: 1;
    /* generate machine code */
unsigned report_info_msg_flag: 1;
    /* report info messages */
unsigned report_warn_msg_flag: 1;
    /* report warnings */
unsigned parse_tree_flag: 1;
    /* generate parse tree */
unsigned int status_update_delay;
    /* number of times a status point is */
    /* passed before calling status_cb */
    /* function 0 means called every time */
char *database;
    /* name of database file */
unsigned database_flag: 1;
    /* read a new database file */
unsigned use_setlocale_flag: 1;
    /* enable calls to setlocale */
};
typedef struct Uil_compile_desc_type {
unsigned int compiler_version;
    /* version number of compiler */
unsigned int data_version;
    /* version number of structures */
char *parse_tree_root; /* parse tree output */
unsigned int message_count [Uil_k_max_status+1];
/* array of severity counts */
};\fR
.fi
.PP
.PP
Following is a description of the message callback function specified by
\fImessage_cb\fP:
.PP
.nf
Uil_continue_type (\fI*message_cb\fP) (\fImessage_data, message_number, severity, msg_buffer,
src_buffer, ptr_buffer, loc_buffer, message_count\fP)
        char \fI*message_data\fP;
        int \fImessage_number\fP;
        int \fIseverity\fP;
        char \fI*msg_buffer\fP, \fI*src_buffer\fP;
        char \fI*ptr_buffer\fP, \fI*loc_buffer\fP;
        int \fImessage_count\fP[];
.fi
.PP
This function specifies a callback function that UIL
invokes instead of printing an
error message when the compiler encounters an error in the UIL source\&.
The callback should return one of the following values:
.IP "\fBUil_k_terminate\fP" 10
Terminate processing of the source file
.IP "\fBUil_k_continue\fP" 10
Continue processing the source file
.PP
The arguments are
.IP "\fImessage_data\fP" 10
Data supplied by the application as the \fImessage_data\fP argument to
the \fBUil\fP function\&.
UIL does not interpret this data in any way; it just passes it to the
callback\&.
.IP "\fImessage_number\fP" 10
An index into a table of error messages and severities for internal use
by UIL\&.
.IP "\fIseverity\fP" 10
An integer that indicates the severity of the error\&.
The possible values are the status constants returned by the \fBUil\fP
function\&.
See \fBReturn Value\fP for more information\&.
.IP "\fImsg_buffer\fP" 10
A string that describes the error\&.
.IP "\fIsrc_buffer\fP" 10
A string consisting of the source line where the error occurred\&.
This string is not always available\&. In this case, the argument is NULL\&.
.IP "\fIptr_buffer\fP" 10
A string consisting of whitespace and a printing character in the
character position corresponding to the column of the source line where
the error occurred\&.
This string may be printed beneath the source line to provide a visual
indication of the column where the error occurred\&.
This string is not always available\&. In this case, the argument is NULL\&.
.IP "\fIloc_buffer\fP" 10
A string identifying the line number and file of the source line where
the error occurred\&.
This is not always available; the argument is then NULL\&.
.IP "\fImessage_count\fP" 10
An array of integers containing the number of diagnostic messages issued
thus far for each severity level\&.
To find the number of messages issued for the current severity level,
use the \fIseverity\fP argument as the index into this array\&.
.PP
Following is a description of the status callback function specified by
\fIstatus_cb\fP:
.PP
.nf
Uil_continue_type (\fI*status_cb\fP) (\fIstatus_data, percent_complete,
        lines_processed, current_file, message_count\fP)
        char \fI*status_data\fP;
        int \fIpercent_complete\fP;
        int \fIlines_processed\fP;
        char \fI*current_file\fP;
        int \fImessage_count\fP[];
.fi
.PP
This function specifies a callback function that is
invoked to allow X applications to
service X events such as updating the screen\&.
The callback should return one of the following values:
.IP "\fBUil_k_terminate\fP" 10
Terminate processing of the source file
.IP "\fBUil_k_continue\fP" 10
Continue processing the source file
.PP
The arguments are
.IP "\fIstatus_data\fP" 10
Data supplied by the application as the \fIstatus_data\fP argument to
the \fBUil\fP function\&.
UIL does not interpret this data in any way; it just passes it to the
callback\&.
.IP "\fIpercent_complete\fP" 10
An integer indicating what percentage of the current source file has
been processed so far\&.
.IP "\fIlines_processed\fP" 10
An integer indicating how many lines of the current source file have
been read so far\&.
.IP "\fIcurrent_file\fP" 10
A string containing the pathname of the current source file\&.
.IP "\fImessage_count\fP" 10
An array of integers containing the number of diagnostic messages issued
thus far for each severity level\&.
To find the number of messages issued for a given severity level, use
the severity level as the index into this array\&.
The possible severity levels
are the status constants returned by the
\fBUil\fP function\&.
See \fBReturn Value\fP for more information\&.
.SH "RETURN"
.PP
This function returns one of the following
status return constants:
.IP "\fBUil_k_success_status\fP" 10
The operation succeeded\&.
.IP "\fBUil_k_info_status\fP" 10
The operation succeeded\&. An informational
message is returned\&.
.IP "\fBUil_k_warning_status\fP" 10
The operation succeeded\&. A warning
message is returned\&.
.IP "\fBUil_k_error_status\fP" 10
The operation failed due to an error\&.
.IP "\fBUil_k_severe_status\fP" 10
The operation failed due to an error\&.
.SH "RELATED"
.PP
\fBUilDumpSymbolTable\fP(3) and
\fBuil\fP(1)\&.
.\" created by instant / docbook-to-man, Sun 22 Dec 1996, 20:16