1CGM_TOOLS(1NCARG)                NCAR GRAPHICS               CGM_TOOLS(1NCARG)
2
3
4

NAME

6       CGM_open,  CGM_close,  CGM_lseek,  CGM_read,  CGM_write, CGM_directory,
7       CGM_freeDirectory, CGM_printDirectory, CGM_getInstr, CGM_flushGetInstr,
8       CGM_putInstr, CGM_flushOutputInstr, CGM_initMetaEdit, CGM_termMetaEdit,
9       CGM_copyFrames,   CGM_deleteFrames,   CGM_mergeFrames   CGM_moveFrames,
10       CGM_readFrames,  CGM_valid, CGM_writeFile, CGM_writeFrames, CGM_append‐
11       Frames - Computer Graphics Metafile operations
12

SYNTAX

14       #include <cgm_tools.h>
15
16       Cgm_fd CGM_open(metafile, size, flags, mode)
17       char *metafile;
18       unsigned size;
19       int flags;
20       int mode;
21
22       int CGM_close(cgm_fd)
23       Cgm_fd cgm_fd;
24
25       int CGM_lseek(cgm_fd, offset)
26       Cgm_fd cgm_fd;
27       int offset;
28
29       int CGM_read(cgm_fd, buf)
30       Cgm_fd cgm_fd;
31       unsigned char *buf;
32
33       int CGM_write(cgm_fd, buf)
34       Cgm_fd cgm_fd;
35       unsigned char *buf;
36
37       Directory *CGM_directory(cgm_fd)
38       Cgm_fd cgm_fd;
39
40       void CGM_freeDirectory(dir)
41       Directory *dir;
42
43       void CGM_printDirectory(dir)
44       Directory *dir;
45
46       int CGM_getInstr(cgm_fd, instr)
47       Cgm_fd cgm_fd;
48       Instr *instr;
49
50       void CGM_flushGetInstr(cgm_fd)
51       Cgm_fd cgm_fd;
52
53       int CGM_putInstr(cgm_fd, instr)
54       Cgm_fd cgm_fd;
55       Instr *instr;
56
57       int CGM_flushOutputInstr(cgm_fd)
58       Cgm_fd cgm_fd;
59
60       Directory *CGM_initMetaEdit (metafile, size)
61       char *metafile;
62       unsigned int size;
63
64       int CGM_termMetaEdit()
65
66       Directory *CGM_copyFrames(start, num, target )
67       unsigned int start;
68       int num;
69       unsigned int target;
70
71       Directory *CGM_deleteFrames(start, num)
72       unsigned int start,
73       num;
74
75       Directory *CGM_mergeFrames(bottom, top)
76       unsigned bottom, top;
77
78       Directory *CGM_moveFrames (start, num, target)
79       unsigned int start, num, target;
80
81       Directory *CGM_readFrames(metafile, start, num, target, size)
82       char *metafile;
83       unsigned int start;
84       int num;
85       unsigned int target, size;
86
87       int *CGM_validCGM(metafile)
88       char *metafile;
89
90       int CGM_writeFile(metafile)
91       char *metafile;
92
93       int CGM_writeFrames(metafile, start, num)
94       char *metafile;
95       unsigned start, num;
96
97       int CGM_appendFrames(metafile, start, num)
98       char *metafile;
99       unsigned start, num;
100

DESCRIPTION

