ESCAPE(3P) — Kubota Pacfic Computer Inc. (29 February 1991)

NAME

ESCAPE − invoke an implementation-dependent function

SYNOPSIS

C Syntax

void
pescape ( func_id, in, store, out )
Pintfunc_id;escape function identifier
Pescape_in_data∗in; input data for the function
Pstorestore;
Pescape_out_data∗∗out; OUT output data of the function

Required PHIGS Operating States

(PHOP, ∗, ∗, ∗)

DESCRIPTION

Purpose

ESCAPE is a standard way of invoking PHIGS functions provided by the implementation but not defined in the PHIGS standard. Such functions are called escape functions. This single function can access any of the implementation-dependent escape functions provided. These functions either perform an action or return information not defined by the PHIGS standard.

The provided escape functions are:

• Enforce synchronized error reporting • Inquire a workstation’s drawable and display • Disable bounds checking of Device Coordinate parameters to PHIGS functions

See the separate manual page for each individual escape for a full description of its function.

C Input Parameters

Applications using the C binding must create a buffer to be used by this function as memory space for storing data associated with the device state. This buffer is passed as the store argument.

The store buffer is a data area managed by PHIGS. While the application is responsible for creating the inital buffer through a call to CREATE STORE, PHIGS manages this area such that there is sufficient memory for the specific inquiry. The data record within the store buffer is accessed by the pointer pointed to by out.

func_id
An integer specifying which escape function to perform. The recognized identifiers are:

−1PUESC_ERRSYNCError Synchronization
−2PUESC_DPYINFOInquire x_tool’s drawable and display
−3PUESC_IGNORE_DC_ERRORSDisable DC bounds checking

in_data
A pointer to a Pescape_in_data union containing the input data record required by the escape function specified in the func_id parameter. Pescape_in_data is defined in phigs.h as follows:

typedef union {
/∗ Implementation dependent escape input data records. ∗/
struct {
Perrsyncsync_on;
} escape_in_u1;
struct {
Pintws_id;
} escape_in_u2;
struct {
Pintignore_DC_errors; /∗ ignore subsequent DC errors if non-zero ∗/
} escape_in_u3;
} Pescape_in_data;

C Output Parameters

out_data
A pointer to a pointer to a Pescape_out_data union. If the specified escape function returns information, PHIGS copies a pointer to the requested information to the variable pointed to by this parameter. This parameter is unused if the escape function does not return any information. Pescape_out_data is defined in phigs.h as follows:

typedef union {
/∗ Implementation dependent escape input data records. ∗/
struct {
    Pint err_ind; /∗ error indicator ∗/
    Display∗display;/∗ may be returned as NULL ∗/
    XIDdrawable_id;
    XID      input_overlay_id;/∗ will be 0 if category not OUTIN ∗/
    char       ∗display_name;
} escape_out_u2;
} Pescape_out_data;

ERRORS

002Ignoring function, function requires state (PHOP, ∗, ∗, ∗)

350Warning, the specified escape is not available on one or more workstations in this implementation. The escape will be processed by those workstations on which it is available

351Ignoring function, one of the fields within the escape data record is in error

Museum