PHIGS is initialized by the function:
OPEN PHIGS(EF, BUFA)
The function must be called before any of the other PHIGS functions described so far can be called. The function is only called once for an invocation of PHIGS.
The parameter EF specifies the name of a file that will be used by PHIGS to return error information to the application program. Error handling in PHIGS is described in Section 12.6. The parameter BUFA defines the amount of memory available for buffer areas. Not all implementations will use this information, and in many cases the buffer area size will be fixed by the implementation.
Opening PHIGS initializes a number of internal variables to default values. For example, the element pointer is initialized to 0 and the edit mode to INSERT. Variables defining the characteristics of a particular implementation (for example the maximum permitted number of open workstations, and the list of available workstation types) are initialized, together with variables which define the characteristics of each of the workstation types supported by the implementation (for example the number of available linetypes).
PHIGS is closed down at the end of a session by the function:
CLOSE PHIGS
The error file is closed, all PHIGS buffers are released, and any other files associated with PHIGS are closed. It should be noted that PHIGS can only be closed after any open structure, open workstations and open archives (see Chapter 14 ) have been closed.
It is usual for an application to open PHIGS at the start of a session and close it at the end rather than open and close the PHIGS system several times within one session. There are occasions where reopening may be sensible (for example, after error recovery).
As an aid to error handling in PHIGS, the operating state of PHIGS is defined by four variables, each of which has two possible values:
Before PHIGS is opened, the state variables are initialized to (PRCL, WSCL, STCL, ARCL). PHIGS defines which state each function can be called in, and which functions cause the state to change.
For example, OPEN PHIGS can only be called in the state (PRCL, WSCL, STCL, ARCL), and changes the state to (PROP, WSCL, STCL, ARCL). OPEN WORKSTATION can only be called if the system state is PROP, and any values are allowed for the remaining states. It is immaterial whether other workstations are already open, or whether a structure is open or any archive files are open.
The notation * is used to indicate that either value is allowed for a particular state variable. Thus OPEN WORKSTATION is allowed in the state (PROP,*,*,*) and the resulting state is (PROP,WSOP,*,*). The functions which create output primitive structure elements in the central structure store, for example, POLYLINE, require that PHIGS is open and a structure is open. The permitted state of these functions is thus (PROP,*,STOP,*). The state is unchanged by these functions. Errors will be reported if a function is called in an invalid state.
Readers familiar with GKS should note that there is a strict ordering to the GKS operating states, but there is no such ordering to the PHIGS operating states. This arises from the decoupling of creation and display of graphical output which is fundamental to PHIGS.
PHIGS has a number of data structures which contain relevant information about the current state of PHIGS. These data structures are hidden from the application programmer in the sense that values in them cannot be set or tested directly by the application program, but the effect of many of the PHIGS functions is to set variables in these data structures and PHIGS provides functions to inquire the contents of most of these data structures (see Section 12.4).
The data structures are known collectively as the PHIGS state lists and description tables. Any reader who has occasion to study the PHIGS Standard itself, will find it useful to understand these data structures.
The state lists and description tables are:
The contents of the PHIGS data structures, with the exception of the traversal state list, are accessed by the application program via a set of inquiry functions.
Inquiry functions in PHIGS allow the application program to access the information in the PHIGS data structures. PHIGS also provides inquiry functions to access the central structure store; discussion of these is postponed to Section 12.5.
Inquiry functions are used for a variety of purposes; the main ones are:
A typical inquiry function has the form:
INQUIRE EDIT MODE(IND, EDITMO)
PHIGS inquiry functions are defined so that calling them can never generate a PHIGS error. This allows inquiry functions to be called in response to an error condition, without generating further errors. Inquiry functions also have no side effects on the PHIGS state and do not modify any of the PHIGS data structures.
It is clearly possible for inquiry functions to be called in states in which the information being inquired is not available. For example the edit mode is not defined if PHIGS is closed, and so the information inquired by INQUIRE EDIT MODE is not available unless the state is (PROP,*,*,*). The first output parameter of each inquiry function, IND, is used to indicate whether the information inquired was available or not.
If IND has the value 0 on return, the information inquired, in t his case the edit mode, is available, and the remaining parameters return the information. Non-zero values of IND indicate that the information is not available, and the precise value returned indicates the reason why the information is not available. For INQUIRE EDIT MODE, there is only one possible reason, and that is that PHIGS is not in the state (PROP,*,*,*). The function:
INQUIRE WORKSTATION CONNECTION AND TYPE (WKID, IND, CONID, WTYPE)
can fail to deliver the information requested if either the operating state is not (PROP,WSOP,*,*), or the workstation specified by WKID is not open. The values of IND returned enable the application program to distinguish between these two cases.
PHIGS has over 110 inquiry functions, so it is not possible to list them all here. The reader should refer to the relevant PHIGS documentation for further details of these.
One usage of inquiry functions, not mentioned above, is to obtain information from the PHIGS data structures, which is required to be given as arguments to a particular PHIGS function. A typical example (see Section 10.2.1) would be to reset the initial value of a VALUATOR logical input device without changing any of the other characteristics. This can be achieved by using an inquiry function to ascertain the current characteristics of the device, and then calling the INITIALIZE VALUATOR function with a new value for the initial value whilst retaining the other characteristics of the device.
INQUIRE VALUATOR DEVICE STATE(WS, DV, MLDR, IND, MODE, ESW,
IVAL, PET, EA, LDR, DATREC)
IF(IND .EQ. 0) INITIALIZE VALUATOR(WS, DV, NEWV AL, PET, EA(l),
EA(2), EA(3), EA(4), LDR, DATREC)
IF(IND .NE. 0) GOTO 300
The effect is to set the initial value of the device to NEWVAL. Other characteristics are unchanged. If a value of IND is returned that is nonzero, some error action would need to be taken. It would probably indicate that the function was invoked at the wrong time (the specified workstation was not open or the device was not available). A number of PHIGS functions require more than one value to be set together, and for these the application would need to use inquiry functions or keep a record of the state of the relevant variables if only a subset of the parameters need to be reset.
PHIGS provides functions which enable the application program to inquire the contents of the central structure store (CSS). These functions follow the same pattern as other inquiry functions described in Section 12.4. The CSS inquiry functions are likely to be of most use for library routines, and for ascertaining the contents of a central structure store which has been imported from an archive file (see Section 14.2).
The name of the open structure and the current value of the element pointer can be inquired using the functions:
INQUIRE OPEN STRUCTURE(IND, ST, SID) INQUIRE ELEMENT POINTER(IND, EP)
The status parameter, ST, on the first function returns the value OPEN if there is an open structure and NONE if there is none.
One usage of INQUIRE ELEMENT POINTER is to determine the position of the end of a structure, so that the element pointer can be restored to that position after some other manipulation has been performed. This is not the only way to achieve this, the structure could be closed and reopened, or a label element could be inserted in the structure at the appropriate position, but it can be a useful technique. The example below shows another way to solve the example given in Section 10.1.6.
SET EDIT MODE(INSERT)
OPEN STRUCTURE(SPMEG)
POST STRUCTURE(WS, SPMEG, 0.2)
SET MARKER TYPE(2)
SET LOCATOR MODE(WS, DV1, EVENT, ECHO)
SET CHOICE MODE(WS, DV2, EVENT, ECHO)
100 CONTINUE
AWAIT EVENT(60, WST, CLASS, DV)
IF (CLASS .EQ. NONE) GOTO 100
IF (CLASS .EQ. LOCATOR) GOTO 200
GET CHOICE(ST, OCHOIC)
INQUIRE ELEMENT POINTER(IND, EP)
SET EDIT MODE(REPLACE)
SET ELEMENT POINTER(1)
SET MARKER TYPE(OCHOIC)
SET EDIT MODE(INSERT)
SET ELEMENT POINTER(EP)
GOTO 100
200 CONTINUE
GET LOCATOR(VI, XA(1), YA(1))
POLYMARKER(l, XA, YA) GOTO 100
300 CONTINUE
CLOSE STRUCTURE
STOP
C STOP option selected
The variable EP is used to store the position of the end of the structure, whilst the set marker type element at the start of the structure is replaced. After replacement, the edit mode is restored to INSERT and the element pointer to point to the end of the structure.
The function INQUIRE CURRENT ELEMENT TYPE AND SIZE enables the type and size of the structure element at the current element position to be ascertained, and INQUIRE CURRENT ELEMENT CONTENT enables its content to be determined. In the Fortran language binding, element content is returned in an integer array, a real array and a character array. For details of the contents of these arrays for each type of structure element, the reader is referred to the documentation of the PHIGS implementation in use. The contents are standardized by the PHIGS language binding standards.
There are also inquiry functions, INQUIRE ELEMENT TYPE AND SIZE and INQUIRE ELEMENT CONTENT which enable the type, size and content of an element at an arbitrary position in the central structure store to be determined. The element position is specified by two parameters, a structure identifier and an element position. The latter defines the element position within the specified structure.
For illustration, one possible usage of these functions is in conjunction with PICK input. The PICK input device returns the traversal path through the central structure store to the structure element which generated the output primitive picked. These inquiry functions would enable the type of the output primitive and the parameters which define it, to be ascertained.
The function INQUIRE STRUCTURE STATUS enables the status of a particular structure to be ascertained. The values returned indicate whether the specified structure is non-existent, exists and is empty, or exists and is not empty.
There are two functions which enable the relationship of a given structure to other structures in the central structure store to be ascertained.
INQUIRE PATHS TO ANCESTORS returns the paths in the central structure store which reference the specified structure. INQUIRE PATHS TO DESCENDANTS returns the paths in the central structure store which are referenced by the specified structure. Each PHIGS function returns a list of paths, where each path is a sequence of (structure identifier, element pointer) pairs. This is a similar data structure to a pick path (but without a pick identifier). The element position associated with a structure identifier is the position within that particular structure of the execute structure element which invokes the next structure in the path. For INQUIRE PATHS TO ANCESTORS, the last element of the path is (S,0), where S is the structure whose ancestors are being inquired, and for INQUIRE PATHS TO DESCENDANTS, the last element is (D,0), where D is the deepest descendant in the structure network which contains no execute structure elements. Ancestor and descendant paths can, like PICK paths, be returned in either TOPFIRST or BOTTOMFIRST order.
In the Fortran language binding, both inquiry functions are mapped to subroutines which return a single path, rather than a list of paths. An output parameter specifies how many paths there are, and an input parameter specifies which particular path is to be returned.
These inquiry functions are useful if a library routine needs to explore the structure network it has to operate on. In general, if an application program is creating a structure network itself, one would expect the application to keep track of the network without recourse to inquiry functions. However, if a structure network is imported from an external source (by an archive file, see Chapter 14), it might be necessary to use inquiry functions to ascertain how and where a particular structure is being used. For example, consider the structure network in Figure 5.7 (Section 5.4.5), reproduced below in Figure 12.2. The corresponding scene is shown in Figure 12.1.
The ancestors of the structure PHON are WKNV, DESK, CN but there are two paths through the ancestors to PHON, depending on which of the execute structure elements in CN is followed. The possible paths returned by INQUIRE PATHS TO ANCESTORS are:
| Path 1 | |
|---|---|
| Structure | Element Pointer |
| WKNV | 2 |
| DESK | 3 |
| CN | 3 |
| PHON | 0 |
| Path 2 | |
|---|---|
| Structure | Element Pointer |
| WKNV | 2 |
| DESK | 3 |
| CN | 5 |
| PHON | 0 |
Similarly, an inquiry to determine the descendants of the structure CN, can produce the two paths:
| Path 1 | |
|---|---|
| Structure | Element Pointer |
| CN | 3 |
| PHON | 0 |
| Path 2 | |
|---|---|
| Structure | Element Pointer |
| CN | 5 |
| PHON | 0 |
The final central structure store inquiry function is the ELEMENT SEARCH function. This function enables an application program to search a specified structure for an occurrence of a specified type of structure element. This function can be useful in conjunction with the INQUIRE ELEMENT CONTENT function for editing structures. The function is:
ELEMENT SEARCH (SID, SEP, SDIR, EISN, EIS, EESN, EES, IND, ST, FEP)
SID and SEP identify the structure to be searched and the element position from which the search is to start. SDIR indicates whether the search is to be forwards or backwards from this position. EISN and EIS specify an element inclusion set (EIS is an array of EISN elements) and EESN and EES specify an element exclusion set (similarly EES is an array of EESN elements). The remaining parameters are output parameters; IND is the error indicator, ST a status indicator (returning the value FAILURE if an element of the required type is not found and SUCCESS if it is found). FEP points to the position of the element found (if any).
Element inclusion sets and exclusion sets are similar to the inclusion and exclusion sets associated with filters. A structure element will satisfy an element search, if its type is included in the inclusion set, and is not contained in the exclusion set. Using the structure network of Figure 12.2 as an example, an element search:
EIS(1)=POLYLINE
EIS(2)=EXECUTE_STRUCTURE
ELEMENT SEARCH(CN, 0, FORWARDS, 2, EIS, 0, EES, IND, ST, FEP)
will return ST with the value SUCCESS and FEP with value 1, because the first element in the structure CN is a polyline structure element. Calling the function again:
ELEMENT SEARCH(CN, 2, FORWARDS, 2, EIS, 0, EES, IND, ST, FEP)
will succeed and return FEP with value 3, the position of the first execute structure element in CN.
One application of this function is to locate all elements of a particular type so that, for example, they could be replaced with something else.
PHIGS has a well-defined set of errors that will be reported to the application. Readers familiar with GKS will find that the error handling mechanism in PHIGS is very similar to that in GKS, although situations which give rise to errors are rather different. The action of many PHIGS functions is to create structure elements which record the parameters specified in the function call. In many cases, it is not possible to check the validity of the parameters when the function is called, but only when the structure element is traversed. The reason for this is that the environment in which a structure element is traversed (typically the values of the transformation matrices), determines the validity of the parameters. An example is provided by SET CHARACTER UP VECTOR. The parameters to the function are specified in a text local coordinate system and must define a vector of non-zero length. However, it can only be determined at traversal time whether the parameters define a non-zero vector or not (to the precision used by the implementation) because only then is the coordinate system defined.
Because of the diverse ways in which traversal can be implemented, it could for example, be implemented as a process asynchronous from the application program, it would be extremely difficult to handle traversal time errors, and so PHIGS defines default actions to be performed in such cases. For SET CHARACTER UP VECTOR, the default action is to use the vector (0,1) for the up vector and (1,0) for the character base vector.
For situations in which errors are to be reported to the application program, PHIGS uses a mechanism which is very similar to the GKS error handling mechanism. All errors are reported by putting details of the error in the error file which was specified when PHIGS was opened.
Typically, occurrence of an error will cause the following information to be recorded in the error file:
PHIGS defines a standard set of error numbers which are reported by PHIGS functions. When an error has been detected, PHIGS calls the error handling procedure:
ERROR HANDLING(ERRNR, FCTID, ERRFIL)
The parameters are the error number (ERRNR), the function in which the error was detected (FCTID) and the name of the error file (ERRFIL). This function records the error in the error file by calling the function:
ERROR LOGGING(ERRNR, FCTID, ERRFIL)
and then returns to the function in which the error was detected. It is normal in PHIGS for a function in which an error is detected to have no effect on the PHIGS state, in other words, PHIGS ignores the function.
Application programs can turn off error reporting by calling the function:
SET ERROR HANDLING MODE(ERHM)
where the parameter ERHM can take the values OFF and ON. The default value is ON. If the mode is set to OFF, control will not be passed to the ERROR RAND LING procedure when an error is detected and the error will therefore not be reported. This facility would seem to be of limited value. The way it is described in the standard certainly does not imply that error checking is turned off if the mode is OFF. It is error reporting, not error checking, that is disabled.
The application program can provide its own error handling mechanisms by replacing the system supplied error handling procedure.
This application procedure can take any appropriate actions, but to avoid chaos ensuing, there are restrictions on what an application supplied error handling procedure should do. Only ERROR LOGGING, inquiry functions or EMERGENCY CLOSE PHIGS (see below) may be called by an application-supplied error handling procedure. The inquiry functions enable the application program to examine the PHIGS state lists, and so more precise reporting of the circumstances surrounding the error is possible than that provided by the system error handling procedure. It is worth noting that an application-supplied error handling procedure should still call the ERROR LOGGING procedure to record the error before returning control to the function in which the error was detected.
In some situations it will not be possible to recover from an error. The function EMERGENCY CLOSE PHIGS can be called in these circumstances to close the files used by PHIGS in as orderly a manner as possible, and save as much of the graphical information generated (for example in archives) as possible. As noted above, this function can safely be called by an application-supplied error handling procedure, and is used by PHIGS itself in response to certain fatal errors.