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

Chapter 7. Controlling the Environment with Defaults and Nicknames

This chapter provides information about defaults and nicknames. It also provides information about processing options (PROCOPTs). Use this information to modify aspects of your environment to suit the needs of your applications.

Overview of Controlling the Environment

In the graPHIGS API system and workstation environment, certain fields (sizes, names, options, etc.) are given preset values by the graPHIGS APIscreen In some instances, these preset values may not suit the needs of the application. The graPHIGS API allows the programmer or end user to change these preset values through defaults and nicknames. Defaults are intended to modify the system environment values, while nicknames are intended to modify values associated with a particular workstation environment.

Changes can be made in two ways:

Defaults allow you to change the system environment. You can control the trace state, direct trace output, adjust the size of the in-core trace table, set input and output buffer and queue sizes, define nucleus connection processing, and inhibit shell syntax checking.

If the same nickname or default value is specified in both an ADIB and an EDF, the EDF value will be ignored and the ADIB value will be used. Because the ADIB has higher priority than the EDF, the application programmer can control the user's environment. The only exception to this rule is the trace control word-- the trace control word itself determines priorities. (Trace priorities are discussed in The graPHIGS Programming Interface: Writing Applications )

Processing of the defaults and nicknames specified through an EDF and/or an ADIB occurs during Open graPHIGS processing.

Nicknames allow you to change workstation environment values. The nickname values associated with a workstation environment are referred to as processing options or PROCOPTS. Nicknames also allow you to change the workstation type (wstype) and connection identifier (connid) parameters specified on the Open Workstation (GPOPWS) and Create Workstation (GPCRWS) subroutines.

If the same nickname is specified in both an ADIB and an EDF, the API resolves the nickname using first the EDF values followed by the ADIB values. Any PROCOPTs included on the selected nicknames are merged with any PROCOPTs specified on the GPCRWS subroutine to produce a final PROCOPT list. See "How The graPHIGS API Processes Nicknames" for a discussion of this processing.

The remainder of this chapter explains how defaults and nicknames are processed, the format of an EDF specification, the format of an ADIB specification, and the explanation and syntax of each default, nickname, and PROCOPT.

The following table compares the EDF and ADIB.

Table 96. Comparison of EDF and ADIB

Name Description Limitations Priority
External Defaults File (EDF) A file for users to modify their environment Not valid for applications running locally on a 6090 in a DAP environment. Each default or nickname value is in effect only if no ADIB value exists.
Application Defaults Interface Block (ADIB) A control block area passed as a parameter by the application program To change defaults, you must re-compile or re-build your program Overrides EDF (except for Trace setting in the EDF)

The External Defaults File (EDF)

The External Defaults File contains records which consist of User-Defined Specifications (UDSs). The UDSs in this file allow you to change user default options at run-time without re-compiling or re-building your application. The API accesses the External Defaults File as follows:

AIX
The file must be named PROFILE or must be specified in the gPPROFILE environment variable. When the GPOPPH subroutine is called, or when a remote graPHIGS API nucleus is started, the graPHIGS API searches for a PROFILE in this order:
  1. gPPROFILE environmental variable

    The gPPROFILE environment variable allows you to specify an alternate filename, or an alternate directory path containing the file, PROFILE, as the external defaults file.

    If the gPPROFILE environmental variable is defined as a valid file name, then that file is used as the External Defaults File. If the gPPROFILE environmental variable is defined as a valid directory name, then that directory is searched for a file named PROFILE. If this file is found, then it is used as the External Defaults File.

    If the gPPROFILE environmental variable is not defined, is defined with an invalid file name or directory name, or there is no file named PROFILE in the defined valid directory name, the search continues.

    For more information on setting environment variables, see the AIX Commands Reference for IBM RS/6000 screen

  2. Current directory

    The current directory is searched for a file named PROFILE. If there is no file named PROFILE in the current directory, the search continues.

  3. /usr/lpp/graPHIGS/etc directory

    The graPHIGS API provides a sample External Defaults File as /usr/lpp/graPHIGS/etc/PROFILEscreen

MVS
AFMDEFS must be the DDNAME used to allocate the sequential data set containing the default information. The file must be F- or V- format, with an LRECL of no greater than 256. The recommended format is F(80).
VM
The file must be named PROFILE , have a filetype of AFMDEFS , and be on a currently-accessed disk when the application calls Open graPHIGS (GPOPPH).

Format of the User-Defined Specification (UDS)

A UDS is a string that can be up to 32,000 characters long. Use one of the following forms for a record in the graPHIGS API External Defaults File:


[label]   UDS-type   UDS-value   [ OPTIONAL COMMENTS ]


[label]  UDS-type UDS-value-part1,  [ OPTIONAL COMMENTS ]
                  UDS-value-part2,  [ OPTIONAL COMMENTS ]
                  UDS-value-part3,  [ OPTIONAL COMMENTS ]
                         screen
                  UDS-value-partn,  [ OPTIONAL COMMENTS ]


* COMMENT TEXT

The UDS-type parameter is one of the following:

AFMMDFT or DEFAULT
- a default value
AFMMNICK or NICKNAME
- a nickname value

The UDS value is specified as keyword=specified_value screen If you specify a keyword with nothing after the equal sign (=), the current value is not changed.

Valid default and nickname keywords and values are given with a description of each default or nickname in the following sections.

Records in the External Defaults File must conform to Assembler-like coding conventions. When specifying a UDS, you must observe the following conventions:

The Application Defaults Interface Block (ADIB)

The Application Defaults Interface Block (ADIB) is the second method for the application programmer to specify defaults and nicknames. The ADIB takes priority over any defaults or nicknames specified also in an External Defaults File (EDF), except possibly the Trace default.

The application must specify the ADIB as the second parameter on the Open graPHIGS (GPOPPH) subroutine. If you don't specify any ADIB options, set the GPOPPH parameter to zero.

Format of the ADIB

The ADIB consists of a fullword integer specifying the ADIB length, followed by any number of Application Default Specifications (ADS). When you specify the value of the length fields in bytes, include the length fields themselves.

This is the format of an ADIB with its ADS:

Figure 8. Format of ADIB and ADS


---------------------------
| Total length of ADIB    | Fullword integer
---------------------------\
|                         | \
|        ADS # 1          |  \
|                         |   \---------------------------
|                         |    | Total length of ADS     | Fullword integer
---------------------------\   ---------------------------
|                         | \  | ADS code (type of ADS)  | Fullword integer
|        ADS # 2          |  \ ---------------------------
|                         |   \|       ADS data          | Variable length
|                         |    ---------------------------
---------------------------
/                         /
/                         /
---------------------------
|                         |
|        ADS # n          |
|                         |
|                         |
---------------------------

The ADS code identifies the type of ADS. The ADS data is a variable length field and is dependent on the type of ADS.

Defaults

