The Set Lower Limit (SETLL) command positions a file at the next record that has a key or relative record number that is greater than or equal to the key or relative record number specified.

The RPG figurative constants *LOVAL, *HIVAL, *START, and *END are supported when used with the KEYLIST parameter. When used with a file with a composite key, figurative constants are treated as though each field of the key contains the figurative constant value. If a figurative constant is used as an actual key value in the file you must use the KEYSTRUCT parameter.

If no record is found in the file that meets the positioning criteria the file is positioned to end of file.

This command never runs in the traditional sense and will return an error if an attempt is made to run the command. The CLF precompilers, when they encounter this command in a CL source program, replace the command and generate CL instructions directly into the compiled CL program.

Restrictions:

• This command can only be used in a CL program that is created using a CLF precompiler command. The CLF precompiler commands are CRTBNDCLF, CRTCLFMOD, and CRTCLFPGM.

Parameters

Key field list (KEYLIST)

Specifies the key values to be used when positioning in a file by key.

You can specify up to 10 values for this parameter. or one of the special values. Each non-special value specified corresponds to one key field in the file's key definition. The definition of the CL variable used does not have to match the definition of the key field within the file. The two definitions can be of different TYPE and LEN. In addition, character expressions can be used.

If the file has a composite key it is not necessary to provide all key values. Positioning by partial key is supported. If a file has three key fields, you can specify one, two, or all three key field values with this parameter.

When specifying numeric variables or numeric literals, any valid numeric datatype can be used. For instance the CL variable may be declared as TYPE(*DEC) while the file key field is defined as TYPE(*INT). When using numeric variables or literals the maximum number of digits at runtime that can be represented to the left of the decimal point is nine. At runtime the maximum number of digits to the right of the decimal point is five. When using a CL variable the variable can be declared with a larger size, for instance TYPE(*DEC) LEN(15 0), but at run time the actual value must be within the range of .00001 to 9999999999.99999.

If the numeric value is outside of this range the system will send message CPF0001 (Error found on POSDBFCLF command) prior to running the command. For numeric keys that exceed this range you can pass the numeric value as a character value or use the KEYSTRUCT parameter.

You cannot specify both KEYLIST and KEYSTRUCT with the same command. You can only specify one of these keywords.

*LOVAL

The first record in the file is positioned to. From this position a READ will read the first record in the access path. If specified this special value must be the only KEYLIST entry.

*START

Positions to just before the first record in the file. There is no record associated with this position and condition EOF will be set. A READ from this position will read the first record in the access path. If specified this special value must be the only KEYLIST entry.

*END

Positions to just after the last record in the file. There is no record associated with this position and condition EOF will be set. A READP from this position will read the last record in the access path. If specified this special value must be the only KEYLIST entry.

*HIVAL

Positions to just after the last record in the file. There is no record associated with this position and condition EOF will be set. A READP from this position will read the last record in the access path. If specified this special value must be the only KEYLIST entry.

unrestricted-value

Specify the CL variables, or literal values, that contain the key values to be used. There must be one CL variable or literal value specified for each key field to be used.

File identifier (FILEID)

Specifies the file identifier that was used on a previous Open File for Processing (OPEN) or Open File using CLF (OPNFCLF) command in the application.

This parameter is used by CLF commands to identify the file to be processed by the command.

If the file is declared using the DCLFCLF command this parameter is optional if the RCDFMT parameter specifies a record format name that is associated with one and only one file ID.

simple-name

Specify a name that matches the FILEID parameter value of a previous OPEN or OPNFCLF command.

Record format (RCDFMT)

Specifies the name of the record format to be used.

*ONLY

There is only one record format defined for the file. This record format will be used by the command.

character-value

Specify the name of the record format to be used.

End of file (EOF)

Specifies a CL variable to receive the End of File status. If the variable value is equal to '1' (true) then End of File was reached when positioning. This variable is set to '0' (false) when End of File is not reached.

End of File is set when using the figurative constants *START or *END and the operation is successful.

