graPHIGS Programming Interface: Subroutine Reference

The graPHIGS Programming Interface : Subroutine Reference

GPCNC - Connect Nucleus

GPCNC (ncid, conn, len, spec)

Purpose

Use GPCNC to establish access to a nucleus from your application. The nucleus allows your application to access resources, such as a workstation and a structure store, for graphics processing.

This subroutine must be invoked in order to communicate with a nucleus. Your application may choose to invoke this subroutine or have the graPHIGS API invoke this subroutine for your application as part of nucleus connection processing

When the graPHIGS API performs nucleus connection processing, it connects to a nucleus (GPCNC) with an identifier set to a value of one, creates a structure store (GPCRSS) with an identifier set to a value of one, and selects that structure store (GPSSS) for editing. This may be done as follows:

If your application is using any workstation except the 6090 workstation, and you want the graPHIGS API to invoke this subroutine for your application as part of nucleus connection processing, then you do not need to do anything additional. When your application executes an Open graPHIGS (GPOPPH) subroutine, the application connects to a nucleus with an identifier set to a value of one, using the 1=CALL connection method.
If your application is using the 6090 workstation, and you want the graPHIGS API to invoke this subroutine for your application as part of nucleus connection processing, then you must use the Define Nucleus Connection Processing (DEFNUC) procopt default in either the Application Defaults Interface Block (ADIB) or the External Default File (EDF) to indicate this.
If you want your application to invoke this subroutine explicitly, then you must use the Define Nucleus Connection Processing (DEFNUC) procopt default in either the Application Defaults Interface Block (ADIB) or the External Defaults File (EDF) to suppress the graPHIGS API from invoking the connect to nucleus as part of nucleus connection processing (If your application is a distributed application process [DAP], then it is not necessary to suppress nucleus connection processing

For information about nucleus connection, see The graPHIGS Programming Interface: Understanding Concepts

For the available nucleus connection methods, connection specifications, and information concerning Application Defaults Interface Block (ADIB) and External Defaults File (EDF), see The graPHIGS Programming Interface: Technical Reference

Parameters

ncid -- specified by user, fullword integer

Nucleus identifier.

conn -- specified by user, fullword integer

Connection method (1=CALL, 2=GAM, 3=SOCKETS ) GAM stands for Graphics Access Method and is the connection method used with the IBM 6090 Graphics System Access.

The connection methods that are supported for each combination of nucleus and application environments are summarized in the following table:

Figure 1. Nucleus/Application Environment

                             Application Environment
 
                         VM      MVS       AIX     6090
                      -------------------------------------
                      |       |       |         |         |
                  VM  | CALL  |  N/A  |   N/A   |   N/A   |
                      |-----------------------------------|
                      |       |       |         |         |
Nucleus          MVS  |  N/A  | CALL  |   N/A   |   N/A   |
Environment           |-----------------------------------|
                      |       |       | CALL or |         |
                 AIX  |  N/A  |  N/A  | SOCKETS |   N/A   |
                      |-----------------------------------|
                      |       |       |         |         |
                6090  |  GAM  |  GAM  |   N/A   | SOCKETS |
                      -------------------------------------

N/A

Not a valid combination

len -- specified by user, fullword integer

Length of the nucleus connection specification.

spec -- specified by user, variable length character string

Connection specification. The required nucleus specification string for each connection method and application environment is summarized in the following table:

Figure 2. Application Environment/Connection Method

                                Connection Method
 
                        1=CALL        2=GAM      3=SOCKETS
                    ------------------------------------------
                    |    Null     |  Filedef   |             |
                 VM |(length = 0) |(length =>8)|      N/A    |
                    |----------------------------------------|
                    |    Null     |   DDNAME   |             |
Application     MVS |(length = 0) |(length =>8)|      N/A    |
Environment         |----------------------------------------|
                    |    Null     |    N/A     |  Nucspec*   |
                AIX |(length = 0) |            |(length >= 2)|
                    |----------------------------------------|
                    |     N/A     |    N/A     |     :0      |
               6090 |             |            |(length = 2) |
                    ------------------------------------------

N/A

Not a valid combination

Nucspec is set to the following specification:
hostname: nucleus connection number
where:

hostname specifies the host name of the system where
the remote graPHIGS API nucleus is running.
nucleus connection number specifies the identifier of
the nucleus on the named system and is a number in
the range 0-255.

Error Codes

201: SPECIFIED NUCLEUS IDENTIFIER ALREADY IS IN USE
203: SPECIFIED CONNECTION METHOD IS NOT SUPPORTED
204: NUCLEUS CONNECTION FAILED
208: CONNECTION NOT CURRENTLY PERMITTED FROM THIS HOST

Related Subroutines

GPDNC: Disconnect Nucleus
GPQCMM: Inquire List of Available Connection Methods
GPQCNC: Inquire List of Connected Nuclei
GPQNS: Inquire Nucleus Specification
GPQSH: Inquire Shell Identifier

RCP code

201337601 (X'0C002B01')