Defaults allow the application programmer or end user to modify the preset values of the graPHIGS API system environment. Following are the default descriptions and their syntax as set through an EDF or an ADIB.

AIXTRCE (AIX Trace Output)

This default directs trace output from the API on the AIX system. It is specified as a string of up to 50 characters that indicates the file path, followed by two 8-character strings that specify a filename and file extension.

Initial Preset Value

the filename AFMTRACE within the current working path.

EDF

To specify this default through an EDF, the correct syntax is:

     AFMMDFT AIXTRCE=(aaa...a,bbbbbbbb,cccccccc)
aaa...a is the file path, bbbbbbbb is the filename and cccccccc is the file extension for trace output.

If you specify no values between commas, for example: AFMMDFT AIXTRCE=,, the values are set to nulls (file path='', file name='', file extension='').

ADIB

To specify this default through an ADIB, the correct structure is:

-------------------------------------
| Total length of ADS (greater      | Fullword integer
| than 8, but a fullword multiple)  |
-------------------------------------
| ADS code = 603                    | Fullword integer
-------------------------------------
| Fully-qualified filename          | Variable-length character string
-------------------------------------

ARCHIVE (File Descriptors)

This default directs the output of an Open Archive File (GPOPAR) subroutine. A From file descriptor and a To file descriptor are specified.

EDF

To specify this default through an EDF, the correct syntax is:

        AFMMDFT ARCHIVE=(aaa...a,bbb...b,)
aaa...a is the From archive file descriptor used in the Open Archive File (GPOPAR) subroutine, bbb...b is the To archive file descriptor to be used instead. Specify both file descriptors with no blanks, but include a comma before closing the parenthesis. Refer to The graPHIGS Programming Interface: Subroutine Reference for information on the Open Archive File (GPOPAR) subroutine. Refer to The graPHIGS Programming Interface: Understanding Concepts for more information on structure archive.
ADIB

To specify this default through an ADIB, the correct structure is:

-------------------------------------
| Total length of ADS (application  | Fullword integer
| dependant)                        |
-------------------------------------
| ADS code = 117                    | Fullword integer
-------------------------------------
| Reserved = 0                      | Fullword integer
-------------------------------------
| Length of From descriptor         | Fullword integer
-------------------------------------
| From Descriptor                   | Variable-length character string
|                                   | (padded to word boundary)
-------------------------------------
| Length of To descriptor           | Fullword integer
-------------------------------------
| To descriptor                     | Variable-length character string
|                                   | (padded to word boundary)
-------------------------------------

CMSTRCE (CMS Trace Output)

This default directs trace output from the API on the VM/CMS system. Two 8-character strings indicate the filename and filetype used by the graPHIGS APIscreen

Initial Preset Value

A filename of AFM00001 and a filetype of AFMTRACE.

EDF

To specify this default through an EDF, the correct syntax is:

       AFMMDFT CMSTRCE=(aaaaaaaa,bbbbbbbb)
aaaaaaaa is the filename, bbbbbbbb is the filetype for receiving trace output in the CMS environment. The statement AFMMDFT CMSTRCE=, sends trace output to the printer.
ADIB

To specify this default through an ADIB, the correct structure is:

-------------------------------------
| Total length of ADS = 24          | Fullword integer
-------------------------------------
| ADS code = 502                    | Fullword integer
-------------------------------------
| Filename                          | 8-byte character string
| - - - - - - - - - - - - - - - - - |
| Filetype                          | 8-byte character string
-------------------------------------

COMBSZ (Input and Output Buffer Sizes)

This default sets the input and output buffer sizes that are to be used for all nucleus connections.

Initial Preset Value

65516 bytes.

EDF

To specify this default through an EDF, the correct syntax is:

AFMMDFT COMBSZ=(n[default],n[default])
where n[default] is the size of the input buffer that the shell uses to receive responses and events from the nucleus. n[default] is the size of the output buffer that the shell uses to send requests to the nucleus.

The size of each of the input and output buffers may have a maximum of 65516 bytes and a minimum of 4K bytes.

ADIB

To specify this default through an ADIB, the correct structure is:

-------------------------------------
| Total length of ADS = 16          | Fullword integer
-------------------------------------
| ADS code = 106                    | Fullword integer
-------------------------------------
| Size of input buffer (in bytes)   | Fullword integer
| - - - - - - - - - - - - - - - - - |
| Size of output buffer (in bytes)  | Fullword integer
-------------------------------------

COMMENT (Programming Comments)

This default lets you annotate the EDF with comments. A comment can be a list of strings of 8 or less non-blank characters. Your application can specify up to 8,000 comment strings. The API ignores comments during default processing. You can specify comments only in the External Defaults File.

EDF

To specify this default through an EDF, the correct syntax is:

       AFMMDFT COMMENT=(cccccccc,cccccccc,........)
ADIB

Not valid.

DAPPATH (DAP Download File Path)

This default allows you to specify the AIX file path for temporary storage of downloaded DAP files. This default must be specified as an EDF on the AIX system, where the target remote nucleus resides.

Initial Preset Value

/tmp/.gP

EDF

To specify this default through an EDF, the correct syntax is:

       AFMMDFT DAPPATH=ccccc
where ccccc is an AIX file path up to fifty characters in length. This file path is used as the temporary directory for the storage of DAP files on the current AIX remote nucleus. The file path is used for the transfer and execute function of the Execute Application Process (GPEXAP) subroutine.
ADIB

Not valid.

DEFACTF (Activate Font Handling)

This default allows you to select the way the graPHIGS API handles activate font requests.

Initial Preset Value

yes

EDF

To specify this default through an EDF, the correct syntax is:

AFMMDFT DEFACTF=yes|no
If DEFACTF=yes, and an activate font request to a workstation fails because the character set/font pair cannot be found on the nucleus disk system, the graPHIGS API searches its disk for the character/font. If it finds the font definition, it will send it to the nucleus for activation to the workstation.

If DEFACTF=no, and an activate font request to a workstation fails, the graPHIGS API simply posts the error to the application.

ADIB

To specify this default through an ADIB, the correct structure is:

-------------------------------------
| Total length of ADS = 12          | Fullword integer
-------------------------------------
| ADS code = 109                    | Fullword integer
-------------------------------------
| Request font handling             | Fullword integer
| 0 = no, 1 = yes                   |
-------------------------------------

DEFNUC (Define Nucleus Connection Processing)

This default defines whether your application will explicitly issue the Connect to Nucleus subroutine (GPCNC) or graPHIGS API will do nucleus connection processing for your application. If this default is not specified, and your application is not a distributed application process (DAP), the graPHIGS API will connect to a nucleus with identifier=1 on behalf of your application, using the CALL connection method. (It will additionally create a structure store using identifier=1 and select that structure store for editing.) If this default is not specified, and your application is a distributed application process (DAP), the graPHIGS API will not connect to a nucleus. Your application must explicitly issue the Connect to Nucleus (GPCNC) subroutine. For an explanation of the connection processing, and for the valid data values, see "Connecting to the Nucleus"screen See also "NUC/TONUC (Nucleus Respecification)" for information on changing the connection method and specification using defaults.

