.\"##
.\" $XConsortium: p239,v 5.2 94/04/17 20:57:12 rws Exp $
.\"##
.\"## 
$XMCOPY
.\"## Copyright (c) 1990, 1991 by Sun Microsystems, Inc. 
.\"## 
.\"##                         All Rights Reserved
.\"## 
.\"## Permission to use, copy, modify, and distribute this software and its 
.\"## documentation for any purpose and without fee is hereby granted, 
.\"## provided that the above copyright notice appear in all copies and that
.\"## both that copyright notice and this permission notice appear in 
.\"## supporting documentation, and that the name of Sun Microsystems,
.\"## not be used in advertising or publicity 
.\"## pertaining to distribution of the software without specific, written 
.\"## prior permission.  
.\"## 
.\"## SUN MICROSYSTEMS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, 
.\"## INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
.\"## EVENT SHALL SUN MICROSYSTEMS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
.\"## CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
.\"## USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
.\"## OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\"## PERFORMANCE OF THIS SOFTWARE.
.ds f \s-2OPEN PHIGS\s+2
.ds h \s-2ERROR HANDLING\s+2
.ds l \s-2ERROR LOGGING\s+2
.TH "OPEN PHIGS" 3P "29 February 1991"
.SH NAME
OPEN PHIGS \- open and initialize the \s-2PHIGS\s+2 environment
.IX "Errors" "OPEN PHIGS"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
popen_phigs ( error_file, memory )
char	*error_file;	\fIname of error file\fP
size_t	memory;	\fI\s-2NOT USED\s+2\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHCL, WSCL, STCL, ARCL)
.SH DESCRIPTION
.SS Purpose
\*f initializes \s-2PHIGS\s+2 and enables access to the \s-2PHIGS\s+2
functions.
\s-2OPEN PHIGS\s+2 
must be called prior to calling any other \s-2PHIGS\s+2 functions.
.SS C Input Parameters
.IP \fIerror_file\fP
A pointer to the \fIerror file\fP to log \s-2PHIGS\s+2 error messages to.
The \fIerror file\fP can be either a pointer to a
valid UNIX file name or a null pointer, for example (char*)0.
A null pointer implies that standard error is to be used as the error file.
If a file name is specified, \s-2PHIGS\s+2 will attempt to access the file
for writing.  If this attempt fails, \*f will fail and the appropriate
error will be reported to standard error.
.IP
The error file argument passed to \*f will be passed to \*h.
\*h will also pass this argument to \*l.
If for some reason \*l cannot access the specified error file,
the error message will be written to standard error.
\*l appends messages to the error file; it does not truncate the file when
\*f is called.  If the specified file does not exist, it will only be
created if \*l is called.
.IP 
\*l writes the abstract \s-2PHIGS\s+2 function name, the
error number, and an error description to the error file.
If for some reason the text for the function name
and/or error description can't be determined, \*l
will just write the function number and the error number.
.IP \fImemory\fP
This parameter is not used by the \s-2PEX-SI API\s+2.
.SS Execution
\s-2OPEN PHIGS\s+2:
.sp .4
.in .7i
.ta .5i
.ti -.2i
\(bu    Connects to a default or specified server. The default server is the one returned
by XDisplayName (\s-2NULL\s+2).
(\s-2OPEN XPHIGS\s+2 must be used to specify a server.)
.sp .2
.ti -.2i
\(bu    Sets the \s-2PHIGS\s+2 system state variable to \s-2`PHOP'\s+2.
.sp .2
.ti -.2i
\(bu    Initializes the default workstation description tables and makes them
available for use by the other \s-2PHIGS\s+2 functions.
These tables reflect the capabilities of the default or specified server.
.sp .2
.ti -.2i
\(bu    Creates the \s-2PHIGS\s+2 state list and initializes it with default values
taken from the \s-2PHIGS\s+2 description table.
.sp .2
.ti -.2i
\(bu    Stores \fIerror file\fP in the \s-2PHIGS\s+2 error state list.
.DT
.sp
.LP
The default values for the \s-2PHIGS\s+2 state list,
\s-2PHIGS\s+2 description table, and workstation description tables
are in the Appendix.
.LP
When an error in \s-2PHIGS\s+2 is detected, \*h is called and passes three
items of informations: the \fIerror file\fP, the function number of the
\s-2PHIGS\s+2 function that detected the error, and the error number.
\*h calls \*l, which writes an error message to the error file.
\s-2PHIGS\s+2 users can replace \*h with a function of their own.
This function may in turn call \*l.
See \*h and \*l for more information.
.LP
\s-2PHIGS\s+2 only writes to the error file if \*l is called, either by
\*h or the application.  If the \fIerror file\fP does not exist when
\*f is called, it will only be created if and when \*l is called.
.LP
.SH ERRORS
.IP 001
Ignoring function, function requires state (\s-2PHCL, WSCL, STCL, ARCL\s+2)
.IP 450
Ignoring function, the specified error file is invalid
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "INQUIRE SYSTEM STATE VALUE (3P)"
.SM "CLOSE PHIGS (3P)"
.SM "OPEN ARCHIVE FILE (3P)"
.SM "OPEN STRUCTURE (3P)"
.SM "OPEN WORKSTATION (3P)"
.SM "OPEN XPHIGS (3P)"
.fi