Null-capable field support in LANSA

Date:Archived
Product/Release:LANSA for the AS/400
Abstract:Using Null capable fields within LANSA
Submitted By:LANSA Technical Support

LANSA for the AS/400 is capable of handling Null-capable fields containing null values for both input and output in externally described database files (i.e OTHER files). Following are the steps and conditions that need to be followed to allow Null value support for these files once they are defined to LANSA.

Note: The meaning of *NULL in LANSA:

In LANSA terms, the special value *NULL indicates all alphanumeric fields should be set to blanks and all numeric fields to zero. It is not NULL (i.e. X'00') as in the "C" language context.

Environment Considerations:

  • The operating system must be at Release V4R1M0 or above of the operating system.
  • The LANSA I/O modules need to be compiled using RPG/IV.
  • Specify the option *RPGIV in the data area DC@OSVEROP to indicate that each program is to be compiled using RPG/IV code, then bound as a single module ILE type program.
  • User Controlled Support for Null-Capable fields was first introduced in OS/400 V4R1M0 on the CRTRPGMOD (Create RPG Module) command by introducing two new handling options for the ALWNULL (Allow Null) parameter.
  • The ALWNULL keyword parameter on the CRTRPGMOD command determines how Null capable fields in an externally described file are handled in an ILE RPG program. There are four options :
    • ALWNULL(*NO) - Do not process records with null values. This is the default value.
    • ALWNULL(*USRCTL) - Read, write, update, and delete records with null values and retrieve and position-to records with null keys.
    • ALWNULL(*INPUTONLY) - Read records with null values to access the data in the null fields.
    • ALWNULL(*YES) - Same as *INPUTONLY.

Change the ALWNULL parameter default on the CRTRPGMOD command to *USRCTL using the CHGCMDDFT command to compile the LANSA I/O modules allowing input and output operations on null capable fields.

File Considerations:

After the file has been loaded into LANSA, virtual code logic and virtual fields need to be created to allow for the handling of the null indicator for each of the null capable fields. The %NULLIND built-in function is used to query or set the value of the null-indicator for null capable fields. This built-in function can only be used if the ALWNULL(*USRCTL) was specified for compilation.

When a record is retrieved from a database file and there are some fields containing null values in the record, default values for the null-capable fields will be placed into those fields containing. Because of these defaults, unless a certain value is used to depict null values, separate fields will need to be used to indicate null values for the fields.

  1. In the LANSA Repository, create virtual fields to be used as null value flag indicators for each of the null capable fields in the file.
     
  2. Include the virtual fields to the file then specify Yes to edit the virtual code.
    DC@P201601 Display Virtual Fields in File Definition
    File : COMPLEV IKLIB Neller - COMPLEV
    Edit virtual field derivation code . . . . . . YES YES, NO
    Sequence Name Description                                     PJF
    &&&              PJF's before virtuals derived on input      B
    &&&              Virtual Fields derived after input
    &&&              PJF's after virtuals derived on input       A
    &&&              Virtual Fields derived before output
    &&&              Undefined Virtual Fields                    U
    FLAG1           Null value indicator flag 1                  U
     
  3. Type in the RPG derivation code for the After Input and Before Output specifications for the file.
    DC@P201602 Edit Virtual Field Derivation Code
    File : COMPLEV IKLIB Neller - test file ( ENG )
    Choose section(s) of file I/O module in which virtual field derivation
    code is to be included ....
    Choose I/O module code section RPGIII type
    File specifications                          "F" specs
    Array specifications                         "E" specs
    External record format or field renames      "I" specs 
    Data structure specifications                "I" specs
    x Calculations after input from file         "C" specs
    x Calculations before output to file         "C" specs
    Internal subroutines                         "C" specs
    Output specifications                        "O" specs
    Compile time array data                      N/Applicable

Null Values:

The %NULLIND built-in function is used to query or set the null indicator for null-capable fields.This built-in function can only be used if the ALWNULL(*USRCTL) value will be specified on the create RPG module command.

  • %NULLIND can only be used in expressions in extended factor 2.
  • When used on the right-hand side of an expression, this function returns the setting of the null indicator for the null-capable field. The setting can be *ON or *OFF.

    E.g:

    CL0N01Factor1+++++++Opcode(E)+Extended-factor2+++++++++++++++++++++++++++
    * Test the null indicator for a null-capable field.
    C IF %NULLIND(fieldname1)
    C :
    C ENDIF
    *
    C IF NOT %NULLIND(fieldname2)
    C :
    C ENDIF

     
  • When used on the left-hand side of an expression, this function can be used to set the null indicator for null-capable fields to *ON or *OFF. The content of a null-capable field remains unchanged.

    E.g:

    CL0N01Factor1+++++++Opcode(E)+Extended-factor2+++++++++++++++++++++++++++
    * Set the null indicator for a null-capable field.
    C EVAL %NULLIND(fieldname1) = *ON
    C EVAL %NULLIND(fieldname2) = *OFF


  • When a record is retrieved from a database file and there are some fields containing null values in the record, database default values for the null-capable fields will be placed into those fields containing null values. The default value will be the user defined DDS defaults or system defaults.
  • When a null-capable field is written (output or update) to an externally described file, a null value is written out if the null indicator for the field is on at the time of the operation.
  • When a null-capable field is output to or updated in an externally described database file, then if the field is null, the value placed in the buffer will be ignored by data management.
  • Fields that have the null indicator on at the time of output have the data moved to the buffer. This means that errors such as decimal-data error, or basing pointer not set, will occur even if the null indicator for the field is on.
  • For physical files, when you specify the DATFMT keyword with values of *JOB, *MDY, *DMY, *YMD, or *JUL and the field allows null value, you must specify a valid date on the DFT keyword for this field, otherwise an error message for invalid date format will occur. See example below:

    |...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
    00010A R RECORD1
    00020A FIELD1 75A ALWNULL
    00030A FIELD2 100A
    00040A FIELD3 L ALWNULL
    00050A DATFMT(*MDY)
    00060A DFT('12/25/93')

