The Write by RRN using CLF (WRTRRNCLF) command is used by a CL program to add data to a file by relative record number. The record can be a subfile record within a display file or a deleted record within a database file. In the case of a database file, the Initialize Physical File Member (INZPFM) command can be used to initialize deleted records within 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 do not need to specify a relative record number you can use the Write Record using CLF (WRTRCDCLF) 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 with either USAGE(*OUTPUT) or USAGE(*BOTH).
• When using a data base file 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.

Parameters

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.

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.

Relative record number (RRN)

Specifies the relative record number of the record to be written.

unsigned integer

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

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 WRTRRNCLF command.

If not using the CLF precompiler this keyword identifies the CL variable to write the record data from. This CL variable is typically defined with 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 WRTRRNCLF

Example 1: Writing Subfile Records

    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              */
    /***********************************************/
    DclFCLF    FileID(VC2DPT)
    DclFCLF    FileID(VC2EMP)
    DclFCLF    FileID(VC2EMPDPT)
    DclFCLF    FileID(DISPLAY) File(VC2DPTDSP1)
    DclIndCLF  CLFInd(*Yes)
    /***********************************************/
    /* Open the files.                             */
    /***********************************************/
    OpnFCLF    FileID(DISPLAY) Usage(*Both)
    OpnFCLF    FileID(VC2DPT) AccMth(*Key)
    OpnFCLF    FileID(VC2EMP) AccMth(*Key)
    OpnFCLF    FileID(VC2EMPDPT) AccMth(*Key)
    /***********************************************/
    /* Initialize department subfile               */
    /***********************************************/
    WrtRcdCLF  RcdFmt(SFLCTLDPT)
    /***********************************************/
    /* Load list of departments into subfile       */
    /***********************************************/
    ReadRcdCLF FileID(VC2DPT) Type(*First) EOF(&EOF)
    DoWhile    Cond(*Not &EOF)
               /************************************/
               /* Get department managers name     */
               /************************************/
               ReadRcdCLF FileID(VC2EMP) +
                 Type(*Key) RcdNotFnd(&RNF) +
                 KeyRel(*EQ) KeyList(&DptMgr)
               /************************************/
               /* 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)
               WrtRRNCLF RcdFmt(SFLDPT) RRN(&Dpt_Count)
               ReadRcdCLF FileID(VC2DPT) Type(*Nxt) +
                 EOF(&EOF)
               EndDo
    /***********************************************/
    /* If VC2DPT is empty then prompt to run the   */
    /* DEV_LOAD sample program                     */
    /***********************************************/
    If         Cond(&Dpt_Count *EQ 0) Then(Do)
               WrtReadCLF 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 */
               /************************************/
               WrtRcdCLF RcdFmt(KEY)
               /************************************/
               /* Clear message indicator          */
               /************************************/
               ChgVar Var(&IN50) Value('0')
               /************************************/
               /* Show Subfile and Control record  */
               /************************************/
               ChgVar Var(&IN21) Value('1')
               WrtReadCLF RcdFmt(SFLCTLDPT)
               /************************************/
               /* Read subfile records to see if   */
               /* user wants to view the employees */
               /* in the department (option 5)     */
               /************************************/
               ReadRcdCLF RcdFmt(SFLDPT) TYPE(*CHG) +
                  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(' ')
                     UpdRcdCLF RcdFmt(SFLDPT)
                     /******************************/
                     /* Now go display employees   */
                     /******************************/
                     CallSubr Subr(Show_Emps)
                     EndDo
                  /*********************************/
                  /* That department is done.  Now */
                  /* check if another was selected */
                  /*********************************/
                  ReadRcdCLF RcdFmt(SFLDPT) Type(*Chg) +
                    EOF(&EOF)
                  EndDo
               EndDo
    /***********************************************/
    /* Close the files as command key 3 was used   */
    /***********************************************/
    CloFCLF    FileID(VC2EMP)
    CloFCLF    FileID(VC2DPT)
    CloFCLF    FileID(VC2EMPDPT)
    CloFCLF    FileID(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 */
    WrtRcdCLF  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    */
    /***********************************************/
    PosDBFCLF  FileID(VC2EMPDPT) Type(*Key) +
                 RcdNotFnd(&RNF) KeyRel(*EQ) +
                 KeyList(&DptID)
    /***********************************************/
    /* If one was found, process all in department */
    /***********************************************/
    If         Cond(*Not &RNF) Then(Do)
               ReadRcdCLF FileID(VC2EMPDPT) Type(*Key) +
                 EOF(&EOF) KeyRel(*NxtEQ) KeyList(&DptID)
               /************************************/
               /* So long as there are employees   */
               /* in department:                   */
               /************************************/
               DoWhile Cond(*Not &EOF)
               /************************************/
               /* Set depart. subfile record number*/
               /* Write department record          */
               /* Get next department record       */
               /************************************/
                  ChgVar Var(&Emp_Count) +
                    Value(&Emp_Count + 1)
                  WrtRRNCLF RcdFmt(SFLEMP) RRN(&Emp_Count)
                  ReadRcdCLF FileID(VC2EMPDPT) +
                    Type(*Key) EOF(&EOF) KeyRel(*NxtEQ) +
                    KeyList(&DptID)
                  EndDo
               /************************************/
               /* With all of the department       */
               /* employees loaded into the        */
               /* subfile, now display the active  */
               /* command keys                     */
               /************************************/
               WrtRcdCLF RcdFmt(KEY)
               /************************************/
               /* Show Subfile and Control record. */
               /* When user hits ENTER or command  */
               /* key 3 return to main line.       */
               /************************************/
               ChgVar Var(&IN21) Value('1')
               WrtReadCLF 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 DEV_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/DEV_DPTU1) SrcFile(VC2CLSRC)

