#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;
Buffer of data to be written. Buffer will be written as data of the type specified by 'dtype' below.
The total number of lines in 'buffer'.
The total number of samples in 'buffer'.
The number of lines of actual valid data in 'buffer'.
The number of samples of actual valid data in 'buffer'.
The starting line of the data within the image.
The starting sample of the data within the image.
The number of lines in the total image.
The number of samples in the total image.
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.
The number of the band within the image to write to.
The total number of bands within the image.
Pointer to the file descriptor pointer obtained from c_eopenr().
Host name of the image file.
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 dataThe parameter dtype specifies the data type of the buffer to be written.
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
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).
put_buf() returns
E_SUCC (0) --> success E_FAIL (-1) --> failure