Function:     GDSI_READ

Purpose:      Reads data from (part of) a set.

Category:     DATA, IMAGE-IO

File:         gdsi_read.c

Author:       K.G. Begeman

Use:          CALL GDSI_READ( SET,                Input    CHARACTER*(*)
                              CLOW,               Input    INTEGER
                              CUPP,               Input    INTEGER
                              BUFFER,             Output   REAL ARRAY
                              BUF_LEN,            Input    INTEGER
                              PIXELS_DONE,        Output   INTEGER
                              TRANS_ID )          In/Out   INTEGER

              SET           set name
              CLOW          coordinate word of lower left corner of the
                            subset to read.
                            If omitted: read the whole set.
              CUPP          coordinate word of upper right corner of the
                            subset to read.
                            If omitted: CLOW is a subset to read.
              BUFFER        array where pixels are stored.
              BUF_LEN       max. number of pixels to read.
                            If omitted: 1 is assumed.
              PIXELS_DONE   number of pixels actually read in one call.
                            Not cumulative for a complete transfer.
                            If omitted: PIXELS_DONE must be equal to BUF_LEN,
                                        otherwise error code -30 will be
                                        returned in TRANS_ID.
              TRANS_ID      transfer identification.
                            = 0  read successful completed.
                            > 0  unique indentifer if read could not be
                                 completed. This unmodified TRANS_ID must be
                                 used until the read has been completed with
                                 TRANS_ID = 0.
                            < 0  a GDS error has been detected.
                                 Some special GDSI_READ error codes:
                                 -30 argument PIXELS_DONE omitted, but was
                                     unequal to BUF_LEN.
                                 -31 illegal transfer identifier.
                                 -32 Unable to allocate enough memory.
                                 -36 cannot open data file.
                                 -38 maximum open sets exceeded.

Related Docs: gdsi_write.dc2, gdsi_cancel.dc2.

Updates:      May 21, 1987: WZ, istalled.
              Dec 21, 1989: WZ, migrated to C.
              Jul  5, 1990: KGB, modified document.
              Oct 31, 1990: WZ, 'naxis', etc. from setsta -> dsc_file.
              Aug 17, 1991: KGB, new algorithm, replaced fopen by open.
              Jan 31, 1994: JPT, attempt to open read-only if read-write fails.
              Mar 24, 1994: JPT, modified for GDS server.
              Jan 15, 1998: VOG, replaced tell() by more common lseek()
              May  1, 2007: JPT, conditional code for Apple Mac included.
              Mar  1, 2011: JPT, use off_t for file offsets.