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
Plong            memory;        not used
unsigned long    xinfo_mask;
Pxphigs_info     * xinfo;

FORTRAN Syntax

SUBROUTINE popenxphigs (ERRFIL, BUFA, DISPLAY, RMDB, NAME, APCLASS, ARGC, ARGV )

INTEGER              ERRFIL       error message file
INTEGER              BUFA         amount of memory units
INTEGER              DISPLAY      address of display
INTEGER              RMDB         address of resource database
CHARACTER* (* )      NAME         application name
CHARACTER* (* )      APCLASS      application class
INTEGER              ARGCP        address of argument count
INTEGER              ARGV         address of argument list

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 PHIGS environment and enables access to the PHIGS functions. OPEN PHIGS or OPEN XPHIGS must be called prior to calling any other PHIGS functions.

This function is not implemented in FORTRAN

C Input Parameters

error_file

A pointer to the error file in which to log PHIGS error messages. 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. When a file name is specified, PHIGS attempts to access the file for writing. If this attempt fails, then OPEN XPHIGS fails, and the appropriate error is reported to standard error.

The error file argument passed to OPEN XPHIGS is passed to ERROR HANDLING. ERROR HANDLING also passes this argument to ERROR LOGGING. If for some reason ERROR LOGGING cannot access the specified error file, then the error message is 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 is created only 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 cannot be determined, then ERROR LOGGING simply writes the function number and the error number.

memory This parameter should be set to the constant PDEF_MEM_SIZE, which is defined in

phigs.h.

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_DISPLAY

The display pointer: display

PXPHIGS_INFO_RMDB

The resource manager: rmdb

PXPHIGS_INFO_APPL_ID

The application name and class: appl_id

PXPHIGS_INFO_ARGS

The 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

xinfo

A 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 * /
XrmDatabase     rmdb;               /* a valid database * /
struct {
    char        * name;
    char        * ap_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;

} 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 the following is true: it supports SunPHIGS structure storage and is the location where a tool workstation is opened if its 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. When display is not specified, the default server is returned by a call to XDisplayName() with an argument of NULL.

rmdb specifies 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. When args are also specified, PHIGS merges them into the database prior to searching the database for resources that PHIGS recognizes. Any merged arguments are removed from the argument list. The resources PHIGS recognizes are:

Argument String Resource Name      Resource Class Type       Valid Values
-display         display           Display        String
-bufmode         bufMode           BufMode        String     single | double
=                geometry          Geometry       String
-label           label             Label          String
-iconlabel       iconLabel         IconLabel      String

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.ap_class are the application name and class to use when resolving resource database attributes. If they are not specified, then 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, if any are found, then the arguments are merged into the specified database.

flags - SunPHIGS does not use this element.

FORTRAN Input Parameters

ERRFIL

The FORTRAN Logical Unit Number of the error file to log PHIGS error messages to. Valid logical unit numbers are those that are:

Associated with the standard preconnected files: standard error and standard output.

Associated with a file that the application has opened prior to calling OPEN PHIGS.

Valid with respect to the FORTRAN I/O system (but which are not yet associated with an open file).

PHIGS interaction with these various types of logical unit numbers is described in the Execution section below.

BUFA

This parameter is ignored. -1 should be passed.

DISPLAY

The address of a valid Display structure, which 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 SunPHIGS structure storage, and is where a tool workstation is opened when its 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. A value of 0 can be used, in which case PHIGS uses the default server returned by an XDisplayName() with a NULL argument.

RMDB

An X resource database handle, which PHIGS uses to build the default workstation description tables. A value of 0 can be used if no resource database is to be used. When a database is specified, 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 NAME and APCLASS. When args are also specified, PHIGS merges them into the database prior to searching the database for resources that PHIGS recognizes. The resources PHIGS recognizes are:

Argument String   Resource Name     Resource Class Type      Valid Values
-display          display           Display        String
-bufmode          bufMode           BufMode        String    single | double
=                 geometry          Geometry       String
-label            label             Label          String
-iconlabel        iconLabel         IconLabel      String

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.

NAME

A character array containing the application name to be used when resolving resource database attributes. A null string can be specified, in which case the name phigs is used.

APCLASS

A character array containing the application class to be used when resolving resource database attributes. A null string can be specified, in which case the name Phigs is used.

ARGCP, ARGV

These parameters are provided for programs that use SunPHIGS in FORTRAN, but obtain a C-style argument count and argument list. ARGCP is an integer set to the address of the argc argument count. ARGV is the array of argv command line arguments. The arguments are searched for attributes recognized by PHIGS and, if any are found, then the arguments are merged into the specified database. A value of 0 should be used for ARGCP when no argument list is available, in which case ARGV is ignored.

Execution

OPEN_XPHIGS sets internal state information and then calls popen_phigs().

ERRORS

001

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

450

Ignoring function, the specified error file is invalid

-200

Ignoring function, cannot connect to the designated or default server

-201

Ignoring function, the specified or default X server does not support a compatible PHIGS extension

SEE ALSO

INQUIRE SYSTEM STATE VALUE (3P)

OPEN PHIGS (3P)

CLOSE PHIGS (3P)