Initial Preset Value

Connection method = CALL, connection specification = NULL. (For DAPs, the initial preset value is 0, which means nucleus connection processing is suppressed and your application will explicitly issue the Connect to Nucleus [GPCNC] subroutine.)

EDF
ADIB

To specify this default through an ADIB, the correct structure is:

-------------------------------------
| Total length of ADS (is           | Fullword integer (must be a multiple of 4)
| application-dependent)            |
-------------------------------------
| ADS code = 104                    | Fullword integer
-------------------------------------
| Connection method                 | Fullword integer
| - - - - - - - - - - - - - - - - - |
| Length of nucleus connection      | Fullword integer
| specification                     |
| - - - - - - - - - - - - - - - - - |                 
| Nucleus connection specification  | Variable-length character string
-------------------------------------

Note:

Specifying a connection method =0, a specification length =0, and an ADS length =16 in the ADIB will suppress graPHIGS API from doing nucleus connection processing.

ERREVENT (Enable Error Event)

You use the ERREVENT default to enable the queuing of errors on the graPHIGS event-queue. When enabled, errors are queued as events of class 401 with a major code equal to the error's number and a minor code of 0. No additional data is queued with the event.

Other than the queuing of an error as an error-event, the error-handling mechanisms of the graPHIGS API are unaffected by the value of the ERREVENT default. See graPHIGS: Understanding Concepts for an explanation of error-handling within the graPHIGS API.

The only errors that cannot be queued on the graPHIGS event-queue are errors related to the state of the graPHIGS API. For example, error 5 "FUNCTION REQUIRES STATE STOP OR NROP (NOT STCL)" is not to be queued on the graPHIGS event queue even if you enable error-event queuing via the ERREVENT default.

In combination with a graPHIGS event-handler, enabling error-events enables the graPHIGS API to inform your application of an error condition without the need for your application to call a graPHIGS API function.

Initial Preset Value

no

EDF
ADIB

To specify this default through an ADIB, the correct structure is:

-------------------------------------
| Total length of ADS = 12          | Fullword integer
-------------------------------------
| ADS code = 119                    | Fullword integer
-------------------------------------
| Request queuing of error-events   | Fullword integer
| 0 = no, 1 = yes                   |
-------------------------------------

HCHECK (Shell Syntax Checking)

This default allows you to specify if the shell will check the syntax of its input parameters.

Initial Preset Value

yes (the shell does syntax checking).

EDF

To specify this default through an EDF, the correct syntax is:

       AFMMDFT HCHECK=yes|no
ADIB

To specify this default through an ADIB, the correct structure is:

-------------------------------------
| Total length of ADS = 12          | Fullword integer
-------------------------------------
| ADS code = 105                    | Fullword integer
-------------------------------------
| Syntax checking                   | Fullword integer
| 0 = no, 1 = yes                   |
-------------------------------------

IQSIZE (Input Queue Size)

With this default you can change the size of the allocated input queue.

Initial Preset Value

16K bytes.

EDF

To specify this default through an EDF, the correct syntax is:

AFMMDFT IQSIZE=n
where n is the queue size, the number of bytes of storage to allocate for the input queue (minimum of 4K bytes).

Note: If storage is not available for the size you request, the graPHIGS API will not open.

ADIB

To specify this default through an ADIB, the correct structure is:

-------------------------------------
| Total length of ADS = 12          | Fullword integer
-------------------------------------
| ADS code = 107                    | Fullword integer
-------------------------------------
| Number of bytes for the queue     | Fullword integer
-------------------------------------

MAXWKS (Maximum Workstation Support)

This default specifies the maximum number of workstations that may be opened and associated to the same structure store.

Initial Preset Value

Four (4).

EDF

To specify this default through an EDF, the correct syntax is:

       AFMMDFT MAXWKS=n
where n is the number of workstations to be opened and associated. n may be any value from 1 to 32.
ADIB

To specify this default through an ADIB, the correct structure is:

-------------------------------------
| Total length of ADS = 12          |
-------------------------------------
| ADS code = 113                    |
-------------------------------------
| Number of workstations            |
-------------------------------------

NICKCHK (Nickname Processing Default)

This default allows you to specify if the graPHIGS API will do nickname processing for workstations opened by your application.

Initial Preset Value

yes

EDF

To specify this default through an EDF, the correct syntax is:

       AFMMDFT NICKCHK=yes|no
If NICKCHK=yes, then the graPHIGS API library performs nickname processing to resolve the workstation type, connection identifier, and options using values specified in the EDF, ADIB, and on the Create Workstation (GPCRWS) or the Open Workstation (GPOPWS) subroutine. It sends the result of that processing to the nucleus when requesting a create workstation. This is the default.

If NICKCHK=no, then the graPHIGS API library does not perform nickname processing to resolve the workstation type, connection identifier, and options. It sends the workstation type, connection identifier, and options as explicitly specified in the Create Workstation (GPCRWS) or Open Workstation (GPOPWS) subroutine to the nucleus to request a create workstation.

ADIB

To specify this default through an ADIB, the correct structure is:

-------------------------------------
| Total length of ADS = 12          | Fullword integer
-------------------------------------
| ADS code = 116                    | Fullword integer
-------------------------------------
| Nickname processing               | Fullword integer
| 0 = no, 1 = yes                   |
-------------------------------------

NUC/TONUC (Nucleus Respecification)

This default allows you to change the nucleus connection processing values (the FROM connection method and connection specification) to the specified replacement values (TO ). This default is used whenever a nucleus is connected (either explicitly using the GPCNC subroutine or implicitly by using the default nucleus connection processing).

If several NUC/TONUC defaults are specified (for example, in the ADIB and in the EDF), the list of them is searched starting with the ADIB defaults, followed by the EDF defaults. The lists are searched until a matching default is found. A match occurs when the input connection method and connection specification (specified on the GPCNC subroutine or from the nucleus connection processing) are both the same as the FROM connection method and connection specification in the default (i.e., the NUC values). When matched, the TO connection method and connection specification values (the TONUC values) replace the input values and are used to complete the nucleus connection processing.

See "Connecting to the Nucleus" for a description of the supported connection methods and connection specifications.

EDF

To specify this default through an EDF, the correct syntax is:

       AFMMDFT NUC=(cml, csl),TONUC=(cm2,cs2)
where cm1 and cs1 are the nucleus connection method and connection specification to be matched and cm2 and cs2 are the replacement connection method and connection specification values.

The NUC and TONUC values must be on the same default specification. If the NUC value is omitted, the default will match any input connection method and specification.

ADIB

