GESCAPE(3NCARG)

✨ NAME ✨

gescape — the lil escape hatch for all your non-standard GKS needs, bestie 💅

---

🦋 DESCRIPTION 🦋

okay so picture this: gescape (aka Escape) is the standard way to do the non-standard stuff in GKS. it's giving "official backdoor" energy. and NCAR GKS is lowkey minimal about it — there are only two user-accessible escape functions defined at all:

• one for changing the name of a metafile 📝
• one for pausing inside an X window ⏸️

that's it. that's the whole menu. no cap.

---

🌸 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 (yes, again, the parameters this time) 👑

• func_id (Input) — the function identifier telling gescape which activity you want. the legal values are "-1391" for changing a metafile name, and "-1396" for effecting a pause in an X window. memorize those two numbers, they're your besties fr fr.
• in_data.escape_r1.size (size_t, Input) — size of the input data record array (the input data record is described right below, keep scrolling 🫶).
• in_data.escape_r1.data (void *, Input) — the input data record itself. here's the tea:
  • if you're calling gescape with func_id equal to -1391, this record should be a character string holding the metafile name you want, left justified and blank filled ✨
  • if you're calling gescape with func_id equal to -1396, this record should be a character string holding the workstation identifier, encoded as a five character number.
• store_data (void *, Input) — storage for output data. not currently in use for NCAR GKS. she's just sitting there, being a vibe 🌈
• out_data.escape_r1.size (size_t, Output) — size of the output data record array. also not currently in use for NCAR GKS. 💀
• out_data.escape_r1.data (void *, Output) — the output data record. yep, you guessed it: not currently in use for NCAR GKS. three for three.

---

💖 USAGE 💖

the sizes of the data records must always be at least "1" in value. don't come at her with a zero, she will not be accepting that. 🙈

---

🎀 EXAMPLES 🎀

so gescape can dynamically change the name of an output metafile — iconic — and to pull that off you should use the calls gopen_gks and gopen_ws instead of c_opngks. but if you are using c_opngks, no worries bestie, go check 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 this one:

       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. timing is everything, periodt.

🚨 also: setting the environment variable NCARG_GKS_OUTPUT overrides any attempt to change the name of an output metafile via a gescape call. she said "I'm the main character now."

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

okay and here's 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. obsessed with the drama of it:

       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();

ngl, 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. take the easy road, queen. 👑

---

🔥 ACCESS 🔥

to use the GKS C-binding routines, load the ncarg_gks and ncarg_c libraries. load 'em up, you got this. 💪

---

🌈 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.

---

and that's the whole page, bestie!! this little love letter dropped way back in March 1993 under the UNIX manual, straight from NCAR GRAPHICS — GESCAPE(3NCARG), slay forever. go forth and escape responsibly 🦋✨💖