This CL variable is typically declared by either the Generate Indicators using CLF (GENINDCLF) command or the Declare Indicators using CLF (DCLINDCLF) command. These commands would have specified CLFIND(*YES). When using these commands the name of the CL variable would be &EOF.

If no CL variable is specified and an end of file condition is encountered the application program will not be sent an escape message.

logical-value

Specify the name of a CL variable declared as TYPE(*LGL).

Error found (ERR)

Specifies a CL logical variable to receive general error status. If the variable value is equal to '1' (true) then an error was found when performing the command. If the variable value is equal to '0' (false) then no error was found when performing the command.

This CL variable can be declared by the Declare Indicators using CLF (DCLINDCLF) command, the Generate Indicators using CLF (GENINDCLF) command, or by you using the Declare CL Variable (DCL) command. The two CLF commands would have specified CLFIND(*YES). When using the CLF commands the name of the CL variable is &ERR.

If no CL variable is specified and an error condition is encountered the application program will be sent an escape message.

logical-value

Specify the name of a CL variable declared as TYPE(*LGL).

Key field structure (KEYSTRUCT)

Specifies the key values to be used when positioning in a file by key.

You cannot specify KEYLIST and KEYSTRUCT with the same command.

Element 1: Number of key fields

unsigned-integer

Specify the number of key fields within the structure element that are to be used. If the file has a composite key it is not necessary to provide all key values. Read by partial key is supported.

Element 2: Structure

character-value

Specify the CL variable that contains the key values. The key fields provided in the CL variable must be declared the same as the key fields defined within the keyed access path being used.

A key field structure can be defined using either the Declare File Key Structure (DCLFKSCLF) or the Generate File Key Structure (GENFKSCLF) command.

Relative record number (RRN)

Specifies the relative record number to be used when positioning within a file by RRN.

unsigned integer

Specify the relative record number of the record to be positioned relative to.

Program opening file (OPNPGM)

The same FILEID value can be in use across multiple programs within a job. Each instance of a file open is uniquely identifed by the OPNPGM parameter. This parameter specifes the application program that initially opened the file using the Declare File using CLF (OPEN) or the Open File using CLF (OPNFCLF) command.

All CLF commands that reference the same FILEID and OPNPGM combination share the same view of the file. If one program causes the position within the file to change all programs see that change. If one program closes the file then the file is closed to all programs.

The combination of FILEID and OPNPGM must be unique within the activation group the application program is running in.

If the program name is *CURPGM then the library qualifier for this parameter is ignored. The library of the current program will be used.

Single values: Program opening file

*CURPGM

The current program opened the file associated with FILEID. It is this file open instance that is to be used.

Qualifier 1: Program opening file

name

Specify the name of the program that initially opened the file identified by FILEID. It is this file open instance that is to be used.

Qualifier 2: Library

*CURLIB

The current library for the thread is used. If there is no current library for the thread then library QGPL is used.

name

Specify the name of the library where the program that initially opened the file is located.

Examples for SETLL

Example 1: Position a File by Key

