Ubuntu Manpage: CGM_open, CGM_close, CGM_lseek, CGM_read, CGM_write, CGM_directory, CGM

NAME

       CGM_open,  CGM_close,  CGM_lseek,  CGM_read,  CGM_write, CGM_directory, CGM_freeDirectory,
       CGM_printDirectory, CGM_getInstr, CGM_flushGetInstr,  CGM_putInstr,  CGM_flushOutputInstr,
       CGM_initMetaEdit,   CGM_termMetaEdit,  CGM_copyFrames,  CGM_deleteFrames,  CGM_mergeFrames
       CGM_moveFrames,     CGM_readFrames,     CGM_valid,     CGM_writeFile,     CGM_writeFrames,
       CGM_appendFrames - Computer Graphics Metafile operations

SYNTAX

       #include <cgm_tools.h>

       Cgm_fd CGM_open(metafile, size, flags, mode)
       char *metafile;
       unsigned size;
       int flags;
       int mode;

       int CGM_close(cgm_fd)
       Cgm_fd cgm_fd;

       int CGM_lseek(cgm_fd, offset)
       Cgm_fd cgm_fd;
       int offset;

       int CGM_read(cgm_fd, buf)
       Cgm_fd cgm_fd;
       unsigned char *buf;

       int CGM_write(cgm_fd, buf)
       Cgm_fd cgm_fd;
       unsigned char *buf;

       Directory *CGM_directory(cgm_fd)
       Cgm_fd cgm_fd;

       void CGM_freeDirectory(dir)
       Directory *dir;

       void CGM_printDirectory(dir)
       Directory *dir;

       int CGM_getInstr(cgm_fd, instr)
       Cgm_fd cgm_fd;
       Instr *instr;

       void CGM_flushGetInstr(cgm_fd)
       Cgm_fd cgm_fd;

       int CGM_putInstr(cgm_fd, instr)
       Cgm_fd cgm_fd;
       Instr *instr;

       int CGM_flushOutputInstr(cgm_fd)
       Cgm_fd cgm_fd;

       Directory *CGM_initMetaEdit (metafile, size)
       char *metafile;
       unsigned int size;

       int CGM_termMetaEdit()

       Directory *CGM_copyFrames(start, num, target )
       unsigned int start;
       int num;
       unsigned int target;

       Directory *CGM_deleteFrames(start, num)
       unsigned int start,
       num;

       Directory *CGM_mergeFrames(bottom, top)
       unsigned bottom, top;

       Directory *CGM_moveFrames (start, num, target)
       unsigned int start, num, target;

       Directory *CGM_readFrames(metafile, start, num, target, size)
       char *metafile;
       unsigned int start;
       int num;
       unsigned int target, size;

       int *CGM_validCGM(metafile)
       char *metafile;

       int CGM_writeFile(metafile)
       char *metafile;

       int CGM_writeFrames(metafile, start, num)
       char *metafile;
       unsigned start, num;

       int CGM_appendFrames(metafile, start, num)
       char *metafile;
       unsigned start, num;

DESCRIPTION

The argument cgm_fd refers to a valid file descriptor created for reading or writing, as
appropriate by CGM_open. CGM_read, CGM_directory, CGM_getInstr and CGM_flushGetInstr
require a file descriptor open for reading. CGM_write, CGM_getInstr,CGM_flushGetInstr and
CGM_flushOutputInstr require a Cgm_fd open for writing. CGM_close and CGM_lseek will
accept any valid Cgm_fd.

The size argument refers to the CGM record size in bytes. For an NCAR CGM this value is
1440.

buf is a pointer to user allocated memory of size size. This storage will be used for
buffering input and output of CGM_read and CGM_write respectively.

The dir argument is a pointer to a Directory structure created with CGM_directory or
CGM_initMetaEdit. dir is a private resource that should NOT be directly modified by the
user. A set of convenience macros is provided for this purpose in cgm_tools.h.

