This section contains the definition of two miscellaneous subroutines. The first is an escape routine used by the graPHIGS API for special functions such as setting plot sizes. The second subroutine is used to read the contents of a workstation's frame buffer.
| GPES (funcid, lidr, idr, mlodr, lodr, odr) |
Purpose
Use GPES to perform an escape function. The specific escape subroutine is identified by way of the identifier parameter. In general, an escape subroutine accepts both an input data record and an output data record to place any output generated by the escape subroutine.
If the specified escape identifier is not supported by the graPHIGS API, then the subroutine may be ignored or produce unexpected results.
Parameters
1001 - Sound Alarm: This escape subroutine causes the specified workstation to sound its alarm. If the workstation does not have an alarm or does not support this escape subroutine, then the escape is ignored. The input data record for this escape code contains the workstation identifier at which to perform this function. There is no output data record generated by this function.
1002 - Enable/Disable Link Switch Notification: When the link switch is modified on a 5080 workstation, this escape subroutine enables or disables the generation of events. The 5080 operator has the capability to switch between a RT PC and a System/370. This escape subroutine may be used to enable application notification of this operator action. Notification is disabled by default. Notification occurs by way of the graPHIGS API event queue. When the switch is changed, an event is placed on the event queue. The event type identifies the direction of the switch. Event type 101 indicates that the 5085 link has been switched away from the application program. Event type 102 indicates that the 5085 link has been switched to the application program. The input data record for this escape code contains the workstation identifier at which to perform this function and a flag which indicates whether this capability is being enabled or disabled. This escape subroutine is only valid for 5080 workstations. When specified with a workstation type other than a 5080, this escape is ignored. There is no output data record generated by this function.
1003 - GDF/CGM Plot Size: This escape subroutine allows the user to specify the width of the plotted output in meters. Zero and negative sizes are not valid. The input data record for this escape code contains the identifier for the workstation at which to perform this function and the value, in floating-point representation, for the size. This escape subroutine is only valid for workstations of type 'GDF' or 'CGM' When specified with a workstation type other than 'GDF' or 'CGM', this escape is ignored. No output data record is generated by this function.
CGM plot scaling is implemented by adjusting the scale factor metric to be equal to 960 * plot size/1000. This is the distance that corresponds to one Virtual device coordinate (VDC) unit. When you change the plot size, values stored in the workstation description table are not changed to reflect the new display size. The nominal line width, nominal edge width, and marker size are not scaled.
GDF scaling is accomplished via a comment order which is
understood by the IBM GDF interpreters which are supplied by
the graPHIGS API program product.
Other interpreters will most likely ignore this information
but will not generate an error.
If you are designing your own interpreter and you wish to
utilize the scaling comment order, note that it consists of
the following 18 bytes.
(For more detailed information, see the
GDDM Base
Programming Reference, Volume 2
).
| Field Length | Content | Meaning |
|---|---|---|
| 1 | X'01' | Comment order. |
| 1 | X'10' | Length of following data. |
| 2 | 0000 | Reserved. |
| 8 | 'graPHIGS' | Application identifier ( char data). |
| 1 | X'01' | Indicates exact scale comment. |
| 1 | X'04' | Length of following data. |
| 4 | 4 byte floating-point | Size in meters of the x dimension of the resulting GDF plot. |
1009 - Window Resize Notification Control: This escape subroutine allows your application to be notified when the window containing a mapped display surface changes size. This escape subroutine also allows your application to specify whether it wants the graPHIGS API to redraw the contents of the window when the window is resized. This escape subroutine is meaningful only on a workstation which uses the facilities of a window system (e.g., X Windows)
The mapped display surface is the subarea of the window that the workstation uses as the workstation's display surface for graphical output and input. The mapped display surface size may change if the user changes the size of the window that contains the mapped display surface. Your application can receive notification of such size changes by enabling this Window Resize Notification function. Notification occurs by way of the graPHIGS API event queue. The new size of the mapped display surface can then be obtained using the Inquire Mapped Display Surface Size (GPQMDS) subroutine. By default, notification is disabled and the window contents will always be redrawn when a resize occurs. The input data record for this escape code contains the workstation identifier at which to perform this function. There is no output data record generated by this function.
1011 - Window Exposure Notification Control: This escape subroutine allows your application to be notified when the window containing a mapped display surface is exposed. This escape subroutine also allows your application to specify whether it wants the graPHIGS API to redraw the contents of the screen when the exposure occurs. This escape subroutine is meaningful only on a workstation which uses the facilities of a window system (e.g., X Window System).
Your application can receive notification each time the window is exposed by enabling this Window Exposure Notification function. Notification occurs by way of the graPHIGS API event queue. By default, notification is disabled and redraw will occur. This function causes generation of event class 106 (Window Exposure Event), retrieved by the Get Window (GPGWIN) subroutine. The input data record for this subroutine code contains the workstation identifier at which to perform this function. There is no output data record generated by this function.
1012 - Window Deletion Notification Control: This escape subroutine allows your application to be notified when the window is deleted (closed) via the Window Manager. (See The graPHIGS Programming Interface: Technical Reference for more details on this function).
1014 - Workstation-Dependent Output: This escape subroutine allows your application to generate workstation-dependent output. The graPHIGS API can send this data directly to the workstation. This escape subroutine is valid only for workstations of type 'CGM' When specified with a workstation type other than 'CGM', this escape is ignored.
The input data record contains the workstation identifier, which specifies where the graPHIGS API performs the subroutine, and the output data, which is not verified by the workstation. The graPHIGS API does not guarantee the validity of the data. It is the application's responsibility to ensure that the data is valid (e.g., proper length(s), identifiers, padding, etc.) When character encoding, floating-point, and/or byte ordering differences exist between the target workstation and the application environment, the application must ensure the validity of this data also. For information on how the application can ensure the validity of this data, see the Convert Data (GPCVD) subroutine. For information on CGM data, see the "CGM Workstation" in The graPHIGS Programming Interface: Technical Reference There is no output data record generated by this function.
----------------------------
| 1 | number of integers (fullword integer)
|--------------------------|
| 0 | number of reals (fullword integer)
|--------------------------|
| 0 | number of strings (fullword integer)
|--------------------------|
| workstation identifier | (fullword integer)
----------------------------
Escape subroutine identifier 1002 (link switch notification) requires the following data record:
----------------------------
0 | 2 | number of integers (fullword integer)
|--------------------------|
4 | 0 | number of reals (fullword integer)
|--------------------------|
8 | 0 | number of strings (fullword integer)
|--------------------------|
12 | workstation identifier | (fullword integer)
|--------------------------|
16 | disable/enable flag | 1=DISABLE, 2=ENABLE (fullword integer)
----------------------------
Escape subroutine identifier 1003 (GDF/CGM plot size)
requires the following data record:
----------------------------
0 | 1 | number of integers (fullword integer)
|--------------------------|
4 | 1 | number of reals (fullword integer)
|--------------------------|
8 | 0 | number of strings (fullword integer)
|--------------------------|
12 | workstation identifier | (fullword integer)
|--------------------------|
16 | plot size value | (real)
----------------------------
Escape subroutine identifier 1009 (Window
Resize Notification Control)
requires the following data record:
----------------------------
0 | 3 | number of integers (fullword integer)
|--------------------------|
4 | 0 | number of reals (fullword integer)
|--------------------------|
8 | 0 | number of strings (fullword integer)
|--------------------------|
12 | workstation identifier | (fullword integer)
|--------------------------|
| disable/enable flag | 1=DISABLE, 2=ENABLE (fullword integer)
|--------------------------|
20 | redraw indicator | 1=REDRAW, 2=NO_DRAW (fullword integer)
----------------------------
Escape subroutine identifier 1011 (Window
Exposure Notification Control)
requires the following data record:
--------------------------
0 | 3 | number of integers (fullword integer)
|------------------------|
4 | 0 | number of reals (fullword integer)
|------------------------|
8 | 0 | number of strings (fullword integer)
|------------------------|
12 | workstation identifier | (fullword integer)
|------------------------|
16 | disable/enable flag | 1=DISABLE, 2=ENABLE (fullword integer)
|------------------------|
20 | redraw indicator | 1=REDRAW, 2=NO_DRAW (fullword integer)
--------------------------
Escape subroutine identifier 1012 (Window
Deletion Notification Control)
requires the following data record:
--------------------------
0 | 2 | number of integers (fullword integer)
|------------------------|
4 | 0 | number of reals (fullword integer)
|------------------------|
8 | 0 | number of strings (fullword integer)
|------------------------|
12 | workstation identifier | (fullword integer)
|------------------------|
16 | disable/enable flag | 1=DISABLE, 2=ENABLE (fullword integer)
--------------------------
Escape subroutine identifier 1014
(Workstation-Dependent Output)
requires the following data record:
----------------------------
0 | 1 | number of integers (fullword integer)
|--------------------------|
4 | 0 | number of reals (fullword integer)
|--------------------------|
8 | 1 | number of strings (fullword integer)
|--------------------------|
12 | workstation identifier | (fullword integer)
|--------------------------|
16-n| data | (byte string)
----------------------------
Error Codes
Related Subroutines
RCP code
201340673 (X'0C003701')