[ Previous | Next | Contents | Glossary | Home | Search ]
The graPHIGS Programming Interface: Technical Reference

Chapter 4. The graPHIGS API Nucleus

Connecting to the Nucleus

Version 2 of the graPHIGS API separates the application interface functions from the graphic management functions by introducing the concept of a shell and a nucleus. The shell is a subroutine library that is part of the application process. It accepts the call from the application, checks the parameters, and transmits the request to the nucleus.

The nucleus receives and processes requests from the application process. A graPHIGS API nucleus controls resources that are created by the application process. These resources include workstations (represented by a workstation state list), structure stores (represented by a structure store state list), image boards, and font directories. The requests sent to the nucleus are directed to one of these resources controlled by the nucleus.

All releases of the graPHIGS API on AIX follow the Version 2 architecture. For Version 2 of the graPHIGS API, a nucleus may reside in any of three environments:

Before your application's request can be sent to a specific nucleus for processing, the application process must connect to that nucleus. Connecting to a nucleus involves selecting a connection method supported by the nucleus and a corresponding nucleus connection specification. Connection methods and connection specifications are selected by explicitly issuing a Connect to Nucleus subroutine call (GPCNC) and/or by specifying a default option (DEFNUC) in either the External Defaults File (EDF) or the Application Default Interface Block (ADIB). The specified connection method and specification can also be controlled through use of the TONUC default option. See Chapter 4, "The graPHIGS API Nucleus," in The graPHIGS Programming Interface: Understanding Concepts for more information about connecting to a nucleus.

Managing the graPHIGS API Nucleus in AIX

In the AIX environment, a remote graPHIGS API nucleus must have been explicitly started before the application attempts connection to it. The graPHIGS API install procedures provide commands to start the nucleus as a process, manage access to it, and to terminate the process and free up the resources at the close of the application. Errors from these procedures do not go to the standard error path but rather return through the application shells as graPHIGS API messages.

Each command has an associated shell script which supplies default values to it. You may modify the scripts to add additional parameters, tailoring them to start customized environments.

The Remote graPHIGS API Nucleus's TCP/IP Port Number (AIX RS/6000 only)

In order for an application to communicate via the SOCKETS connection method (TCP/IP) to a remote graPHIGS API nucleus, the graPHIGS API shell, which is linked with the application, must know the name of the host on which the graPHIGS API nucleus is running and the TCP/IP port number, on which the graPHIGS API nucleus is "listening" for connections. The hostname is provided as the first part of the connection specification when the host connects to the nucleus. The TCP/IP port number must be determined at run time.

The remote graPHIGS API nucleus, when started (with the gPinit command), needs to know on which TCP/IP port number to "listen" for connections from graPHIGS API shells.

The TCP/IP port number is determined by adding the nucleus connection number of the target remote graPHIGS API nucleus and the base port number as defined in the system file /etc/servicesscreen The default base port number is 8000.

Important Notes:

  1. The remote graPHIGS API nucleus uses the /etc/services file on the same host on which it is started. The graPHIGS API shell uses the /etc/services file on which the application is running. Therefore, it is mandatory that the base port number, as defined in the /etc/services file on each host, is the same for all hosts which use the remote graPHIGS API nuclei.
  2. The use of a hostname alias to direct routing over redundant networks may result in refused connections because the graPHIGS API remote nucleus and gPgated authorize access by hostname. When the gPhost or the chgPcon command is issued, the target hostname must match the hostname configured on the target host.
  3. The user should be aware of potential conflicts with other services defined in /etc/servicesscreen Remote graPHIGS API nuclei with identification numbers of 0 through 255 will attempt to use TCP/IP port numbers 8000 through 8255, respectively, although only the base port number of 8000 will be reserved in /etc/servicesscreen

gPafut

Purpose

Recover an archive file that has been left in an incomplete state.

Syntax

 
 
         ---------------  ---------------
         |             |  |             |
gPafut --|             |--|             |--|
         -- -r fdesc1 --  -- -o fdesc2 --

Description

The gPafut command recovers the data in a specified archive file so that the archive file is usable by the graPHIGS APIscreen An archive file can be left in an unusable state when the application updating it (by archiving structures to the file or deleting structures from the file) terminates abnormally. If the archive file is incomplete, then the application receives one of two messages: 1110 CONCURRENT USAGE OF FILE a2 NOT ALLOWED (because it appears that another application has already opened the file) or 1205 FILE IS NOT A VALID graPHIGS ARCHIVE FILE (because various fields are set incorrectly ).

Two options are available for use with the gPafut command:

-r
specifies the recover option. The data in the archive file identified by fdesc1 is recovered.
-o
specifies the output option. The data in the archive file identified by fdesc1 is placed in the file identified by fdesc2 screen

