The Change Null Attribute (CHGNULACLF) command is used in a CL program to change the field attribute indicating whether a field is null or not.
When a run-time error in the program is encountered, for instance changing null status information for a field that is associated with a file that is not open, the CHGNULACLF command will run as if no change request had been made.
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 function 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.
- The file containing the null-capable field must be declared in the CL program using the Declare File using CLF (DCLFCLF) command. The file must be opened using the Open File using CLF (OPNFCLF) command with ALWNULL(*YES) specified.
- You can only change the status of a null-capable field upon successfully running the Read Record using CLF (READRCDCLF) command. Once a record has been read you can change the null status of one or more fields in the record. Reading a second record using the same File ID, including a different record format of the file, will prevent you from changing null status information associated with the fields of the first record read. Reading a record from a file will cause all CHGNULACLF command usage to refer to the most recently read record.
- 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.
Examples for CHGNULACLF
Example 1: Changing the Null Status of a Field
Dcl Var(&Is_Null) Type(*Lgl) Value('1')
ChgNulACLF Var(&SomeFld) VarAtr(&Is_Null)
This example sets the null status of a field named &SOMEFLD to being null. Only one file declared by the program defines the field &SOMEFLD as the FILEID and RCDFMT keywords are not being used.
Example 2: Changing the Null Status of a Field
/**********************************************************/
/* */
/* This program takes one parameter -- Department ID */
/* */
/* The program will set the date and time of the next */
/* department meeting (DPTNXTMTG) to null. */
/* */
/**********************************************************/
Pgm Parm(&DptID_In)
Dcl Var(&DptID_In) Type(*Char) Len(2)
/***********************************************/
/* Declare the logical variable &IS_NULL */
/* that, by having a value of '1' (on), */
/* represents a null-capable field being null. */
/***********************************************/
Dcl Var(&Is_Null) Type(*Lgl) Value('1')
/***********************************************/
/* 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 */
/* VC2DPTNUL file with sample data. */
/***********************************************/
Dcl Var(&RcdCnt) Type(*Dec) Len(10 0)
/***********************************************/
/* Declare the VC2DPTNUL Department Master and */
/* CLF related indicators (this program uses */
/* CLF related indicator &RNF - Record not */
/* found. */
/***********************************************/
DclFCLF FileID(VC2DPTNUL)
DclIndCLF CLFInd(*Yes)
/***********************************************/
/* Test to see if the &DPTID parameter was */
/* passed (only needed for bound programs). */
/* If not, end with an error message. */
/***********************************************/
ChgVar Var(&DptID) Value(&DptID_In)
MonMsg MsgID(MCH3601) Exec(Do)
RmvMsg Clear(*All)
SndPgmMsg Msg( +
'Department ID is a required parameter')
Return
EndDo
/***********************************************/
/* Open the VC2DPTNUL file for update, keyed */
/* access, and allowing null field values. */
/***********************************************/
OpnFCLF FileID(VC2DPTNUL) Usage(*Both) +
AccMth(*Key) AlwNull(*Yes)
/***********************************************/
/* Get the current record count and, if 0, */
/* display how to load records. */
/***********************************************/
RtvFInfCLF FileID(VC2DPTNUL) NbrRcds(&RcdCnt)
If Cond(&RcdCnt = 0) Then(Do)
OpnFCLF FileID(VC2FEMPTY) Usage(*Both) +
LvlChk(*No)
WrtReadCLF FileID(VC2FEMPTY) +
RcdFmt(DPTNUL)
CloFCLF FileID(VC2FEMPTY)
CloFCLF FileID(VC2DPTNUL)
Return
EndDo
/***********************************************/
/* Read the VC2DPTNUL record associated with */
/* the department ID passed as a parameter */
/* to this program. */
/* */
/* The &RNF indicator will be set to '1' (on) */
/* if there is no record found equal to the */
/* department ID parameter value. */
/***********************************************/
ReadRcdCLF FileID(VC2DPTNUL) Type(*Key) +
RcdNotFnd(&RNF) KeyRel(*EQ) +
KeyList(&DptID)
/***********************************************/
/* If no department record is found, send a */
/* message to the user. */
/***********************************************/
If Cond(&RNF) Then(SndPgmMsg Msg('Department' +
*BCat &DPTID *BCat 'not found.'))
/***********************************************/
/* If a department record is found: */
/* */
/* 1. Change the null attribute associated */
/* with the &DPTNXTMTG field to null */
/* 2. Upate the department record */
/***********************************************/
Else Cmd(Do)
ChgNulACLF Var(&DptNxtMtg) VarAtr(&Is_Null)
UpdRcdCLF FileID(VC2DPTNUL)
EndDo
/***********************************************/
/* Having completed the update close the */
/* file and return to the caller */
/***********************************************/
CloFCLF FileID(VC2DPTNUL)
EndPgm
This example sets the date and time of a departments next meeting to NULL. 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.
To load sample data into the VC2DPTNUL file use the DEV_LOADNL sample program. The DEV_LOADNL program source can be found in member DEV_LOADNL of source file VC2CLSRC in library VC2CLF. You compile this program with either CRTBNDCLF DEV_LOADNL or CRTCLFPGM DEV_LOADNL. CALL DEV_LOADNL will then load 5 records into the VC2DPTNUL database file. When adding the record for department MS DEV_LOADNL will also set the next department meeting field, DPTNXTMTG, to null.
The source for this example can be found in member DEV_CHGNUL of source file VC2CLSRC in library VC2CLF. The source for file VC2DPTNUL can be found in member VC2DPTNUL 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. The VC2FEMPTY display file is created in library VC2CLF as part of the CLF install process.
To compile DEV_CHGNUL you use the CLF precompiler command Create Bound CLF Program (CRTBNDCLF) or Create CLF Program (CRTCLFPGM).
To run DEV_CHGNUL you call it with one parameter - a department ID. A valid department ID would be 'RO'. An invalid ID would be 'MO'.
