put_buf - Writes a 2-D buffer of data to an image

SYNTAX

#include "worgen.h"

int put_buf (buffer, nlbuf, nsbuf, nlav, nsav, slbuf, ssbuf, nlti, nsti, nextflg, band, bands, fdesc, host, dtype, wtype)

     unsigned char      *buffer;
     long               *nlbuf;
     long               *nsbuf;
     long               *nlav;
     long               *nsav;
     long               *slbuf;
     long               *ssbuf;
     long               *nlti;
     long               *nsti;
     long               *nextflg;
     long               *band;
     long               *bands;
     struct FDESC       **fdesc;
     char               *host;
     long               *dtype;
     long               *wtype;

PARAMETERS

buffer (input, byte array)

Buffer of data to be written. Buffer will be written as data of the type specified by 'dtype' below.

nlbuf (input, integer)

The total number of lines in 'buffer'.

nsbuf (input, integer)

The total number of samples in 'buffer'.

nlav (input, integer)

The number of lines of actual valid data in 'buffer'.

nsav (input, integer)

The number of samples of actual valid data in 'buffer'.

slbuf (input/output, integer)

The starting line of the data within the image.

ssbuf (input/output, integer)

The starting sample of the data within the image.

nlti (input, integer)

The number of lines in the total image.

nsti (input, integer)

The number of samples in the total image.

nextflg (input, integer)

Next flag. Allowable values are:

    = CREAT (-1):    This is the first call to put_buf() for this image
                     (NEW FILE).  The image will need to be created before
                     writing data.
    = INIT  (0):     This is the first call to put_buf() for this image at
                     this location (EXISTING FILE).  The image will need 
                     to be reopened before writing data.
    = CURNT (1):     Previous call to but_buf() has been made.  Write the 
                     data to the image without relocating.  Useful for
                     writing multiple bands without relocating within the 
                     image.
    = NEXT  (2):     Previous call to put_buf() has been made.  Relocate
                     to the 'next' data block (reopening the image if 
                     necessary), then write the block of data.

band (input, integer)

The number of the band within the image to write to.

bands (input, integer)

The total number of bands within the image.

fdesc (input, pointer to struct FDESC pointer)

Pointer to the file descriptor pointer obtained from c_eopenr().

host (input, character string, length(CMLEN))

Host name of the image file.

dtype (input, integer)

Data type. Allowable data types are:

    = EBYTE (1):     unsigned byte data
    = EWORD (2):     signed two byte data
    = ELONG (3):     signed four byte data
    = EREAL (4):     four byte floating point data
The parameter dtype specifies the data type of the buffer to be written.

wtype (input, integer)

Output data type. Convert the data and write it to the image as data of type 'wtype'. Allowable data types are:

    = SAME  (0):     no conversion necessary
    = EBYTE (1):     unsigned byte data
    = EWORD (2):     signed two byte data
    = ELONG (3):     signed four byte data
    = EREAL (4):     four byte floating point data

DESCRIPTION

The function put_buf() allows the application programmer to write an image using random access image I/O without implementing all of the low-level details.

Error checking is performed on the input parameters, where appropriate. The function put_buf() was designed such that the application programmer can write an entire image by simply making multiple calls to put_buf() writing consecutive blocks of data to an image. The origin, or beginning location of the data on the image must be specified. The 'nextflg' parameter determines whether to relocate to the 'next block' of data on the image before writing, or to write at the current origin. For the sake of efficiency, the application programmer may want to write multiple bands of data before moving on to the next data block (each call to put_buf() writes data to one band only). All of the image file opening, closing, and reopening is performed by put_buf() except the final closing of the file. The final closing of the image file must be done by the application programmer using the random access routine eclose().

If the application programmer is 'jumping around' within an image (writing blocks of data in a random fashion), the image must be closed by calling eclose() every time a move to a new location within the image is anticipated. Consequently, disk access time is optimized by taking advantage of the 'next' capability, and writing consecutive blocks of data.

When the programmer is taking advantage of the 'next flag' capability, the data blocks within an image are consecutive on a column-first basis (the first 'n' blocks are written to the first column, then the block at the top of the second column is written, etc). This sequencing scheme optimizes the efficiency of the low-level random image I/O functions.

Partial buffers of data may be written, when appropriate (when incomplete data blocks on the bottom or right-hand side of the image are encountered).

Warning:

samples in the buffer is less than the total number of samples allocated to the buffer, the values cannot reside in contiguous memory locations (i.e. there must by 'gaps' in the memory locations). This is because C stores 2-D arrays in a row-first manner. The buffer of data written by put_buf() is to be thought of as a 2-D array.

RETURN VALUE

put_buf() returns

     E_SUCC  (0) --> success
     E_FAIL (-1) --> failure