The SETLL command is used in the Show_Emps subroutine to position the file to the first employee of a department.

    Pgm
    /***********************************************/
    /* Declare working variables                   */
    /* &DPT_COUNT - used to load department records*/
    /*   to subfile                                */
    /* &EMP_COUNT - used to load employee records  */
    /*   to subfile                                */
    /***********************************************/
    Dcl        Var(&Dpt_Count) Type(*Dec)
    Dcl        Var(&Emp_Count) Type(*Dec)
    /***********************************************/
    /* Declare files and indicators:               */
    /* VC2DPT - Department master file             */
    /* VC2EMP - Employee master file               */
    /* VC2EMPDPT - Logical file of employees by    */
    /*   department                                */
    /* VC2DPTDSP1 - Display file                   */
    /* CLF command related indicators              */
    /***********************************************/
    File       FileID(VC2DPT)
    File       FileID(VC2EMP)
    File       FileID(VC2EMPDPT)
    File       FileID(DISPLAY) File(VC2DPTDSP1)
    Inds       CLFInd(*Yes)
    /***********************************************/
    /* Open the files.                             */
    /* VC2DPT - Department master file             */
    /* VC2EMP - Employee master file               */
    /* VC2EMPDPT - Logical file of employees by    */
    /*   department                                */
    /* VC2DPTDSP1 - Display file                   */
    /* CLF command related indicators              */
    /***********************************************/
    Open       DISPLAY File(VC2DPTDSP1) Usage(*Both)
    Open       VC2DPT AccMth(*Key)
    Open       VC2EMP AccMth(*Key)
    Open       VC2EMPDPT AccMth(*Key)
    /***********************************************/
    /* Initialize department subfile               */
    /***********************************************/
    Write      RcdFmt(SFLCTLDPT)
    /***********************************************/
    /* Load list of departments into subfile       */
    /***********************************************/
    Read       VC2DPT EOF(&EOF)
    DoWhile    Cond(*Not &EOF)
               /************************************/
               /* Get department managers name     */
               /************************************/
               Chain &DptMgr VC2EMP RcdNotFnd(&RNF)
               /************************************/
               /* If no mgr, set to *NONE          */
               /************************************/
               If Cond(*Not &RNF) Then(ChgVar +
                    Var(&DptMgrName) Value(&EmpFName))
               Else Cmd(ChgVar +
                    Var(&DptMgrName) Value(*None))
               /************************************/
               /* Set depart. subfile record number*/
               /* Write department record          */
               /* Get next department record       */
               /************************************/
               ChgVar Var(&Dpt_Count) Value(&Dpt_Count + 1)
               Write RcdFmt(SFLDPT) RRN(&Dpt_Count)
               Read VC2DPT EOF(&EOF)
               EndDo
    /***********************************************/
    /* If VC2DPT is empty then prompt to run the   */
    /* DEV_LOAD sample program                     */
    /***********************************************/
    If         Cond(&Dpt_Count *EQ 0) Then(Do)
               Exfmt RcdFmt(EMPTYFILE)
               ChgVar Var(&IN03) Value('1')
               EndDo
    /***********************************************/
    /* Continue showing the department list until  */
    /* command key 3 is used                       */
    /***********************************************/
    DoWhile    Cond(*Not &IN03)
               /************************************/
               /* Show active command keys and any */
               /* messages that may have been sent */
               /************************************/
               Write RcdFmt(KEY)
               /************************************/
               /* Clear message indicator          */
               /************************************/
               ChgVar Var(&IN50) Value('0')
               /************************************/
               /* Show Subfile and Control record  */
               /************************************/
               ChgVar Var(&IN21) Value('1')
               Exfmt RcdFmt(SFLCTLDPT)
               /************************************/
               /* Read subfile records to see if   */
               /* user wants to view the employees */
               /* in the department (option 5)     */
               /************************************/
               ReadC SFLDPT EOF(&EOF)
               DoWhile Cond(*Not &EOF)
                  If Cond(&SflOpt = '5') Then(Do)
                     /******************************/
                     /* First remove the '5' if    */
                     /* one was typed in           */
                     /******************************/
                     ChgVar Var(&SflOpt) Value(' ')
                     Update RcdFmt(SFLDPT)
                     /******************************/
                     /* Now go display employees   */
                     /******************************/
                     CallSubr Subr(Show_Emps)
                     EndDo
                  /*********************************/
                  /* That department is done.  Now */
                  /* check if another was selected */
                  /*********************************/
                  ReadC RcdFmt(SFLDPT) EOF(&EOF)
                  EndDo
               EndDo
    /***********************************************/
    /* Close the files as command key 3 was used   */
    /***********************************************/
    Close      VC2EMP
    Close      VC2DPT
    Close      VC2EMPDPT
    Close      DISPLAY
    /***********************************************/
    /* And return to our caller                    */
    /***********************************************/
    Return
    /***********************************************/
    /* Subroutine to display department employees  */
    /***********************************************/
    Subr       Subr(Show_Emps)
    /***********************************************/
    /* Initialize employee subfile                 */
    /***********************************************/
    ChgVar     Var(&IN21) Value('0') /* Clear SFL */
    Write      RcdFmt(SFLCTLEMP)
    /***********************************************/
    /* Set employee subfile record number to 0     */
    /* in case this isn't the first department     */
    /* the user selected today                     */
    /***********************************************/
    ChgVar     Var(&Emp_Count) Value(0)
    /***********************************************/
    /* Load list of employees into subfile         */
    /***********************************************/
    /***********************************************/
    /* Position to first employee in department    */
    /***********************************************/
    SetLL      &DptID VC2EMPDPT
    ReadE      &DptID VC2EMPDPT EOF(&EOF)
    /***********************************************/
    /* So long as there are employees in dpt:      */
    /***********************************************/
    DoWhile    Cond(*Not &EOF)
               /************************************/
               /* Set depart. subfile record number*/
               /* Write department record          */
               /* Get next department record       */
               /************************************/
               ChgVar Var(&Emp_Count) +
                 Value(&Emp_Count + 1)
               Write RcdFmt(SFLEMP) RRN(&Emp_Count)
               ReadE &DptID VC2EMPDPT EOF(&EOF)
               EndDo
    If         Cond(&Emp_Count *GT 0) Then(Do)
               /************************************/
               /* With all of the department       */
               /* employtees loaded into the       */
               /* subfile, now display the active  */
               /* command keys                     */
               /************************************/
               Write     RcdFmt(KEY)
               /************************************/
               /* Show Subfile and Control record. */
               /* When user hits ENTER or command  */
               /* key 3 return to main line.       */
               /************************************/
               ChgVar Var(&IN21) Value('1')
               Exfmt RcdFmt(SFLCTLEMP)
               EndDo
    Else       Cmd(Do)
    /***********************************************/
    /* No employees found in department            */
    /***********************************************/
               ChgVar Var(&MsgTxt) +
                  Value('No employees in department' +
                    *BCat &DptID)
               ChgVar Var(&IN50) Value('1')
               EndDo
    EndSubr
    EndPgm

