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.
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:
In addition, you can specify the workstation processing options (PROCOPTS) by using the PROCOPTS option (see "PROCOPT (Processing Options)") on the Create Workstation (GPCRWS) subroutine call.
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 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:
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
The current directory is searched for a file named PROFILE. If there is no file named PROFILE in the current directory, the search continues.
The graPHIGS API provides a sample External Defaults File as /usr/lpp/graPHIGS/etc/PROFILEscreen
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:
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) 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.
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 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.
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.
the filename AFMTRACE within the current working path.
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='').
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 -------------------------------------
This default directs the output of an Open Archive File (GPOPAR) subroutine. A From file descriptor and a To file descriptor are specified.
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.
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) -------------------------------------
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
A filename of AFM00001 and a filetype of AFMTRACE.
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.
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 -------------------------------------
This default sets the input and output buffer sizes that are to be used for all nucleus connections.
65516 bytes.
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.
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 -------------------------------------
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.
To specify this default through an EDF, the correct syntax is:
AFMMDFT COMMENT=(cccccccc,cccccccc,........)
Not valid.
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.
/tmp/.gP
To specify this default through an EDF, the correct syntax is:
AFMMDFT DAPPATH=cccccwhere 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.
Not valid.
This default allows you to select the way the graPHIGS API handles activate font requests.
yes
To specify this default through an EDF, the correct syntax is:
AFMMDFT DEFACTF=yes|noIf 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.
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 | -------------------------------------
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.
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.)
AFMMDFT DEFNUC=(n,ccc ... ccc)where n is an integer that specifies one of the connection methods supported by your nucleus and ccc ... ccc is a variable-length character string that specifies a nucleus connection specification in support of the method selected.
Note:
As part of doing nucleus connection processing, the graPHIGS API will additionally create a structure store (GPCRSS) using identifier=1 and select that structure store (GPSSS) for editing.
AFMMDFT DEFNUC=(0,)
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.
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.
no
AFMMDFT ERREVENT=yes|no
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 | -------------------------------------
This default allows you to specify if the shell will check the syntax of its input parameters.
yes (the shell does syntax checking).
To specify this default through an EDF, the correct syntax is:
AFMMDFT HCHECK=yes|no
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 | -------------------------------------
With this default you can change the size of the allocated input queue.
16K bytes.
To specify this default through an EDF, the correct syntax is:
AFMMDFT IQSIZE=nwhere 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.
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 -------------------------------------
This default specifies the maximum number of workstations that may be opened and associated to the same structure store.
Four (4).
To specify this default through an EDF, the correct syntax is:
AFMMDFT MAXWKS=nwhere n is the number of workstations to be opened and associated. n may be any value from 1 to 32.
To specify this default through an ADIB, the correct structure is:
------------------------------------- | Total length of ADS = 12 | ------------------------------------- | ADS code = 113 | ------------------------------------- | Number of workstations | -------------------------------------
This default allows you to specify if the graPHIGS API will do nickname processing for workstations opened by your application.
yes
To specify this default through an EDF, the correct syntax is:
AFMMDFT NICKCHK=yes|noIf 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.
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 | -------------------------------------
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.
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.
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.
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.
no (the graPHIGS API will check for X events)
To specify this default through an EDF, the correct syntax is:
AFMMDFT SYNCPROC=yes|no
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 -------------------------------------
This default indicates the state of the Trace Control Word (whether it allows tracing or not).
The trace word itself determines priority.
0 (off).
To specify this default through an EDF, the correct syntax is:
AFMMDFT TRACE=nwhere 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.
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 -------------------------------------
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.
100 entries.
To specify this default through an EDF, the correct syntax is:
AFMMDFT TRTABL=nwhere n is an integer, in the range of 5 to 1000, that defines the number of trace entries you want in the trace table.
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 -------------------------------------
This default is an 8-character string indicating the DDNAME used by the API to direct trace output on MVS/TSO.
AFMTRACE
To specify this default through an EDF, the correct syntax is:
AFMMDFT TSOTRCE=ccccccccwhere cccccccc is the DDNAME for the MVS/TSO trace output.
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 -------------------------------------
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").
The following steps explain the process the graPHIGS API uses to process nicknames.
Each nickname scan operates as follows:
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").
The CONNID is a string of characters used to specify the connection identifier to which this nickname applies.
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.
The workstation type is a string of 0-8 characters used to match the nickname 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.
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.
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 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.
This PROCOPT lets you create a logical input device even if a physical device is not present.
To specify this PROCOPT through an EDF, the correct syntax is:
AFMMNICK PROCOPT=((CLDEVS),...
To specify this PROCOPT through an ADIB, the correct structure is:
------------------------------------- | Total length of ADS = 8 | Fullword integer ------------------------------------- | ADS code = 23 | Fullword integer -------------------------------------
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.
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.
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 -------------------------------------
This PROCOPT lets you specify the number of depth cue table entries.
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.
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 -------------------------------------
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.
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.
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 -------------------------------------
This PROCOPT lets you specify workstation color tables to be initialized for direct color rather than initialized for the default which is indexed color.
To specify this PROCOPT through an EDF, the correct syntax is:
AFMMNICK PROCOPT=((DIRCOLOR),...
To specify this PROCOPT through an ADIB, the correct structure is:
------------------------------------- | Total length of ADS = 8 | Fullword integer ------------------------------------- | ADS code = 29 | Fullword integer -------------------------------------
This PROCOPT lets you specify the size of the display for the workstation.
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.
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 -------------------------------------
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
To specify this PROCOPT through an EDF, the correct syntax is:
AFMMNICK PROCOPT=((DUMPFLGS, n),...where n is the desired option value.
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 -------------------------------------
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
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.
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 | -------------------------------------
This PROCOPT lets you specify the number of edge bundle table entries.
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.
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 | -------------------------------------
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:
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.
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 -------------------------------------
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.
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.
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 -------------------------------------
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.
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.
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 | | . | | . -------------------------------------
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
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.
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) | -------------------------------------
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.
To specify this PROCOPT through an EDF, the correct syntax is:
AFMMNICK PROCOPT=((HWCURS)),...
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.
This PROCOPT lets you specify the number of interior bundle table entries.
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.
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 | -------------------------------------
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
To specify this PROCOPT through an EDF, the correct syntax is:
AFMMNICK PROCOPT=((IMAGEFMT, n),...where n is an image output format.
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 -------------------------------------
This PROCOPT lets you specify the keyboard installed for the NATIVE workstation.
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
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 | -------------------------------------
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
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.
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 -------------------------------------
This PROCOPT lets you specify the number of light source table entries.
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.
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 | -------------------------------------
This PROCOPT lets you specify the number of polyline bundle table entries.
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.
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 | -------------------------------------
This PROCOPT lets you specify the number of polymarker bundle table entries.
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.
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 | -------------------------------------
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
To specify this PROCOPT through an EDF, the correct syntax is:
AFMMNICK PROCOPT=((PNTHLHSR, n),...where n is the primitive's HLHSR coordinate system.
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 | -------------------------------------
This PROCOPT lets you specify the number of string devices for the workstation. For specific device information, see "String Devices"screen
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
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 -------------------------------------
This PROCOPT lets you specify the number of text bundle table entries.
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.
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 | -------------------------------------
This PROCOPT lets you specify the number of view table entries for the workstation. For specific device information, see "General Workstation Facilities"screen
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.
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 -------------------------------------
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.
To specify this PROCOPT through an EDF, the correct syntax is:
AFMMNICK PROCOPT=((XNAME, cccc),...
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 -------------------------------------
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.
To specify this PROCOPT through an EDF, the correct syntax is:
AFMMNICK PROCOPT=((XNOCLRMP),...
To specify this PROCOPT through an ADIB, the correct structure is:
------------------------------------- | Total length of ADS = 8 | Fullword integer ------------------------------------- | ADS code = 28 | Fullword integer -------------------------------------
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.
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.
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 -------------------------------------
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.)
To specify this PROCOPT through an EDF, the correct syntax is:
AFMMNICK PROCOPT=((XWINDID, n),...
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 -------------------------------------
This table summarizes the parameters you can
specify with a PROCOPT.
| 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 | |||||