The start, num and target arguments are used to address frame numbers in a metafile being
edited with one of the commands: CGM_copyFrames, CGM_deleteFrames, CGM_readFrames,
CGM_moveFrames, CGM_writeFrames and CGM_mergeFrames. The start argument is the first
frame in a sequence of num frame(s) to perform the editing operation on. target is similar
to start and is used by commands that require two frame addresses such as copy. Addressing
begins at zero.

CGM_open
This command is modeled after the unix open command. It will open a CGM for reading
or writing as specified by the flags argument and return a Cgm_fd file descriptor.
The flags and open parameters are passed directly on to the system open command.
For a detailed explanation of these two arguments see open(2).

CGM_close
Delete a file descriptor. The inverse of CGM_open. See close(2).

CGM_read
CGM_read attempts to read size bytes from the object referenced through the
descriptor cgm_fd. size is set at the creation of cgm_fd by CGM_open. CGM_read
returns the number of bytes successfully read. A zero is returned on EOF and a
negative number implies an error occurred. The unix system call read is called by
CGM_read. See read(2).

CGM_write
Attempts to write a single record of size bytes from buf from the object referenced
by cgm_edit where size is the record size parameter provided at the creation of
cgm_fd. write returns the number of bytes successfully written. A negative return
number implies an error occurred. The unix system call write is called by
CGM_write. See write(2).

CGM_lseek
Advance the file pointer of cgm_fd to offset bytes. Upon successful completion the
current file pointer offset is returned. A negative return value is an error. The
unix system call lseek is called by CGM_lseek. See lseek(2).

CGM_directory
Create a table of contents for the metafile referenced by cgm_fd. Return a pointer
to this table of type Directory. The contents of the directory include number of
metafiles, number of frames, record offset for each frame, frame length in records,
optional frame description and metafile status. These fields are meant to be read
only and should only be referenced by the convenience macros provided in
cgm_tools.h. A NULL pointer is returned on failure.

CGM_freeDirectory
Free memory allocated to a directory created by CGM_directory or CGM_initMetaEdit.

CGM_printDirectory
Print the contents of a directory pointed to by dir to the standard output.

CGM_getInstr,
Fetch the next instruction in file referenced by cgm_edit and convert it into a
usable format pointed to by instr. CGM_getInstr provides an interface to the
metafile for extracting CGM elements. The user need not be concerned with the
binary format of the metafile. The fields of the Instr are as described in
cgm_tools.h. The user should note that the maximum allowable data length returned
in a single invocation is 32760 bytes. The CGM standard allows upto 32767 bytes to
be stored in a single instruction. But 32767 is not a nice number to work with.
Should the data length of a CGM instruction exceed 32760 bytes, indicated by the
boolean more flag, the next invocation of CGM_getInstr will return the remaining
data up to the same limit, etc. CGMgetInstr requires a valid Cgm_fd open for
reading. For a description on CGM see the ANSI standard.

CGM_flushGetInstr
Flush the input buffer used by CGM_getInstr. CGM_getInstr buffers the contents of
the CGM and only performs actual reads as necessary. If the user desires other then
sequential read access to a CGM it becomes necessary to flush the input buffer
before reading from a new location.

CGM_putInstr
The analog to CGM_getInstr. This function buffers CGM instructions to be written to
a CGM referenced by cgm_fd. Again the user need not be concerned with the binary
format of the file. Writes are performed sequentially in record size size as
specified during the creation of cgm_fd. The same data length constraints that are
placed on CGM_getInstr hold for CGM_putInstr. If the user wants to output
instructions with a data length greater than 32760 bytes then the data must be
broken up into blocks no greater than this size. The user must also set the boolean
more flag in the Instr. cgm_fd must be a valid file descriptor open for writing.
For a description of the fields of the Instr see the file cgm_tools.h.

CGM_flushOutputInstr
Flush the output buffer used by CGM_putInstr for the file referenced by cgm_fd. It
is necessary to explicitly flush the output buffer used by CGM_putInstr before the
file is closed or any random access is performed. Otherwise not all CGM elements
will actually get written.

