3.19 cobfa_stkey()

Positions to the record indicated by the value of an arbitrary key.

long  cobfa_stkey  (
  long  fd,                            /* file descriptor       */
  long  stflgs,                        /* positioning attribute */
  const char  *recarea,                /* record area           */
  const struct fa_keydesc  *keydesc,   /* record key structure  */
                                       /* specification         */
  long  keynum,                        /* record key number     */
                                       /* specification         */
  long  keyleng                        /* valid key length      */
);

Description

In the file indicated by the file descriptor <fd>, positions to the record matching the value of an arbitrary key held in the record area <recarea> and the requested positioning mode <stflgs>. Successful repositioning establishes the reference key for subsequent sequential read.

The positioning mode <stflgs> includes the following two categories, which are associated by a logical OR. If omitted, default values are assigned (default: *).

Positioning mode (COBOL syntax)

	FA_FIRST	First record (START FIRST RECORD)
*	FA_EQUAL	Record equivalent to the record key value. (START KEY IS = )
	FA_GREAT	Record greater than the record key value. (START KEY IS > )
	FA_GTEQ	Record equivalent to or greater than the record key value. (START KEY IS >= )
	FA_LESS	Record smaller than the record key value. (START KEY IS < )
	FA_LTEQ	Record equivalent to or smaller than the record key value. (START KEY IS <= )

Reversed-order read flag (COBOL syntax)
*
-
Reads in logically order upon sequential read.
FA_REVORD
Reads in logically reversed order upon sequential read. (START WITH REVERSED ORDER)
- The default of the reversed-order read flag is disabled.
- If the positioning mode exceeds the record key value (FA_GREAT) or is equivalent to or greater than the record key value (FA_GTEQ), the reversed-order read flag (FA_REVORD) cannot be specified.
- The reversed-order flag specified is disabled by any random read, positioning, file close, or end of file ending condition.

An arbitrary record key is specified by using record key structure specification <keydesc>. For the struct fa_keydesc type, see "4.1.1 struct fa_keydesc".

If NULL is specified for this record key structure specification, record key number specification <keynum> is valid as an arbitrary record key specified. To specify the primary record key, specify 1 for the record key number. To specify the alternate record key, specify 2 or greater for the record key number. This value corresponds to the list of the order in which alternate record keys were declared when the indexed file was created. For the first alternate record key, specify 2. For the second alternate record key, specify 3. For the following alternate record keys, specify the corresponding numbers in the same way.

The valid key length <keyleng> is used to shorten the length of the valid reference key. In most cases, in which the key length is not shortened, 0 is specified for <keyleng>. The entire arbitrary record key is valid as a reference key. To shorten the valid key length, specify 1 or a greater value. This value indicates key length from the top of the key.

Execution Conditions

File Organization	Sequential file	-
	Record sequential file	-
	Relative file	-
	Indexed file	Executable
Open Mode	INPUT mode	Executable
	OUTPUT mode	-
	I-O mode	Executable
	EXTEND mode	-
Access Mode	Sequential	Executable
	Random	-
	Dynamic	Executable

Return Values

0: Successful	Function executed successfully
-1: Failed	Function failed. To get extended error information, call the cobfa_errno or cobfa_stat functions

Generated Status

Return value of cobfa_errno ()		Return value of cobfa_stat ()
Successful	FA_ENOERR	0	Function executed successfully
Failure (not all) (*)	FA_ENOTOPEN	47	The specified file is opened in a mode other than INPUT mode and I-O mode. Alternatively, an invalid file descriptor is specified
	FA_EBADACC	90	The file is opened with the file organization or access mode that does not allow this function to be executed
	FA_EBADFLAG	90	The positioning mode not allowing execution of this function is specified. Alternatively, another flag specification is incorrect
	FA_ENOREC	23	The record corresponding to the specified condition does not exist
	FA_EBADKEY	90	The specified record key structure or record key number does not exist or is not correct

* : Typical status values are described above. For other values, see "Chapter 5 Error Number and I-O Status".

*	-	Reads in logically order upon sequential read.
	FA_REVORD	Reads in logically reversed order upon sequential read. (START WITH REVERSED ORDER)