NGREOP(3NCARG)

📦 version 6.6.2, in epel 9, fedora 43, fedora 44

💖 NGREOP — bestie, we're reopening a metafile 💖

okay so real talk, this is a page from the NCAR Graphics manual (the 3NCARG corner of the world), and it's about NGREOP, which is the little subroutine that reopens an existing NCAR Graphics metafile for appending. like, you already made a metafile, you closed it (maybe only temporarily, no drama), and now you wanna go back in and add more stuff. that's the whole vibe. ✨

🌸 SYNOPSIS 🌸

CALL NGREOP(WKID, CONID, ITYPE, FNAME, IOPT, IAT, RAT,
            NCOLRS, NSTART, CTAB)

🦋 C-BINDING SYNOPSIS 🦋

#include <ncarg/ncargC.h>
#include <ncarg/gks.h>

void c_ngsrat(int wkid, int conid, int itype, char *fname,
              int iopt, int *iat, float *rat, int ncolrs,
              int nstart, Gcolr_rep *ctab)

(yes bestie, the C binding synopsis in the source really does say c_ngsrat up there, we do not touch it, we do not fix it, we simply respect the lore 💅)

✨ DESCRIPTION ✨

okay so here's the whole cast of arguments, one by one, no skipping, no summarising, we're doing this properly:

  • WKID — an input variable of type INTEGER, and it's the workstation identifier that this freshly reopened metafile will be known by from now on. important tea: it does not have to match the workstation identifier that was used to create the original metafile. glow-up, honestly. 👑
  • CONID — an input variable of type INTEGER specifying the connection identifier.
  • ITYPE — an input variable of type INTEGER specifying the workstation type. rn the only valid value is "1". and listen, this subroutine may be augmented in the future to accommodate PostScript files, so keep an eye out. 🔭
  • FNAME — an input variable of type CHARACTER specifying the filename of the metafile being opened for appending.
  • IOPT — an input variable of type INTEGER that says what you actually want to happen. choose your fighter:
    • = 0 — reestablish the color table only (using the color table in the argument CTAB described below). heads up though: the attributes of the reopened workstation get set to default values, and they may well be out of sync with the current GKS attributes. lowkey chaotic. 😬
    • = 1 — reestablish the color table and GKS state (that GKS state coming in via the arguments IAT and RAT described below). the state values will not be flushed to the metafile.
    • = 2 — reestablish the color table and GKS state and flush the GKS state values to the metafile.
    • = 3 — reestablish the color table and flush the current GKS state values to the metafile (not the values in IAT and RAT). values to the metafile.
if IOPT equals 1 or 2, then IAT and RAT must be supplied. otherwise, not. that's the rule bestie, no cap.
  • IAT — an input array of type INTEGER dimensioned for 14, holding GKS integer state variables like this:
    • IAT( 1) = Clip indicator
    • IAT( 2) = Line type
    • IAT( 3) = Polyline color index
    • IAT( 4) = Marker type
    • IAT( 5) = Polymarker color index
    • IAT( 6) = Text font
    • IAT( 7) = Text precision
    • IAT( 8) = Text color index
    • IAT( 9) = Text path
    • IAT(10) = Text horizontal alignment
    • IAT(11) = Text vertical alignment
    • IAT(12) = Fill area interior style
    • IAT(13) = Fill are style index
    • IAT(14) = Fill area color index
  • RAT — an input array of type REAL dimensioned for 7, holding the REAL GKS attribute settings like this:
    • RAT( 1) = Linewidth scale factor
    • RAT( 2) = Marker scale factor
    • RAT( 3) = Character expansion factor
    • RAT( 4) = Character spacing
    • RAT( 5) = Character height in world coordinates
    • RAT( 6) = Character up vector, X component in world coordinates
    • RAT( 7) = Character up vector, Y component in world coordinates
  • NCOLRS — an input variable of type INTEGER specifying the number of colors in the color table supplied in the argument CTAB, described below. fun fact: NCOLRS can be 0. zero. nothing. empty. 🫙
  • NSTART — an input variable of type INTEGER specifying the color index associated with the first color in the color table CTAB (all the other color indices get filled in, in sequence). for example, if NCOLRS = 3 and NSTART = 4, then the color values defined in CTAB would be used to define color indices 4, 5, and 6. math is mathing. 🔢
  • CTAB — in the FORTRAN version of this routine, a two-dimensional input array of type REAL dimensioned CTAB(3,NCOLRS); in the C version of this routine, a one-dimensional input array of type Gcolr_rep dimensioned ctab[ncolrs]. it specifies a color table used to initialize the reopened metafile. and no, this color table does not necessarily have to agree with the color table that was in effect when the original metafile was created. freedom. 🌈

🎀 USAGE 🎀

the most common usage of NGREOP would be in conjunction with usage of NGSRAT and NGMFTC. here's the routine: NGMFTC would be used to temporarily close a metafile, and NGSRAT used to save the state of the GKS primitive attributes at the time of the close. then, to reopen that temporarily closed metafile, you'd call NGREOP with the attribute settings you previously saved and a setting of IOPT of 2. and honestly? NGMFTC can be used to temporarily close a metafile any time after it has been opened, even in the middle of a picture. mid-picture closure. iconic behavior. 😌

now, crucial detail, don't skip this one: NGREOP only reopens the metafile and does not activate it. so it will be necessary to call GACWK before sending graphics primitives to the reopened metafile. it's giving "you have to knock before you enter." 🚪

and also, NGREOP can be used to reopen a previously created metafile too — either one created in an independent job step, or one created in the same job step. flexible queen. 💅

🔥 EXAMPLES 🔥

the following sequence:

CALL NGMFTC(1)
CALL NGSRAT(2, IAT, RAT)

  ... do stuff

CALL NGREOP(CALL NGREOP(1, 2, 1, 'gmeta1', 2, IAT, RAT,
            NCOLS, 0, CTAB)

would temporarily close the metafile with workstation ID of 1 (in this case a metafile with name "gmeta1") and save the GKS state variables at the time of the close. then the call to NGREOP would reopen the metafile for appending. and yes, that example really is written like that in the original, we reproduce it faithfully, character for character, it's part of the heritage now. 🏛️

use the ncargex command to see the following relevant example: pgkex27. go look at it, it's cute.

💜 ACCESS 💜

to use NGREOP or c_ngreop, load the NCAR Graphics libraries ncarg, ncarg_gks, and ncarg_c — preferably in that order. order matters bestie, trust. 🫶

🌟 MESSAGES 🌟

NGREOP issues the same messages as those issued by GOPWK. same energy, different subroutine.

👑 SEE ALSO 👑

Online: ngmftc(3NCARG), ngsrat(3NCARG)

Online URL: http://ngwww.ucar.edu/ngdoc/ng/gks/gkshome.html

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, you understood it, you're literally a metafile-appending legend now. this was the NCAR Graphics manual, NGREOP(3NCARG), straight out of October 1996, and the source line says UNIX at the bottom. slay, mwah, go append something beautiful. 💖✨🎀🦋🌸💅

📦 where this page comes from