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

FIELD

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

TYPE

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

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

If the REFFLD parameter is not *NONE:

LENGTH

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

Type

Notes for Length parameter

*REFFLD

*REFFLD, or any value that is valid for the underlying field type of the reference field.

*DEC or synonym *PACKED

LENGTH(*REFFLD) may only be specified if parameter REFFLD is specified.

If the REFFLD Parameter is specified, and it is an RDML field, changing the length to 31 or higher will make the working field an RDMLX field.

*CHAR

LENGTH(*REFFLD) may only be specified if parameter REFFLD is specified.

*STRING

If LENGTH(*REFFLD) REFFLD(*NONE) is specified, the length will default to 256.

*SIGNED

LENGTH(*REFFLD) may only be specified if parameter REFFLD is specified.

If the REFFLD Parameter is specified, and it is an RDML field, changing the length to 31 or higher will make the working field an RDMLX field.

*BIN

LENGTH(*REFFLD) may only be specified if parameter REFFLD is specified.

*DATE

Dates are fixed size (always 10)

incr/decr must be *NONE

# to incr/decr must be *NONE

*TIME

Times are fixed size (always 8)

incr/decr must be *NONE

# to incr/decr must be *NONE

*DATETIME

19, 21-29.

The various lengths influence the number of fractional seconds. This must be made clear. A length of 19 means no fractional seconds, 21 - 29 means 1 - 9 fractional seconds. The DECIMALS parameter has no impact.

If LENGTH(*REFFLD) REFFLD(*NONE) is specified, the length will default to the ISO standard of 26: YYYY-MM-DD HH:MM:SS.ffffff

incr/decr must be *NONE

# to incr/decr must be *NONE

 

 

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

DECIMALS

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.

REFFLD

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

LABEL

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.

DESC

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.

COLHDG

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.

EDIT_CODE

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.

EDIT_WORD

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.

INPUT_ATR

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:

Attribute

Description / Comments

A

P

S

AB

Allow to be blank.

Y

Y

Y

ME

Mandatory entry check required.

Y

Y

Y

MF

Mandatory fill check required.

Y

Y

Y

M10

Modulus 10 check required.

 

Y

Y

M11

Modulus 11 check required.

 

Y

Y

VN

Valid name check required.

Y

 

 

FE

Field exit key required.

Y

Y

Y

LC

Lowercase entry allowed. If you do NOT set this attribute, refer to PC Locale uppercasing requested in Review or Change a Partition's Multilingual Attributes in the LANSA for i User Guide.

Y

 

 

RB

Right adjust and blank fill.

 

Y

Y

RZ

Right adjust and zero fill.

 

Y

Y

RL

Move cursor right to left.

Y

Y

Y

RLTB

Tab cursor right/left top/bottom. Valid in SAA/CUA partitions only. Affects all screen panels

Y

Y

Y

GRN

Display with color green.

Y

Y

Y

WHT

Display with color white.

Y

Y

Y

RED

Display with color red.

Y

Y

Y

TRQ

Display with color turquoise.

Y

Y

Y

YLW

Display with color yellow.

Y

Y

Y

PNK

Display with color pink.

Y

Y

Y

BLU

Display with color blue.

Y

Y

Y

BL

Display blinking.

Y

Y

Y

CS

Display with column separators.

Y

Y

Y

HI

Display in high intensity.

Y

Y

Y

ND

Non-display (hidden field).

Y

Y

Y

RA

Auto record advance field

Y

Y

Y

SREV

Store in reversed format. This special attribute is provided for bi-directional languages & is not applicable in this context.

Y

N

N

SBIN

Store in binary format. This special attribute is provided for repository fields & is not applicable in this context.

Y

N

N

HIND

HINDI Numerics. Display using HINDI numerals. Refer to Hindi Numerics in the LANSA for i User Guide.

N

Y

Y

CBOX *

Check Box

Y

N

N

RBnn *

Radio Button

Y

N

N

PBnn *

Push Button

Y

N

N

DDXX *

Drop Down.

Y

N

N

 

 

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):

Attribute

Description / Comments

ABCH

Action bar and pull-down choices

PBPT

Panel title

PBPI

Panel identifier

PBIN

Instructions to user

PBFP

Field prompt / label / description details

PBBR

Brackets

PBCM

Field column headings

PBGH

Group headings

PBNT

Normal text

PBET

Emphasized text

PBEN *

Input capable field (normal)

PBEE *

Input capable field (emphasized)

PBCH

Choices shown on menu

PBSC

Choice last selected from menu

PBUC

Choices that are not available

PBCN

Protected field (normal)

PBCE

Protected field (emphasized)

PBSI

Scrolling information

PBSL

Separator line

PBWB

Pop-up window border

FKCH

Function key information

 

 

Note: Normally only PBEN and PBEE would be specified as input attributes. Refer to SAA/CUA Implementation in the LANSA Application Design Guide for more details of these attributes. Also note that only one color can be specified for a field. Use of colors may affect other attributes. Refer to IBM manual Data Description Specifications for more details. Keywords that should be reviewed are CHECK, COLOR and DSPATR.

OUTPUT_ATR

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:

Attribute

Description / Comments

A

P

S

GRN

Display with color green.

Y

Y

Y

WHT

Display with color white.

Y

Y

Y

RED

Display with color red.

Y

Y

Y

TRQ

Display with color turquoise.

Y

Y

Y

YLW

Display with color yellow.

Y

Y

Y

PNK

Display with color pink.

Y

Y

Y

BLU

Display with color blue.

Y

Y

Y

BL

Display blinking.

Y

Y

Y

CS

Display with column separators.

Y

Y

Y

HI

Display in high intensity.

Y

Y

Y

ND

Non-display (hidden field).

Y

Y

Y

SREV

Store in reversed format. This special attribute is provided for bi-directional languages and is not applicable in this context.

Y

N

N

SBIN

Store in binary format. This special attribute is provided for repository fields & is not applicable in this context.

Y

N

N

Urxx

User Defined Reporting Attribute. Provides access to IBM i DDS statements for printer files. Refer to User Defined Reporting Attributesin the LANSA for i User Guide.

Y

Y

Y

HIND

HINDI Numerics. Display using HINDI numerals. Refer to Hindi Numerics in the LANSA for i User Guide.

N

Y

Y

CBOX *

Check Box

Y

N

N

RBnn *

Radio Button

Y

N

N

PBnn *

Push Button

Y

N

N

DDxx *

Drop Down.

Y

N

N

 

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):

Attribute

Description / Comments

ABCH

Action bar and pull-down choices

PBPT

Panel title

PBPI

Panel identifier

PBIN

Instructions to user

PBFP

Field prompt / label / description details

PBBR

Brackets

PBCM

Field column headings

PBGH

Group headings

PBNT

Normal text

PBET

Emphasized text

PBEN

Input capable field (normal)

PBEE

Input capable field (emphasized)

PBCH

Choices shown on menu

PBSC

Choice last selected from menu

PBUC

Choices that are not available

PBCN *

Protected field (normal)

PBCE *

Protected field (emphasized)

PBSI

Scrolling information

PBSL

Separator line

PBWB

Pop-up window border

FKCH

Function key information

 

Note: Normally only PBCN and PBCE would be specified as output attributes. Refer to SAA/CUA Implementation in the LANSA Application Design Guide for more details of these attributes. Also note that only one color can be specified for a field. Use of colors may affect other attributes. Refer to IBM manual Data Description Specifications for more details. Keywords that should be reviewed are COLOR and DSPATR.

DEFAULT

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:

TO_OVERLAY

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:

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.

         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.

SHIFT

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.