fdesc1 and fdesc2 identify archive files with the following information:

gPinit

Purpose

Starts a remote graPHIGS API nucleus.

Syntax

         -- -n:0 ------   -- -s10 -----   --------- 
         |            |   |           |   |       |
gPinit --|            |---|           |---|       |-->                              
         -- -n:nucid --   -- -snserv --   -- -ti -- 
 
         -- -IAFMTRACE.NUC --   ---- -w10 ------   -----------
         |                  |   |              |   |         |
    -->--|                  |---|              |---|         |-->                            
         -- -Itrfilename ----   -- -c:display --   -- -wnwks -
 
         ---------   -- -p/tmp/.gP ---   ----------
         |       |   |               |   |        |
    -->--|       |   |               |   |        |--|                  
         -- -a ---   -- -pdappath ----   -- -r5 ---

Description

The gPinit command starts a remote graPHIGS API nucleus as a separate process named gP. The nucleus is initialized with the default state list and resource stores. It is then ready to accept connections from applications/graPHIGS API shells which connect to a remote nucleus and use this nucleus as the connection specification.

The connection specification that should be used to connect to this nucleus is:

  [hostname]:nucid

If gPinit is unsuccessful, the following message will appear at the terminal:

  AFM605 gP IS UNABLE TO START A REMOTE NUCLEUS

If unable to easily determine the cause for the failure, invoke gPq with the nucleus ID that you intended to use:

gPq -n:nucid

If gPq returns the process ID of an active nucleus, you have tried to start a nucleus with an identifier that is already in use. You must either terminate that active nucleus, or simply have your application connect to the active nucleus.

If gPq does not return the process ID of an active nucleus, the previous nucleus with the same identifier may not have terminated normally. To allow starting up another nucleus with the same identifier, issue gPterm with the same identifier:

gPterm -n:nucid

gPinit should now be able to start a nucleus with that identifier.

Flags

-n:nucid
Specifies the numeric identification of this remote graPHIGS API nucleus. This number is used in the connection specification used by the application when connecting to this nucleus. The default is 0.
-snserv
Defines the maximum number of X workstation servers to which this nucleus will be able to connect. The default is 10.
-ti
Enables internal trace. SeeThe Personal graPHIGS Programming Interface: Installation and Problem Diagnosis screen
-Itrfilename
Specifies the internal trace path name. The default is AFMTRACE.NUC.
-c:display
Forces the nucleus to act in conjunction with the specified X workstation server operating on the same host as the nucleus. See the following description of the gPhost command.
-w:nwks
Defines the maximum number of graPHIGS API workstations that may be associated to a single structure store. The default is ten. See Chapter 7. "Controlling the Environment with Defaults and Nicknames" for more information.
-a
Enables the nucleus for DAP execution when the nucleus is started. The default is that the nucleus is not enabled for DAP execution.
-pdappath
Specifies the AIX file path for the temporary storage of downloaded DAP files. The default AIX file path is /tmp/.gP
-r5
Specifies that the DAP to be executed should run as an X11R5 client. The default is that the DAP would run as an X11R6 client. This new option is especially useful for DAPs that depend on X11R5 functionality which no longer exists in X11R6; that is, XAsyncInput().

If the following message is observed while running an X11R5 DAP, then restart the graPHIGS remote nucleus by adding the -r5 option to the gPinit command:

"WARNING: The XAsyncInput API is no longer implemented in X11R6."

Examples

  1. To start a remote graPHIGS API nucleus running with an identification number of 0, with the current directory as its working directory: 
    gPinit
  2. To start a remote graPHIGS API nucleus running with an identification number of 10, running in conjunction with an X server number 0, with the current directory as its working directory: 
    gPinit -n:10 -c:0
  3. To start a remote graPHIGS API nucleus running with an identification number of 0, with the current directory as its working directory, and increase the number of servers to which it is able to connect to 20: 
    gPinit -s20

Files

/usr/bin/gPinit
/usr/lpp/graPHIGS/bin/gP

Related Information

The following commands:

gPhost, gPq, gPterm, and makegP (AIX PS/2 only)screen

gPhost

Purpose

Changes the access security handling characteristics for a remote nucleus.

Syntax

         -- -n:0 ------   -------------------------   
         |            |   |      --------------   |
gPhost---|            |---|      |            |   |-->                       
         -- -n:nucid --   -------|            |----
                             ^   -- hostname --  |
                             |                   |
                             |-------------------|
        -------  ---------------
        |     |  |             |
   -->--|     |--|             |-->           
        -- + --  -- hostname ---

Description

