Get Next List Entry

GetNextEntry

The GetNextEntry procedure retrieves an entry from a list generated by one of the CrtxxxList procedures.

The GetNextEntry procedure can be used to retrieve the entry from a list of entries stored in a user space. The entries must have been enumerated into the user space by one of the RPG xTools CrtxxList procedures or by one of the OS/400 QUSLxxx APIs, such as QUSLFLD, QUSLMBR, QUSLRCD, or QDBLDBR

nNextRefFld   GetNextEntry(
 szUserSpace    21A    Const 
 nRefFld        10I 0        
 szRtnBuf     8196A    OPTIONS(*VARSIZE)       
 nRtnBufLen     10I 0  OPTIONS(*NOPASS)
)

Parameters

szUserSpace

[input Char(21) const] The name of the user space that contains the list generated by a previous CrtxxxList procedure or QUSLxxx API. The parameter consists of two parts (1) in the first 10 positions, the name of the user space, and (2) in the second 10 positions, the name of the library in which the user space is located. For example:

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

'XTOOLS   QTEMP     '

The user space named XTOOLS in library QTEMP is used.

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

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

'QTEMP/MYSPACE       '

The qualified user space name is MYSPACE in the QTEMP library. Either syntax is acceptable.

The special value '*' (an asterisk) may be specified, which causes the procedure to use the default user space (created in the QTEMP library). Any data currently stored in the default user space is replaced.

An easy way to create this parameter using the default format is to define a data structure with two subfields, each 10 positions in length. For example:

.....DName+++++++++++EUDS.......Length+TDc.Functions++++++++++

     D UserSpace       DS

     D  szUSName                     10A   Inz('XTOOLS')

     D  szUSLib                      10A   Inz('QTEMP')

nRefFld

[input/output Int(4) (10i0)] The referenced field ID of the field to be retrieved. This is the entry's index on the list. A value of 1 retrieves the first field description, when calling this procedure for the first time, ensure that this parameter is 1 or higher as a value of zero returns no entry. Upon completion the field specified for this parameter is updated to the value of the next entry on the list. The updated value can be used on the next call to the procedure to retrieve the next entry from the list. If the last entry on the list is returned, this parameter is set to zero.

szRtnBuf

[output Char(*) const] A field or data structure that receives the entry's information. A field whose length is the same as one of the structures that follow is recommended. If a data structure is specified for this parameter is must be the proper format and length as designated by the corresponding CRTxxxLIST procedure. Unpredictable results will occur if the some other format is specified.

nRtnBufLen [ optional ]: [input Int(4) (10i0)] This optional parameter may be used when the length of the szRtnBuf parameter is different from the default length. The default length is the length associated with the format used to generate the list. For example, if a list of fields has been generated into the user space specified on the szUserSpace parameter, the default length is %SIZE(QUSL0100). This is the data structure used by the FLDL0100 format when calling the CrtFldList procedure. If you're passing in a data structure for the szRtnBuf parameter and that data structure is based on the data structure templates provided in QSYSINC/QRPGLESRC then you may leave off this parameter.

Return Value

The ordinal (integer index) of the next entry in the list of entries, or zero (0) if the last entry's information has been retrieved. This is the same value that is returned on the nRefFld parameter. The return value may be ignored, or used to simplify a conditional loop through the list of fields.

Return Value	Description
0	End of field list; no additional fields to retrieve. Note: When the final entry is retrieved, the return value is n+1, where n is the number of actually entries on the list. If that return value is then used on a subsequent GetNextEntry, the return value is 0 and no new value is returned. This allows a DOW or DOU loop to be controlled by a Dow GetNextEntry > 0 condition.
1 to n	A reference ordinal (integer value) that may be used on subsequent calls to GetNextEntry().
-1	The reference field ordinal specified on the nRefFld parameter is outside the range of fields; it may have been larger than the maximum number of fields in the list.
-2	There are no fields in the user space specified on the szUserSpace parameter or the user space does not exist. Use the CrtFldList() procedure to first create the list of field names.

Remarks

