NAME

OPEN XPHIGS − open and initialize PHIGS in the X environment

SYNOPSIS

C Syntax

void
popen_xphigs ( error_file, memory, xinfo_mask, xinfo )
char∗error_file;name of error file
Plongmemory;/fInot used/fP
unsigned longxinfo_mask;
Pxphigs_info∗xinfo;

Required PHIGS Operating States

(PHCL, WSCL, STCL, ARCL)

DESCRIPTION

Purpose

OPEN XPHIGS is similar to OPEN PHIGS but allows specification of additional run-time options.  It initializes the API and enables access to the PHIGS functions.  OPEN PHIGS or OPEN XPHIGS must be called prior to calling any other PHIGS functions. 

C Input Parameters

error_file
A pointer to the error file to log PHIGS error messages to.  The error file 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, PHIGS will attempt to access the file for writing.  If this attempt fails, OPEN XPHIGS will fail and the appropriate error will be reported to standard error. 

The error file argument passed to OPEN XPHIGS will be passed to ERROR HANDLING.  ERROR HANDLING will also pass this argument to ERROR LOGGING.  If for some reason ERROR LOGGING cannot access the specified error file, the error message will be written to standard error.  ERROR LOGGING appends messages to the error file; it does not truncate the file when OPEN XPHIGS is called.  If the specified file does not exist, it will only be created if ERROR LOGGING is called. 

ERROR LOGGING writes the abstract PHIGS 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, ERROR LOGGING will just write the function number and the error number. 

memory
This parameter is not used by the PEX-SI API. 

xinfo_mask
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.

PXPHIGS_INFO_DISPLAYThe display pointer: display
PXPHIGS_INFO_RMDBThe resource manager: rmdb
PXPHIGS_INFO_APPL_IDThe application name and class: appl_id
PXPHIGS_INFO_ARGSThe command line arguments: args
PXPHIGS_INFO_FLAGS_NO_MON The No Monitor flag: flags.no_monitor
PXPHIGS_INFO_FLAGS_CLIENT_SS The Force Client SS flag: flags.force_client_SS

xinfoA pointer to a Pxphigs_info structure.  This structure is used to specify X-related options to PHIGS.  xinfo is defined in phigs.h as follows:

typedef struct {
Display∗display; /∗ valid display pointer ∗/
XrmDatabasermdb;/∗ 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 {
unsignedno_monitor: 1;/∗ 1 ==> monitor will not be executed ∗/
unsignedforce_client_SS;/∗ 1 ==> always use client-side CSS ∗/
} flags;
} Pxphigs_info;

Only the fields indicated by xinfo_mask are examined. 

display specifies both the PHIGS default server and the connection PHIGS is to use when communicating with it.  The PHIGS default server holds the master copy of the central structure store, if it supports PEX structure storage, and is where tool workstations are opened if their location is not specified to the OPEN WORKSTATION function.  PHIGS uses the specified connection for all communication to the default server, even if a different connection is specified for a drawable workstation in a subsequent call to OPEN WORKSTATION.  PHIGS uses the specified connection for the duration of the PHIGS session; it must not be closed before calling CLOSE PHIGS.  If display is not specified, the default server will be the one returned by a call to XDisplayName() with an argument of NULL. 

rmdb an X resource database handle.  PHIGS 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 appl_id.  If args are also specified PHIGS 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 PHIGS recognizes are:

Argument StringResource NameResource Class Type Valid Values
-displaydisplayDisplayString
-bufmodebufModeBufModeStringsingle | double
=geometryGeometryString
-labellabelLabelString
-iconlabeliconLabelIconLabelString

The display resource specifies the name of the default server.  The bufMode resource specifies the default buffering mode, “single” or “double”.  The geometry resource specifies the default window location and size for phig_ws_type_x_tool workstation types.  The geometry is specified in the standard X geometry format:
<width>x<height>{+-}<xoffset>{+-}<yoffset>. 
The label resource specifies the window label for phig_ws_type_x_tool workstation types.  The iconLabel resource specifies the icon label for phig_ws_type_x_tool workstation types. 

appl_id.name and appl_id.class are the application name and class to use when resolving resource database attributes.  If not specified, the name “phigs” and class “Phigs” are used. 

args.argc_p is a pointer to the argument count, args.argv is the array of command line arguments.  The arguments are searched for attributes recognized by PHIGS and are merged into the specified database, if any. 

flags.no_monitor indicates whether the PHIGS Monitor (PM) is executed during popenphigs().  The PM is a separate program started by PHIGS that handles window events and PHIGS input for PHIGS workstations.  PHIGS 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 PM is not executed (flags.no_monitor = 1), PHIGS will not monitor and respond to X window events nor will it provide any PHIGS workstations that support PHIGS input devices.  All the predefined workstation types will be of category OUTPUT (output only).  If the PM is executed (flags.no_monitor = 0), PHIGS will monitor relevant window events and will provide predefined workstation types of category OUTIN (input and output). 

flags.force_client_SS indicates whether the API should use client side structure storage even if server side structure storage is available in X servers with the PEX extension.  flags.force_client_SS = 1 indicates that client side structure storage should always be used.  flags.force_client_SS = 0 indicates that server side structure storage should be used if available. 

Execution

OPEN XPHIGS sets internal state information and then calls popen_phigs(). 

ERRORS

001Ignoring function, function requires state (PHCL, WSCL, STCL, ARCL)

450Ignoring function, the specified error file is invalid

-200Ignoring function, cannot connect to the designated or default server

-201Ignoring function, the specified or default X server does not support a compatible PEX extension

SEE ALSO

INQUIRE SYSTEM STATE VALUE (3P)
OPEN PHIGS (3P)
CLOSE PHIGS (3P)

September 02, 1992