NAME

       gescape - Provide "Escape" mechanism for non-standard GKS features

DESCRIPTION

       gescape  (Escape)  - provides a standard way of implementing nonstandard GKS features.  NCAR GKS has only
       two user-accessible escape functions defined: one for changing the name of a  metafile  and  another  for
       pausing in an X window.

SYNOPSIS

       #include <ncarg/gks.h>

       void   gescape(Gint   func_id,   const   Gescape_in_data  *in_data,  Gstore  *store_data,Gescape_out_data
       **out_data);

DESCRIPTION

       func_id     (Input) - A function identifier specifying the requested  activity.   The  legal  values  for
                   func_id  are  "-1391"  for changing a metafile name and "-1396" for effecting a pause in an X
                   window.

       in_data.escape_r1.size
                   (size_t, Input) - Size of the input data record array (for input data record, see below).

       in_data.escape_r1.data
                   (void *, Input) - Input data record.  For calls to gescape with func_id equal  to  -1391  the
                   input  data  record  should  be  a character string containing the desired metafile name left
                   justified and blank filled; for calls to gescape with func_id equal to -1396 the  input  data
                   record  should  be a character string containing the workstation identifier encoded as a five
                   character number.

       store_data  (void *, Input) - Storage for output data.  Not currently in use for NCAR GKS.

       out_data.escape_r1.size
                   (size_t, Output) - Size of the output data record array.  Not currently in use for NCAR GKS.

       out_data.escape_r1.data
                   (void *, Output) -  Output data record.    Not currently in use for NCAR GKS.

USAGE

       The sizes of the data records must always be at least "1" in value.

EXAMPLES

       gescape can be used to dynamically change the name of an output metafile and to do so one should use  the
       calls  gopen_gks  and  gopen_ws  instead  of  c_opngks.   If you are using c_opngks, see the man page for
       setusv(3NCARG) for changing the name of the metafile.

       To change the name of the output metafile inside your program, you should make  a  call  similar  to  the
       following:

              int str_len = 12;
              Gescape_in_data in_data;
              gopen_gks("stdout",0);
              in_data.escape_r1.data = (Gdata *)malloc(str_len*sizeof(char));
              strcpy(in_data.escape_r1.data, "new.cgm.name" );
              in_data.escape_r1.size = str_len;
              gescape(-1391,&in_data,NULL,NULL);

       The  call  to gescape to change the metafile name must always occur just before the call to gopen_ws that
       opens a CGM workstation.  Setting the environment variable  NCARG_GKS_OUTPUT  overrides  any  attempt  to
       change the name of an output metafile via a gescape call.

       See  the  "User's  Guide for NCAR GKS-0A Graphics" for a more complete example of changing metafile names
       from within a code.

       Here is an example of a piece of code that will create an X window, draw a line, and then  pause  waiting
       for a mouse click or a key click.

              Gescape_in_data in_data;
              int str_len = 5;

              gopen_gks("stdout",0);
              gopen_ws(3,NULL,8);
              gactivate_ws(3);
              c_line(0.,0.,1.,1.);
              c_sflush();
              in_data.escape_r1.data = (Gdata *)malloc(str_len*sizeof(char));
              strcpy(in_data.escape_r1.data, "    3" );
              in_data.escape_r1.size = str_len;
              gescape(-1396,&in_data,NULL,NULL);

              gdeactivate_ws(3);
              gclose_ws(3);
              gclose_gks();

       The  functions  c_frame  and c_ngpict are in general much easier to use and more flexible than the direct
       ESCAPE call for pausing in an X window.  It is suggested that those functions be used.

ACCESS

       To use the GKS C-binding routines, load the ncarg_gks and ncarg_c libraries.

SEE ALSO

       Online: setusv(3NCARG), frame(3NCARG), ngpict(3NCARG), gks(3NCARG), ncarg_gks_cbind(3NCARG)

       Hardcopy: User's Guide for NCAR GKS-0A Graphics; NCAR Graphics Fundamentals, UNIX Version

COPYRIGHT

       Copyright (C) 1987-2009
       University Corporation for Atmospheric Research
       The use of this Software is governed by a License Agreement.

UNIX                                               March 1993                                    GESCAPE(3NCARG)