'\" 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" "library call"

.SH "NAME"

\fBUil\fP \(em Invokes the UIL compiler from within an application

.iX "Uil"

.iX "uil functions" "Uil"

.iX "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