This command adds or deletes hosts from the access list maintained by the specified nucleus, or displays the current access list for the specified nucleus. gPhost may also be used to disable or enable host access checking. The nucleus must reside on the same host as where the command is issued.

Entering gPhost with no arguments, other than a -n, displays the current host access list for the specified nucleus.

If the specified nucleus was started and defined to run in conjunction with an X server (via gPinit with the -c flag), the server's security characteristics will be used in addition to whatever characteristics are defined for the nucleus. In this case, any host which is permitted to access the server will be allowed to access the nucleus.

The default access list for a remote nucleus is only the current host. To allow an application running on another host to connect to the specified nucleus, the other host must be on the access list of the nucleus, or access checking must be disabled.

Additional hosts may be added to the default host access list by creating the file /etc/gP?screen (the? is the identifier of the nucleus for which to enable access).

Entering gPhost with a + or a - as a flag by itself will disable or enable, respectively, host access checking for the specified nucleus.

If an application attempts to connect to a remote nucleus from a host which is not on the nucleus' host access list, the application will receive the graPHIGS API error number 208screen

Flags

-n:nucid
Specifies the numeric identification of the remote graPHIGS API nucleus. The default is 0.
-hostname
Deletes the hostname from the access list of the specified nucleus. If no host name follows the -, host access checking is disabled.
+hostname
Adds the hostname to the access list of the specified nucleus. If no host name follows the +, host access checking is enabled. The + is optional; if a hostname is specified alone, it will be added to the access list.

Examples

  1. To display the current host access list for the nucleus whose identification number is 2: 
    gPhost -n:2
  2. To disable access checking for the nucleus whose identification is 1: 
    gPhost -n:1 +
  3. To add the hosts named 'xyz' and 'abc' to the access list for the nucleus whose identification is 0: 
    gPhost +xyz +abc

Files

/usr/bin/gPhost
/usr/lpp/graPHIGS/bin/gphost
/etc/gP
?screen

Related Information

gPinitscreen The AIXWindows User's Guide screen The The graPHIGS Programming Interface: Messages and Codes screen

gPq

Purpose

Inquire information about remote graPHIGS API nuclei.

Syntax

       --------------------
       |                  |
gPq ---|                  |                   
       --- -n:nucid ------- 
        ^                |
        |----------------|

Description

This command is intended to provide the user with a means of determining the state of remote graPHIGS API nuclei.

Issuing gPq with no arguments will display a list of all currently active nuclei running on the same host where the command is issued. The list consists of the nucleus' name followed by the process ID of the nucleus.

If one or more nucleus identifiers are specified, a list containing each specified nucleus ID and its process ID is displayed. If information for a nucleus associated with a particular identifier could not be found, message "AFM0604" will be displayed instead of the process ID. If a specified nucleus that was thought to be active was deemed "Not Active", try gPq again. If the nucleus is still "Not Active", it may be in some error state and should probably be terminated.

Flags

-n:nucid
Specifies the numeric identification of the remote graPHIGS API nucleus to query.

Examples

  1. To display a list of all active remote graPHIGS API nuclei on the user's system: 
    gPq
  2. To display information about nuclei with identification numbers 0, 1, and 10: 
    gPq -n:0 -n:1 -n:10

Files

/usr/bin/gPq
/usr/lpp/graPHIGS/bin/gpq

Related Information

The following commands:

gPinit,
gPtermscreen

gPterm

Purpose

Terminates the specified remote graPHIGS API nucleus.

Syntax

          -- -n:0 -------
          |             |
gPterm ---|             |  
          -- -n:nucid ---

Description

This command will stop the nucleus and release resources back to the operating system. The command must be issued from the same host as where the nucleus was started.

This command will also release resources held by a nucleus which terminated abnormally.

Flags

-n:nucid
Specifies the numeric identification of the remote graPHIGS API nucleus. The default is 0.

Files

/usr/bin/gPterm
/usr/lpp/graPHIGS/bin/gpterm

Related Information

gPinitscreen

makegP (AIX PS/2 only)

Purpose

Relinks the remote graPHIGS API nucleus. This command is not provided in graPHIGS API on the RS/6000.

Syntax

makegP

Description

This command relinks the remote graPHIGS API nucleus, allowing the end user to change which workstations the nucleus will support. To use makegP, you must be a member of the system group or have superuser authority. Be sure there are no remote graPHIGS nuclei active.

makegP is an interactive, menu-driven program.

Files

/usr/bin/makegP
/usr/lpp/graPHIGS/bin/gP
/usr/lpp/graPHIGS/bin/gP.o
/usr/lpp/graPHIGS/bin/gPAPA.o
/usr/lpp/graPHIGS/bin/gPAPAGDF.o
/usr/lpp/graPHIGS/bin/gPNOWS.o
/usr/lpp/graPHIGS/bin/gPX.o
/usr/lpp/graPHIGS/bin/gPXGDF.o
/usr/lib/libgP.a

