The Retrieve Null Attribute (RTVNULACLF) command is used in a CL program to retrieve information on whether a field is currently null.
When an error in the program, for instance retrieving null status information for a field that is not null-capable or retrieving null status information for a field that is associated with a file that is not open, the RTVNULACLF command will indicate the the field is not null.
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 retrieve 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 retrieve 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 accessing null status information associated with the fields of the first record read. Reading a record from a file will cause all RTVNULACLF 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 RTVNULACLF
Example 1: Retrieving the Null Status of a Field
Dcl Var(&Null_Atr) Type(*Lgl)
RtvNulACLF Var(&SomeFld) VarAtr(&Null_Atr)
This example retrieves the null status of a field named &SOMEFLD. If &SOMEFLD is currently null the value of the CL variable &NULL_ATR, null attribute, will be set to '1' (on). If the field is not currently null then the CL variable &NULLATR will be set to a value of '0' (off). The &SOMEFLD field is defined by only one file within the program.
Example 2: Displaying the Null Status of a Database Field
/**********************************************************/
/* */
/* This program takes one parameter -- Department ID */
/* */
/* The program will display the date and time of the next */
/* department meeting (DPTNXTMTG). If NULL, the program */
/* will display a single dash ('-') */
/* */
/**********************************************************/
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 logical variable &NULL_STS. */
/* This will contain the status of a tested */
/* field read from the VC2DPTNUL database. */
/***********************************************/
Dcl Var(&Null_Sts) Type(*Lgl) Value('1')
/***********************************************/
/* 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 input, keyed */
/* access, and allowing null field values. */
/***********************************************/
OpnFCLF FileID(VC2DPTNUL) AccMth(*Key) +
AlwNull(*Yes)
/***********************************************/
/* 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: */
/* */
/* If &DPTNXTMTG is NULL display the */
/* department ID and a '-' */
/* Otherwise display the department ID and */
/* the time for next department meeting */
/***********************************************/
Else Cmd(Do)
RtvNulACLF Var(&DptNxtMtg) VarAtr(&Null_Sts)
If Cond(&Null_Sts *EQ &Is_Null) Then( +
SndPgmMsg Msg(&DptID *BCat '-'))
Else Cmd(SndPgmMsg Msg( +
&DptID *BCat &DptNxtMtg))
EndDo
/***********************************************/
/* Having completed the update close the */
/* file and return to the caller */
/***********************************************/
CloFCLF FileID(VC2DPTNUL)
EndPgm
This example reads a department record from the VC2DPTNUL database file. If the DPTNXTMTG field of the record is NULL, the department ID and a '-' are displayed. If DPTNXTCHG is not NULL, the department ID and time of next department meeting are set.
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_DSPNUL 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.
To compile DEV_DSPNUL you use the CLF precompiler command Create Bound CLF Program (CRTBNDCLF) or Create CLF Program (CRTCLFPGM).
To run DEV_DSPNUL you call it with one parameter - a department ID. A department ID with a NULL DPTNXTMTG field is 'MS'. A department is with a non-NULL DPTNXTMTG field is 'A1'. An invalid department ID is 'MO'.
