getdb

Name

getdb, getsdb, getkdb — Read dataset

Synopsis

subroutine getdb(handle,name,idiv,buffer,type,size,status)
integer*4 handle
character*(*) name
integer*4 idiv
integer*4 | integer*8
real*4 | real*8 buffer(*)
complex real*4 | complex real*8 buffer(*)
character*4 type
integer*4 size
integer*4 status

subroutine getsdb(handle,name,ipos,buffer,type,size,status)
integer*4 handle
character*(*) name
integer*4 ipos
integer*4 | integer*8
real*4 | real*8 buffer(*)
complex real*4 | complex real*8 buffer(*)
character*4 type
integer*4 size
integer*4 status

subroutine getkdb(handle,name,idiv,buffer,type,size,status)
integer*4 handle
character*(*) name
integer*4 idiv
character*(*) buffer
integer*4 size
integer*4 status

Description

getdb transfers size data elements of a dataset name from a database identified by handle to the array buffer. getdb only works for dataset types I, J, E, C, F, Z, and U.

getkdb transfers size characters of a dataset name from a database identified by handle to the string buffer. getkdb only works for dataset types K (character strings). If the requested set size nc is set to 0 before calling getkdb the whole set will be returned and nc will be set to the maximum set size.

Note

	Note
If the requested dataset size `size` is set to 0 before calling these functions the whole set will be returned and `size` will be set to the maximum set size. While this feature is maintained for compatibility reasons, it is deprecated because it may lead to buffer overflow problems. It is recommended (a) to query the set or sub-set size beforehand, (b) to make sure that the size of the buffer is sufficient, and (c) to specify the obtained size as the requested set or sub-set size `size` when calling `getdb` or `getkdb`. `getsdb` does not accept `size` to be set to 0 upon entry.

If the requested dataset size size is set to 0 before calling these functions the whole set will be returned and size will be set to the maximum set size. While this feature is maintained for compatibility reasons, it is deprecated because it may lead to buffer overflow problems. It is recommended (a) to query the set or sub-set size beforehand, (b) to make sure that the size of the buffer is sufficient, and (c) to specify the obtained size as the requested set or sub-set size size when calling getdb or getkdb. getsdb does not accept size to be set to 0 upon entry.

getsdb transfers parts of a of a dataset name from a database identified by handle to buffer. Starting at the relative address ipos within the dataset (count starts at 1), size data elements are transferred to buffer. getsdb only works for dataset types I, J, E, C, F, Z, and U. getsdb does not support K sets (characters).

If the sub-division index idiv is set to 0 the sub-division structure is ignored. If idiv > 0, the sub-record idiv will be returned if the set has been initialized with dssdb. If not, an error is reported.

Parameters

handle: Database handle (input). The file handle handle may not exceed the maximum number of simultaneously open databases.
name: Name of dataset (input). The string may not exceed the maximum dataset name length.
idiv: Sub-division number (input). idiv must be greater than or equal to 0.
buffer: Array to which data will be copied.
type: Dataset type (input). type must be set to I, J, E, C, F, Z, U (getdb, getsdb). Dummy variable in case of getkdb).
ipos: Relative start address within dataset, count starting at relative word address 1 (input). getsdb only.
size: Number of data elements to be transferred (input).
status: Status code returned (output). Upon successful completion of the operation, the status value 0 is returned. A negative value is returned, if an error has been detected. A positive value is returned, if a warning has been issued. See MemCom error codes.