If the user space specified on the szUserSpace parameter does not exist, or the caller does not have authority to the user space object, the procedure will return -2 and end. If this happens, check the XT_ERRMSGID subfield of the XT_ERROR data structure for the message ID and reason for the failure.

Example

The following example creates a user space named FIELDLIST in the QTEMP library and enumerates a list of fields for the CUSTMAST file. Then, using the GetNextEntry() procedure, each field description is retrieved. A list of field names and descriptions is then printed.

      ** The Binding Directory XTOOLS contains only the XTOOLS *SRVPGM name.

     H BNDDIR('XTOOLS')

     H   DFTACTGRP(*NO)

.....FFileName++IFEASFRlen+LKeylnKFDevice+.Functions++++++++++

     FQPRINT    O    F  132        PRINTER OFLIND(*INOF)

XX    /INCLUDE XTOOLS/QCPYSRC,LISTS

XX    /INCLUDE XTOOLS/QCPYSRC,RTKERROR

      /INCLUDE QSYSINC/QRPGLESRC,QUSLFLD

.....DName+++++++++++EUDS.......Length+TDc.Functions++++++++++

     D LSTFFD          PR

     D  szFile                       10A

     D  szLib                        10A

      **  The *ENTRY PLIST is specified here

     D LSTFFD          PI

     D  szFile                       10A

     D  szLib                        10A

.....DName+++++++++++EUDS.......Length+TDc.Functions++++++++++++++++++++++++++

     D szUs            DS

     D  szUSName                     10A   Inz('FIELDLIST')

     D  szUSLib                      10A   Inz('QTEMP')

     D ShortType       S              1A   DIM(7) CTDATA PERRCD(7)

     D FullType        S              4A   DIM(7) CTDATA PERRCD(7)

     D FldName         S                   Like(QUSFN02)

     D DataType        S              5A

     D nLength         S                   Like(QUSFLB)

     D szDecPos        S              2A

     D szText          S                   Like(QUSFTD)

      /IF DEFINED(*V5R1M0)

     D szFieldDesc     DS                  LikeDS(QUSL0100)

      /ELSE

     D szFieldDesc     S                   Like(QUSL0100)

      /ENDIF

     D nRef            S             10I 0

     D i               S             10I 0

     D nFldCnt         S             10I 0

.....C..n01..............OpCode(ex)Extended-factor2++++++++++++++++++++++++++

     C                   eval      *INLR = *ON

      **  Create the user space and enumerate the list of fields

      **  for the TESTDDS file. If 0 is returned, the function failed.

XX   C                   If        CrtFldList(szUS : szFile : szLib) <= 0

      **  We can check XT_ERRMSGID at this point to see what the error is.

XX   C     XT_ERRMSGID   DSPLY

     C                   return

     C                   endif

     C                   Except    Heading

      **  Set the starting point to the first field

XX   C                   eval      nRef = 1

      **  Iterate through each field until end-of-list is detected.

     C                   DoW       GetNextEntry(szUS : nRef : szFieldDesc) > 0

      **  Copy the values from the couriously named IBM fields to normal names.

     C                   eval      FldName = QUSFN02

      **  If the data type is numeric use the digits value, otherwise

      **  use the "buffer length" value.

XX   C                   if        InList(QUSDT: 'P':'S':'B')

     C                   eval      nLength = QUSIGITS

     C                   evalr     szDecPos = %CHAR(QUSDP)

     C                   else

     C                   eval      szDecPos = *BLANKS

     C                   eval      nLength = QUSFLB

     C                   if        QUSVLFI = *ON

      **  If the data-type is Char and VARLEN is specified,

      **  decrease the buffer length by the 2-byte binary prefix

      **  that is added for variable length fields.

     C                   eval      nLength = nLength - 2

     C                   endif

     C                   endif

     C                   eval      i = 1

     C     QUSDT         LOOKUP    ShortType(I)                           88

     C                   if        %EQUAL

     C                   eval      DataType = FULLTYPE(I)

     C                   if        DataType = 'Char'

     C                             and QUSVLFI = *ON

     C                   Eval      DataType ='VChar'

     C                   endif

     C                   endif

     C                   eval      szText = QUSFTD

      **  At this point, we can do anything we want with the data,

      **  in this example, it is simply printed.

     C                   Except    FieldDesc

     C                   enddo