To run DEV_DPTU1 you can use the command

    Call Pgm(QTEMP/DEV_DPTU1)

DEV_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.

Example 2: Writing Database Records

This example demonstrates writing a new record by RRN to replace a deleted record within a file.

    /******************************************************/
    /* This program randomly reads the 12th record of the */
    /* VC2EMP physical file by relative record number.    */
    /* The employee name found (Ruth) is displayed. The   */
    /* record is then deleted and an attempt to read the  */
    /* same record made. The record should not be found   */
    /* as it has been deleted and a message is sent based */
    /* on whether or not the record is successfully read. */
    /* The program then writes a new 12th record to add   */
    /* a new employee. The program then re-reads the 12th */
    /* record and displays the employee name found (Chad) */
    /******************************************************/
    Pgm
    /******************************************************/
    /* Declare the file and CLF indicators                */
    /******************************************************/
    DclFCLF    FileID(VC2EMP)
    DclIndCLF  CLFInd(*Yes)
    /******************************************************/
    /* Open the file for RRN access and update            */
    /******************************************************/
    OpnFCLF    FileID(VC2EMP) Usage(*Both)
    /******************************************************/
    /* Read the 12th record and display the name found    */
    /******************************************************/
    ReadRcdCLF FileID(VC2EMP) Type(*RRN) RRN(12)
    SndPgmMsg  Msg(&EmpFName *BCat 'found')
    /******************************************************/
    /* Delete the record read and try to re-read it.      */
    /* A record-not-found condition should be returned.   */
    /******************************************************/
    DltRcdCLF  FileID(VC2EMP)
    ReadRcdCLF FileID(VC2EMP) Type(*RRN) RRN(12) +
                 RcdNotFnd(&RNF)
    If         Cond(&RNF) Then( +
               SndPgmMsg Msg('Record not found'))
    Else       Cmd(SndPgmMsg Msg( +
               &EmpFName *BCat 'found after delete'))
    /******************************************************/
    /* Write a new record at the deleted position (RRN 12)*/
    /******************************************************/
    ChgVar     Var(&EmpFName) Value('Chad')
    ChgVar     Var(&EmpSts) Value(F)
    WrtRRNCLF  FileID(VC2EMP) RRN(12)
    /******************************************************/
    /* Read the 12th record and display the name found    */
    /******************************************************/
    ReadRcdCLF FileID(VC2EMP) Type(*RRN) RRN(12)
    SndPgmMsg  Msg(&EmpFName *BCat 'found after write')
    /******************************************************/
    /* Close the file and return                          */
    /******************************************************/
    CloFCLF    FileID(VC2EMP)
    EndPgm

The source for this example can be found in member DEV_RRNUSG 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 compile DEV_RRNUSG into library QTEMP you can use the commands

    AddLibLE Lib(VC2CLF)
    CrtBNDCLF Pgm(QTEMP/DEV_RRNUSG) SrcFile(VC2CLSRC)

Prior to running DEV_RRNUSG you should reload the VC2EMP database file to ensure that the expected results are seen. To reload the file you can refer to the source member DEV_LOAD in source file VC2CLF/VC2CLSRC or Appendix D of the CLF Programmer's Guide.

After reloading the VC2EMP file you can call DEV_RRNUSG with the command

    Call Pgm(QTEMP/DEV_RRNUSG)

You should see the following messages displayed

    Ruth found
    Record not found
    Chad found after write

Error messages for WRTRRNCLF

*ESCAPE Messages

VC25018

File &1 is not open for update or writing of new records.

VC2501E

Write to file ID &2 not successful.

VC2502E

File ID &1 is not open.

VC25065

RCDBUF parameter is missing on &2 command.

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.