This chapter describes the following sections:
The graPHIGS API gateway daemon, gPgated, is a process which enables a GDDM/graPHIGS API application using GAM to access an AIX graPHIGS API remote nucleus, and graPHIGS API workstations managed by it. (See The Personal graPHIGS Programming Interface: Customization and Problem Diagnosis for specific hardware and software requirements). gPgated uses one or more IBM RS/6000 Host Interface Attachment (HIA) features connected to an IBM 5088 or 6098 communications controller to communicate to graPHIGS API nuclei running locally, or to graPHIGS API nuclei running remotely via TCP/IP over a LAN. Figure 4 is a high level diagram that represents the components of this configuration:
Figure 4. GDDM/graPHIGS API Application to graPHIGS API Remote Nucleus Flow
The configuration is flexible. A few of the options are:
With this many options, some tuning (i.e., configuration management) may be required to provide optimal performance and/or resource utilization. In this environment, items such as network capacity planning become very important.
Also, ensure that you have met the hardware and software requirements. See The Personal graPHIGS Programming Interface: Customization and Problem Diagnosis for requirements specific to the gateway function.
After the hardware and software prerequisites are satisfied, the system administrator should use the AIX command smit 5085 to perform some HIA configuration at the gateway node. If this is a new adapter, you must add it as an hia and define:
If you have or are going to install the AIX 3270 Host Connection Program/6000, you should customize the HIA-attached 3270 sessions at this time as well.
This information defines the range of 5080 addresses that the gateway administers. The 5080 channel address is an arbitrary three- or four-digit hex number representing the first IBM S/390 device address assigned to the range. No checking is done on this data, but it is used in assigning connections and is passed to the user when the connection is granted.
The administrator may also want to customize the TCP/IP port number of the gPgated service in /etc/servicesscreen There is a default assignment of 7999 at the time the graPHIGS API API is installed. See "The gPgated TCP/IP Port Number (AIX RS/6000 only)" for more information on the TCP/IP port number. The procedure for customizing the TCP/IP port number is identical to customizing for the graPHIGS API remote nucleus. See The Personal graPHIGS Programming Interface: Customization and Problem Diagnosis for information on customizing for a graPHIGS API remote nucleus.
Once the HIA is configured, the gPgated command may be invoked to start the graPHIGS API gateway daemon. The options for the gPgated command are described in gPgatedscreen
For those administrators who wish to have a fixed GAM address to workstation connection bindings, use the -p option to predefine those connections. Note that a gPhost command must be issued at the user workstation to allow the daemon to communicate with the remote nucleus. You could include this in a shell script that is used to start the graPHIGS API remote nucleus. Under some conditions, a not-ready-to-ready interrupt may be required at the host to invoke a "startup" program. The chgPcon command allows you to do this. For details on the chgPcon command see chgPconscreen gPhost command is defined in section gPhostscreen
The graPHIGS API remote nucleus must be running on the user workstation before communication may be initiated. Use the gPinit command to start a remote nucleus. See gPinit for more information on this command.
If you establish the connection profile entry for this workstation/nucleus configuration before the nucleus is initialized, then you must issue a gPhost command to permit the gateway daemon to transmit data to the nucleus. If you do not issue the gPhost command, then when the application attempts to open the connection, the following message appears:
AFM0208 CONNECTION NOT CURRENTLY PERMITTED FROM THIS HOST TO NUCLEUS 'hostname:0'
See gPhost for more information on this command.
To run a GDDM/graPHIGS API application to a Personal graPHIGS API remote nucleus, ensure that the following items have been completed:
If you encounter problems with this procedure, see the problem determination section in The Personal graPHIGS Programming Interface: Customization and Problem Diagnosis for more information.
To override application nucleus connection defaults, use the graPHIGS API default facilities as described in Chapter 7. "Controlling the Environment with Defaults and Nicknames"screen An example of a graPHIGS API PROFILE entry is:
AFMMDFT DEFNUC=(2, ibmagc) AFMMNICK TOCONNID=connid,TOWSTYPE=nucwstype
Where ibmagc is the DDNAME of the device, connid is the connection identifier which may be * or others, as defined in Chapter 7. "Controlling the Environment with Defaults and Nicknames", and nucwstype is the remote nucleus workstation type desired, e.g., X or CGM. Other parameters are allowed as desired. For example, you can use the XNAME PROCOPT ( see "XNAME (X Default String)") for installation specific information. In the default case where there are no matches in the .Xdefaults file, use XNAME to set the title information for the X-window opened for a created workstation. For example:
PROCOPT=((XNAME,MVS3_YourApplication_YourGRAFaddr))This example puts the string: MVS3_Your application_YourGRAFaddr in the X-window title bar.
| 6095 Users |
|---|
If you are using GDDM/graPHIGS API on the 6095, at this time there are known limitations to function or functional differences that you may encounter. See Chapter 3. "Workstation Description Tables" for these limitations. |
For each connection where a gateway daemon runs, a certain amount of real memory and virtual memory (paging space) is required. A minimum of 128 Kb of real memory and 1024 Kb of paging space should be allocated for each connection. Therefore, a machine with a minimum of 16 Mb of real memory and 32 Mb of paging space is able to support eight connections. In order to support more than eight connections, more paging space is needed and more real memory is needed for optimum performance.
There is an option to allocate more memory to each connection to help buffer outbound data. Depending on the application and IBM S/390 loading, allocating more memory can have a profound effect on elapsed time for large model downloads. This buffer can be considered a speed matching device, or a balloon in the pipeline that allows data to be transmitted to the graPHIGS API remote nucleus as fast as can be accepted. The system administrator may want to use this option as a tuning parameter and trade off reduced model download time against increased real memory and virtual memory requirements.
The lsgPcon command enables the administrator to monitor the progress of data flow through the system. The lsgPcon -S command returns data that is useful in the tuning process. In particular, if paging is invoked on buffers exceeded a large number of times, the administrator might want to use the -b option to increase the buffer size.
gPgated, chgPcon, and lsgPcon must use the same TCP/IP port number when communicating across a TCP/IP network.
The graPHIGS API gateway daemon needs to know on which TCP/IP port number to "listen" for information from chgPcon and lsgPcon commands. Likewise, these commands must know on which TCP/IP port number to send information. The gPgated TCP/IP port number is determined when the graPHIGS API gateway daemon is started by an inquiry to the services database (most commonly represented by the system file /etc/services) for the port number of the gPgated service. If any command fails to find the gPgated service in the services database, a default base port of 7999 is used.
Important Notes:
Purpose
Start a graPHIGS API gateway daemon to allow a GDDM/graPHIGS API shell to communicate with Personal graPHIGS API remote nuclei.
Syntax
------------------ ------------------ --------
| | | | | |
gPgated ---| |---| |---| |-->
-- -ftrfilename -- -- -pprfilename -- -- -w --
------------------ ------------------
| | | |
-->--| |---| |--|
-- -ggatewaynum -- -- -bbuffersize --
OR
------------------
| |
gPgated shutdown ---| |--|
-- -ggatewaynum --
Description
The gPgated command starts a graPHIGS API gateway daemon. This daemon allows a GDDM/graPHIGS API application, using a 5088 or 6098 communications control unit and the GAM connection method, to communicate with Personal graPHIGS API remote nuclei. The daemon process runs on a RS/6000 that has a 5080 Host Interface Adapter (HIA) installed and configured with 5080-type devices enabled. One IBM S/390 device address is required to access each connection to a remote nucleus. Each graPHIGS API gateway daemon can support up to sixteen concurrent connections.
The graPHIGS API gateway daemon is initialized with the specified options, which may assign some connection profile entries. The daemon is then ready to accept changes to the runtime connection profile via the chgPcon command, or configuration inquiries via the lsgPcon command.
The runtime connection profile is a table of entries containing the following information:
See chgPcon for information on establishing the runtime connection profile.
When an entry exists in the runtime connection profile, whether it has been added due to the processing of a chgPcon command, or was defined in the initial configuration file specified by the -p option, the IBM S/390 device address state associated with that entry makes a not-ready-to-ready transition, i.e. comes onlinescreen When execution of the chgPcon command causes an entry to be deleted from the runtime connection profile, the IBM S/390 device address state associated with that entry is set to not-ready, or offlinescreen If an entry is deleted while an application's device is OPEN , then an asynchronous error is generated before the state changes to not-ready to allow the application to terminate.
The runtime connection profile information is recorded in a "warmstart" data file. This data file may be used in the event of a system failure to recover connection profile information. For details, see the -w option described below.
Once the graPHIGS API gateway daemon is running and a runtime connection profile entry is established, a GDDM/graPHIGS API application may attempt to connect to a graPHIGS API remote nucleus by using the GAM connection method.
If gPgated is successful, a series of messages such as the following appear in the transaction file for each configuration file entry:
gPgated: Device address devaddr allocated to hostname:nucidWhere devaddr is an address in the range defined in the HIA configuration, using the AIX command smit 5085, and hostname:nucid is the hostname and nucleus identifier of the target graPHIGS API remote nucleus.
If the -p option is not specified, no messages appear.
See The Personal graPHIGS Programming Interface: Customization and Problem Diagnosis for information on configuring the HIA for the gateway node.
If gPgated is unsuccessful, one of the following messages may appear at the terminal:
AFM1101 NOT ENOUGH STORAGE TO PERFORM REQUESTED FUNCTION AFM1203 FILE SERVICE open ERROR RETURN CODE = 13 ON FILE xxxxx AFM1107 FILE /usr/profile NOT FOUND gPgated: Illegal option option gPgated already started
In these cases, the graPHIGS API gateway daemon terminates.
gPgated is intended to run as a daemon which provides service to users on the network continually. In the event that a reconfiguration needs to take place, or gPgated needs to be stopped, the gPgated shutdown command option causes it to gracefully exit. You must use either root privileges or the same userid that initiated gPgated to run this shutdown command, otherwise, the command is unsuccessful and the following error message occurs:
AFM1201 SYSTEM SERVICE shmct1 ERROR RETURN CODE = 1
Important:
If the gateway daemon terminates or is abnormally ended, you should use the gPgated shutdown command to perform the cleanup that normally occurs upon exit. This ensures normal startup when you next use the gateway daemon.
If you are having problems starting a gateway daemon, refer to the problem determination section of The Personal graPHIGS Programming Interface: Customization and Problem Diagnosis screen
Flags
// Tue May 21 10:23:31 1991 gPgated: GAM address e63 allocated to :0 //
Once initialization is completed, the -ftrfilename flag also causes gPgated to run as a background process.
where hexaddr is the three or four digit hex GAM address to be assigned to the connection, hostname is the internet name of the target host, nucid is the graPHIGS API remote nucleus identifier to connect at the node hostname, and the -b option applies to each entry allowing the system administrator to tailor buffering to individual applications for specific users. See -bbuffersize for the definition of the -b option.
abc5 rover:0 #joes current workstation abc6 rover:0 #joes current workstation #This line is a comment. abc7 :0 #administrators session on local node abc8 stranger:255 #interesting setup abc9 cad:0 -b1024 #1 Meg buffer on this connection abca cad:1 -b0 #But no buffering allowed here
For each target remote nucleus in the file, the graPHIGS API gateway daemon attempts to issue a gPhost command to allow itself access to that nucleus. If the target remote nucleus is not running, the user needs to issue the gPhost command manually after the remote nucleus is started. See the gPhost command for more details. This option is mutually exclusive with the -w option.
| -w | Specifies that the initial configuration file saved during the last execution of gPgated be used to establish new connections, i.e. a"warmstart" screen. It retrieves this data from the file
/tmp/.gP/gPgated.warmstart.data, which is the file that gPgated uses to record the current runtime connection profile.
This option is mutually exclusive with the -p option. |
| -b buffersize | Specifies the size of the internal buffer pool to be used
for each connection.
This buffer is used when the graPHIGS API remote nucleus
consumes data more slowly than the IBM S/390 produces it.
buffersize is a positive decimal number indicating
the number of 1024 byte blocks to use before invocation of
the pacing mechanism.
The default is 256 1024-byte blocks
per connection.
Note: You may need to adjust the paging space when using large buffers. |
| shutdown | Requests that the gateway daemon be gracefully terminated. The session connection profile is saved to be used for a later "warmstart" and applications are notified that open connections are being broken as required. This option is mutually exclusive with all options other than the -g option. |
Examples
gPgated
gPgated shutdown
gPgated -pmyconfig
gPgated -pmyconnections -fmylog
gPgated -w -fmylog
gPgated -w -b64
gPgated -g4
gPgated shutdown -g4
Files
/usr/bin/gPgated /usr/lpp/graPHIGS/bin/gPgated /tmp/.gP/gPgated.warmstart.data0 /tmp/.gP/gPgated.warmstart.data1 /tmp/.gP/gPgated.warmstart.data2 /tmp/.gP/gPgated.warmstart.data3 /tmp/.gP/gPgated.warmstart.data4 /tmp/.gP/gPgated.warmstart.data5 /tmp/.gP/gPgated.warmstart.data0.bak /tmp/.gP/gPgated.warmstart.data1.bak /tmp/.gP/gPgated.warmstart.data2.bak /tmp/.gP/gPgated.warmstart.data3.bak /tmp/.gP/gPgated.warmstart.data4.bak /tmp/.gP/gPgated.warmstart.data5.bak
Related Information
The following commands:
The AIX System Management Information Tool (smit 5085).
The graPHIGS Programming Interface: Messages and Codes screen
Purpose
Add/change/delete a runtime connection profile entry for a graPHIGS API gateway daemon.
Syntax
-- -n:0 ------ -------- ----------------
| | | | | |
chgPcon ---| |---| |---| |-->
-- -n:nucid -- -- -d -- --- -adevaddr --
------------------ --------------
| | | |
-->--| |---| |--|
-- -ggatewaynum -- -- hostname --
Description
This command modifies runtime connection profile entries for the graPHIGS API gateway daemon running on the specified host. If there is an entry for the specified IBM S/390 device address in the runtime connection profile, the entry is changed or deleted. Otherwise, the entry is added.
The command may be used to add or modify an entry such that a connection to an IBM S/390 device address allocated to the gateway may connect to the specified graPHIGS API remote nucleus. The nucleus must reside on the host where the command is issued. At the time the runtime connection profile entry is added, the host on which the graPHIGS API gateway daemon is running is granted access to the local nucleus, so that the gPhost command need not be used.
The command may also be used to delete a runtime connection profile entry.
If chgPcon is successful, the following message appears at the terminal:
gPgated: GAM address devaddr allocated to hostname:nucidWhere devaddr is the IBM S/390 device address used by the GDDM/graPHIGS API application, hostname is the host name of the local workstation and nucid is the nucleus identifier of the remote graPHIGS API nucleus to which the connection will be established.
If chgPcon is unsuccessful, one of the following messages appear at the terminal:
AFM0604 NUCLEUS n1 NOT STARTED OR NOT RESPONDING AFM0616 NO DEVICE ADDRESSES AVAILABLE AFM0617 DEVICE ADDRESS devaddr ALREADY ALLOCATED OR UNAVAILABLE AFM0593 COMMUNICATION ERROR: MAJOR 7 MINOR 73 AFM1101 NOT ENOUGH STORAGE TO PERFORM REQUESTED FUNCTION
If you are having problems running the application, refer to the problem determination section of The Personal graPHIGS Programming Interface: Customization and Problem Diagnosis screen
Flags
| -g:gatewaynum | Specifies the numeric suffix to be appended to the HIA device name that is opened and managed. The default is zero, for example, /dev/hia0 screen |
| -n:nucid | Specifies the nucleus identifier of the graPHIGS API remote nucleus. The default is zero. |
| -d | Deletes the runtime connection profile entry which defines a
connection between the specified remote nucleus and the IBM S/390
device address.
A new runtime connection profile entry for the
IBM S/390 device address may then be added.
If the -d flag is not
specified then an entry is changed or added instead of deleted.
When the -d flag is specified but the -a flag is not specified, then the connection that is dropped is the first one encountered that conforms to the specified parameters. If there are multiple connections that match the specified parameters, then the user should consider using the -a flag unless the specifics of the connection are unimportant. |
| -adevaddr | Requests that a specific GAM address
devaddr be reserved
or dropped according to the flags specified.
If hostname:nucid already has allocated the
address and the
-d option is not specified, then
a reset function is performed.
This reset causes a not-ready-to-ready
interrupt to be received at the IBM S/390 and all internal state
information to be reset for that connection.
The following message occurs:
gPgated: GAM address devaddr reset for hostname: nucid |
| hostname | Specifies the name of the host where the graPHIGS API gateway daemon
is running.
If a hostname is not specified, the default is the local host. |
Examples
chgPcon
chgPcon -n:2
chgPcon gatenode
chgPcon -n:2 gatenode
chgPcon -a13cb -n:2 gatenode
chgPcon -a13cb -n:2 -g3 gatenode
chgPcon -d gatenode
chgPcon -d -n:2 gatenode
chgPcon -d -n:2 -g1 gatenode
chgPcon -d
chgPcon -d -a13cb
Files
/usr/bin/chgPcon
Related Information
gPgatedscreen lsgPconscreen gPhostscreen The graPHIGS Programming Interface: Messages and Codes screen
Purpose
Inquire runtime connection profile information from a graPHIGS API gateway daemon.
Syntax
-- -q --- ------------------ --------------
| | | | | |
lsgPcon ---|one of:|--| |--| |--|
| -q | -- -ggatewaynum -- -- hostname --
| -Q |
| -s |
| -S |
| -r |
| -R |
---------
Description
This command inquires runtime connection profile information from a graPHIGS API gateway daemon running on the specified host.
If lsgPcon is successful, one or more of the following messages appear at the terminal:
devaddr hostname:nucid stateinfoWhere devaddr is the IBM S/390 device address used by the GDDM/graPHIGS API application, and hostname:nucid is the hostname and nucleus identifier of the host where the graPHIGS API gateway daemon is running. stateinfo may be one of the following:
There exists a runtime connection profile entry which defines the connection between the IBM S/390 device address and the graPHIGS API remote nucleus.
The runtime connection profile entry is defined and there is an active connection between the IBM S/390 device address and the graPHIGS API remote nucleus.
If lsgPcon is unsuccessful, one of the following messages appear at the terminal:
AFM0604 NUCLEUS n1 NOT STARTED OR NOT RESPONDING AFM0593 COMMUNICATION ERROR: MAJOR 7 MINOR 73
If you are having problems running the application, refer to the problem determination section of The Personal graPHIGS Programming Interface: Customization and Problem Diagnosis screen
Flags
| hostname | Specifies the hostname of the gateway to which the inquiry will be sent. |
| -g:gatewaynum | Specifies the numeric suffix to be appended to the HIA device name that is opened and managed. The default is zero, for example, /dev/hia0 . |
| -q | Requests the return of the status of those connections allocated to the requesters node at the specified gateway. This is the default option. This option is mutually exclusive with all other options. |
| -Q | Requests the return of the status of all connections at the specified gateway. The default is for the return of only those connections allocated to the requesters node at the specified gateway. This option is mutually exclusive with all other options. |
| -s | Requests the return of the status of those connections allocated to the requesters node at the host where the specified gateway daemon is running (as with the -q option). In addition, requests the return of the I/O statistics associated with those connections. This option is mutually exclusive with all other options. |
| -S | Requests the return of the status of all connections at the host where the specified gateway daemon is running (as with the -Q option). In addition, requests the return of the I/O statistics associated with those connections. This option is mutually exclusive with all other options. |
| -r | Requests the reset of the I/O statistics of those connections allocated to the requesters node at the host where the specified gateway daemon is running. This option is mutually exclusive with all other options. |
| -R | Requests the reset of I/O statistics of all connections at the host where the specified gateway daemon is running. This option is mutually exclusive with all other options. |
Examples
lsgPcon
lsgPcon -Q gatenode
lsgPcon -s
lsgPcon -r
lsgPcon -S gatenode
lsgPcon -S -g1 gatenode
lsgPcon -R gatenode
Files
/usr/bin/lsgPcon
Related Information
gPgatedscreen chgPconscreen The graPHIGS Programming Interface: Messages and Codes screen
The GDDM graPHIGS API provides SOCKETS communication so that an application executing in a VM or MVS environment can connect to a remote graPHIGS nucleus on a supported workstation, such as a RS/6000.
Note: Although the SOCKETS connection method is easier to use than the GAM connection method and provides comparable or better performance, it often consumes more mainframe CPU resources for the same application.
Note: We do not recommend using the SOCKETS connection method on MVS for production purposes. The implementation of TCP/IP Version 2 Release 2 on current MVS systems forces the address space of any application using the SOCKETS connection method to become non-swappablescreen are used then system wide performance will be negatively impacted. The impact will depend on the sizes of the applications and the amount of system memory. This problem does not exist in the VM environment. Furthermore, on current MVS systems, i.e. MVS Versions 2, 3, and 4, use of TCP/IP connections with Version 2 of TCP/IP forces the application address space to become non-swappablescreen are used then system wide performance is negatively impacted. For this reason customers are not encouraged to use the SOCKETS connection method on MVS for production purposes. This is not a problem for applications run in the VM environment.
The SOCKETS connection method for the graPHIGS API requires that the IBM TCP/IP licensed program product be installed and operational on your CPU. The required versions are:
If you want to take advantage of the host name resolution capability, then you need the run time libraries for the IBM C/370 program product. The required version is:
Host name resolution is the ability to specify a host name instead of an IP address when using the Connect to Nucleus (GPCNC) subroutine or specifying the DEFNUC or TONUC options in either the External Defaults File (EDF) or the Application Default Interface Block (ADIB).
To connect to a remote graPHIGS nucleus, an application must supply a nucleus connection specification using the Connect to Nucleus (GPCNC) subroutine specifying the DEFNUC or TONUC options in either the External Defaults File (EDF) or the Application Default Interface Block (ADIB).
For information about GPCNC see The graPHIGS Programming Interface: Subroutine Reference screen For more information about overriding application nucleus connection defaults, see Chapter 7. "Controlling the Environment with Defaults and Nicknames"screen
The specification is defined as <hostname>:<nucleus_id>. There are two ways this can be done, depending on whether you have host name resolution enabled. Generally, enabling host name resolution makes it easier to use. For example, a host called "host1", with internet address "129.40.17.9" is running a remote graPHIGS nucleus with id "0".
If host name resolution is enabled, you can use the following specifications:
AFMMDFT DEFNUC=(3,host1:0) AFMMNICK TOCONNID=host1:0If host name resolution is NOT enabled, you need to use the following specifications:
AFMMDFT DEFNUC=(3,129.40.17.9:0) AFMMNICK TOCONNID=129.40.17.9:0
The following libraries need to be concatenated to the STEPLIB of the job which runs the application to enable host name resolution:
// DD DSN=EDC.SEDCLINK,DISP=SHR // DD DSN=PLI.SIBMLINK,DISP=SHRThese lines should be modified to specify the actual names of your IBM C/370 SEDCLINK and SIBMLINK datasets. Further information on link-editing and running TCP/IP for MVS applications can be found in the IBM TCP/IP for MVS: Programmer's Reference, SC31-6087. Further information on link-editing and running C/370 for MVS applications can be found in the IBM C/370: Programming Guide, SC09-1384.
The AFMZRES MODULE, which was generated by your system programmer as part of the GDDM graPHIGS installation process, must be available (on an accessed disk) for your application while it is executing.
Also, the following libraries need to be GLOBALed when the application is executed (in addition to the graPHIGS API run-time libraries) to enable host name resolution:
GLOBAL TXTLIB COMMTXT IBMLIB EDCBASE GLOBAL LOADLIB EDCLINKFurther information on link-editing and running TCP/IP for VM applications can be found in the IBM TCP/IP for VM: Programmer's Reference, SC31-6084 screen Further information on link-editing and running C/370 for VM applications may be found in the IBM C/370: Programming Guide, SC09-1384 screen
Note: You may be required to use the gPhost command on the target workstation to allow the target nucleus to receive data from the application process.
If an error related directly to the TCP/IP SOCKETS support for the graPHIGS API occurs, the following error will be reported by the graPHIGS API:
AFM0593 COMMUNICATION ERROR: MAJOR 7, MINOR xxxThe MINOR code will generally equate to a TCP/IP "errno" value, as defined in the TCPERRNO file shipped with the TCP/IP program products.
Error codes which are not defined in the TCPERRNO file are generally configuration problems, and should be report to system support personnel, or IBM Support personnel.
See the GDDM graPHIGS program directory for more information on the customization and configuration that must be performed by your system programmer in order to use the SOCKETS connection method.
The graPHIGS/GAM direct connection of the graPHIGS nucleus to 6098 with FDDI feature enables a host graPHIGS API application using GAM to access an AIX workstation and graPHIGS API workstations managed by it. (See The Personal graPHIGS Programming Interface: Customization and Problem Diagnosis for specific hardware and software requirements). The direct connection function provides a high bandwidth, low-cost connection from the GDDM/graPHIGS API shell to a remote nucleus.
Figure 5 is a high-level diagram that represents the components of this configuration using a graPHIGS/GAM direct connection:
Figure 5. graPHIGS/GAM Direct Connection
The configuration is flexible. A few of the options are:
With this many options, some tuning (i.e., configuration management) may be required to provide optimal performance and/or resource utilization. In this environment, items such as network capacity planning become very important.
After the hardware and software prerequisites are satisfied, the system administrator should customize the 6098 with FDDI. Specifically, for users of the mkgPcon command, the system administrator may set up a 6098 configuration parameter called the environment descriptor to help in associating an IBM S/390 device address and a 6098 port number. See mkgPcon and ls6098 for more information on the environment descriptor.
For further information on customizing the 6098 with FDDI feature, see User's Guide for the IBM 6098 FDDI Feature , GA23-2069.
The graPHIGS API remote nucleus must be running on the user workstation before communication may be initiated. Use the gPinit command to start a remote nucleus. See gPinit for more information on this command.
To run a GDDM/graPHIGS API application to a Personal graPHIGS API remote nucleus, ensure that the following items have been completed:
If you encounter problems with this procedure, see the problem determination section in The Personal graPHIGS Programming Interface: Customization and Problem Diagnosis for more information.
To override application nucleus connection defaults, use the graPHIGS API default facilities as described in Chapter 7. "Controlling the Environment with Defaults and Nicknames"screen An example of a graPHIGS API PROFILE entry is:
AFMMDFT DEFNUC=(2, ibmagc) AFMMNICK TOCONNID=connid,TOWSTYPE=nucwstype
Where ibmagc is the DDNAME of the device, connid is the connection identifier which may be * or others, as defined in Chapter 7. "Controlling the Environment with Defaults and Nicknames", and nucwstype is the remote nucleus workstation type desired, e.g., X or CGM. Other parameters are allowed as desired. For example, you can use the XNAME PROCOPT ( in Chapter 7. "Controlling the Environment with Defaults and Nicknames", (See "XNAME (X Default String)") for installation specific information).
In the default case where there are no matches in the .Xdefaults file, use XNAME to set the title information for the X-window opened for a created workstation. For example:
PROCOPT=((XNAME,MVS3_YourApplication_YourGRAFaddr))This example puts the string: MVS3_Your application_YourGRAFaddr in the X-window title bar.
| 6095 Users |
|---|
If you are using GDDM/graPHIGS API on the 6095, at this time there are known limitations to function or functional differences that you may encounter. See Chapter 3. "Workstation Description Tables" for these limitations. |
Purpose
Make a connection to or break a connection from a 6098 with FDDI feature.
Syntax
-- -n:0 ----- ------------------------
| | -------- |one of: |
mkgPcon ---| |---| |---| -a application_name |--- hostname
---n:nucid -- -- -d -- | -o offset |
------------------------
Description
This command makes a connection to or breaks a connection from the 6098 with FDDI feature and provides verification and identification of the requested action.
Making a connection with the 6098 with FDDI feature causes an IBM S/390 device address to be allocated to the specified graPHIGS API remote nucleus. The nucleus must reside on the workstation where the command is issued and be running at the time the mkgPcon command is used. At the time the connection is made, the 6098 with FDDI feature is granted access to the local nucleus, so that the gPhost command need not be used.
This command may also be used to break a single connection. The gPterm command may be used to break all connections to the nucleus.
The IBM S/390 device address that is assigned when a connection is made is a function of:
The first two are controlled by your system programmer and planner. The last is a function of the parameters used on the mkgPcon command and 6098 port availability. There is a one-to-one correlation between 6098 port and channel address. There are up to 256 ports (device addresses) available, and they are referred to by their offset from a configured base port. Thus, the value range of port offsets is 0 to 255 (or 0x0 to 0xff).
The 6098 provides two mechanisms for port assignments:
When you use the mkgPcon command, the hostname parameter determines the 6098 and thus the channel and control unit offset. To determine the S/390 device address, you must add the offset returned by the mkgPcon command to the data provided to you by your system programmer on the channel and control unit offset. There is a 6098 configuration parameter, known as the channel path id, which is a text string that may be set by your administrator to provide that information. It is recommended that the channel path id data be in the form:
CPUname channel_path other_useful_data <base_hex_address>If it is, then mkgPcon parses base_hex_address, performs the addition, and returns the IBM S/390 device address desired. So the manual operation described above is only required if the administrator has not customized the 6098 in the prescribed manner.
The following is an example of input for making a connection:
mkgPcon -a'FPGP TESTING USAGE' w20
If mkgPcon is successful, the following message appears at the terminal:
mkgPcon: Attempting connection on port 8
Then one of the following messages appears:
EITHER
mkgPcon: Host 'w20' accepted connection on port 8
OR
mkgPcon: Host 'w20' accepted connection on device address 19A2
If mkgPcon is unsuccessful, one of the following messages appear at the terminal:
AFM0604 NUCLEUS n1 NOT STARTED OR NOT RESPONDING AFM0593 COMMUNICATION ERROR: MAJOR 7 MINOR 73 AFM0640 UNKNOWN HOST 'w20' AFM0641 HOST 'w20' NOT RESPONDING AFM0642 HOST 'w20' IS NOT AN IBM 6098 W/FDDI FEATURE AFM0643 HOST 'w20' HAS NO FREE 'FPGP TESTING USAGE' PORTS AFM0644 HOST 'w20' DID NOT ACCEPT THE CONNECTION AS SPECIFIED AFM0646 HOST 'w20' HAS NO CONNECTION AS SPECIFIED TO BE DELETED AFM0645 RPC FUNCTION get base port FAILED FOR APPLICATION 'TEST123' ON PORT 36 AFM1201 SYSTEM SERVICE read ERROR RETURN CODE = 73
If you are having problems running the application, refer to the problem determination section of The Personal graPHIGS Programming Interface: Customization and Problem Diagnosis screen
Flags
| -n:nucid | Specifies the nucleus identifier of the graPHIGS API remote nucleus. The default is zero. |
| -d | Deletes the connection between the specified remote nucleus and the IBM S/390 device address. A new connection for the IBM S/390 device address may then be added. |
| -a | Defines the port number selection by application namescreen
The application name is an arbitrary string of up to 31
characters.
When using blank characters within an application name,
enclose the application
name in quotes, for example:
'FPGP TESTING USAGE' |
| -o | Defines the port number selection by offset from base.
This parameter may be entered in any of three forms: octal,
hexidecimal, or decimal. Using the standard notation:
|
| hostname | A required parameter that specifies the name or IP address of the 6098 with FDDI feature. |
Examples
mkgPcon hostname
mkgPcon -n:2 hostname
mkgPcon -o0xfe -n:2 hostname
mkgPcon -atesting123 hostname
mkgPcon -d hostname
mkgPcon -d -n:2 hostname
mkgPcon -d -o0xfe hostname
mkgPcon -d -atesting123 hostname
Files
/usr/bin/mkgPcon
Related Information
ls6098screen Chapter 4. "The graPHIGS API Nucleus"screen The graPHIGS Programming Interface: Messages and Codes screen
Purpose
Inquire connection information for the 6098 with FDDI feature.
Syntax
ls6098 hostname
Description
This command inquires connection information of a 6098 with FDDI feature called hostnamescreen
The following is an example of input for making an inquiry about connection information for a 6098 with FDDI feature:
ls6098 w20
where w20 is the hostname.
If ls6098 is successful, messages like the following appear at the terminal:
IBM 6098 named 'w20' returns descriptor 'KGNVMP: LAB: CHPID 19: w20' Application Name Starting Port,Number of Ports,State FPGP TESTING USAGE 0008 0008 NOTBUSYwhere KGNVMP: LAB: CHPID 19: w20 is the environment descriptor or location of the 6098 with FDDI feature.
If ls6098 is unsuccessful, one of the following messages appear at the terminal:
AFM0593 COMMUNICATION ERROR: MAJOR 7 MINOR 73 AFM0640 UNKNOWN HOST 'w20' AFM0641 HOST 'w20' NOT RESPONDING AFM0642 HOST 'w20' IS NOT AN IBM 6098 W/FDDI FEATURE AFM1201 SYSTEM SERVICE read ERROR RETURN CODE = 73
Flags
Examples
ls6098 hostname
Files
/usr/bin/ls6098
Related Information
mkgPconscreen The graPHIGS Programming Interface: Messages and Codes screen