To specify this default through an ADIB, the correct structure is:

-------------------------------------
| Total length of ADS (greater      | Fullword integer
| than 8, but a fullword multiple)  |
-------------------------------------
| ADS code = 110                    | Fullword integer
-------------------------------------
| FROM connection method            | Fullword integer
-------------------------------------
| TO connection method              | Fullword integer
-------------------------------------
| FROM specification length         | Fullword integer
-------------------------------------
| FROM specification                | (padded to word boundary)
-------------------------------------
| TO specification length           | Fullword integer
-------------------------------------
| TO specification                  | (padded to word boundary)
-------------------------------------

Specify the value of zero in the FROM connection method and FROM specification length fields in order for the ADS default to match any input method and specification.

SYNCPROC (Synchronous X Event Processing)

This default tells the graPHIGS API that the application will be monitoring X events for the graPHIGS X workstations and will notify the graPHIGS API when an event occurs.

Initial Preset Value

no (the graPHIGS API will check for X events)

EDF

To specify this default through an EDF, the correct syntax is:

     AFMMDFT SYNCPROC=yes|no
ADIB

To specify this default through an ADIB, the correct structure is:

-------------------------------------
| Total length of ADS = 12          | Fullword integer
-------------------------------------
| ADS code = 120                    | Fullword integer
-------------------------------------
| SYNCPROC active                   | Fullword integer
| 0 = no, 1 = yes                   | Fullword integer
-------------------------------------

TRACE (Trace Control Word)

This default indicates the state of the Trace Control Word (whether it allows tracing or not).

The trace word itself determines priority.

Initial Preset Value

0 (off).

EDF

To specify this default through an EDF, the correct syntax is:

       AFMMDFT TRACE=n
where n is the value of the Trace Control Word. See The graPHIGS Programming Interface: Writing Applications or The GDDM/graPHIGS Programming Interface: Installation and Problem Diagnosis for more information about the function and priority of trace.
ADIB

To specify this default through an ADIB, the correct structure is:

-------------------------------------
| Total length of ADS = 12          | Fullword integer
-------------------------------------
| ADS code = 102                    | Fullword integer
-------------------------------------
| Trace Control Word                | Fullword integer
-------------------------------------

TRTABLE (Trace Table Entries)

This default lets you determine the number of trace entries that the API holds in the cyclic in-core trace table. This does not apply to AIX.

Initial Preset Value

100 entries.

EDF

To specify this default through an EDF, the correct syntax is:

       AFMMDFT TRTABL=n
where n is an integer, in the range of 5 to 1000, that defines the number of trace entries you want in the trace table.
ADIB

To specify this default through an ADIB, the correct structure is:

-------------------------------------
| Total length of ADS = 12          | Fullword integer
-------------------------------------
| ADS code = 103                    | Fullword integer
-------------------------------------
| Number of trace table entries     | Fullword integer
-------------------------------------

TSOTRCE (TSO Trace Output)

This default is an 8-character string indicating the DDNAME used by the API to direct trace output on MVS/TSO.

Initial Preset Value

AFMTRACE

EDF

To specify this default through an EDF, the correct syntax is:

       AFMMDFT TSOTRCE=cccccccc
where cccccccc is the DDNAME for the MVS/TSO trace output.
ADIB

To specify this default through an ADIB, the correct structure is:

-------------------------------------
| Total length of ADS = 16          | Fullword integer
-------------------------------------
| ADS code = 401                    | Fullword integer
-------------------------------------
| MVS/TSO DDNAME                    | 8 character bytes
-------------------------------------

Nicknames

Using nicknames, you can modify values associated with a particular workstation environment. You can specify a different workstation type and connection identifier as well as processing options (called PROCOPTS: see "PROCOPT (Processing Options)").

Each nickname specification may contain a workstation type (WSTYPE: see "WSTYPE (Workstation Type)") and connection identifier (CONNID: see "CONNID (Connection Identifier)") to match the workstation type and connection identifier specified on the Open Workstation (GPOPWS) or Create Workstation (GPCRWS) subroutine calls.

The nickname may also contain to-workstation types (TOWSTYPE: see "TOWSTYPE (Target Workstation Type)") and to-connection identifiers (TOCONNID: see "TOCONNID (Target Connection Identifier)") to replace the matched WSTYPE and CONNID specified on the GPOPWS or GPCRWS subroutines. Both of these specifications are optional. You can specify multiple nickname specifications and/or define more than one nickname for the same WSTYPE and CONNID.

Additionally, you may specify PROCOPT workstation environment values. These are applied to the workstation environment to allow customization of certain options.

A nickname in the EDF may then appear as

AFMMNICK CONNID=matched_connid,
         TOCONNID=new_connid,
         WSTYPE=matched_wstype,
         TOWSTYPE=new_wstype,
         PROCOPT=((keyword1,value1),(keyword2,value2)...)

When you specify a nickname ADS in the ADIB, you specify:

There are two formats for a nickname ADS. One format is for compatibility and supports connection identifiers that are specified as 8-byte character strings. A second format supports connection identifiers that are variable-length character strings.

Figure 9. Nickname Specification, ADS codes 2001 and 2002


                                                      FORMAT 2:
                                                      VARIABLE-LENGTH CHARACTER STRING CONNECTION IDENTIFIERS
                                                      -----------------------
                                                      | Total length of ADIB| Fullword integer
                                                      -----------------------
                                                      | Total length of ADS | Fullword integer
FORMAT 1:                                             ----------------------- 
8-BYTE CHARACTER STRING CONNECTION IDENTIFIER         | ADS code = 2002     | Fullword integer
-----------------------                               -----------------------
| Total length of ADIB| Fullword integer              |     from WSTYPE     | 8-byte character string
-----------------------                               -----------------------
| Total length of ADS | Fullword integer              |Length of from CONNID| Fullword integer
-----------------------                               -----------------------
| ADS code = 2001     | Fullword integer              |     from CONNID     | Variable-length character
-----------------------                               |                     |  string (padded to word boundary)
|     from WSTYPE     | 8-byte character string       -----------------------
-----------------------                               |      to WSTYPE      | 8-byte character string
|     from CONNID     | 8-byte character string       -----------------------
-----------------------                               | Length of to CONNID | Fullword integer
|      to WSTYPE      | 8-byte character string       -----------------------
-----------------------                               |      to CONNID      | Variable-length
|      to CONNID      | 8-byte character string       |                     |  string (padded to word boundary)
-----------------------                               -----------------------
|Length of PROCOPT 1  | Fullword integer              |Length of PROCOPT 1  | Fullword integer
-----------------------                               -----------------------
|    PROCOPT 1 code   | Fullword integer              |    PROCOPT 1 code   | Fullword integer
-----------------------                               -----------------------
|    PROCOPT 1 data   |                               |    PROCOPT 1 data   |
-----------------------                               -----------------------
|Length of PROCOPT 2  | Fullword integer              |Length of PROCOPT 2  | Fullword integer
-----------------------                               -----------------------
|    PROCOPT 2 code   | Fullword integer              |    PROCOPT 2 code   | Fullword integer
-----------------------                               -----------------------
|    PROCOPT 2 data   |                               |    PROCOPT 2 data   |
-----------------------                               -----------------------
/                     /                               /                     /
/                     /                               /                     /
-----------------------                               -----------------------
|Length of PROCOPT n  | Fullword integer              |Length of PROCOPT n  | Fullword integer
-----------------------                               -----------------------
|    PROCOPT n code   | Fullword integer              |    PROCOPT n code   | Fullword integer
-----------------------                               -----------------------
|    PROCOPT n data   |                               |    PROCOPT n data   |
-----------------------                               -----------------------

