Subroutine:    GDSD_READ

Purpose:       Read GDS descriptor item.

Category:      GDS

File:          gdsd_basic.c

Author:        J.P. Terlouw

Use:           CALL GDSD_READ( SET ,          Input    CHARACTER*(*)
                               KEY ,          Input    CHARACTER*20
                               LEVEL ,        Input    INTEGER
                               BUFFER ,       Output   any type except CHARACTER
                               NBYTES ,       Input    INTEGER
                               POSITION ,     Input    INTEGER
                               DONE ,         Output,  INTEGER
                               ERROR )        Output,  INTEGER
               
               SET      =  Name or handle of set.
               KEY      =  Name of descriptor item.
               LEVEL    =  Coordinate word specifying the substructure from
                           which the descriptor item is to be obtained. 
                           If the item is not present at this level, higher 
                           levels are inspected until the item is found or
                           proven to be not present.
               BUFFER   =  Variable or array of receiving the data to be read.
               NBYTES   =  Number of bytes to be read. Optional argument. If it
                           is omitted, the current length of the descriptor
                           item is used.
               POSITION =  Relative position, starting at 1, from which will
                           be read. If zero (0) is specified, reading is done
                           from the current reading position. Optional argument.
                           If it is omitted, the default 1 is assumed.
               DONE     =  The number of bytes which have actually been read.
                           Optional argument. If it is omitted and the number 
                           of bytes which have been transferred is not equal
                           to the requested length of the transfer, an error
                           condition exists.
               ERROR    =  Error return code. In case of success, it will 
                           contain the level where the item has been found.
                           Optional argument.

Note:         This routine does not allow buffers of the type CHARACTER.
              Buffers of this type can be handled by the special routine
              GDSD_READC.

Updates:      25-May-87   original document
              14-Nov-89   rewritten in C
               1-Mar-94   rewritten for GDS server