.\"##
.\" $XConsortium: p242,v 5.2 94/04/17 20:57:14 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 XPHIGS\s+2
.ds h \s-2ERROR HANDLING\s+2
.ds l \s-2ERROR LOGGING\s+2
.TH "OPEN XPHIGS" 3P "29 February 1991"
.SH NAME
OPEN XPHIGS \- open and initialize \s-2PHIGS\s+2 in the \s-2X\s+2 environment
.IX "Errors" "OPEN XPHIGS"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
popen_xphigs ( error_file, memory, xinfo_mask, xinfo )
char	*error_file;	\fIname of error file\fP
Plong	memory;	/fInot used/fP
unsigned long	xinfo_mask;
Pxphigs_info	*xinfo;
.fi
.ft R
.SS Required PHIGS Operating States
(PHCL, WSCL, STCL, ARCL)
.SH DESCRIPTION
.SS Purpose
\s-2OPEN XPHIGS\s+2 is similar to \s-2OPEN PHIGS\s+2 but allows
specification of additional run-time options.
It initializes the \s-2API\s+2 and enables access to the \s-2PHIGS\s+2
functions.
\s-2OPEN PHIGS\s+2 or \s-2OPEN XPHIGS\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 \s-2UNIX\s+2 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, \s-2OPEN XPHIGS\s+2 will fail and the appropriate
error will be reported to standard error.
.IP
The error file argument passed to \s-2OPEN XPHIGS\s+2 will be passed to
\s-2ERROR HANDLING\s+2.  \s-2ERROR HANDLING\s+2 will also pass this argument to \s-2ERROR LOGGING\s+2.
If for some reason \s-2ERROR LOGGING\s+2 cannot access the specified error file,
the error message will be written to standard error.
\s-2ERROR LOGGING\s+2 appends messages to the error file; it does not truncate the file when
\s-2OPEN XPHIGS\s+2 is called.  If the specified file does not exist, it will only be
created if \s-2ERROR LOGGING\s+2 is called.
.IP 
\s-2ERROR LOGGING\s+2 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, \s-2ERROR LOGGING\s+2
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.
.IP \fIxinfo_mask\fP
A bitmask indicating which of the options are being set.
This mask is a bitwise OR of one or more of the valid option mask bits and
indicates which fields of the Pxphigs_info structure are set.
.nf
.ta .5i +2.5i
.sp .2
	PXPHIGS_INFO_DISPLAY	The display pointer: \fIdisplay\fP
	PXPHIGS_INFO_RMDB	The resource manager: \fIrmdb\fP
	PXPHIGS_INFO_APPL_ID	The application name and class: \fIappl_id\fP
	PXPHIGS_INFO_ARGS	The command line arguments: \fIargs\fP
	PXPHIGS_INFO_FLAGS_NO_MON	The No Monitor flag: \fIflags.no_monitor\fP
	PXPHIGS_INFO_FLAGS_CLIENT_SS	The Force Client SS flag: \fIflags.force_client_SS\fP
