OPEN PHIGS(3P) — SUNPHIGS LIBRARY

NAME

OPEN PHIGS − open and initialize the PHIGS environment

SYNOPSIS

C Syntax

void
popenphigs ( err_file, memory )
Pchar∗err_file;name of error file
Plongmemory;bytes of memory available for buffer space

FORTRAN Syntax

SUBROUTINE popph ( ERRFIL, BUFA )
INTEGERERRFILerror message file
INTEGERBUFAamount of memory units

Required PHIGS Operating States

(PHCL, WSCL, STCL, ARCL)

DESCRIPTION

Purpose

OPEN PHIGS initializes the PHIGS environment and enables access to the PHIGS functions. OPEN PHIGS must be called prior to calling any other PHIGS functions.

C Input Parameters

err_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, e.g., (Pchar∗)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 PHIGS will fail and the appropriate error will be reported to standard error.

The error file argument passed to OPEN PHIGS will be passed to ERROR HANDLING. ERROR HANDLING will also pass this argument to the 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 PHIGS 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 should be set to the constant PDEFAULT_MEM_SIZE, which is defined in phigs.h.

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 associated with the standard preconnected files standard error and standard output, those associated with a file the application has opened prior to calling OPEN PHIGS, and those that are valid with respect to the FORTRAN I/O system but are not yet associated with an open file. The PHIGS interaction with these various types of logical unit numbers is described in the Execution section below.

BUFAThis parameter is ignored. -1 should be passed.

Execution

OPEN PHIGS:

•Sets the PHIGS system state variable to ‘PHOP’.

•Initializes the default workstation description tables and makes them available for use by the other PHIGS functions.

•Creates the PHIGS state list and initialize it with default values taken from the PHIGS description table.

•Stores error file in the PHIGS error state list.

The default values for the PHIGS state list, PHIGS description table, and workstation description tables are in the Appendix.

When an error in PHIGS is detected, ERROR HANDLING is called and passed three items of informations: the error file, the function number of the PHIGS function that detected the error, and the error number. ERROR HANDLING calls the ERROR LOGGING, which writes an error message to the error file. PHIGS users can replace ERROR HANDLING with a function of their own. This function may in turn call ERROR LOGGING. See ERROR HANDLING and ERROR LOGGING for more information.

PHIGS only writes to the error file if ERROR LOGGING is called, either by ERROR HANDLING or the application. If the error file does not exist when OPEN PHIGS is called, it will only be created if and when ERROR LOGGING is called.

FORTRAN Error Files

The error file argument to OPEN PHIGS is a FORTRAN logical unit number. Valid logical unit numbers are those enumerated in the FORTRAN Parameters section above. The PHIGS interaction with these various types of logical unit numbers is as follows:

Logical unit numbers associated with the preconnected units standard error and standard output. ERROR LOGGING will log error messages to these files.

Logical unit numbers associated with files opened by the application prior to calling OPEN PHIGS. ERROR LOGGING will log error messages to these files. They are not otherwise accessed by PHIGS.

Note: If it’s desired to append the output of ERROR LOGGING to the file, the file should be opened with the option fileopt=’eof’ in the FORTRAN open statement.

Valid logical unit numbers that are not associated with an open file. If ERROR LOGGING is called, a file with the name fort.lun will be created, where lun will be replaced with the value of the logical unit number. ERROR LOGGING will then log error messages to the new file. If ERROR LOGGING is not called, no file will be created. If a file with the derived name already exists its contents will be overwritten.

Specifying an invalid logical unit numbers will cause OPEN PHIGS to fail with error number 450: Ignoring function, the specified error file is invalid. ERROR LOGGING will use logical unit number 0 (stderr by default) to log this error.

The logical unit numbers preconnected to standard input (logical unit number 5 by default) cannot be used as the PHIGS error file if it is still associated with standard input when ERROR LOGGING is called. If it is desired to use this logical unit number, it must be disassociated from standard input (see the Sun FORTRAN Programmer’s Guide for how to do this).

A logical unit number whose value is valid but cannot be written to will cause an additional error message to be logged when ERROR LOGGING is called. This additional error, along with the specified error, will be logged to logical unit number 0 (stderr by default) and will indicate the FORTRAN error number returned from the FORTRAN write call (that returned to the iostat specifier) and the logical unit number used. If logical unit number 0 can not be written to in this case, neither error will be logged.

The default PHIGS error file is standard error. When the PHIGS system state is PPHCL (PHIGS Closed), invocations of ERROR LOGGING will log errors to this file. The exception is invocations of ERROR LOGGING within a call to OPEN PHIGS. In this case the error file specified in the OPEN PHIGS call will be used.

ERRORS

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

450Ignoring function, the specified error file is invalid

Museum