The source for this example can be found in member RPG_DPTU1 of source file VC2CLSRC in library VC2CLF. The source for file VC2DPT can be found in member VC2DPT of source file QDDSSRC in library VC2CLF. The source for file VC2EMP can be found in member VC2EMP of source file QDDSSRC in library VC2CLF. The source for file VC2EMPDPT can be found in member VC2EMPDPT of source file QDDSSRC in library VC2CLF. The source for file VC2DPTDSP1 can be found in member VC2DPTDSP1 of source file QDDSSRC in library VC2CLF.

All of the referenced objects should currently exist in library VC2CLF. To create this example program into QTEMP you can use the commands

    AddLibLE Lib(VC2CLF)
    CrtBndCLF Pgm(QTEMP/RPG_DPTU1) SrcFile(VC2CLSRC)

To run RPG_DPTU1 you can use the command

    Call Pgm(QTEMP/RPG_DPTU1)

RPG_DPTU1 will display a subfile of the departments found in the VC2DPT department master file. From this subfile you can display the employees of one (or more) departments by using option 5. All departments contain employess other than Administrative Support. Command key 3 can be used to exit the program.

Error messages for SETLL

*ESCAPE Messages

CPF0001

Error found on &1 command.

VC25019

File ID &1 is not open for keyed access.

VC2501A

File &1 is not open for access by relative record number.

VC2501B

Record not found in file &1.

VC2501C

End of file for file &1.

VC25021

The &4 command was not successful when accessing File ID &2.

VC25025

Target datatype of &1 not recognized.

VC2502E

File ID &1 is not open.

VC29002

Function did not complete. See previously listed messages related to possible user errors.

VC29003

Function did not complete. See previously listed messages for possible cause.

VC29004

Function did not complete. See previously listed messages for possible cause.

VC29005

Function did not complete. Contact your service provider.

VC29013

Function did not complete. See previously listed messages for possible cause.