.sp .2
.fi
.bp
.IP \fIxinfo\fP
A pointer to a Pxphigs_info structure.
This structure is used to specify X-related options to \s-2PHIGS\s+2.
\fIxinfo\fP is defined in phigs.h as follows:
.nf
.ta .5i +.5i +1.0i +1.25i 
.sp .4
typedef struct {
.sp .2
	Display		*display;	/* valid display pointer */
	XrmDatabase	rmdb;	/* a valid database */
	struct {
		char	*name;
		char	*class;
	} appl_id;		/* for resolving database attributes */
	struct {
		int	*argc_p;
		char	**argv;
	} args;			/* for merging args into specified database */
	struct {
		unsigned	no_monitor: 1;	/* 1 ==> monitor will not be executed */
		unsigned	force_client_SS;	/* 1 ==> always use client-side CSS */
	} flags;
.sp .2
} Pxphigs_info;
.sp .4
.fi
Only the fields indicated by \fIxinfo_mask\fP are examined.
.IP
\fIdisplay\fP specifies both the \s-2PHIGS\s+2 default server and the connection
\s-2PHIGS\s+2 is to use when communicating with it.
The \s-2PHIGS\s+2 default server holds the master copy of the
central structure store,
if it supports \s-2PEX\s+2 structure storage, and is where \fItool\fP
workstations are opened if their location is not specified to the
\s-2OPEN WORKSTATION\s+2 function.
\s-2PHIGS\s+2 uses the specified connection for all communication to the
default server,
even if a different connection is specified for a \fIdrawable\fP
workstation in a subsequent call to \s-2OPEN WORKSTATION\s+2.
\s-2PHIGS\s+2 uses the specified connection for the duration of the
\s-2PHIGS\s+2 session; it must not be closed before calling \s-2CLOSE PHIGS\s+2.
If \fIdisplay\fP is not specified, the default server will be the one
returned by a call to XDisplayName() with an argument of \s-2NULL\s+2.
.IP
\fIrmdb\fP an X resource database handle.
\s-2PHIGS\s+2 uses this database to build the default workstation description
tables.
Database searches are on the resource names and classes listed below.
Each search is qualified by the name and class specified in \fIappl_id\fP.
If \fIargs\fP are also specified \s-2PHIGS\s+2 will merge them into the database
prior to searching the database for resources PHIGS recognizes.
Any merged arguments will be removed from the argument list.
The resources \s-2PHIGS\s+2 recognizes are:
.sp .4
.ta 1.25i +1.25i +1.25i +.75i
.nf
\f(BIArgument String	Resource Name	Resource Class	Type	Valid Values\fP
-display	display	Display	String
-bufmode	bufMode	BufMode	String	single | double
=	geometry	Geometry	String
-label	label	Label	String
-iconlabel	iconLabel	IconLabel	String
.fi
.sp .4
The \fIdisplay\fR resource specifies the name of the default server.
The \fIbufMode\fR resource specifies the default buffering mode, ``single'' or
``double''.
The \fIgeometry\fR resource specifies the default window location and size for
\fIphig_ws_type_x_tool\fR workstation types.
The geometry is specified in the standard X geometry format:
.br
.ta .5i
	<width>x<height>{+-}<xoffset>{+-}<yoffset>.
.br
The \fIlabel\fR resource specifies the window label for
\fIphig_ws_type_x_tool\fR workstation types.
The \fIiconLabel\fR resource specifies the icon label for
\fIphig_ws_type_x_tool\fR workstation types.
.IP
\fIappl_id.name\fP and \fIappl_id.class\fP are the application name and
class to use when resolving resource database attributes.
If not specified, the name ``phigs'' and class ``Phigs'' are used.
.IP
\fIargs.argc_p\fP is a pointer to the argument count,
\fIargs.argv\fP is the array of command line arguments.
The arguments are searched for attributes recognized by \s-2PHIGS\s+2 and
are merged into the specified database, if any.
.IP
\fIflags.no_monitor\fP indicates whether the \s-2PHIGS\s+2 Monitor
(\s-2PM\s+2) is executed during popenphigs().
The \s-2PM\s+2 is a separate program started by
\s-2PHIGS\s+2 that handles window events and \s-2PHIGS\s+2 input for
\s-2PHIGS\s+2 workstations.
\s-2PHIGS\s+2 has complete control over this program; 
no user action is required to deal with it other than to indicate if it
should be used or not.
If the \s-2PM\s+2 is not executed (flags.no_monitor = 1), \s-2PHIGS\s+2 
will not monitor and respond to X window events nor will it provide any
\s-2PHIGS\s+2 workstations that support \s-2PHIGS\s+2 input devices.
All the predefined workstation types will be of category \s-2OUTPUT\s+2
(output only).
If the \s-2PM\s+2 is executed (flags.no_monitor = 0), \s-2PHIGS\s+2 will
monitor relevant window events and will provide predefined workstation types
of category \s-2OUTIN\s+2 (input and output).
.IP
\fIflags.force_client_SS\fP indicates whether the \s-2API\s+2 should use
client side structure storage even if server side structure storage is
available in \s-2X\s+2 servers with the \s-2PEX\s+2 extension.
\fIflags.force_client_SS\fP = 1 indicates that client side structure
storage should always be used.
\fIflags.force_client_SS\fP = 0 indicates that server side structure 
storage should be used if available.
.SS Execution
\s-2OPEN XPHIGS\s+2 sets internal state information 
and then calls popen_phigs().
.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
.IP -200
Ignoring function, cannot connect to the designated or default server
.IP -201
Ignoring function, the specified or default X server does not
support a compatible \s-2PEX\s+2 extension
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "INQUIRE SYSTEM STATE VALUE (3P)"
.SM "OPEN PHIGS (3P)"
.SM "CLOSE PHIGS (3P)"
.fi