102       The argument cgm_fd refers to a valid file descriptor created for read‐
103       ing  or  writing,  as appropriate by CGM_open. CGM_read, CGM_directory,
104       CGM_getInstr and CGM_flushGetInstr require a file descriptor  open  for
105       reading.  CGM_write,  CGM_getInstr,CGM_flushGetInstr  and CGM_flushOut‐
106       putInstr require a Cgm_fd open for  writing.  CGM_close  and  CGM_lseek
107       will accept any valid Cgm_fd.
108
109       The  size argument refers to the CGM record size in bytes.  For an NCAR
110       CGM this value is 1440.
111
112       buf is a pointer to user allocated memory of size  size.  This  storage
113       will  be  used for buffering input and output of CGM_read and CGM_write
114       respectively.
115
116       The dir argument is a pointer to a  Directory  structure  created  with
117       CGM_directory  or  CGM_initMetaEdit.   dir  is  a private resource that
118       should NOT be directly modified by  the  user.  A  set  of  convenience
119       macros is provided for this purpose in cgm_tools.h.
120
121       The  start,  num and target arguments are used to address frame numbers
122       in a metafile being edited with one of  the  commands:  CGM_copyFrames,
123       CGM_deleteFrames,  CGM_readFrames,  CGM_moveFrames, CGM_writeFrames and
124       CGM_mergeFrames.  The start argument is the first frame in  a  sequence
125       of  num frame(s) to perform the editing operation on. target is similar
126       to start and is used by commands that require two frame addresses  such
127       as copy. Addressing begins at zero.
128
129       CGM_open
130              This  command  is  modeled  after the unix open command. It will
131              open a CGM for reading or writing  as  specified  by  the  flags
132              argument and return a Cgm_fd file descriptor. The flags and open
133              parameters are passed directly on to the  system  open  command.
134              For a detailed explanation of these two arguments see open(2).
135
136       CGM_close
137              Delete a file descriptor. The inverse of CGM_open. See close(2).
138
139       CGM_read
140              CGM_read  attempts to read size bytes from the object referenced
141              through the descriptor cgm_fd. size is set at  the  creation  of
142              cgm_fd  by  CGM_open.  CGM_read returns the number of bytes suc‐
143              cessfully read. A zero is returned on EOF and a negative  number
144              implies  an error occurred.  The unix system call read is called
145              by CGM_read. See read(2).
146
147       CGM_write
148              Attempts to write a single record of size bytes  from  buf  from
149              the  object referenced by cgm_edit where size is the record size
150              parameter provided at the creation of cgm_fd. write returns  the
151              number  of  bytes successfully written. A negative return number
152              implies an error occurred.  The unix system call write is called
153              by CGM_write. See write(2).
154
155       CGM_lseek
156              Advance  the  file  pointer of cgm_fd to offset bytes. Upon suc‐
157              cessful completion the current file pointer offset is  returned.
158              A negative return value is an error.  The unix system call lseek
159              is called by CGM_lseek. See lseek(2).
160
161       CGM_directory
162              Create a table  of  contents  for  the  metafile  referenced  by
163              cgm_fd.   Return  a pointer to this table of type Directory. The
164              contents of the directory include number of metafiles, number of
165              frames,  record  offset for each frame, frame length in records,
166              optional frame description and metafile status. These fields are
167              meant  to be read only and should only be referenced by the con‐
168              venience macros provided  in  cgm_tools.h.  A  NULL  pointer  is
169              returned on failure.
170
171       CGM_freeDirectory
172              Free memory allocated to a directory created by CGM_directory or
173              CGM_initMetaEdit.
174
175       CGM_printDirectory
176              Print the contents of a directory pointed to by dir to the stan‐
177              dard output.
178
179       CGM_getInstr,
180              Fetch  the  next instruction in file referenced by cgm_edit  and
181              convert  it  into  a  usable  format  pointed   to   by   instr.
182              CGM_getInstr  provides an interface to the metafile for extract‐
183              ing CGM elements. The user need not be concerned with the binary
184              format of the metafile. The fields of the Instr are as described
185              in cgm_tools.h.  The user should note that the maximum allowable
186              data  length returned in a single invocation is 32760 bytes. The
187              CGM standard allows upto 32767 bytes to be stored  in  a  single
188              instruction. But 32767 is not a nice number to work with. Should
189              the data length of a CGM instruction exceed 32760  bytes,  indi‐
190              cated   by  the  boolean  more  flag,  the  next  invocation  of
191              CGM_getInstr will return the remaining data upto the same limit.
192              And  so  on... CGMgetInstrrequires a valid Cgm_fd open for read‐
193              ing. For a description on CGM see the ANSI standard.
194
195       CGM_flushGetInstr
196              Flush the input buffer used by CGM_getInstr.  CGM_getInstr  buf‐
197              fers  the  contents of the CGM and only performs actual reads as
198              necessary. If the user desires other then sequential read access
199              to  a  CGM it becomes necessary to flush the input buffer before
200              reading from a new location.
201
202       CGM_putInstr
203              The analog to CGM_getInstr. This function buffers  CGM  instruc‐
204              tions  to  be  written  to a CGM referenced by cgm_fd. Again the
205              user need not be concerned with the binary format of  the  file.
206              Writes  are performed sequentially in record size size as speci‐
207              fied during the creation of cgm_fd. The same  data  length  con‐
208              straints  that are placed on CGM_getInstr hold for CGM_putInstr.
209              If the user wants to output  instructions  with  a  data  length
210              greater  than  32760  bytes then the data must be broken up into
211              blocks no greater than this size. The user  must  also  set  the
212              boolean  more  flag  in  the  Instr. cgm_fd must be a valid file
213              descriptor open for writing. For a description of the fields  of
214              the Instr see the file cgm_tools.h.
215
216       CGM_flushOutputInstr
217              Flush the output buffer used by CGM_putInstr for the file refer‐
218              enced by cgm_fd. It is necessary to explicitly flush the  output
219              buffer  used  by  CGM_putInstr  before the file is closed or any
220              random access is performed. Otherwise not all CGM elements  will
221              actually get written.
222
223       CGM_initMetaEdit
224              Initialize  a  metafile  for editing. This is the initialization
225              routine for the higher level editing routines contained in  this
226              package:   CGM_copyFrames,   CGM_deleteFrames,   CGM_readFrames,
227              CGM_moveFrames, CGM_writeFile, CGM_writeFrames,  and  CGM_merge‐
228              Frames.  These routines only work on one metafile at a time (the
229              one named in CGM_initMetaEdit. Invoking this routine for a  sec‐
230              ond  time  without  explicitly  saving any changes will have the
231              effect of loading a new file and discarding all changes made  in
232              the  previous file.  CGM_initMetaEdit and all proceeding editing
233              functions that make changes to the file return a  pointer  to  a
234              Directory  as  a convenience that allows the user to examine the
235              state of the file.  The contents of the  directory  are  private
236              and  should  NOT be changed by the user. A set of macros is pro‐
237              vided in cgm_tools.h to be used for retrieving  the  directory's
238              contents.  Note:  no  changes are actually made to the edit file
239              unless it is explicitly overwritten with either CGM_writeFile or
240              CGM_writeFrames.
241
242       CGM_termMetaEdit
243              Terminate  the  editing  session  started with CGM_initMetaEdit.
244              This routine should be called after  any  editing  changes  have
245              been  saved,  if  desired  to  save them, and before exiting the
246              editing session.  CGM_termMetaEdit frees valuable resources.
247
248       CGM_copyFrames
249              Copy num frames beginning with start to the frame  addressed  by
250              target. If target is already occupied then the source frames are
251              inserted in its place while the target frame, and all proceeding
252              frames,  are advanced. CGM_copy operates on the file initialized
253              by CGM_initMetaEdit (the edit file). On successful completion  a
254              pointer  to  the  current directory is returned. On error a NULL
255              pointer is returned.
256
257       CGM_deleteFrames
258              Delete num frames from the edit file starting with frame  start.
259              On  successful  completion a pointer to the current directory is
260              returned. On error a NULL pointer is returned.
261
262       CGM_mergeFrames
263              Overwrite the contents of frame addressed bottom with the  union
264              of  the  frame at location bottom and the frame at location top.
265              The effect of this command is  equivalent  to  drawing  the  top
266              frame  on top of the bottom frame. It is not a union in the true
267              sense of the word.  On successful completion a  pointer  to  the
268              current  directory  is  returned.  On  error  a  NULL pointer is
269              returned.
270
271       CGM_moveFrames
272              Move a block of num frames from the edit file starting with with
273              frame start to the position occupied by frame target On success‐
274              ful completion a pointer to the current directory  is  returned.
275              On error a NULL pointer is returned.
276
277       CGM_readFrames
278              Read  num  frames  from metafile file starting with frame start.
279              Insert the frames at address target in the edit file.   On  suc‐
280              cessful  completion  a  pointer  to  the  current  directory  is
281              returned. On error a NULL pointer is returned.
282
283       CGM_validCGM
284              Determine whether a file is a valid NCAR CGM or not. This  func‐
285              tion performs a few simple diagnostics in an effort to determine
286              whether a given file is in the NCAR CGM format. The  tests  per‐
287              formed  are not rigorous and it is conceivable that the informa‐
288              tion retrieved is incorrect.  A return of 1  indicates  a  valid
289              NCAR CGM.  A return of 0 indicates the file is not a NCAR CGM. A
290              return of -1 indicates an error occurred and the global variable
291              `errno' is set accordingly.
292
293       CGM_writeFile
294              Write  the  entire  contents  of  the current edit file to file.
295              CGM_writeFile returns the integer one on success and a  negative
296              number on failure.
297
298       CGM_writeFrames
299              Write  a  block of num frames starting with frame start to file.
300              The source frames come from the edit file.  Note: CGM frames are
301              contained  in  a  wrapper made up of CGM delimiter elements. The
302              file created by CGM_writeFrames will use the wrapper provided by
303              the current edit file. Thus if a file foo contains n frames that
304              are read into an editing session with a file goo and then  these
305              same  frames are written out to a file zoid, zoid may or may not
306              be the same as the original foo.   CGM_writeFrames  returns  the
307              integer one on success and a negative number on failure.
308
309       CGM_appendFrames
310              Append  a block of num frames starting with frame start to file.
311              file must already exist and be a valid  NCAR  CGM.   CGM_append‐
312              Frames  returns the integer one on success and a negative number
313              on failure.
314

SEE ALSO

316       ANSI X3.122 Computer Graphics Metafile for the Storage and Transfer  of
317       Picture Description Information.
318

BUGS

320       CGMs  with  more  the  one metafile stored in the are not guaranteed to
321       work.
322
323       Should not have to explicitly flush the output buffer for CGM_getInstr.
324       This should be handled automatically when the file is closed.
325
327       Copyright (C) 1987-2007
328       University Corporation for Atmospheric Research
329
330       This  documentation  is  free  software; you can redistribute it and/or
331       modify it under the terms of the GNU General  Public  License  as  pub‐
332       lished  by  the  Free  Software  Foundation;  either  version  2 of the
333       License, or (at your option) any later version.
334
335       This software is distributed in the hope that it will  be  useful,  but
336       WITHOUT  ANY  WARRANTY;  without  even  the  implied  warranty  of MER‐
337       CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU  General
338       Public License for more details.
339
340       You should have received a copy of the GNU General Public License along
341       with this software; if not, write  to  the  Free  Software  Foundation,
342       Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
343
344
345
346
347NCARG                            January 1993                CGM_TOOLS(1NCARG)
Impressum