appds_read_record

	status.i4.v = appds_read_record(table_name.i1a.r, recs_requested.i4.v, 
					select_key.g.v, return_buffer.g.v, 
					recs_returned.i4.r, error_text.i1a.r, 
					db_name.i1a.r, db_server.i1a.r)

	This routine will attempt to read one or more records from an APPDS 
	table.  Record selection is based on the current access mode for the
	table and the value given in the select_key variable.  All records
	retrieved are placed in the return buffer in ascending order.  Upon
	completion the read/write pointer is set to the record ID of the last
	record retrieved.  (Note: There is a limit of 250 records which may
	me requested at the same time.)

 	for sequential access:	record access mode is set to APPDS_SEQ
	---------------------
	Record(s) are retrieved from the specified APPDS table based on the 
	location of the read/write pointer.  If a  non-NULL value is given for 
	select_key then the read write pointer is reset to the top of the table
	before any records are retrieved.  The first record read is the record 
	following the current location of the read/write pointer.  The number 
	of records returned is always equal to the number requested.  If the 
	number of records requested is greater then the number of records 
	available an error is returned.

	table_name	name of the APPDS table
	recs_requested	number of records requested (maximum is 250)
	select_key	specifies if the read/write pointer is reset before 
			records are read  (A non-NULL value indicates that the
			pointer is to be reset.)
	return_buffer	pointer to a data buffer where the return data is stored
	recs_returned	number of records placed in the return buffer
	error_text	a pointer to a buffer to where any error messages are 
			placed (NULL indicates that no error text is wanted)
	db_name		name of the database where the APPDS table is found
			(if NULL the default value of APPDS_DEFAULT_DB is used) 
	db_server	name of the database server 
			(if NULL the default value of APPDS_DEFAULT_SERVER
			 is used) 

 	for indexed access:	record access mode is set to APPDS_INDX
 	----------------
	Record(s) are retrieved based on the record IDs which are positional 
	record references, e.g. record ID 1 is the first record in the table.  
	The select_key variable is a list of one ore more record IDs.  Each 
	record ID must be within the limits of the table, greater than 0 and 
	less then or equal to the maximum record count set for that table.
	Retrieved records are placed in the return buffer in ascending order
	and indexes that refer to non existing records are NULL filled.  The
	value of the rec_returned variable is set to equal the number of
	returned records that actually contain data.
	An example; if the requested indexes are 1,5,3,2,4 and record data 
	exists for indexes 1,5,2 then the return buffer will look like this: 
	<record 1><record 2><NULL data><NULL data><record 5> and the 
	recs_returned variable will be set to 3.

	table_name	name of the APPDS table
	recs_requested	number of records requested; the number of record IDs
			within the select_key array (maximum is 250)
	select_key	a list of record IDs, array of int integers (4 bytes)
	return_buff	pointer to a data buffer where the return data is stored
	recs_returned	number of records placed in the return buffer
	error_text	a pointer to a buffer to where any error messages are 
			placed (NULL indicates that no error text is wanted)
	db_name		name of the database where the APPDS table is found
			(if NULL the default value of APPDS_DEFAULT_DB is used) 
	db_server	name of the database server 
			(if NULL the default value of APPDS_DEFAULT_SERVER
			 is used)

	for keyed access:	record access mode is set to APPDS_KEY
	-----------------
	Record(s) are retrieved based on the key value specified in the 
	select_key variable.  The data type for the select_key variable must be 
	the same as the data type of the key column of the APPDS table.  The 
	key column is the first element in the record, for records where the 
	first element is an array the record ID is used.  The recs_requested 
	variable specifies the maximum number of records that can fit into the 
	return buffer.  If the number of records that match the select_key is 
	greater than the recs_requested value and APPDS_OVERRUN error code is 
	returned and no records are read.

	table_name	name of the APPDS table
	recs_requested 	maximum number of records that can fit into the return 
			buffer (maximum is 250)
	select_key	key value for which matching records are retrieved
	return_buff	pointer to a data buffer where the return data is stored
	recs_returned	number of records placed in the return buffer
	error_text	a pointer to a buffer to where any error messages are 
			placed (NULL indicates that no error text is wanted)
	db_name		name of the database where the APPDS table is found
			(if NULL the default value of APPDS_DEFAULT_DB is used) 
	db_server	name of the database server
			(if NULL the default value of APPDS_DEFAULT_SERVER is
			 used)

	This function returns ACNET status values as follows:

	APPDS_SUCCESS		requested records were read
	APPDS_READEND		attempted to reference a record beyond the
				table limits
	APPDS_INVARG		invalid argument type 
	APPDS_MEMFAIL		failed to allocate memory
	SQL_xxx			system error occurred

	This function requires the following include files:

	appds_h, clib_h, acnet_errors_h

	Related functions:

	appds_free_table_cache, appds_get_inter_mode, appds_set_inter_mode,
	appds_write_record, appds_delete_record, appds_key_match_count,
	appds_set_db_timeout, appds_get_db_timeout

	C/C++ usage:

	usage example