The Write Record using CLF (WRTRCDCLF) command is used by a CL program to add data to a file. The command writes a record to the file from 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.
If you need to write a record by relative record number you can use the Write by Relative Record Number by CLF (WRTRRNCLF) command. WRTRRNCLF must be used when writing to a subfile record or writing to a specific database record that has been previously deleted.
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 with either USAGE(*OUTPUT) or USAGE(*BOTH).
- The user must have write (*ADD) data authority to the file.
- 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 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 WRTRCDCLF command.
If not using the CLF precompiler this keyword identifies the CL variable to write the record data from. This CL variable is typically declared by the Generate File Field Definition (GENFFDCLF) command.
- character-value
- Specify the name of a CL variable to write the record from. This CL variable is typically declared by the Generate File Field Definition (GENFFDCLF) command and has the same name as the record format name unless the file and record format names are the same.
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 WRTRCDCLF
Example 1: Write a Record to a Database File
ChgVar Var(&EmpNbr) Value(0001)
ChgVar Var(&EmpSts) Value('F')
ChgVar Var(&EmpFName) Value('Rebecca')
ChgVar Var(&EmpDpt) Value(' ')
ChgVar Var(&EmpDptM) Value('A1')
ChgVar Var(&EmpExt) Value('9044')
WrtRcdCLF FileID(VC2EMP)
This example writes one record to the sample employee master file VC2EMP. This example is an extract from program DEV_LOAD that loads employee and department records into the CLF provided sample databases.
The full source for the example can be found in member DEV_LOAD of source file VC2CLSRC in library VC2CLF.
Example 2: Write to a Database File with Error Checking
DclIndCLF CLFInd(*Yes)
ChgVar Var(&EmpNbr) Value(0001)
ChgVar Var(&EmpSts) Value('F')
ChgVar Var(&EmpFName) Value('Rebecca')
ChgVar Var(&EmpDpt) Value(' ')
ChgVar Var(&EmpDptM) Value('A1')
ChgVar Var(&EmpExt) Value('9044')
WrtRcdCLF FileID(VC2EMP) ERR(&ERR)
If Cond(&ERR) Then(SndPgmMsg +
Msg('Write operation failed'))
This example is similiar to Example 1 except that error checking has been added to the WRTRCDCLF command. If an error is encountered when writing the record then the message 'Write operation failed' is sent.
The CL variable &ERR is defined due to the addition of DCLINDCLF CLFIND(*YES) earlier in the program source. If ERR(&ERR) is not coded for the WRTRCDCLF command and an error is encountered then an escape message will be sent.
Example 3: Writing to an Externally Described Print File
Pgm
/***********************************************/
/* This program creates a printed report */
/* listing employees in key sequence using */
/* the VC2EMPDPT access path (Dept/First name) */
/***********************************************/
/***********************************************/
/* Declare two working variables: */
/* &CURLIN - the current line number printed */
/* &PAGOVR - the overflow line number for a */
/* page */
/***********************************************/
Dcl Var(&CurLin) Type(*Dec) Len(3 0)
Dcl Var(&PagOvr) Type(*Dec) Len(3 0)
/***********************************************/
/* Declare our files and indicators */
/* VC2EMPDPT - Employees by department */
/* VC2POSPRT - External printer file */
/* CLF Indicators - &EOF used in program */
/***********************************************/
DclFCLF FileID(VC2EMPDPT)
DclFCLF FileID(VC2POSPRT)
DclIndCLF CLFInd(*Yes)
/***********************************************/
/* Open the files */
/***********************************************/
OpnFCLF FileID(VC2EMPDPT) AccMth(*Key)
OpnFCLF FileID(VC2POSPRT) Usage(*Output)
/***********************************************/
/* Retrieve the page overflow line number */
/***********************************************/
RtvFInfCLF FileID(VC2POSPRT) PrtFOvrFlw(&PagOvr)
/***********************************************/
/* Write titles for report on first page */
/***********************************************/
WrtRcdCLF RcdFmt(HEADING)
/***********************************************/
/* Read the first record from VC2EMPDPT */
/***********************************************/
ReadRcdCLF FileID(VC2EMPDPT) EOF(&EOF)
DoWhile Cond(*Not &EOF)
/**********************************************/
/* While we have not reached End of File */
/* on VC2EMPDPT: */
/* 1 Retrieve the current print line number */
/* 2 If the current print line number is */
/* greater than or equal to the overflow */
/* line number then start a new page and */
/* re-write titles on the page */
/* 3 Write the detail employee print line */
/* 4 Read the next employee record */
/* 5 Continue in this loop until End of File */
/**********************************************/
RtvFInfCLF FileID(VC2POSPRT) CurPrtLine(&CurLin)
If Cond(&CurLin *GE &PagOvr) Then( +
WrtRcdCLF RcdFmt(HEADING))
WrtRcdCLF RcdFmt(DETAILS)
ReadRcdCLF FileID(VC2EMPDPT) EOF(&EOF)
EndDo
/***********************************************/
/* At End of File close the files and return */
/***********************************************/
CloFCLF VC2EMPDPT
CloFCLF VC2POSPRT
EndPgm
The example program opens the VC2EMPDPT logical file and creates a report using the external printer file VC2POSPRT. The report lists all employees in the CLF provided sample database. The VC2EMPDPT logical file is keyed by employee first name within department.
The source for the example can be found in member DEV_POSPRT of source file VC2CLSRC in library VC2CLF. The source for logical file VC2EMPDPT can be found in member VC2EMPDPT of source file QDDSSRC in library VC2CLF. The source for printer file VC2POSPRT can be found in member VC2POSPRT of source file QDDSSRC in library VC2CLF.
The logical file VC2EMPDPT and printer file VC2POSPRT should currently exist in library VC2CLF. To compile the DEV_POSPRT program into QTEMP you can use the commands
AddLibLE Lib(VC2CLF)
CrtBndCLF Pgm(QTEMP/DEV_POSPRT) SrcFile(VC2CLSRC)
To run the program you can call it using the command
Call Pgm(QTEMP/DEV_POSPRT)
Example 4: Write a Record Containing a Null field to a Database File
/**********************************************************/
/* */
/* This program loads the sample VC2DPTNUL file. This */
/* file is used with CLF commands that work with */
/* null-capable fields. */
/* */
/* The VC2DPTNUL file is similiar to the VC2DPT file. The */
/* difference is that the department manager (DPTMGR), */
/* time of next department meeting (DPTNXTMTG), and date */
/* of last department manager change (DPTMGRC) fields are */
/* defined as being null capable. The next department */
/* meeting field for department MS is set to NULL. */
/* */
/* To use this program: */
/* */
/* 1. Create the VC2DPTNUL physical file. To create */
/* the file into QTEMP use the command */
/* */
/* CRTPF FILE(QTEMP/VC2DPTNUL) + */
/* SRCFILE(VC2CLF/QDDSSRC) */
/* */
/* 2. Create the DEV_LOADNL program after ensuring */
/* that your library list allows the precompiler */
/* to locate the VC2DPTNUL file. To create the */
/* program into QTEMP use the command */
/* */
/* CRTBNDCLF PGM(QTEMP/DEV_LOADNL) + */
/* SRCFILE(VC2CLF/VC2CLSRC) */
/* */
/* 3. Call the program using the command */
/* */
/* CALL PGM(QTEMP/DEV_LOADNL) */
/* */
/**********************************************************/
Pgm
/**********************************************************/
/* Declare the VC2DPTNUL file */
/**********************************************************/
DclFCLF FileID(VC2DPTNUL)
/**********************************************************/
/* */
/* Declare: */
/* &NOT_NULL to set null attribute *OFF */
/* &IS_NULL to set null attribute *ON */
/* */
/**********************************************************/
Dcl Var(&Not_Null) Type(*Lgl) Value('0')
Dcl Var(&Is_Null) Type(*Lgl) Value('1')
/**********************************************************/
/* Open the VC2DPTVAR file for output/writing and allow */
/* NULL fields */
/**********************************************************/
OpnFCLF FileID(VC2DPTNUL) Usage(*Output) +
AlwNull(*Yes)
/**********************************************************/
/* Now just set the fields and write the records. */
/* CHGNULACLF is used to set &DPTNXTMTG of department MS */
/* to NULL. */
/**********************************************************/
ChgVar Var(&DptID) Value(A1)
ChgVar Var(&DptName) Value('Corporate Management')
ChgVar Var(&DptMgr) Value(1)
ChgVar Var(&DptNxtMtg) +
Value('2008-12-17-10.00.00.000000')
ChgVar Var(&DptMgrC) Value('11/14/2008')
ChgVar Var(&DptStrT) Value('08:00:00')
WrtRcdCLF FileID(VC2DPTNUL)
ChgVar Var(&DptID) Value(MN)
ChgVar Var(&DptName) Value('Product Development')
ChgVar Var(&DptMgr) Value(13)
ChgVar Var(&DptNxtMtg) +
Value('2008-12-19-15.00.00.000000')
ChgVar Var(&DptMgrC) Value('10/10/2008')
ChgVar Var(&DptStrT) Value('07:00:00')
WrtRcdCLF FileID(VC2DPTNUL)
ChgVar Var(&DptID) Value(CO)
ChgVar Var(&DptName) Value('Product Support')
ChgVar Var(&DptMgr) Value(205)
ChgVar Var(&DptNxtMtg) +
Value('2008-12-03-11.30.00.000000')
ChgVar Var(&DptMgrC) Value('01/02/2008')
ChgVar Var(&DptStrT) Value('06:30:00')
WrtRcdCLF FileID(VC2DPTNUL)
ChgVar Var(&DptID) Value(MS)
ChgVar Var(&DptName) Value('Administrative Support')
ChgVar Var(&DptMgr) Value(40)
ChgNulACLF Var(&DptNxtMtg) VarAtr(&Is_Null)
ChgVar Var(&DptMgrC) Value('08/15/2008')
ChgVar Var(&DptStrT) Value('08:00:00')
WrtRcdCLF FileID(VC2DPTNUL)
ChgNulACLF Var(&DptNxtMtg) VarAtr(&Not_Null)
ChgVar Var(&DptID) Value(RO)
ChgVar Var(&DptName) Value('Product Marketing')
ChgVar Var(&DptMgr) Value(107)
ChgVar Var(&DptNxtMtg) +
Value('2009-01-05-08.00.00.000000')
ChgVar Var(&DptMgrC) Value('08/15/2008')
ChgVar Var(&DptStrT) Value('07:30:00')
WrtRcdCLF FileID(VC2DPTNUL)
CloFCLF FileID(VC2DPTNUL)
EndPgm
The sample program loads 5 records into the VC2DPTNUL database file. The file used, VC2DPTNUL, is based on the VC2DPT file used in many CLF examples. The difference is that some of the fields are now defined as being null-capable. When adding the record for department 'MS' DEV_LOADNL will set the next department meeting field, DPTNXTMTG, to null.
The source for the example can be found in member DEV_LOADNL of source file VC2CLSRC in library VC2CLF. The source for physical file VC2DPT can be found in member VC2DPT of source file QDDSSRC in library VC2CLF.
To compile example DEV_LOADNL use either Create Bound CLF Program (CRTBNDCLF) or Create CLF Program (CRTCLFPGM).