See examples and explanations of PROCOPTS starting on page "PROCOPT (Processing Options)"screen Default values are workstation-dependent (see Part 1. "PART 1. Workstations").

How The graPHIGS API Processes Nicknames

The following steps explain the process the graPHIGS API uses to process nicknames.

  1. When your application calls Open graPHIGS (GPOPPH), the API builds two lists of nicknames: one list from any nicknames found in the EDF and the other list from any nicknames found in the ADIB. These lists are used on all subsequent Open Workstation (GPOPWS) and Create Workstation (GPCRWS) subroutine calls.
  2. When the Open or Create Workstation subroutine is called, the two nickname lists are scanned to determine replacement values for the workstation type and connection identifier and to obtain the associated PROCOPT values. (The criteria of the search is described below.) The workstation type and connection identifier passed on the subroutine call are used to scan the EDF file nicknames. Any replacement values for the workstation identifier and/or connection identifier are then used to scan the ADIB nicknames. (If the EDF scan did not result in replacement values, then the subroutine input values are used to scan the ADIB nicknames.) The connection identifier and workstation type nickname values from the ADIB scan are then used to open the specified device.
  3. The nickname scan is a multi-pass scan that searches for nicknames which match the current workstation type and connection identifier: when matching values are found, the specified replacement values become the current workstation type and connection identifier, replacing the previous values. The scan is then resumed with the replacement values.

    Each nickname scan operates as follows:

    1. Before the scan is started, the API constructs a "current" parameter list that contains: These current values are those passed to each of the two scans (See step 2 above).
    2. The nickname specifications are compared for any WSTYPE and CONNID values that both match the "current" WSTYPE and CONNID values. A blank or nulls in the nickname specification WSTYPE or CONNID always matches the "current" WSTYPE or CONNID value.
    3. When a match is found, the API creates a "replacement" parameter list from the nickname TOWSTYPE and (TOWSTYPE: see "TOWSTYPE (Target Workstation Type)") TOCONNID values, (TOCONNID: see "TOCONNID (Target Connection Identifier)") and obtains any PROCOPT values specified by the nickname.
    4. This process continues until the end of the nickname list is reached. If any matches were found, the "current" values are updated with the "replacement" values found (the TOWSTYPE and TOCONNID). The nickname list is then re-scanned using these new "current" values. Any previously-matched nicknames are excluded from the re-scan.
    5. The API continues re-scanning (steps B through E above) the nickname list until a scan is completed without any further matches. The last "current" WSTYPE and CONNID values are returned from the scan process, along with any PROCOPT values from the matching nickname specification.
  4. When the two nickname lists have been scanned, the final WSTYPE (see "WSTYPE (Workstation Type)") and CONNID (see "CONNID (Connection Identifier)") values are used to complete the Open Workstation or Create Workstation processing.
  5. PROCOPTs (see "PROCOPT (Processing Options)") may be specified as part of the nickname specifications and as a parameter on the Create Workstation subroutine call.
The PROCOPTs are merged together to form a combined PROCOPT list. The merge is performed as follows:
  1. If the subroutine call is for Create Workstation and PROCOPTs (see "PROCOPT (Processing Options)") are specified, the entire list of specified PROCOPTs is obtained.
  2. If any PROCOPTs were specified on the matching nickname from the ADIB scan, then any of these PROCOPTs not already specified in the Create Workstation list are added to that list of PROCOPTs (if any).
  3. If any PROCOPTs were specified on the matching nickname from the EDF scan, then any of these PROCOPTs not already specified in the merged list (see B above) are added to that list of PROCOPTs (if any).
The resultant merged list of PROCOPTs is then used to complete the Open or Create workstation processing.

Nickname Syntax

Nicknames are intended to modify values associated with a particular workstation environment. The syntax explanations of a nickname set through an EDF and an ADIB follow (see "ADIB").

CONNID (Connection Identifier)

The CONNID is a string of characters used to specify the connection identifier to which this nickname applies.

TOCONNID (Target Connection Identifier)

The target connection identifier is a string of characters that replace the specified connection identifier, if the wstype and connid parameters match the corresponding actual values.

WSTYPE (Workstation Type)

The workstation type is a string of 0-8 characters used to match the nickname workstation type.

TOWSTYPE (Target Workstation Type)

The actual workstation type is a string of 0-8 characters that are the real value substituted for a connection identifier. The towstype replaces the actual workstation type if the wstype and connid parameters match the corresponding actual values.

PROCOPT (Processing Options)

PROCOPTS are a list of processing options. You can use these options to change the way in which the API treats a specific device or to specify workstation-specific default values. PROCOPTS can also be specified with the option parameter on the Create Workstation subroutine call (GPCRWS). Each specification defines a specific workstation option followed by a number of arguments that are valid for that option.

PROCOPTS are listed in the form of "PROCOPT-specifications" (PROCOPT-specs). Each PROCOPT-spec defines a specific workstation option followed by a number of arguments that are valid for that option in the following format:

PROCOPT=((PROCOPT_spec),(PROCOPT_spec),...)

The expanded PROCOPT appears like this:

PROCOPT=((option_keyword,argument,argument),(option_keyword,argument),...

See "PROCOPTS" for details about PROCOPTS.

Nickname Example

The following sample EDF nickname specification changes from one workstation to another and specifies a PROCOPT:

AFMMNICK CONNID=*,
         TOCONNID=IBM5080,
         WSTYPE=GDDM,
         TOWSTYPE=5080,
         PROCOPT=((DISPLMOD,5080-16))

PROCOPTS

PROCOPTS are a list of processing options. You can use these options to change the way in which the API treats a specific device or to specify workstation-specific default values. PROCOPTS can also be specified with the option parameter on the Create Workstation (GPCRWS) subroutine. Each specification defines a specific workstation option followed by a number of arguments that are valid for that option.

Examples and explanations of PROCOPT specifications follow. Default values are workstation-dependent. See Chapter 3. "Workstation Description Tables" for specific workstation values.

CLDEVS (Create Input Device)

This PROCOPT lets you create a logical input device even if a physical device is not present.

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

       AFMMNICK PROCOPT=((CLDEVS),...
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
| Total length of ADS = 8           | Fullword integer
-------------------------------------
|  ADS code =  23                   | Fullword integer
-------------------------------------

DCMETERS (Device Coordinate Meters)

This PROCOPT enables you to define the width and height of the display device in Device Coordinate (DC) meters. Both the width and the height values must be greater than zero (0.0). The maximum value for both the width and the height is subject to the capabilities of the workstation.

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

       AFMMNICK PROCOPT=((DCMETERS, float1, float2),...
where float1 is the display width specified in meters and float2 is the display height specified in meters.
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS = 16         | Fullword integer
-------------------------------------
|  ADS code =  36                   | Fullword integer
-------------------------------------
|  Display width in meters          | Short floating-point value
-------------------------------------
|  Display height in meters         | Short floating-point value
-------------------------------------
 

DCTES (Depth Cue Table)

This PROCOPT lets you specify the number of depth cue table entries.

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

       AFMMNICK PROCOPT=((DCTES, n),...
where n is the number of depth cue table entries.
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS = 12         | Fullword integer
-------------------------------------
|  ADS code = 21                    | Fullword integer
-------------------------------------
|  Number of depth cue entries      | Fullword integer
-------------------------------------

DCUNITS (Device Coordinate Address Units)

This PROCOPT enables you to define the width and height of the display in Device Coordinate (DC) address units. The minimum value for either the width or the height is 8. Likewise, the maximum value for either the width or the height is 4096.

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

       AFMMNICK PROCOPT=((DCUNITS, n1, n2),...
where n1 is the display width in address units and n2 is the display height in address units.
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS = 16         | Fullword integer
-------------------------------------
|  ADS code =  35                   | Fullword integer
-------------------------------------
|  Display width in address units   | Fullword integer
-------------------------------------
|  Display height in address units  | Fullword integer
-------------------------------------
 

DIRCOLOR (Direct Color)

This PROCOPT lets you specify workstation color tables to be initialized for direct color rather than initialized for the default which is indexed color.

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

       AFMMNICK PROCOPT=((DIRCOLOR),...
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
| Total length of ADS = 8           | Fullword integer
-------------------------------------
|  ADS code =  29                   | Fullword integer
-------------------------------------

DISPLMOD (Display Model)

This PROCOPT lets you specify the size of the display for the workstation.

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

       AFMMNICK PROCOPT=((DISPLMOD, cccccccc),...
where cccccccc is an 8-character string specifying the display model.

See "Display Models" for possible values of this PROCOPT.

ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS = 16         | Fullword integer
-------------------------------------
|  ADS code = 9                     | Fullword integer
-------------------------------------
|  Display model                    | 8-byte character string
-------------------------------------

DUMPFLGS (Dump Flags)

This PROCOPT lets you indicate the enabling and disabling of the 5080 workstation diagnostic options.

For specific information on the setting of the dump flag values, see The GDDM/graPHIGS Programming Interface: Installation and Problem Diagnosis screen

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

       AFMMNICK PROCOPT=((DUMPFLGS, n),...
where n is the desired option value.
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS = 12         | Fullword integer
-------------------------------------
|  ADS code = 5                     | Fullword integer
-------------------------------------
|  5080 diagnostic options          | Fullword integer
-------------------------------------

DUMPPRFX (Dump Prefix)

This PROCOPT provides the prefix of the file to which 5080 workstation diagnostic data is written.

For specific device information, see The GDDM/graPHIGS Programming Interface: Installation and Problem Diagnosis screen

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

       AFMMNICK PROCOPT=((DUMPPRFX, cccc),...
where cccc is a 4-character string specifying the file prefix.
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS = 12         | Fullword integer
-------------------------------------
|  ADS code = 6                     | Fullword integer
-------------------------------------
|  File prefix for 5080 diagnostic  | 4-byte character string
|  data                             |
-------------------------------------

EBTES (Edge Bundle Table)

This PROCOPT lets you specify the number of edge bundle table entries.

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

       AFMMNICK PROCOPT=((EBTES, n),...
where n is the number of edge bundle table entries.
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS = 12         | Fullword integer
-------------------------------------
|  ADS code = 20                    | Fullword integer
-------------------------------------
|  Number of edge bundle table      | Fullword integer
|  entries                          |
-------------------------------------

ECHOMETH (Input Echo)

This PROCOPT lets you specify the type of input echoing to be done for NATIVE or X workstations.

For displays with less than 8-bit planes, the default echo is Exclusive-Or on the color table.

With bit plane echoing, the number of available colors is halved and the echo is always white.

With XOR, echoing is implemented by exclusive-or on the color table. For example, with a 16-color, 4-bit plane device, suppose a locator echo area is filled with color 5 and a rubber-band line prompt/echo type is selected. This rubber-band line will appear in color 10 (0101 exclusive or'd with 1111 = 1010). In this instance, you should ensure that color 10 is visible with a background color of 5.

The colors of:

will not be set by XOR echoing.
EDF

To specify this PROCOPT through an EDF, the correct syntax is:

       AFMMNICK PROCOPT=((ECHOMETH, n),...
where n is 1 for reserve bit plane or 2 for XOR.
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS = 12         | Fullword integer
-------------------------------------
|  ADS code = 10                    | Fullword integer
-------------------------------------
|  Method of input echoing          | Fullword integer
-------------------------------------

FBUFFER (Frame Buffer Configuration)

This PROCOPT lets you select the number of logical buffers that comprise the physical frame buffer.

Note:

This PROCOPT is only supported when running Direct Window Access using the High Performance 3D Color Graphics Processor (8 bit or 24 bit)screen

By default, if running with Direct Window Access:

If not running with the Direct Window Access: all adapters have a frame buffer consisting of one buffer and this PROCOPT is ignored.

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

       AFMMNICK PROCOPT=((FBUFFER, n),...
where n is the number of buffers and may be set to a value of 1 or 2.
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS = 12         | Fullword integer
-------------------------------------
|  ADS code = 31                    | Fullword integer
-------------------------------------
|  Organization of frame buffer     | Fullword integer
-------------------------------------

FONTLIST (Character Font List)

This PROCOPT allows you to specify user-defined character sets as valid character set/font identifiers for a 5080 workstation.

Specify a list of up to 10 (the maximum allowable) filenames of the symbol definition files of the desired user-defined character sets. If a filename cannot be found, it will be ignored and no error will be generated.

Note: All the character sets that the graPHIGS API defines are automatically included and never need to be specified via the FONTLIST.

Below is an example of the PROCOPT you would use to specify Character Set 229 Font 128, Character Set 229 Font 129, and Character Set 101 Font 128:

PROCOPT=((FONTLIST,AFME580,AFME581,AFM6580)

Note: When a 5080 workstation is opened, the API also uses these names to determine the sizes of the desired character sets in order to allocate sufficient storage in the 5085 for them.

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

       AFMMNICK PROCOPT=((FONTLIST, cccccccc,cccccccc,...),...
where cccccccc is a valid 8-character character set filename.
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS =  n         | Fullword integer
|  (application dependent)          |
-------------------------------------
|  ADS code = 15                    | Fullword integer
-------------------------------------
|  Up to 10 font list filenames     | n 8-byte character strings
|                                   |    .
|                                   |    .
-------------------------------------

FONTPSIZ (Font Pool Size)

For a 5080 workstation, this PROCOPT indicates the maximum number of character sets which can be active at one time (including the primary character set). Note also the considerations in "IBM 5080 Character Set Restrictions"screen

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

       AFMMNICK PROCOPT=((FONTPSIZ, n),...
where n is an integer between 1 and 10 (maximum allowable value). If you do not specify FONTPSIZ, a value of 3 is used.
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS = 12         | Fullword integer
-------------------------------------
|  ADS code =  14                   | Fullword integer
-------------------------------------
|  Number of 5080 maximum active    | Fullword integer
|  character font sets (1-10)       |
-------------------------------------

HWCURS (Hardware Crosshair Cursor)

This PROCOPT allows you to request the use of the full-screen hardware crosshair cursor provided by the AIX X cursor extension code in place of the usual crosshair cursor provided by the graPHIGS API (through the use of the GPCUS subroutine).

The hardware cursor provides a performance improvement over the current crosshair cursor. Unfortunately, though, the hardware cursor spans the entire display. For applications that normally use full-screen windows this will not be a problem. For applications that use smaller windows, the user may or may not wish to use this cursor.

The PROCOPT will be supported on all graPHIGS X workstation types. The X server where the window will be created must support the AIX X cursor extension in order for this PROCOPT to take effect.

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

       AFMMNICK PROCOPT=((HWCURS)),...
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS = 8          | Fullword integer
-------------------------------------
|  ADS code =  39                   | Fullword integer
-------------------------------------

Note: The hardware cursor may also be activated by defining an AIX environment variable (in lieu of using a PROCOPT). If the gPHWCURS environment variable is defined at the time that the nucleus is started (in the case of a remote nucleus being started via the gPinit command) or when the AIX application is started, then when a crosshair cursor is requested (as defined by the GPCUS subroutine), the full-screen hardware crosshair cursor will be used instead of the regular crosshair cursor provided by the graPHIGS workstation.

IBTES (Interior Bundle Table)

This PROCOPT lets you specify the number of interior bundle table entries.

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

       AFMMNICK PROCOPT=((IBTES, n),...
where n is the number of interior bundle table entries.
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS = 12         | Fullword integer
-------------------------------------
|  ADS code =  19                   | Fullword integer
-------------------------------------
|  Number of interior bundle table  | Fullword integer
|  entries                          |
-------------------------------------

IMAGEFMT (Image Output Format)

This PROCOPT enables you to define the image format used for output images. The valid formats are 1=PSL1_4BIT , 2=PSL1_8BIT , and 3=IOCA_FS10 where:

The default image format is 1=PSL1_4BIT screen

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

       AFMMNICK PROCOPT=((IMAGEFMT, n),...
where n is an image output format.
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS = 12         | Fullword integer
-------------------------------------
|  ADS code =  37                   | Fullword integer
-------------------------------------
|  Image output format              | Fullword integer
-------------------------------------

KEYBOARD (Language Keyboard)

This PROCOPT lets you specify the keyboard installed for the NATIVE workstation.

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

       AFMMNICK PROCOPT=((KEYBOARD, n),...
where n is an integer from the following list to identify the keyboard:
  1 = United States English
  2 = United Kingdom English
  3 = German
  4 = French
  5 = Italian
  6 = Japanese
  7 = Swedish
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS = 12         | Fullword integer
-------------------------------------
|  ADS code =  11                   | Fullword integer
-------------------------------------
|  Number that identifies the       | Fullword integer
|  installed keyboard               |
-------------------------------------

LOCDEVS (Locator Devices)

This PROCOPT lets you specify the number of locator devices for the workstation. The limit for the number of locator devices is device dependent. For specific device information, see "Locator Devices"screen

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

       AFMMNICK PROCOPT=((LOCDEVS, n),...
where n is the number of locator devices your workstation is to support.
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS = 12         | Fullword integer
-------------------------------------
|  ADS code = 3                     | Fullword integer
-------------------------------------
|  Number of locator devices        | Fullword integer
-------------------------------------

LSTES (Light Source Table)

This PROCOPT lets you specify the number of light source table entries.

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

       AFMMNICK PROCOPT=((LSTES, n),...
where n is the number of light source table entries.
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS = 12         | Fullword integer
-------------------------------------
|  ADS code = 22                    | Fullword integer
-------------------------------------
|  Number of light source table     | Fullword integer
|  entries                          |
-------------------------------------

PLBTES (Polyline Bundle Table)

This PROCOPT lets you specify the number of polyline bundle table entries.

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

       AFMMNICK PROCOPT=((PLBTES, n),...
where n is the number of polyline bundle table entries.
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS = 12         | Fullword integer
-------------------------------------
|  ADS code = 16                    | Fullword integer
-------------------------------------
|  Number of polyline bundle table  | Fullword integer
|  entries                          |
-------------------------------------

PMBTES (Polymarker Bundle Table)

This PROCOPT lets you specify the number of polymarker bundle table entries.

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

       AFMMNICK PROCOPT=((PMBTES, n),...
where n is the number of polymarker bundle table entries.
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS = 12         | Fullword integer
-------------------------------------
|  ADS code =  17                   | Fullword integer
-------------------------------------
|  Number of polymarker bundle      | Fullword integer
|  table entries                    |
-------------------------------------

PNTHLHSR (Annotation Text and Marker Hidden Line Hidden Surface Removal)

This PROCOPT enables you to define the coordinate system in which HLHSR of all annotation text and polymarker primitives will occur. The valid values are 1=VIEWING_COORDINATES and 2=DEVICE_COORDINATES screen 1=VIEWING_COORDINATES screen

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

       AFMMNICK PROCOPT=((PNTHLHSR, n),...
where n is the primitive's HLHSR coordinate system.
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS = 12         | Fullword integer
-------------------------------------
|  ADS code =  38                   | Fullword integer
-------------------------------------
|  Primitive's HLHSR coordinate     | Fullword integer
|  system                           |
-------------------------------------

STRDEVS (String Devices)

This PROCOPT lets you specify the number of string devices for the workstation. For specific device information, see "String Devices"screen

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

       AFMMNICK PROCOPT=((STRDEVS, n),...
where n is the number of string devices. The limit for the number of string devices is device dependent. For specific device information, see "String Devices"screen
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS = 12         | Fullword integer
-------------------------------------
|  ADS code = 4                     | Fullword integer
-------------------------------------
|  Number of string devices         | Fullword integer
-------------------------------------

TXBTES (Text Bundle Table)

This PROCOPT lets you specify the number of text bundle table entries.

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

       AFMMNICK PROCOPT=((TXBTES, n),...
where n is the number of text bundle table entries.
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS = 12         | Fullword integer
-------------------------------------
|  ADS code = 18                    | Fullword integer
-------------------------------------
|  Number of text bundle table      | Fullword integer
|  entries                          |
-------------------------------------

VWTBLSZ (View Table Entries)

This PROCOPT lets you specify the number of view table entries for the workstation. For specific device information, see "General Workstation Facilities"screen

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

       AFMMNICK PROCOPT=((VWTBLSZ, n),...
where n is the number of view table entries. All workstations must have at least one definable view table entry. Therefore, you must specify VWTBLSZ greater than or equal to 2 (view 0 plus one definable entry). The maximum limit for the view table size is device dependent.
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS = 12         | Fullword integer
-------------------------------------
|  ADS code =  2                    | Fullword integer
-------------------------------------
|  Number of view table entries     | Fullword integer
-------------------------------------

XNAME (X Default String)

This PROCOPT lets you specify a name to be used to resolve the defaults in the .Xdefaults file. If this PROCOPT is not specified, then the graPHIGS API will use the default string 'graPHIGS' to resolve the defaults.

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

      AFMMNICK PROCOPT=((XNAME, cccc),...
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS = variable   | Fullword integer
-------------------------------------
|  ADS code =  27                   | Fullword integer
-------------------------------------
|  Length of default string         | Fullword integer
-------------------------------------
|  Default String                   | Variable length character string
|                                   | padded to a word boundary
-------------------------------------

XNOCLRMP (Do Not Create an X Color Map)

This PROCOPT lets you specify to not have graPHIGS API create an X color map. This implies that the application cannot access the color map via graPHIGS API.

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

      AFMMNICK PROCOPT=((XNOCLRMP),...
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS = 8          | Fullword integer
-------------------------------------
|  ADS code =  28                   | Fullword integer
-------------------------------------

XWINDASP (Window Aspect Ratio)

This PROCOPT lets you change the aspect ratio of the window to the displayed surface of the X Workstation. Whenever the graPHIGS API window is resized, the device driver establishes a new display surface size within that window. This is the largest subarea of the resized X-Window that maintains the aspect ratio provided by this procopt (or the root window, if XWINDASP PROCOPT is not specified). The current display contents are scaled uniformly to this new mapped display surface size.

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

      AFMMNICK PROCOPT=((XWINDASP, float1,
float2),...
where float1 is the value of the aspect ratio specifying the size in the x direction and float2 is the value of the aspect ratio specifying the size in the y direction.
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS = 16         | Fullword integer
-------------------------------------
|  ADS code =  30                   | Fullword integer
-------------------------------------
|  size of the window (x-direction) | Floating-point number
-------------------------------------
|  size of the window (y-direction) | Floating-point number
-------------------------------------
 

XWINDID (X Window Identifier)

This PROCOPT lets you pass a window identifier to the graPHIGS APIscreen The window was created by your application and the graPHIGS API will use this for the X workstation display window. (See the GPES subroutine (escape 1018) for information on getting a list of visuals in order to guarantee that the application's window will be usable by the graPHIGS nucleus.)

EDF

To specify this PROCOPT through an EDF, the correct syntax is:

      AFMMNICK PROCOPT=((XWINDID, n),...
ADIB

To specify this PROCOPT through an ADIB, the correct structure is:

-------------------------------------
|  Total length of ADS = 12         | Fullword integer
-------------------------------------
|  ADS code =  25                   | Fullword integer
-------------------------------------
|  Window Identifier                | Fullword integer
-------------------------------------

PROCOPT Parameters Table

This table summarizes the parameters you can specify with a PROCOPT.

Table 97. PROCOPT Parameters

Identifier Length Type Name Description Workstations
2 12 Integer VWTBLSZ Number of view table entries 6090, 5080, GDDM, NATIVE, GDF, X, XSOFT, XPEX, IMAGE
3 12 Integer LOCDEVS Number of locator devices 6090, 5080, GDDM, NATIVE, X, XSOFT, XPEX
4 12 Integer STRDEVS Number of string devices 6090, 5080, GDDM, NATIVE, X, XSOFT, XPEX
5 12 Bit (32) DUMPFLGS Dump flag 5080
6 16 Char (4) DUMPPRFX Dump file prefix 5080
9 16 Char (8) DISPLMOD Monitor model 5080, NATIVE
10 12 Integer ECHOMETH Input device echo method NATIVE, X, XSOFT
11 12 Integer KEYBOARD Keyboard language NATIVE
14 12 Integer FONTPSIZ Font pool size 5080
15 16-881 Char (8) FONTLIST Font list 5080
16 12 Integer PLBTES Number of polyline bundle table entries 6090, X, XSOFT, XPEX, IMAGE
17 12 Integer PMBTES Number of polymarker bundle table entries 6090, X, XSOFT, XPEX, IMAGE
18 12 Integer TXBTES Number of text bundle table entries 6090, X, XSOFT, XPEX, IMAGE
19 12 Integer IBTES Number of interior bundle table entries 6090, X, XSOFT, XPEX, IMAGE
20 12 Integer EBTES Number of edge bundle table entries 6090, X, XSOFT, XPEX, IMAGE
21 12 Integer DCTES Number of depth cue table entries 6090, X, XSOFT, XPEX, IMAGE
22 12 Integer LSTES Number of light source table entries 6090, X, XSOFT, XPEX, IMAGE
23 8   CLDEVS Create logical input devices even if physical devices are not present 6090, X, XSOFT, XPEX
25 12 Integer XWINDID X workstation display window identifier X, XSOFT, XPEX
27 Variable Char XNAME Name used to resolve the defaults in the .Xdefaults file X, XSOFT, XPEX
28 8   XNOCLRMP Do not have the graPHIGS API create an X color map X, XSOFT, XPEX
29 8   DIRCOLOR Initialize workstation color map for direct color X, XSOFT, XPEX
30 16 Float (2) XWINDASP Initial Aspect Ratio X, XSOFT, XPEX
31 12 Integer FBUFFER Number of buffers that comprise the frame buffer X, XPEX
35 16 Integer (2) DCUNITS Device Coordinate address units IMAGE
36 16 Float (2) DCMETERS Device Coordinate meters IMAGE
37 12 Integer IMAGEFMT Image output format IMAGE
38 12 Integer PNTHLHSR Primitive's HLHSR Coordinate system X, XSOFT, IMAGE
39 8 Integer HWCURS Hardware Crosshair Cursor X, XSOFT
Note: 1 Application-dependent

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