CGM_initMetaEdit
Initialize a metafile for editing. This is the initialization routine for the
higher level editing routines contained in this package: CGM_copyFrames,
CGM_deleteFrames, CGM_readFrames, CGM_moveFrames, CGM_writeFile, CGM_writeFrames,
and CGM_mergeFrames. These routines only work on one metafile at a time (the one
named in CGM_initMetaEdit. Invoking this routine for a second time without
explicitly saving any changes will have the effect of loading a new file and
discarding all changes made in the previous file. CGM_initMetaEdit and all
proceeding editing functions that make changes to the file return a pointer to a
Directory as a convenience that allows the user to examine the state of the file.
The contents of the directory are private and should NOT be changed by the user. A
set of macros is provided in cgm_tools.h to be used for retrieving the directory's
contents. Note: no changes are actually made to the edit file unless it is
explicitly overwritten with either CGM_writeFile or CGM_writeFrames.

CGM_termMetaEdit
Terminate the editing session started with CGM_initMetaEdit. This routine should
be called after any editing changes have been saved, if desired to save them, and
before exiting the editing session. CGM_termMetaEdit frees valuable resources.

CGM_copyFrames
Copy num frames beginning with start to the frame addressed by target. If target is
already occupied then the source frames are inserted in its place while the target
frame, and all proceeding frames, are advanced. CGM_copy operates on the file
initialized by CGM_initMetaEdit (the edit file). On successful completion a pointer
to the current directory is returned. On error a NULL pointer is returned.

CGM_deleteFrames
Delete num frames from the edit file starting with frame start. On successful
completion a pointer to the current directory is returned. On error a NULL pointer
is returned.

CGM_mergeFrames
Overwrite the contents of frame addressed bottom with the union of the frame at
location bottom and the frame at location top. The effect of this command is
equivalent to drawing the top frame on top of the bottom frame. It is not a union
in the true sense of the word. On successful completion a pointer to the current
directory is returned. On error a NULL pointer is returned.

CGM_moveFrames
Move a block of num frames from the edit file starting with with frame start to the
position occupied by frame target On successful completion a pointer to the current
directory is returned. On error a NULL pointer is returned.

CGM_readFrames
Read num frames from metafile file starting with frame start. Insert the frames at
address target in the edit file. On successful completion a pointer to the current
directory is returned. On error a NULL pointer is returned.

CGM_validCGM
Determine whether a file is a valid NCAR CGM or not. This function performs a few
simple diagnostics in an effort to determine whether a given file is in the NCAR
CGM format. The tests performed are not rigorous and it is conceivable that the
information retrieved is incorrect. A return of 1 indicates a valid NCAR CGM. A
return of 0 indicates the file is not a NCAR CGM. A return of -1 indicates an error
occurred and the global variable `errno' is set accordingly.

CGM_writeFile
Write the entire contents of the current edit file to file. CGM_writeFile returns
the integer one on success and a negative number on failure.

CGM_writeFrames
Write a block of num frames starting with frame start to file. The source frames
come from the edit file. Note: CGM frames are contained in a wrapper made up of
CGM delimiter elements. The file created by CGM_writeFrames will use the wrapper
provided by the current edit file. Thus if a file foo contains n frames that are
read into an editing session with a file goo and then these same frames are written
out to a file zoid, zoid may or may not be the same as the original foo.
CGM_writeFrames returns the integer one on success and a negative number on
failure.

CGM_appendFrames
Append a block of num frames starting with frame start to file. file must already
exist and be a valid NCAR CGM. CGM_appendFrames returns the integer one on success
and a negative number on failure.

BUGS

       CGMs with more the one metafile stored in the are not guaranteed to work.

       Should not have to explicitly flush the output buffer for CGM_getInstr.   This  should  be
       handled automatically when the file is closed.

COPYRIGHT

       Copyright (C) 1987-2009
       University Corporation for Atmospheric Research

       The use of this Software is governed by a License Agreement.

NAME

SYNTAX

DESCRIPTION

SEE ALSO

BUGS

COPYRIGHT