.\"
.\" $XConsortium: p045,v 5.3 94/04/17 20:54:46 hersh Exp $
.\"
.\" 
$XMCOPY
.\" Copyright (c) 1990, 1991 by Sun Microsystems, Inc. and the X Consortium.
.\" 
.\"                         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 names of Sun Microsystems,
.\" and the X Consortium 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-2ESCAPE -2\s+2
.ds e \s-2ESCAPE\s+2
.ds s Sun\s-2PHIGS\s+2
.ds pr \s-2PACK DATA RECORD\s+2
.ds ur \s-2UNPACK DATA RECORD\s+2
.ds eh \s-2ERROR HANDLING\s+2
.TH "ESCAPE -2" 3P "29 February 1991"
.SH NAME
ESCAPE -2 \- inquire workstation's display and window information
.IX "SunView" "ESCAPE -2" "\fISunView\fP" "ESCAPE -2"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pescape ( func_id, in, store, out )
Pint	func_id;	\fIescape function identifier\fP
Pescape_in_data	*in;	\fIinput data for the function\fP
Pstore	store;	\fIpointer to the buffer\fP
Pescape_out_data	**out;	\fIOUT output data of the function\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, *, *, *)
.SH DESCRIPTION
.SS Purpose
\s-2ESCAPE -2\s+2
returns display and window information for the specified workstation.
.SS C Input Parameters
Applications using the \s-2C\s+2 binding must create a buffer to be used by this
function as memory space for storing data associated with the device state.
This buffer is passed as the \fIstore\fP argument.  
.LP
The store buffer is a data area managed by \s-2PHIGS\s+2. While the application 
is responsible for creating the inital buffer through a call to \s-2\CREATE STORE\s+2, 
\s-2PHIGS\s+2 manages this area such that there is sufficient memory for the 
specific inquiry. The data record within the store buffer is accessed 
by the pointer pointed to by \fIout\fR.
.IP \fIfunc_id\fP
The function identifier for this escape is \s-2PUESC_DPYINFO\s+2,
which is defined in phigs.h to be -2.
.IP \fIin\fP
A pointer to a Pescape_in_data union, which contains the escape_in_u2 member
used by this escape function.
This member is defined in phigs.h as:
.nf
.ta .5i +1.0i 
.sp .4
struct {
.sp .2
	Pint	ws_id;
.sp .2
} escape_in_u2;
.fi
.RS
.IP \fIws_id\fP
The indentifier of the workstation for which 
the display and window information is to be returned.
.RE
.IP \fIstore\fP
The memory buffer \s-2PHIGS\s+2 is to use for storing
the information returned.
This buffer must exist prior to calling this function (see
\s-2CREATE STORE (3P)\s+2).
.SS C Output Parameters
.IP \fIout\fP
A pointer to a pointer to a Pescape_out_data union, which contains the escape_out_u2 member
used by this escape function.
\s-2PHIGS\s+2 copies a pointer to the requested information 
to the variable pointed to by this parameter.
This member is defined in phigs.h as:
.nf
.ta .5i +1.2i  +1.5i
.sp .4
struct {
.sp .2
	Pint	err_ind;
	Display	*display;	/* may be returned as NULL */
	XID	drawable_id;
	XID	input_overlay_id;	/* will be 0 if category not OUTIN */
	char	*display_name;
.sp .2
} escape_out_u2;
.fi
.IP
\fIerr_ind\fP
will contain the error number of any error detected by this function.
.IP
\fIdisplay\fP
is a pointer to the Display used by the \s-2PHIGS\s+2 workstation.
This pointer may be returned as NULL if \s-2PHIGS\s+2 is not
maintaining a connection to the display in the application's process.
If \fIdisplay\fP is NULL, the \fIdisplay_name\fP parameter, also returned
by this escape, can be used to identify the server used by the PHIGS
workstation.
.IP
\fIdrawable_id\fP
is the X window id of the drawable used by the specified workstation
for \s-2PHIGS\s+2 output.
.IP
\fIinput_overlay_id\fP
is the X window id of the window used by the specified workstation
for Locator, Pick, and Stroke input.
.IP
\fIdisplay_name\fP
is the name of the display used by the specified workstation.
.SS Execution
The \s-2INQUIRE WORKSTATION'S DRAWABLE AND DISPLAY\s+2 escape returns
Display and window information associated with the specified workstation.
While intended to be used for x_tool type workstations, where the application 
doesn't create the window or establish the display connection, this escape
will also work with x_drawable workstations.
.SH ERRORS
.IP 003
Ignoring function, function requires state (PHOP, WSOP, *, *)
.IP 054
Ignoring function, the specified workstation is not open.
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "ESCAPE (3P)"
.SM "CREATE STORE (3P)"
.SM "DELETE STORE (3P)"
.fi