Related Information

The AIX PS/2 Personal graPHIGS Programming Interface: Installation and Problem Diagnosis screen

The Nucleus Description Table

The Nucleus Description Table contains configuration information for a graPHIGS API nucleus. The values in the NDT are provided by and initialized by the system. Inquiries to an NDT return information about a nucleus' default values and general characteristics.

Table 90. Nucleus Facilities

Nucleus Facilities Data Type 6090 Values S/390 Values AIX Values Inquiry
Nucleus storage size I n bytes No limit1 No limit1 GPQNCS [size]
Note: 1 "No limit" returns a 0 on the inquiry.

Table 91. Nucleus Description Table for Workstation

Workstation Facilities Data Type 6090 Values S/390 Values AIX Values Inquiry
Maximum number of simultaneously opened workstations I 1 No limit1 No limit1 N/A
Number of available generic workstation types I 1 3 9 GPQWTN [totnum]
Available generic workstation types S '6090 ' '5080 ' 'GDDM ' 'GDF ' 'X ' 'GDF ' 'CGM ' 'XLIB ' 'XDWA ' 'NATIVE ' 'XPEX ' 'XSOFT ' 'IMAGE ' GPQWTN [wstype]
Note: 1 "No limit" returns a 0 on the inquiry.

Table 92. Nucleus Description Table for Structure Store

Structure Store Facilities Data Type 6090 Values S/390 Values AIX Values Inquiry
Maximum number of simultaneously existing structure stores I 1 No limit1 No limit1 N/A
Maximum number of simultaneously associated workstations I 1 4 322 GPQWTN [maxa]
Number of available structure store types I 1 1 1 N/A
Available structure store types (NORMAL ) E NORMAL NORMAL NORMAL N/A
Note: 1 "No limit" returns a 0 on the inquiry.

2 See "MAXWKS (Maximum Workstation Support)" for more details.


Table 93. Nucleus Description Table for Image Board

Image Board Facilities Data Type 6090 Values S/390 Values AIX Values Inquiry
Maximum number of simultaneously existing image boards I No limit1 N/A No limit1 N/A
Maximum number of simultaneously associated workstations I 1 N/A No limit1 N/A
Number of available image board types I 1 N/A 1 N/A
Available image board types (NORMAL ) E NORMAL N/A NORMAL N/A
Maximum image board size 2[default]I No limit1 N/A No limit1 GPQIBF [n,v]
Number of available image board bit depths I 5 N/A 5 GPQIBF [totnum]
Available image board bit depths (bit depth 1, 2, 4, 8, 12) E 1, 2, 4, 8, 12 N/A 1, 2, 4, 8, 12 GPQIBF [depth]
Number of available two-operand pixel operations I 1 N/A 1 GPQPO [totnum]
List of available two-operand pixel operations (REFLECTION) E REFLECTION N/A REFLECTION GPQPO [op]
Number of available three-operand pixel operations I 2 N/A 2 GPQPO [totnum]
List of available three-operand pixel operations (LOGICAL OPERATION, ARITHMETIC OPERATION) E LOGICAL OPERATION, ARITHMETIC OPERATION N/A LOGICAL OPERATION, ARITHMETIC OPERATION GPQPO [op]
Number of available pixel data formats I 1 N/A 1 N/A
Available pixel data formats (PIXEL ARRAY) E PIXEL ARRAY N/A PIXEL ARRAY N/A
Note: 1 "No limit" returns a 0 on the inquiry.

Table 94. Nucleus Description Table for Font Directory

Font Directory Facilities Data Type 6090 Values S/390 Values AIX Values Inquiry
Maximum number of simultaneously existing font directories I 1 No limit1 No limit1 N/A
Maximum number of simultaneously associated workstations I 1 No limit1 No limit1 N/A
Number of available font directory types I 1 1 1 N/A
Available font directory types (NORMAL ) E NORMAL NORMAL NORMAL N/A
Note: 1 "No limit" returns a 0 on the inquiry.

Table 95. Nucleus Description Table for Application Region

Application Region Facilities Data Type 6090 Values S/390 Values AIX Values Inquiry
Maximum number of simultaneously defined application regions1 I No limit2 N/A N/A N/A
Note: 1 The 6090 workstation supports as many application regions as storage is available. However, only up to three of the distributed applications may connect to the 6090 nucleus at any one time.

2 "No limit" returns a 0 on the inquiry.

[ Previous | Next | Contents | Glossary | Home | Search ]