This chapter introduces advanced concepts that are part of the graPHIGS API Version 2. These topics are based on proposed extensions to the PHIGS standard called "PHIGS+" concepts presented in this part of the book involve an organizational change that divides the graPHIGS API into two distinct parts; the graPHIGS API shell and the graPHIGS API nucleus The shell is tightly coupled to the user application and performs syntax checking and building of the graphics data stream. The nucleus, on the other hand, is tightly coupled to the resources used by a graPHIGS API application such as structure stores and workstations. A nucleus manages the resources that may be shared simultaneously by a number of application processes. Each application process is a separate thread of execution with its own shell but attached to the same nucleus. By dividing your application into multiple processes, you can distribute parts of the application to the workstation as a Distributed Application Process (DAP).
Applications written to run under Version 1 of the graPHIGS API should still run under Version 2. For a further discussion of Version 1 and Version 2 compatibility, please see Appendix B. "Compatibility"
Some of the advanced graPHIGS API capabilities include:
This chapter describes the basic concepts for controlling the various new components of the graPHIGS API products. These components are supported to satisfy the following requirements:
The following section explains how to create and manipulate graphical data on a remote workstation. It will also point out the best mechanism to support such remote data manipulation. Access to the same workstation from multiple application processes is described as well, and you will learn how to maintain the integrity and security of each resource and application process.
Following is a list of the major differences between Version 1 and Version 2 of the graPHIGS API:
A typical example of the graPHIGS API environment is shown in the figure, "The graPHIGS API Environment."
Within this picture, the boxes roughly represent the following components:
As described above, structure stores, workstations, image boards, and font directories reside in a graPHIGS API nucleus and can be shared by multiple application processes, through multiple shells. Therefore, they are called resources of the graPHIGS API nucleus.
Within a nucleus, each resource is identified and referenced by a tag called a resource identifier A resource identifier is not the same as the identifier used in the graPHIGS API subroutine calls, such as the workstation identifier of the Open Workstation (GPOPWS) subroutine. To be able to use any of the advanced graPHIGS API functions, the workstation identifier is assigned by the application while the resource identifier is assigned to a resource by the nucleus when the resource is created. Regardless of how many application processes connect to the nucleus or what identifiers the processes use for the resource, each resource identifier is always unique within a specific nucleus. Nucleus resources which an application process can access are considered attached to the application.
When a resource is created at the request of your application process, it is implicitly attached to your application. A resource can also be attached to the application explicitly via the Attach Resource (GPATR) subroutine. In either case, your application process can assign its own identifier to the resource. Once a resource is attached to your application and has been assigned an application identifier, it is always referred to by the application identifier. Mapping between the application identifier and a resource identifier on the nucleus is automatically performed by the graPHIGS API shell.
An application process must have a graPHIGS API shell. Issuing the Open graPHIGS (GPOPPH) subroutine creates a graPHIGS API shell.
The graPHIGS API shell is responsible for receiving the parameters of the application's subroutine calls, validating them for correct syntax and for ensuring that calls are made in the correct sequence. The shell also builds the request in a form that is expected by the nucleus. This may involve data conversion such as IBM floating-point format to IEEE floating-point formats, ASCII-to-EBCDIC, and byte-swapping. The shell is also responsible for receiving responses and events from a nucleus and performing any necessary conversions. A nucleus response is the return of information to the shell that was directly requested by the shell through a previous request to the nucleus. Events are generated independently by the nucleus for a variety of reasons and sent to the shell asynchronously. Typical types of events include input device data and errors. The shell also provides trace facilities and error logging.
To perform these functions, each shell maintains the following information:
The graPHIGS API shell is terminated by the Close graPHIGS (GPCLPH) subroutine. If there are any nuclei connected to the shell, the Close graPHIGS subroutine call removes all of these connections.
Conceptually, a shell can access any nucleus on any node if there is a physical communication path between them. However, a given shell may have limitations as to which nuclei can be accessed, and which graPHIGS API subroutines are supported. Within each shell there is a graPHIGS API shell description table (PDT) and a graPHIGS API shell state list (PSL). By issuing the supported PDT and PSL inquiries, you may determine the capabilities, limitations, and state of a shell.
Generally speaking, a graPHIGS API nucleus exists and works independently of any graPHIGS API shell or application. A nucleus may run in a S/370, AIX, or 6090 environment and is created either through an environment-dependent mechanism outside of the graPHIGS API or when an application process tries to connect its shell to a nucleus.
A nucleus that exists in the same process is called a private nucleus. Only the shell that initiated the private nucleus may communicate with that nucleus. If a nucleus exists in a different process than the application, then that nucleus is called a remote nucleus (whether or not the nucleus resides on the same node as the application). A remote nucleus can communicate with any shell that is allowed to connect to it.
A special type of remote nucleus can exist on AIX: a child nucleus. A child nucleus is created when an application wants to connect to a private nucleus, but the nucleus has special requirements that it cannot fulfill inside the application's process (for example, not being threadable when running on a multiprocessing system or when the X Asynchronous Event Handling extension does not exist -- for example, X11R6). Only the shell that parented the child nucleus may communicate with the child nucleus.
A connection between a graPHIGS API shell and a graPHIGS API nucleus is established by the Connect to Nucleus (GPCNC) subroutine with the following parameters:
The nucleus connection methods currently supported are listed below:
The figures below describe the connection methods and corresponding connection specifications supported by the different combinations of shell/nucleus environments:
Supported Connection Methods
Shell Environment
VM MVS AIX 6090
---------------------------------
| | | | |
VM | CALL | N/A | N/A | N/A |
Nucleus |-------------------------------|
Environment | | | | |
MVS | N/A | CALL | N/A | N/A |
|-------------------------------|
| GAM or| GAM or|CALL or| |
AIX |SOCKETS|SOCKETS|SOCKETS| N/A |
|-------------------------------|
| | | | |
6090 | GAM | GAM | N/A |SOCKETS|
---------------------------------
Connection Specifications
Connection Method
1=CALL 2=GAM 3=SOCKETS
-----------------------------------------
| Null | Filedef | Nucspecx |
VM | (length=0) | (length<=8)| (length>=2)|
|---------------------------------------|
| Null | DDNAME | Nucspecx |
Application MVS | (length=0) | (length<=8)| (length>=2)|
Environment |---------------------------------------|
| Null | N/A | Nucspecx |
AIX | (length=0) | | (length>=2)|
|---------------------------------------|
| N/A | N/A | :0 |
6090 | | | (length=2) |
-----------------------------------------
N/A Not a valid combination
x Nucspec is set to the following specification:
hostname: nucleus connection number Where:
- hostname specifies the node id of an AIX
system.
- nucleus connection number specifies a
a nucleus on the named system and is a number
in the range of 0-255.
You may choose to have your application call the Connect to Nucleus (GPCNC) subroutine or have the graPHIGS API make the connect as part of the defaults processing performed by the Open graPHIGS (GPOPPH) subroutine. This may be done as follows:
The most important role of the graPHIGS API nucleus is to distribute requests from graPHIGS API shells to nucleus resource handlers, and to distribute events or errors generated by nucleus resource handlers to graPHIGS API shells. For this purpose, the nucleus maintains the following information for each application process (shell) connected to the nucleus and each resource existing in the nucleus:
Similar to the resource identifier, the identifier of each shell is unique within the nucleus and assigned by the nucleus when the shell is connected to the nucleus. This shell identifier is mainly used to validate an application's access to a resource. The application does not need to know the shell identifier except when the application wants to communicate with other applications through the graPHIGS API application message facility. To determine your shell identifier assigned by the nucleus, use the Inquire Shell Identifier (GPQSH) subroutine.
The connection between a shell and nucleus is terminated explicitly by the Disconnect Nucleus (GPDNC) subroutine and implicitly by the Close graPHIGS (GPCLPH) subroutine. When the connection is destroyed, all resources in the nucleus that are attached to the shell are automatically detached from it.
As with shells, some nuclei may have limitations such as the number or type of shells to which the nucleus can be connected, the number and type of resources that can be created, and the set of functions actually supported.
Within each nucleus there is a Nucleus Description Table (NDT) and a Nucleus State List (NSL). By issuing the supported NDT and NSL inquiries, your application may determine the capabilities, limitations, and state of a nucleus.
The following two sections describe workstation and structure store resources.
A structure store is a repository for structures. Once a connection between your shell and nucleus is established, your application can create a number of structure stores in the nucleus, limited only by the amount of memory available to the nucleus and its maximum supported number. The graPHIGS API shell associates one or more structure stores within the same nucleus to a workstation in order to produce output on the workstation. However, only one structure store may be associated with a workstation at any one time. Associating a structure store to a workstation implicitly disassociates a structure store previously associated. Several workstations within a nucleus may be associated to the same structure store. Your application program is responsible for managing structure names among the structure stores that it owns.
The Create Structure Store (GPCRSS) subroutine creates a structure store resource in the specified nucleus, and attaches it to the graPHIGS API shell. All structure stores are mutually independent. For example, a structure within a structure store can reference only structures within that structure store. Subroutines applied to a structure store affect only that structure store and have no side effects on other structure stores. The same structure identifier can be used in more than one structure store without conflict.
Your application can access multiple structure stores, therefore, it is important to select the desired structure store before editing. Selecting a structure store may be done implicitly when the graPHIGS API does nucleus connection processing or explicitly by your application calling the Select Structure Store (GPSSS) subroutine.
Structure stores can be created and manipulated using one of two methods. The default method, which provides compatibility between Version 1 and Version 2 of the graPHIGS API, relies on the automatic connection of a nucleus and the creation of a structure store. The structure store is also automatically selected to be the current structure store so that the following Version 1 code will continue to work:
Open graPHIGS (GPOPPH) Open Structure (GPOPST) . . . Edit . . . Close Structure (GPCLST)
To suppress the default creation of both a nucleus and structure store or to allow an existing application to run on a 6090, your application must specify either an Application Defaults Interface Block (ADIB) or use an External Defaults File (EDF). ADIBs and EDFs are discussed in detail in The graPHIGS Programming Interface: Technical Reference When default nucleus and structure store processing creation is suppressed, your application will take the following form:
Open graPHIGS (GPOPPH)
(specifying DEFNUC in ADIB or EDF)
Connect Nucleus (GPCNC)
Create Workstation (GPCRWS)
Create Structure Store (GPCRSS) or Attach Structure Store (GPATR)
Associate Structure Store to Workstation (GPASSW)
Select Structure Store (GPSSS)
Open Structure (GPOPST)
.
.
.
(Edit Structure)
.
.
.
Close Structure (GPCLST)
Close Workstation (GPCLWS)
Close graPHIGS (GPCLPH)
In order to display the contents of a structure store on a workstation, the structure store must be associated to a workstation using the Associate Structure Store to Workstation (GPASSW) subroutine.
A structure store is automatically associated with a workstation when your application issues the Open Workstation (GPOPWS) subroutine, and a structure store is currently selected.
If your application has not selected the structure store or uses GPCRWS to create a workstation, then the structure store will not be automatically associated with the workstation. Using the Detach Resource (GPDTR) enables your application to detach a structure store from its shell. If GPDTR removes the final reference to the structure store, either through an attachment to a shell or association to a workstation, the structure store itself is released.
For each structure store within the nucleus, there is a Structure Store State List (SSL). By issuing the supported SSL inquiries, your application may determine the state of a structure store.
The Create Workstation (GPCRWS) subroutine creates a workstation resource owned by a graPHIGS API nucleus and attaches the workstation to the graPHIGS API shell. GPCRWS requires the following parameters:
Using the GPOPWS subroutine creates a workstation resource on a nucleus with identifier 1.
A workstation can display graphical data from any structure store existing in the nucleus where the workstation resides. In order to specify which structure store is used for display, use the Associate Structure Store with Workstation (GPASSW) subroutine. A workstation can display graphical data within one structure store only. All display subroutines, such as Associate Root with View (GPARV) subroutine, are treated as referring to a structure within the structure store associated with a particular workstation.
Your application can detach a workstation from the graPHIGS API shell using the Detach Resource (GPDTR) or Close Workstation (GPCLWS) subroutine. GPCLWS detaches the workstation resource on a nucleus with nucleus identifier 1. If this subroutine removes the final reference to the workstation, the workstation and all its resources are removed from the nucleus.
For each workstation within the nucleus, there are two Workstation Description Tables (WDT) and a Workstation State List (WSL). By issuing the supported WDT and WSL inquiries, you may determine the capabilities, limitations, and state of a workstation.
The two WDTs for each workstation are:
To obtain the most accurate information about a workstation, you should inquire its capabilities from the actual workstation description table. In order to do this you must specify the actual workstation type on the inquiry. The actual workstation type is returned by the Inquire Realized Connection and Type (GPQRCT) subroutine.
Typically, you won't need to know the details of the communication mechanism used between a graPHIGS API shell and nucleus. However, to achieve the maximum performance and to fully understand topics discussed in subsequent sections, you must have a general understanding of the communication mechanism.
Data transmitted between a shell and a nucleus consists of a sequence of buffered data structures called procedures Most procedures correspond to a subroutine call in the graPHIGS API and are used by the graPHIGS API to pass information between a shell and nucleus. The length of a procedure is limited by the I/O buffer size that has a maximum value of 64K bytes. The most important consequence of this limitation is that the definition data of each output primitive cannot exceed 64K bytes. For example, the number of vertices specified in a Polyline 3 primitive must be less than approximately 5,000.
A graPHIGS API shell normally allocates two 64K I/O buffers, one outbound and one inbound, for each nucleus connection. However, when you want to minimize the amount of storage used by the shell, your application can override the default I/O buffer sizes through the COMBSZ default of an Application Defaults Interface Block (ADIB) or an External Defaults File (EDF).
By default, the data created by a shell is sent to a nucleus when one of the following situations occur:
Two mechanisms are supplied for the application to change the default action for some of these situations. One is the Set Shell Deferral State (GPSHDF) subroutine that enables the application to suppress automatic data sending caused by the subroutines within the first group of this list. This enables the application to realize an animation sequence without causing unnecessary I/O operations between the shell and nucleus. For example, a series of alternating invocations of Set View Matrix and Update Workstation can be accumulated into the I/O buffer and sent to a nucleus with a single I/O operation. The nucleus would then generate multiple frames on the display surface without I/O overhead between each frame. Another mechanism to change the default action is provided by the Synchronize (GPSYNC) subroutine that enables the application to force data transmission directly. When the application issues Synch, any buffered requests are sent to the nucleus immediately.
Data is sent from a nucleus to a shell in the following situations:
A nucleus can receive requests from multiple shells at any time and is only required to guarantee the following:
When a workstation is shared by multiple shells, usage of the workstation's input devices is serialized as follows:
Likewise, when an input device is set to Request mode, only the application process that activated the device is notified when a break action occurs.
When a structure store is shared by multiple application processes, access to the structure store is also treated in a special manner. When an application process calls the Open Structure (GPOPST) subroutine, the currently selected structure store is dedicated to that application process. All subsequent structure modification requests from other application processes are not processed and are blocked by the nucleus, until the 'owning' application process calls the Close Structure (GPCLST) subroutine.
Notice that the structure store state described here is different from the structure state of the graPHIGS API shell. The structure state of the shell is mainly used to check whether an application process issues graPHIGS API calls in the correct sequence or not. For example, any output primitive subroutines will only be processed if the structure is opened to make sure these primitives are correctly stored in a structure. The purpose of the structure store state in the nucleus is not for validity checking but for ensuring that structure editing operations are consistent between application processes. For example, the Delete Structure (GPDLST) subroutine deletes not only the specified structure but also all references to the structure. If your application issues this subroutine call while another application process has a structure open, this automatic deletion of structure references (Execute Structure elements) can cause many problems.
All requests to a structure store that are blocked by this mechanism are not discarded but processed at a later time. There is no assurance that these blocked requests are processed immediately after the current owner issues a Close Structure. If the previous owner issues another Open Structure request, the structure store may be dedicated to the same application process again. Switching between requests from different application processes is not guaranteed to be performed in any particular order.
When a font directory is shared by multiple application processes, access to the font directory is treated in a special manner. When an application process calls the Load Font (GPLDFO) subroutine to load a font into the directory, the specified font directory is dedicated to that application process. All subsequent requests from other processes to access the font directory are blocked by the nucleus until the the load of the font completes. When the load of the font completes, the font directory may then be accessed by other application processes.
When an image board is shared by multiple application processes, access to the image board is also treated in a special manner. When an application process calls the Write Rectangle (GPWRCT) subroutine, requests from other processes to access the image board are blocked by the nucleus until the write to the image board completes. When the write to the image completes, the image board may be accessed by other application processes.
The graPHIGS API gives you the ability to divide your application into multiple Distributed Application Processes (DAPs). Each DAP is a separate executable graPHIGS API process with its own graPHIGS API shell. These DAPS are downloaded to the remote nucleus by a connected shell process, using the Initiate Application Process (GPINAP) subroutine or the Execute Application Process (GPEXAP) subroutine. A DAP that already exists on the node containing the remote nucleus can be executed by using GPINAP or GPEXAP. The use of DAPS allows you to offload some functions that cannot be performed efficiently across a network.
A DAP can perform many diverse functions, including:
On an AIX system, a DAP has the same privileges and restrictions as any other application on the system, as shown in the figure, "DAP Organization."
For a discussion of compiling, starting, and terminating DAPs, see The graPHIGS Programming Interface: Writing Applications
One method for two application processes to communicate is through the application message facilities provided by the graPHIGS API as discussed in the following section.
In order for multiple application processes to communicate, the graPHIGS API provides a message facility used to send application defined messages from one application process to the event queue of another process. The messages are sent using the Send Broadcast Message (GPSBMS) and Send Private Message (GPSPMS) subroutines and can be retrieved from the event queue by the target process using the Get Message (GPGTMS) subroutine.
The format of the message event is defined by the graPHIGS API, but there is no restriction on the contents of the application message. The graPHIGS API shell and nucleus do not perform any validity checking or implicit conversion on the message data and no additional information, such as the originator of the message, is supplied in the message event. The graPHIGS APIthat performs the following conversions:
In order to prevent an application process from receiving unexpected messages sent by unknown applications, the following two levels of protection are provided.
The Send Private Message (GPSPMS) subroutine has the following parameters:
Because the broadcast message has no specific target, the application need not specify any shell identifier or message password. The broadcast message is sent to all shells attached to the specified nucleus which have their shell password ALL. The Send Broadcast Message (GPSBMS) subroutine has the following parameters:
A typical scenario for two applications processes to share a resource by using the application messages is presented below. The resource being shared is a structure store created by the first application process.
Note: The message contains the shell identifier and message password of application 2.
Note: A private message is used because application process 1 now has the shell identifier and message password of application process 2 from the data passed in the broadcast message.
One application process can attach a nucleus resource (a workstation, structure store, image board, or font directory) created by another application process to its process by using the Attach Resource (GPATR) subroutine with the following parameters:
To be able to attach a resource, your application must know the resource's nucleus resource identifier and password. Initially, this information is known only to the application process that created the resource. The nucleus resource identifier is assigned by the nucleus when the resource is created and can be retrieved using the Inquire Nucleus Resource Identifier (GPQNCR) subroutine.
The password of each resource can have one of the following values:
Each time a resource is created in a nucleus, the resource's password is set to 0=NONE so it cannot be shared by any other application process. Therefore, when two or more application processes want to share a resource, its password must be explicitly set to some value other than zero by the Set Password (GPPW) subroutine. For security reasons, this subroutine allows only the application process that created the resource to change its password.
A scenario for two application processes to share a resource follows:
The resource is being shared by the 2 application processes.
The graPHIGS API supports user exits and provides subroutines that can work in conjunction with a conference utility. Although the software required in a conference utility is considerable in size, the benefits can be great. Designers collaborating from remote sites can view the same model simultaneously, with each workstation able to interact with the application. New users of the graPHIGS API also benefit when getting assistance from the help desk through a conference utility. The following graPHIGS API subroutines are available for use with a conference utility.
Refer to The graPHIGS Programming Interface: Technical Reference for more information about user exits and a description of a typical conference utility.
