7.30.1 DEFINE Parameters

COLHDG

DECIMALS

DEFAULT

DESC

EDIT_CODE

EDIT_WORD

FIELD

INPUT_ATR

LABEL

LENGTH

OUTPUT_ATR

REFFLD

SHIFT

TO_OVERLAY

TYPE

Specifies the name of the field which is to be defined. The field name must start with a # and not be defined in the LANSA data dictionary. In addition, it must not be the name of a group or list defined within this function. Avoid the use of field names like SQLxxx, as this may cause problems when used in functions that use SQL (Structured Query Language) facilities. (IE Command SELECT_SQL.)

Specifies the type of field which is being defined. The permissible values are:

• *BIN indicates a Binary working field.

• *BOOLEAN indicates a Boolean working field. Valid values for use with a Boolean are True and False (not case sensitive) or 1 and 0 (zero).

• *CHAR indicates an Alpha working field.

• *DATE indicates a Date working field.

• *DATETIME indicates a Datetime working field.

• *DEC or synonym *PACKED indicates a Packed working field.

• *FLOAT indicates a Float working field.

• *INT indicates an Integer working field.

• *NVARCHAR indicates an NVarChar working field.

• *REFFLD indicates the type comes from the Reference field in the REFFLD parameter.

• *SIGNED indicates a Signed working field.

• *STRING indicates a String working field.

• *TIME indicates a Time working field.

If the Function or Component is not RDMLX enabled, only *REFFLD, *DEC, and *CHAR are valid types.

If the REFFLD parameter is not *NONE:

• and the referenced field is an RDMLX field
  the TYPE parameter MUST be specified as *REFFLD.

• and the reference field is an RDML field
  the TYPE parameter may only be set to *REFFLD, *DEC or *CHAR.
  Specifying the type as other than *REFFLD is not recommended as it renders useless the fundamental idea of repository fields.

Specifies the length of the field being defined. If the value *REFFLD is specified then the length to be used is the same as the field specified on the REFFLD parameter. For specific information on allowable field, lengths see Field Types

"Incr/decr" value is used in conjunction with *REFFLD on the length parameter. The purpose of this field is to allow the length value as obtained from the field specified on the REFFLD keyword to be altered. Permissible values are *PLUS, *MINUS and *NONE. *PLUS specifies that the REFFLD field length attribute is to be increased. *MINUS specifies that the REFFLD field length attribute is to be decreased. *NONE specifies that the REFFLD field length attribute is to remain the same.

"# to incr/decr" value is used in conjunction with the *REFFLD value on the length parameter and is directly related to the "incr/decr" value. The purpose of this field is to specify the value by which the REFFLD field length value is to be increased or decreased. Permissible values for this field are a numeric value or the value *NONE.

Specifies the number of decimal positions of the field being defined and is used in conjunction with the type value of *DEC. If the value *REFFLD is specified then the decimal positions to be used are the same as the field specified on the REFFLD parameter. Otherwise, a value in the range 0 to 63 must be specified.

All Fields of types other than Signed and Packed must have DECIMALS(0) or  DECIMALS(*REFFLD *NONE *NONE) specified.

"Incr/decr" value is used in conjunction with *REFFLD on the decimals parameter. The purpose of this field is to allow the decimal positions value as obtained from the field specified on the REFFLD keyword to be altered. Permissible values are *PLUS, *MINUS and *NONE. *PLUS specifies that the REFFLD field decimal positions attribute is to be increased. *MINUS specifies that the REFFLD field decimal positions attribute is to be decreased. *NONE specifies that the REFFLD field decimal positions attribute is to remain the same.

"# to incr/decr" value is used in conjunction with the *REFFLD value on the decimal positions parameter and is directly related to the "incr/decr" value. The purpose of this field is to specify the value by which the REFFLD field decimal positions value is to be increased or decreased. Permissible values for this field are a numeric value or the value *NONE.

Specifies the name of the field on which this definition is based.

Specifies the 15-character label which should be assigned to this field. *DEFAULT indicates the default label should be used. If the REFFLD parameter is used then the label of the referenced field will be used. If the REFFLD parameter is not used then the name of the field being defined will be used as the label.

Specifies the 50-character description that should be assigned to this field. *DEFAULT specifies the default description should be used. If the REFFLD parameter is used then the description of the referenced field will be used. If the REFFLD parameter is not used then the name of the field being defined will be used as the description.

Specifies the 3 x 20 character column headings that should be assigned to this field. *DEFAULT specifies that the default column headings should be used. If the REFFLD parameter is specified then the column heading of the referenced field will be used. If REFFLD is not used then the name of the field will be used as column heading 1.

