Retrieve Key List

RtvKeyList

The RtvKeyList procedure returns the list of key fields for a given file.

This procedure returns the key list for any database file. The key list may be simple or complete, that is it may include only the field names, or additional information based on a format option specified by the caller.

num-key-fields  =  RtvKeyList(
  szFile            21A   Const 
  rtnBuffer      65535A   Options(*VARSIZE) 
  nRtnBufLen        10I 0 Const
  nFmtOption        10I 0 Const Options(*NOPASS) 
  szLclRmt          10A   Const Options(*NOPASS)
)

Parameters

szFile

[input Char(21) const]  The qualified file and library name whose key list will be returned. This parameter consists of two parts (1) in the first 10 positions, the name of the source file, and (2) in the second 10 positions, the name of the library in which the source file is located. For example:

 *...v....1....v....2.

'CUSTMAST  PRODLIBR   '

 

An alternative syntax is also supported for the szFile parameter. The alternate syntax allows you to specify the file name using qualified syntax. This is similar to that of an OS/400 CL command. The file may be qualified using qualified name syntax, as follows:

 *...v....1....v....2.

'PRODLIBR/CUSTMAST    '

 

szRtnBuffer

[ input Char(*) any-size ]  Up to 120 key fields may be returned (the OS/400 maximum). The key fields are returned to the variable passed on this parameter.  The format of this key fields returned to this parameter is controlled by the nFmtOption parameter.

nRtnBufferLen

[input Int(4) const]  The length of the variable specified on the szRtnBuffer parameter. The maximum number of bytes returned to the szRtnBuffer parameter be the smaller of this value and actually number of bytes needed to store the key list.

nFmtOption [ optional ] DFT(0)

[ input Char(1) const ] Specify the default reply if the user should not specify a reply (i.e., an empty or blank reply is processed). If no default reply is specified, then the character specified in position 1 of the szOptions parameter is used as the default reply. The following special values may be specified as the default reply.

Value	Meaning
0	Simplified key list. This is the default and only the key field names are returned. They are structure as one field name every 10 positions and copied to the return variable specified on the szRtnBuffer parameter.
1	Key list and ASCEND/DESCEND flag. The key field name is returned in positions 1 through 10 and the letter 'A' (for ascending) or 'D' (for descending) is returned in position 11. One 11-byte entry is returned for each field that makes up the key list.
2	Complete key list information is returned for each key field. This information includes the record format name, field name, data type, field length and decimals, buffer size, and flags for the ASCEND/DESCEN, ALTSEQ and ALWNULL keywords. A data structure, like the one listed below, is returned for each key field      D XT_KeyList_T   DS                  QUALFIED      D  FmtName                      10A      D  FldName                      10A      D  FldType                       1A      D  FldLen                       10I 0      D  FldDec                       10I 0      D  FldBufLen                    10I 0      D  KeyFlags                     10A      D   SEQUENCE                     1A   Overlay(KeyFlags)      D   ALTSEQ                       1A   Overlay(KeyFlags:*NEXT)      D   ALWNULL                      1A   Overlay(KeyFlags:*NEXT)      D   Reserved8                    7A   Overlay(KeyFlags:*NEXT)

szLocalRemote [ optional ] DFT('*LCL')

[ input Char(10) const ]  Specfies wether to search local or local and remove systems for the file name specified on the szFile parameter. Valid options are: *LCL and *RMT

Return Value

If the function succeeds, the return value is the number of key fields in the file.  The amount of information returned is the lesser of the space needed for the returned key list or the length of the return variable (i.e., the value specified for the nRtnBufLen parameter).

Example

      /INCLUDE QCPYSRC,lists

     D pKeys           S               *   Inz(%addr(CustKeys))

     D CustKeys        S            165A

     D Keys            S             10A   Dim(15) Based(pKeys)

     C                   eval      nKeys=RtvKeyList('MYLIB/CUSTMAST':

     C                                   CustKeys : %size(CustKeys):1)

In this example, the key fields for the CUSTMAST file in the MYLIB library are returned along with their ascending/descending flag. If the CUSTMAST DDS is as follows:

     A          R CUSTREC

     A            CUSTNO         7P 0

     A            REGION         3S 0

     A            DIV            2A

     A            CRTDATE         L

     A            CUSTNAME      30A

     A            ADDR1         30A

     A            ADDR2         30A

     A            CITY          30A

     A            STATE         25A

     A            ZIPCODE       10A

     A            YTDSALES       9P 2

     A            YTDCREDITS     9P 2

     A            CURAMTDUE      7P 2

     A          K CUSTNO

     A          K REGION

     A          K DIV                       DESCEND

The structure of the key list returned for this file is be formatted as follows: