.\" @(#)PEXInitialize.3 1.4 95/03/24 SMI;
.so man3/pex.macs
.TH PEXInitialize 3 "May 1995" "Solaris PEXlib Reference Manual" ""
.SH NAME
PEXInitialize - Initialize PEXlib display connection
.SH SYNTAX
.HP
int PEXInitialize\^(\^Display *\fIdisplay\fP\^, PEXExtensionInfo **\fIinfo_return\fP\^, int \fIlength\fP\^, char *\fIerror_string\fP\^)
.SH PARAMETERS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful
.B XOpenDisplay
call.
.IP \fIinfo_return\fP 1i
Returns a pointer to the extension information; if available
(see the Description).
.IP \fIlength\fP 1i
The length, in bytes, of the memory allocated for the error string.
.IP \fIerror_string\fP 1i
A pointer to memory allocated for the error string.
.SH RETURNS
.LP
Zero if successful; otherwise, one of the following return values:
.LP
.RS
.nf
.B PEXBadExtension
.B PEXBadProtocolVersion
.B PEXBadFloatConversion
.B PEXBadLocalAlloc
.RE
.fi
.SH DESCRIPTION
.\" indexing
.IX PEXInitialize
.LP
.B PEXInitialize
initializes PEXlib for the specified display.
.LP
.B PEXInitialize
can be called multiple times; subsequent calls will result in the same return
value as the first call.
.LP
Standard
.B PEXInitialize
failure return values are:
.LP
.B PEXBadExtension
- the PEX server extension does not exist,
.LP
.B PEXBadProtocolVersion
- the PEX server extension does not support a compatible protocol version,
.LP
.B PEXBadFloatConversion
- the PEX server extension does not support a protocol floating point format
compatible with PEXlib's native format or a format to which PEXlib supports
conversion, or
.LP
.B PEXBadLocalAlloc
- PEXlib client-side allocation failed.
.LP
If
.B PEXInitialize
is successful (return value is zero), or if the return value is
.B PEXBadProtocolVersion,
a pointer to the extension information is returned in
.I info_return.
Otherwise, a NULL pointer is returned in
.I info_return.  The
extension information is private to PEXlib and must not be modified or freed
by the application.
.LP
The error string parameter specifies an address to
memory allocated by the application.
The constant
.B PEXErrorStringLength
is defined as a guideline for the size to allocate for the error string.
If no failure occurred, the memory
addressed by the error string parameter will be unchanged.
If a failure does occur, an error string giving further information about
the failure will be copied into this memory (up to the maximum specified by the
length parameter).
.LP
The actual string returned is implementation dependent, and is provided
primarily for convenience in printing an error message for the application's
end-user.
.SH DATA STRUCTURES
.LP
.nf
typedef struct {
	unsigned short		major_version;
	unsigned short		minor_version;
	unsigned long		release;
	unsigned long		subset_info;
	char			*vendor_name;
	int			major_opcode;
	int			first_event;
	int			first_error;
.br
} PEXExtensionInfo;
.fi
.SH ERRORS
None
.SH SEE ALSO
.LP
.nf
.BR PEXGetExtensionInfo (3)
.BR PEXGetEnumTypeInfo (3)
.BR PEXGetImpDepConstants (3)
.BR PEXMatchRenderingTargets (3)
.fi