SYNTAX

#include "las.h"

FUNCTION c_eopens (fdesc, fname, bands, sl, ss, nl, ns, offset, acc, dtype, nbuf, opt)

     int                *fdesc;
     char               *fname;
     long                bands[];
     long               *sl;
     long               *ss;
     long               *nl;
     long               *ns;
     long                offset[];
     long               *acc;
     long               *dtype;
     long               *nbuf;
     long                opt[];

PARAMETERS

fdesc (output, integer)

File descriptor to be used internally by the image I/O subroutines. The calling routine should pass by reference an integer of the machine's word size. From C this is an int. For the caller intending to use the sequential calls c_egroup() and c_estep(), an array of integers dimensioned the size f the number of files + 1, the last being for a null terminator, can be passed directly to the c_egroup() call. The fdesc parameter should be a C static or global or a FORTRAN common or saved variable when used outside the scope of the c_eopens().

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

Host name of the image file to be opened.

bands (input/output, integer)

If acc = IREAD or IUPDATE, this parameter is a null terminated array that contains the band numbers of the files. If acc = IREAD or IUPDATE and if the bands variable is 0, all the bands of the file are specified. If acc = IWRITE, bands is a single parameter to be passed by reference that is used as the number of bands.

sl (input, integer)

Starting line of image to be processed.

ss (input, integer)

Starting sample of image to be processed.

nl (input/output, integer)

Number of lines. On read access if nl = 0, the number of lines in the file is specified and returned.

ns (input/output, integer)

Number of samples. On read access if ns = 0, the number of samples in the file is specified and returned.

offset (input, integer array)

An array that must be dimensioned no smaller than the number of bands to be processed in the file. This array will be filled with offsets into the user's buffer so the program can read from them or write to these data areas. This array contains the number of pixels that the bands are offset from the beginning of the buffer. Thus it is normal to multiply the offset by the size of the data type.

These offsets assume zero relative arrays; therefore, FORTRAN users should add 1 in their address space to allow for one relative arrays. The offset array should be declared the same as fdesc array so that its address remains static throughout the application program.

acc (input, integer)

Specifies whether the file is to be opened for:

          = IREAD   (0):        Read access
          = IWRITE  (1):        Write access
          = IUPDATE (2):        Read/write access

dtype (input/output, 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

If acc = IWRITE, it specifies the data type of the input. The default is the same for the output. If conversion is required, see opt.

nbuf (input, integer)

Specifies the number of previously read lines that will be guaranteed to remain in the user's buffer. For most applications, 0 is sufficient for this parameter.

Note: Values other than zero are not currently handled.

opt (input, integer array)

This array is used for optional parameters not normally used by the applications. A typical application should simply pass an array of 0's (zero's) for this parameter. However, if data conversion is needed on write, the first element of the opt array should be filled with the appropriate data type to be written to the file. The dtype parameter is used as the data type seen by the application. When acc = IWRITE, The second element of the opt array is used if the program must override the value of the LAS global $COMPFLG for image compression. The last element of the opt array should be 0 indicating that no further options will be needed by this program. Because of buffering, data conversion cannot be done when acc = IUPDATE.

Allowable values for the image compression option are:

          = COMPRES    (5):     Turn on image compression
          = NO_COMPRES (6):     Turn off image compression

DESCRIPTION

The c_eopens() call is used to open an image file and initialize for reading or writing, for sequential access, and data conversion. c_eopens() also allows the user to window the file.

RETURN VALUE

c_eopens() returns

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