Virtual Logic Code Warnings:

RPG/IV:- The syntax format must be in RPG/IV and each line of code must have the text **ILE after the form type. This will compile the virtual logic as RPG/IV instead of the RPG/III default. See examples below.

VC_USING:- All fields in the file used in the virtual code must be specified in the VC_USING command.

PACKED/SIGNED:- In the virtual code, only use the real name of the fields as defined in the files.

BINARY:- At this point in time, null-capable Binary fields must use the renamed LANSA field from the I/O module in the virtual code. After these files are loaded, they need to be made operational with the option to keep the compilation source listing. The source code must be scanned for the renamed field. Binary field renames always have the format @Bxxxx.

E.g:

380 I*=====================================================================
381 I* DATA STRUCTURE SPECIFICATIONS AND RECORD FORMAT FIELD RENAMES
382 I*=====================================================================
383 IBLOCKR@R
384 I FLD1 @F0001
385 I FLD2 @F0002
386 I FLD3 @B0003

E.g:

*---------------------------------------------------------------------
* RPG record format . . . . : UPDATE@R
* External format . . . . . : COMPLER : IKLIB/TEST1
*---------------------------------------------------------------------
3365=O*(NOTOUT) @F0001 15A CHAR 15 (FLD1)
3366=O*(NOTOUT) @F0002 16A CHAR 1 (FLD2)
3367=O*(NOTOUT ALWNULL) @B0003 34B BIN2 4,0 (FLD3)

Calculations after input from file

The virtual code in this section can be used to set the user null flag indicator fields for the null capable fields prior to being displayed or processed. The code below, is only an example of setting the null flags for the three null capable fields including a Binary field.

E.g:

CL0N01Factor1+++++++Opcode(E)+Extended-factor2++++++++++++++++++++
C*
C* VC_USING FIELDS(FLD1 FLAG1 FLD2 FLAG2 FLD3 FLAG3)
C*
C* Test if null indicator for FLD1 is on.
C*
C**ILE IF %NULLIND(FLD1)
C**ILE MOVE 'Y' FLAG1
C**ILE ELSE
C**ILE MOVE 'N' FLAG1
C**ILE ENDIF
C*
C* Test if null indicator for FLD2 is off.
C*
C**ILE IF NOT %NULLIND(FLD2)
C**ILE MOVE 'N' FLAG2
C**ILE ELSE
C**ILE MOVE 'Y' FLAG2
C**ILE ENDIF
C*
C* Test if null indicator for FLD3 is off. (BINARY FIELD)
C*
C**ILE IF %NULLIND(@B0003)
C**ILE MOVE 'Y' FLAG3
C**ILE ELSE
C**ILE MOVE 'N' FLAG3
C**ILE ENDIF
C*
C* Set the null indicator for FLD1 to on.
C**ILE EVAL %NULLIND(FLD1) = *ON
C*
C* Set the null indicator for FLD2 to off.
C**ILE EVAL %NULLIND(FLD2) = *OFF
C*
C* Set the null indicator for FLD3 to off.
C**ILE EVAL %NULLIND(@B0003) = *OFF
****************** End of data **********************************

Calculations before output to file

The virtual code in this section will set the null capable fields to null values if the user null flag indicators are set for null values. The code below is an example of setting the null capable fields to null values if the null flag is positive.

E.g:

CL0N01Factor1+++++++Opcode(E)+Extended-factor2++++++++++++++++++++
C*
C* VC_USING FIELDS(FLD1 FLAG1 FLD2 FLAG2)
C*
C* Check to see which NULL capable fields should be set to
C* NULL values.
C**ILE IF FLAG1 = 'Y'
C**ILE EVAL %NULLIND(FLD1) = *ON
C**ILE ELSE
C**ILE EVAL %NULLIND(FLD1) = *OFF
C**ILE MOVE 'N' FLAG1
C**ILE ENDIF
C*
C**ILE IF FLAG2 = 'N'
C**ILE EVAL %NULLIND(FLD2) = *OFF
C**ILE MOVE 'N' FLAG2
C**ILE ELSE
C**ILE EVAL %NULLIND(FLD2) = *ON
C**ILE ENDIF
C*
C**ILE IF FLAG3= 'N'
C**ILE EVAL %NULLIND(@B0003) = *OFF
C**ILE MOVE 'N' FLAG3
C**ILE ELSE
C**ILE EVAL %NULLIND(@B0003) = *ON
C**ILE ENDIF
****************** End of data ***********************************

After the virtual derivation code has been inserted and the changes to the file committed, compile the file, keeping the compilation source listing for any compilation errors.