.....OFormat++++DAddn01n02n03Except++++SpbSpaSkbSka.Constant++++++++++++++++++

     OQPRINT    E            Heading        1

     O                                           +9 'File Field Descriptions'

     OQPRINT    E            Heading        1

     O                                           +2 'File:'

     O                       szFile              +1

     OQPRINT    E            Heading        2

     O                                           +2 '  Library:'

     O                       szLib            +   1

     OQPRINT    E            Heading        1

     O                                           +2 'Field Name'

     O                                           +2 'Type'

     O                                           +4 'Length'

     O                                           +1 'Dec'

     O                                           +1 'Text'

     OQPRINT    E            FieldDesc

     O                       FldName             +2

     O                       DataType            +2

     O                       nLength       Z     +0

     O                       szDecPos         +   1

     O                       szText              +2

**CTDATA SHORTTYPE

PSBAZLT

**CTDATA FULLTYPE

Pkd Znd Bin CharDts DateTime

In the above example, the fields from the database file named CUSTMAST in the ORDENTRY library are enumerated into the user space named FIELDLIST in the QTEMP library. If the user space does not exist, it will be created.

The GetNextEntry procedure is call with the QUSL0100 data structure as its return buffer. QUSL0100 is imported into this source member from the QSYSINC library by the /INCLUDE directive.

Returned Value Structure

** From the source member: QSYSINC/QRPGLESRC(QUSLFLD)

DQUSL0100 DS

D* Field Name

D QUSFN02 1 10

D* Data Type

D QUSDT 11 11

D* Usage

D QUSU 12 12

D* Output Buffer Position

D QUSOBP 13 16B 0

D* Input Buffer Position

D QUSIBP 17 20B 0

D* Field Length Bytes

D QUSFLB 21 24B 0

D* Digits

D QUSIGITS 25 28B 0

D* Decimal Positions

D QUSDP 29 32B 0

D* Field Text Description

D QUSFTD 33 82

D* Edit Code

D QUSEC00 83 84

D* Edit Word Length

D QUSEWL 85 88B 0

D* Edit Word

D QUSEW 89 152

D* Column Heading1

D QUSCH1 153 172

D* Column Heading2

D QUSCH2 173 192

D* Column Heading3

D QUSCH3 193 212

D* Internal Field Name

D QUSIFN 213 222

D* Alternate Field Name

D QUSAFN 223 252

D* Length Alternate Field

D QUSLAF 253 256B 0

D* Number DBCS Characters

D QUSDBCSC 257 260B 0

D* Null Values Allowed

D QUSNVA 261 261

D* Variable Field Indicator

D QUSVFI 262 262

D* Date Time Format

D QUSDTF 263 266

D* Date Time Separator

D QUSDTS 267 267

D* Variable Length Field Ind

D QUSVLFI 268 268

D* Field Description CCSID

D QUSCCSID00 269 272B 0

D* Field Data CCSID

D QUSCCSID01 273 276B 0

D* Field Column Heading CCSID

D QUSCCSID02 277 280B 0

D* Field Edit Words CCSID

D QUSCCSID03 281 284B 0

D* UCS2 Displayed Length

D QUSCS2DL 285 288B 0

D* Field Data Encoding Scheme

D QUSFDES 289 292B 0

D* Maximum Large Object Length

D QUSMLOL 293 296B 0

D* Large Object Pad Length

D QUSLOPL 297 300B 0

D* UDT Name Length

D QUSUDTNL 301 304B 0

D* UDT Name

D QUSUDTN 305 432

D* UDT Library Name

D QUSUDTLN 433 442

D* Datalink Control

D QUSDC03 443 443

D* Datalink Integrity

D QUSDI03 444 444

D* Datalink Read Permission

D QUSDRP 445 445

D* Datalink Write Permission

D QUSDWP 446 446

D* Datalink Recovery

D QUSDR 447 447

D* Datalink Unlink Control

D QUSDUC02 448 448