The Personal graPHIGS Programming Interface: Customization and Problem Diagnosis

Chapter 5. Problem Determination for gPgated, the graPHIGS API Gateway Daemon

If you encounter a problem when attempting to run a graPHIGS API application or connect to a graPHIGS API gateway, follow this procedure:

Check that gPgated, the graPHIGS API gateway daemon, is running and that there is a run time connection profile entry which associates an IBM S/370 device address with the target remote graPHIGS API nucleus. Use the lsgPcon command to verify that the entry exists. (See The graPHIGS Programming Interface: Technical Reference for more information on the lsgPcon command.) This may return one of a number of different messages depending on your connection, nucleus, and general workstation state. Messages and appropriate actions are as follows:

Figure 5-1. Messages and Appropriate Actions

Message	Action
lsgPcon AFM0602 No connection exists on path hostname:nucid	go to Step 2
device address hostname:nucid DEFINED	Verify that this is the run time connection profile entry desired. If so, go to Step 3 If not, go to Step 2
device address hostname:nucid OPEN	This device address is in use. You may wish to try another device address.
lsgPcon unknown hostname hostname	go to Step 4
lsgPcon AFM0604 gPgated hostname NOT STARTED OR NOT RESPONDING	go to Step 5
gPhost AFM0604 NUCLEUS gP xxx NOT STARTED OR NOT RESPONDING	go to Step 6

Use the chgPcon command to add a run time connection profile entry, associating an IBM S/370 device address with the target remote nucleus. (See The graPHIGS Programming Interface: Technical Reference for more information on the chgPcon command.)
Use the gPhost command to determine whether the graPHIGS API gateway daemon is allowed to communicate with the target remote nucleus. (See The graPHIGS Programming Interface: Technical Reference for more information on the gPhost command.)
If the host on which the graPHIGS API gateway daemon is running is not in the list returned by gPhost, use the gPhost command to add the host. (See The graPHIGS Programming Interface: Technical Reference for more information on the gPhost command.)

Then go to Step 7
You have a TCP/IP configuration problem. The host where the graPHIGS API gateway daemon is running is not defined. Contact your network administrator.
The graPHIGS API gateway daemon does not appear to be running. Check to see if the specified host is the desired gateway. If so, use the gPgated command to restart the graPHIGS API gateway daemon. (See The graPHIGS Programming Interface: Technical Reference for more information on the gPgated command.)
Use the gPq command to determine whether the remote graPHIGS API nucleus is running on your workstation. If there is no response, execute the gPinit command to start the remote graPHIGS API nucleus. (See The graPHIGS Programming Interface: Technical Reference for more information on the gPq and gPinit commands.)
Then go to Step 3
Restart your GDDM/graPHIGS API application.

Expected Behavior Under Problem Conditions

Under problem conditions, several types of system failures are possible. Following is a list of potential problems and the expected default system behavior:

Application abnormal termination

On MVS and MVS/XA, GAM closes the connection to your graPHIGS nucleus, and then the workstation and its resources are freed.
On VM and VM/XA, GAM may not get control to close the connection, so the workstation and its resources may appear to "hang" until the application is restarted. GAM open processing causes the workstation and its resources to be freed and then open processing proceeds.

IBM S/370 failure

This failure does not affect the graPHIGS API gateway daemon or any connections. If a 'system reset' is required, warning messages are recorded at the host where the graPHIGS API gateway daemon is running.

IBM 5088 or 6098 failure

Depending on the kind of failure, there may be no greater impact than an IBM S/370 failure, as described above. Run the utility program panel20 at the host where the graPHIGS API gateway daemon is running. (See the IBM RISC System/6000 5080 Graphics System Installation, Operation, and Problem Determination for more information about the panel20 command.)

If the link status code is 0, no action is required. If the status for a connection is not as expected, the graPHIGS API gateway daemon may need to be restarted with the gPated command. (See The graPHIGS Programming Interface: Technical Reference for more information on the gPgated command.)

If the IBM 5088 or 6098 is restarted, not-ready-to-ready interrupts are received at the IBM S/370.

Host Interface Adapter (HIA) failure

This is indicated by a link status of 2 (adapter error) in the utility program panel20 This is a terminating error and requires the graPHIGS API gateway daemon to be terminated and the adapter to be reconfigured. This may be done simply by shutting down, or by the following command sequence:

 rmdev -l hia0
 mkdev -l hia0

Error log information from the errpt command should be reported to your service representative. Once the graPHIGS API gateway daemon is restarted and the connections are re-established, not-ready-to-ready interrupts are received at the IBM S/370.

gPgated failure

In the event of a graPHIGS API gateway daemon abend, there is a "warmstart" option that allows the gateway to be restarted with the same run time connection profile that existed at the time of failure. Once the connections are re-established, not-ready-to-ready interrupts are received at the IBM S/370.

TCP/IP network failure

Depending on the nature of the failure, one of two things may occur:

If a specific link is broken, it appears as if it were a workstation failure as described below, with the potential for more than one workstation to be involved
The following error may be logged in the gateway transaction file:
```
AFM0593 COMMUNICATION ERROR: MAJOR 7, MINOR
errno
```

In either case, the IBM S/370 device address associated with the connection receives an asynchronous error (Attention-UC).

Personal graPHIGS remote nucleus or user workstation failure

The following error may be logged in the gateway transaction file:

AFM0204 NUCLEUS CONNECTION FAILED
DEVICE ADDRESS
xxx, NUCLEUS ':0' MAJOR 7, MINOR
errno
ABNORMALLY terminated

The associated IBM S/370 device address receives an asynchronous error (Attention-UC) and the connection remains OPEN At this point, the application should react to the error and disconnect the nucleus.

Using the Trace Facility

The graPHIGS API gateway daemon is capable of using the AIX system trace facility. If detailed problem determination is required, your support representative may ask you to generate a trace file.

To generate a trace file, follow these steps:

Log on as super user to the host at which the graPHIGS API gateway daemon is running.
Invoke the trace command as follows:
```
   trace -aj280,281,282
```
Run the application to the point of error.
Turn trace off by issuing the following command:
```
   trcstop
```
Format the trace data by issuing the following command:
```
   trcrpt -o trace.file
```

See "The graPHIGS API Trace Facility" for more information on the graPHIGS API trace facility.