The Update Record using CLF (UPDRCDCLF) command is used by a CL program to update data in a file. The command updates the currently locked record in the file using one or more CL variables.
The CL variables must be declared in the CL program with a Declare File using CLF (DCLFCLF) command, a Generate File Field Definition (GENFFDCLF) command, a Declare Indicators using CLF (DCLINDCLF) command, a Generate Indicators using CLF (GENINDCLF) command, a user provided Declare CL Variable (DCL) command, or a user provided Declare File (DCLF) command.
Restrictions:
- This command is valid only within a CL program.
- The file identified by the FILEID parameter must have been previously opened using the Open File using CLF (OPNFCLF) command and USAGE(*BOTH).
- The record being updated must have been previously read.
- The user must have update (*UPD) data authority.
- Input/Output operations to a CLF shared file open should not be run concurrently among threads in a job. A shared file open is one where the OPNPGM parameter has been specifed with a value other than *CURPGM. If application thread serialization is used CLF shared files will utilize a common I/O feedback information area.
File identifier (FILEID)
Specifies the file identifier that was used on a previous 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.
When using the precompiler, and 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.
This is a required parameter when not using the CLF precompiler.
- simple-name
- Specify a name that matches the FILEID parameter value of a previous 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).
Parameter containing record (RCDBUF)
When using the CLF precompiler support (CRTBNDCLF, CRTCLFMOD, or CRTCLFPGM), and the specified FILEID is defined using the DCLFCLF command, this keyword should not be specified. The precompiler will determine the appropriate buffer to be used based on the specified RCDFMT. If this keyword is used and the CL variable specified is not the same as what the precompiler would have calculated, then the user is responsible for all formatting of the CL variable prior to using the UPDRCDCLF command.
If not using the CLF precompiler this keyword identifies the CL variable to update the record from. This CL variable is typically defined by the Generate File Field Definition (GENFFDCLF) command.
- character-value
- Specify the name of a CL variable to update the record from. This CL variable is typically declared by the Generate File Field Definition (GENFFDCLF) command.
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 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 UPDRCDCLF
Example 1: Update a Database Record by Key
Pgm
/***********************************************/
/* Declare the Employee master file VC2EMP, */
/* display file VC2EMPDSP1, and indicators */
/* associated with CLF Input/Output commands */
/***********************************************/
DclFCLF FileID(VC2EMP)
DclFCLF FileID(VC2EMPDSP1)
DclIndCLF CLFInd(*Yes)
/***********************************************/
/* Declare the packed decimal field &RcdCnt */
/* that will be used to determine the current */
/* record count. If the file is empty */
/* (&RCDCNT = 0), prompt with how to load the */
/* VC2DPT 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 load records. */
/***********************************************/
OpnFCLF FileID(VC2EMP) Usage(*Both) AccMth(*Key)
RtvFInfCLF FileID(VC2EMP) NbrRcds(&RcdCnt)
If Cond(&RcdCnt = 0) Then(Do)
OpnFCLF FileID(VC2FEMPTY) Usage(*Both) +
LvlChk(*No)
WrtReadCLF FileID(VC2FEMPTY) RcdFmt(EmpEmp)
CloFCLF FileID(VC2FEMPTY)
CloFCLF FileID(VC2EMP)
Return
EndDo
/***********************************************/
/* Having verified that records exist now open */
/* the display file for this program. */
/***********************************************/
OpnFCLF FileID(VC2EMPDSP1) Usage(*Both)
/***********************************************/
/* Enter a DOWHILE loop that is exited when */
/* command key 3 is pressed. */
/* */
/* Within the loop: */
/* 1 Write and read the VC2EMPDSP1 *DSPF */
/* record format PROMPT. PROMPT asks for */
/* employee number. A valid employee */
/* number would be 00001. The user can */
/* press ENTER or command key 3. */
/* 2 If command key 3 was pressed leave the */
/* DoWhile loop */
/* 3 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)
WrtReadCLF RcdFmt(PROMPT)
If Cond(&IN03) Then(Leave)
ReadRcdCLF FileID(VC2EMP) TYPE(*Key) +
RcdNotFnd(&RNF) KeyRel(*EQ) +
KeyList(&EmpNbr)
If Cond(&RNF) Then(Do)
ChgVar Var(&IN50) Value('1')
Iterate
EndDo
WrtReadCLF RcdFmt(CHANGE)
Select
When Cond(&IN03) Then(Leave)
When Cond(&IN12) Then(Do)
RlsRcdCLF VC2EMP
Iterate
EndDo
When Cond(&IN23) Then(DltRcdCLF VC2EMP)
OtherWise Cmd(UpdRcdCLF FileID(VC2EMP))
EndSelect
EndDo
/***********************************************/
/* When F3 is used to exit the DoWhile loop */
/* close the files and return */
/***********************************************/
CloFCLF FileID(VC2EMP)
CloFCLF FileID(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.
DEV_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 WRTREADCLF command with the record format EMPEMP. The developer does not have to specify both keywords when using the WRTREADCLF 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 DEV_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 DEV_EMPU1 should currently exist in library VC2CLF. To compile example DEV_EMPU1 into QTEMP you can use the commands
AddLibLE Lib(VC2CLF)
CrtBndCLF Pgm(QTEMP/DEV_EMPU1) SrcFile(VC2CLSRC)
To test the program you can use the command
Call Pgm(QTEMP/DEV_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.
Example 2: Detecting an Error When Updating
Pgm
/******************************************************/
/* Declare the Employee master file VC2EMP, and */
/* indicators associated with CLF commands */
/******************************************************/
DclFCLF FileID(VC2EMP)
DclIndCLF CLFInd(*Yes)
/******************************************************/
/* Open VC2EMP and immediately attempt to update a */
/* a record. The update operation will fail with an */
/* error as the program has not previously read any */
/* records. */
/******************************************************/
OpnFCLF FileID(VC2EMP) Usage(*Both) AccMth(*Key)
UpdRcdCLF FileID(VC2EMP) ERR(&ERR)
/******************************************************/
/* Test for an error with the update (logical */
/* variable &ERR is "on") and send an appropriate */
/* message. */
/******************************************************/
If Cond(&ERR) Then(SndPgmMsg Msg( +
'Update operation failed'))
Else Cmd(SndPgmMsg Msg('Test program failed'))
/******************************************************/
/* Close VC2EMP and return */
/******************************************************/
CloFCLF FileID(VC2EMP)
EndPgm
This example demonstrates one way to check for an error when using the UPDRCDCLF command. If the ERR parameter is not used then escape message VC25037 will be sent if an error is encountered. The program could use the MONMSG command to detect that an error has been encountered.
The source for the example program can be found in member DEV_UPDERR of source file VC2CLSRC in library VC2CLF. The source for file VC2EMP can be found in member VC2EMP of source file QDDSSRC in library VC2CLF.
The VC2EMP file should currently exist in library VC2CLF. To create DEV_UPDERR in QTEMP you can use the commands
AddLibLE Lib(VC2CLF)
CrtBndCLF Pgm(QTEMP/DEV_UPDERR) SrcFile(VC2CLSRC)
