GESCAPE(3NCARG)

💅 GESCAPE — the escape hatch, bestie

okay so this is gescape, aka Escape, from the NCAR Graphics manual (3NCARG, section 3, the library-calls girlies). It's the standard lil doorway for doing nonstandard GKS stuff — the things the spec didn't plan for. And ngl, NCAR GKS only has two user-accessible escape functions wired up: one for renaming a metafile and one for pausing inside an X window. That's it. That's the whole menu. 🎀

---

✨ 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) the function identifier, i.e. "which escape are we doing today". The legal values are literally just two: "-1391" for changing a metafile name, and "-1396" for making a pause happen in an X window. Those are the only two. No secret menu. 🙈
• in_data.escape_r1.size — (size_t, Input) the size of the input data record array (and yeah, the input data record itself is described right below, keep scrolling bestie).
• in_data.escape_r1.data — (void *, Input) the input data record. 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, okay? And if you're calling with func_id equal to -1396, the record should be a character string holding the workstation identifier, encoded as a five character number. Five. Characters. Not four, not six. 💀
• store_data — (void *, Input) storage for output data. Not currently in use for NCAR GKS. Iconic of it to be here though. 👑
• out_data.escape_r1.size — (size_t, Output) the size of the output data record array. Not currently in use for NCAR GKS.
• out_data.escape_r1.data — (void *, Output) the output data record. Not currently in use for NCAR GKS. (Are we sensing a theme? We are. 🍓)

---

🌸 USAGE 🌸

The sizes of the data records must always be at least "1" in value. Like, always always. Don't be out here passing zero, it's not the vibe.

---

💖 EXAMPLES 💖

So gescape can be used to dynamically change the name of an output metafile, and to pull that off you should use the calls gopen_gks and gopen_ws instead of c_opngks. If you are using c_opngks, go read the man page for setusv(3NCARG) for changing the name of the metafile — that's your girl for that situation.

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

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 that changes the metafile name must always happen just before the call to gopen_ws that opens a CGM workstation. Timing is everything, bestie. Also: setting the environment variable NCARG_GKS_OUTPUT overrides any attempt to change the name of an output metafile via a gescape call. So if you set that and then wonder why your rename didn't take — that's why. 😭

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

Now 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:

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

💡 Real talk though: 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. Like, genuinely, save yourself the trouble. 🫶

---

🧚 ACCESS 🧚

To use the GKS C-binding routines, load the ncarg_gks and ncarg_c libraries. Both. Load both. ✨

---

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

---

okay that's the whole page, you ate it, go rename a metafile responsibly 💜 this was the UNIX version of GESCAPE(3NCARG), dated March 1993 — yeah, she's vintage, and she's still serving. bye bestie, mwah 🎀✨