The Modify Existing Record (UPDATE) command modifies the last record retrieved and locked for update.
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.
- This command can only be used with database records and display file subfile records.
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.
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).
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 UPDATE
Example 1: Update Current Record
This example uses the UPDATE command when the user presses the ENTER key from the CHANGE display file record format.
Pgm
/******************************************************/
/* Declare the Employee master file VC2EMP, display */
/* VC2EMPDSP1, and CLF related indicators */
/******************************************************/
File FileID(VC2EMP)
File FileID(VC2EMPDSP1)
Inds CLFInd(*Yes)
/******************************************************/
/* Declare the packed decimal field &RcdCnt. This */
/* will be used to determine the current record count */
/* of VC2EMP. If the file is empty (&RCDCNT = 0), */
/* prompt with how to load the file with sample data. */
/******************************************************/
Dcl Var(&RcdCnt) Type(*Dec) Len(10 0)
/******************************************************/
/* Open VC2EMP and verify that records have been */
/* loaded into the file. If not, tell the user how to */
/******************************************************/
Open FileID(VC2EMP) Usage(*Both) AccMth(*Key)
RtvFInfCLF VC2EMP NbrRcds(&RcdCnt)
If Cond(&RcdCnt = 0) Then(Do)
Open VC2FEMPTY Usage(*Both) LvlChk(*No)
Exfmt FileID(VC2FEmpty) RcdFmt(EMPEMP)
Close VC2FEMPTY
Close VC2EMP
Return
EndDo
/******************************************************/
/* Having verified that records exist now open the */
/* display file for the program. */
/******************************************************/
Open VC2EMPDSP1 Usage(*Both)
/******************************************************/
/* Enter a DOWHILE loop until F3 is used */
/* */
/* Within the loop: */
/* 1 Write and read the VC2EMPDSP1 *DSPF record */
/* format PROMPT. PROMPT asks for an employee */
/* number. A valid employee would be 1. The user */
/* can press ENTER or F3 from PROMPT. */
/* 2 If F3 is pressed leave the DoWhile loop */
/* 3 Otherwise read the employee record for the */
/* employee number entered. */
/* 4 If no record is found (&RNF is '1') a message */
/* is displayed based on &IN50 */
/* 5 If a record is found record format CHANGE is */
/* written and read. */
/* CHANGE allows the user to maintain employee */
/* information (ENTER), delete the employee (F23), */
/* return to PROMPT without updating the employee */
/* record (F12), or exit the application (F3). */
/* 6 The user is then returned to the PROMPT display */
/* to enter the next employee number */
/******************************************************/
DoWhile Cond(*Not &IN03)
Exfmt RcdFmt(PROMPT)
If Cond(&IN03) Then(Leave)
Chain &EmpNbr VC2EMP RcdNotFnd(&RNF)
If Cond(&RNF) Then(Do)
ChgVar Var(&IN50) Value('1')
Iterate
EndDo
Exfmt RcdFmt(CHANGE)
Select
When Cond(&IN03) Then(Leave)
When Cond(&IN12) Then(Do)
UnLock VC2EMP
Iterate
EndDo
When Cond(&IN23) Then(Delete VC2EMP)
OtherWise Cmd(Update VC2EMP)
EndSelect
EndDo
/******************************************************/
/* When F3 is used close the files and return */
/******************************************************/
Close VC2EMP
Close VC2EMPDSP1
EndPgm
This example opens the VC2EMP physical file for file maintenance. As the program allows a user to view, update, and delete records in the VC2EMP database the database file is opened for keyed IO and both read and write.
RPG_EMPU1, when initially called, verifies that there are records in the VC2EMP file. If not, the program displays a prompt to inform the caller that records need to be loaded prior to running the program. The display file used for this prompt, VC2FEMPTY, is not declared within the program using the DCLFCLF command. Because DCLFCLF was not used the developer needs to supply both the FILEID and the RCDFMT keywords when using the EXFMT command with the record format EMPEMP. The developer does not have to specify both keywords when using the EXFMT command with record formats of the VC2EMPDSP1 display file. In the case of VC2EMPDSP1 the developer used the DCLFCLF command and the precompiler is able to determine the FILEID to use based on only the RCDFMT keyword being provided by the developer.
The source for the example can be found in member RPG_EMPU1 of source file VC2CLSRC in library VC2CLF. The source for physical file VC2EMP can be found in member VC2EMP of source file QDDSSRC in library VC2CLF. The source for display file VC2EMPDSP1 can be found in member VC2EMPDSP1 of source file QDDSSRC in library VC2CLF. The source for display file VC2FEMPTY can be found in member VC2FEMPTY of source file QDDSSRC in library VC2CLF.
All objects referenced by RPG_EMPU1 should currently exist in library VC2CLF. To compile example RPG_EMPU1 into QTEMP you can use the commands
AddLibLE Lib(VC2CLF)
CrtBndCLF Pgm(QTEMP/RPG_EMPU1) SrcFile(VC2CLSRC)
To test the program you can use the command
Call Pgm(QTEMP/RPG_EMPU1)
From the prompt screen you can enter an employee number such as 52. After using the ENTER key you should see the details of employee 52's VC2EMP record. From this screen you can use command key 23 to delete the record, ENTER to update the record with any changes you may have keyed in, command key 12 to exit the screen without updating the record, and command key 3 to exit the program.