Specifies the edit code (if any) which is to be assigned to the field being defined. If no edit code is specified then the value *DEFAULT is assumed.

*DEFAULT indicates that the edit code of the REFFLD field should be used if the REFFLD parameter is used. Otherwise, no edit code should be used for the field.

Use of edit codes for all numeric fields (e.g. type *DEC) is strongly recommended.

Fields of type Integer, Signed, or Packed may have an Editcode or Editword, or may leave both as *DEFAULT. However, Integer does not allow edit codes W and Y. All other field types must have EDIT_CODE(*DEFAULT) EDIT_WORD(*DEFAULT).

Edit codes supported by LANSA are shown in Standard Field Edit Codes.

Specifies the edit word (if any) which is to be assigned to the field being defined. If no edit word is specified then the value *DEFAULT is assumed.

*DEFAULT indicates that the edit word of the REFFLD field should be used if the REFFLD parameter is used. Otherwise no edit word should be used for the field.

Fields of type Integer, Signed, or Packed may have an Editcode or Editword, or may leave both as *DEFAULT. All other field types must have EDIT_CODE(*SAME) EDIT_WORD(*SAME).

Use of edit words should only be attempted by experienced users as the validity checking done by LANSA is unsophisticated.

Note that by using the REFFLD option and EDIT_WORD(*DEFAULT) you are specifying that the edit word associated with the REFFLD should be used. However, if the length or number of decimal positions used are different to the REFFLD field then the associated edit word may be invalid. In such cases it will be necessary to define the required edit word.

Note also that the operating system handles edit words involving floating currency symbols on screen panels differently to how they are handled on reports. In such cases, it is suggested that a separate field (or a "virtual" field) is used for report production.

When an edit word is defined in LANSA via the RDML command language it should be enclosed in triple quotes as opposed to single quotes.

For example:

Correct Method for defining an edit word for a 5,2 numeric field requiring a trailing %.

   DEFINE FIELD(#INCREASE) TYPE(#DEC) LENGTH(5) DECIMALS(2) LABEL('Sales Increase') EDIT_WORD('''   .  %''')

Incorrect Method for defining an edit word for a 5,2 numeric field requiring a trailing %.

   DEFINE FIELD(#INCREASE) TYPE(#DEC) LENGTH(5) DECIMALS(2) LABEL('Sales Increase') EDIT_WORD('   .  %')

For further details, refer to keyword EDTWRD in IBM manual Data Description Specifications.

Specifies the input attributes which are to be assigned to the field being defined. If no input attributes are defined then the value *DEFAULT is assumed.

*DEFAULT indicates that the input attributes of the REFFLD field should be used if the REFFLD parameter is used. Otherwise the system default input attributes list for either alpha or numeric fields should be used according to the field type.

For information on allowable attributes for RDMLX fields see Field Types

Valid input attributes for types A (alphanumeric), P (packed), and S (signed) are:

Attributes marked with * represent the field with the corresponding GUI WIMP construct. Refer to GUI WIMP Constructs in the LANSA for i User Guide for more information.

In partitions that comply with SAA/CUA guidelines the following attributes may be used as well (and are in fact preferred to those described above):

Specifies the output attributes which are to be assigned to the field being defined. If no output attributes are specified then the value *DEFAULT is assumed.

*DEFAULT indicates that the output attributes of the REFFLD field should be used if the REFFLD parameter is used. Otherwise the system default output attributes list for either alpha or numeric fields should be used according to the field type.

For information on allowable attributes for RDMLX fields see Field Types

Valid output attributes for types Alpha (A), Packed (P), and Signed (S) are:

Attributes marked with an * represent the field with the corresponding GUI WIMP construct. Refer to GUI WIMP Constructsin the LANSA for i User Guide for more information

In partitions that comply with SAA/CUA guidelines, the following attributes may be used as well (and are in fact preferred to those described above):

Specifies the default value which is to apply to the field being defined.

This is the value that the field will contain when the function begins to execute. Note that using the EXCHANGE command can appear to alter the default value of a field.

For information on what DEFAULT(*DEFAULT) means for RDMLX fields see Field Types

If no default value is specified then *DEFAULT is assumed. This means that if the REFFLD parameter has been specified the default value of the REFFLD field will be used. If the REFFLD parameter has not been used then a default value of *BLANKS will be used for alphanumeric fields and a default value of *ZERO for numeric fields will be used.

Default values specified can be:

• A system variable such as *BLANKS, *ZERO, *DATE or any other specifically defined at your installation.

• An alphanumeric literal such as BALMAIN.

• A numeric literal such as 1, 10.43, -1.341217.

• A process parameter such as *UP01.

• *SQLNULL is allowed as a default value for any field type that has ASQN as an input or output attribute.

• *NULL is allowed as a default value for any field type (if the partition is RDMLX enabled).

Specifies that the field being defined is to fully or partially overlay (i.e. occupy the same storage locations) as the field referenced in this parameter.

It is invalid for RDMLX fields to be overlaid or overlay another field.

*NONE, which is the default value, indicates that the field being defined is to occupy its own storage area and not to overlay any other field.

The only other allowable value that can be specified here is the name of another field defined in this program or the data dictionary, optionally followed by a starting position.

The TO_OVERLAY parameter is a powerful facility that allows a field to occupy the same storage (ie: memory locations) as another field. The power of this parameter means that you must understand exactly what it causes to happen and what problems you may cause yourself in using it.

The following notes and comments should be read in full before attempting to use this parameter:

• You must NOT overlay a field onto a field that is itself overlaid onto another field. This is NOT checked by the full function checker and may cause a compile failure.

• You should fully understand the IBM i data storage formats of character, signed/zoned decimal and packed decimal before attempting to overlay fields of varying types. Overlaying of fields means that you can easily cause invalid decimal data to be placed into decimal fields, thus causing your program to fail in an unpredictable manner.

• Array index fields must not be overlaid on or by other fields (in any context).

• The start position component of this parameter allows you to overlay just a part of a specific field, rather than its entire length. The start position is a full byte position, even when using packed decimal fields. When you specify a start position you MUST ensure that you do not overlay the field beyond the end position of the field being overlaid.
  
  This is NOT checked by the full function checker. Failure to observe this rule can cause dangerous and unpredictable results.
  
  

• A packed decimal field of even length can be overlaid on another field, however the RPG compiler will always interpret the overlaying field as the next highest odd length. For example:

   DEFINE FIELD(#DEC6) TYPE(*DEC) LENGTH(6) DECIMALS(0)
   DEFINE FIELD(#OVR6) TYPE(*DEC) LENGTH(6) DECIMALS(0) TO_OVERLAY(#DEC6)

       will cause #DEC6 to be treated by the RPG compiler as a packed decimal (6,0) value. However, #OVR6 will be treated by the RPG compiler as a packed decimal (7,0) value. There is no memory length problem here, both fields require 4 bytes of memory to be stored, it is just the way that the RPG compiler works that may cause a presentation length problem on reports.       HOWEVER, if #OVR6 is put on a screen as only *OUTPUT, the function compile will crash. This is because the external description of #OVR6 from the display file will say that it is 6 digits, packed. Meanwhile, as stated above, the overlay causes the RPG compiler to assume that #OVR6 is 7 digits, packed.

• When the data validation commands RANGECHECK, VALUECHECK, DATECHECK, CALLCHECK, CONDCHECK, FILECHECK or SET_ERROR are used on an overlaying field, they also set an error for the overlaid field.
  
  For example:

         DEFINE FIELD(#INPUT) TYPE(*CHAR) LENGTH(3)
         DEFINE FIELD(#INPC1) TYPE(*CHAR) LENGTH(1)       TO_OVERLAY(#INPUT 1)
         DEFINE FIELD(#INPC3) TYPE(*CHAR) LENGTH(1)       TO_OVERLAY(#INPUT 3)
         REQUEST FIELDS(#INPUT)
         BEGINCHECK
         VALUECHECK FIELD(#INPC1) WITH_LIST('A' 'B' 'C')
         VALUECHECK FIELD(#INPC3) WITH_LIST('X' 'Y' 'Z')
         ENDCHECK

This program accepts a 3 character field (#INPUT) from the workstation and validates that the first character is an A, B or C and also that the last character is an X, Y or Z.

When an error is triggered against overlaid fields #INPC1 or #INPC3 by the VALUECHECK commands, it is also triggered against the overlaid field #INPUT. This means that when the REQUEST command is (re)executed in an error situation, field #INPUT will be displayed in reverse video.

Specifies the keyboard shift (if any) which is to be assigned to the field being defined. If no keyboard shift is specified then the value *DEFAULT is assumed.

*DEFAULT indicates that the keyboard shift of the REFFLD field should be used if the REFFLD parameter is used. Otherwise no keyboard shift should be used for the field.

For information on what values of SHIFT, apart from *DEFAULT, are valid for each working field type see Field Types.

For working fields of type Boolean, SHIFT must be *DEFAULT.

Refer to the IBM manual Data Description Specifications for more details. Position 35 for display files is the entry that should be reviewed.