7.63.1 FUNCTION Parameters

OPTIONS

RCV_DS

RCV_LIST

TRIGGER

OPTIONS

Allows up to 9 different options to be specified. Values that may be specified in this parameter include:

*NOMESSAGES

Specifies that the program will never be required to route messages in from its caller, nor route messages back to its caller (unless it fails). By using this option the entry and exit resources used by a compiled RDML function can be reduced.

When this option is used, outstanding developer messages are not checked for. This can benefit performance of heavily used / called functions in a production environment where developer services is on.

*DEFERWRITE

Portability Considerations

Will be ignored with no known effect to the application, if used in Visual LANSA code.

Specifies that any IBM i display file created to service DISPLAY, REQUEST or POP_UP commands within this program should always use the DFRWRT(*YES) parameter. By using this option the time spent by the program waiting for device responses can be reduced.

Any program that uses a POP_UP command, or communicates to remotely attached devices, should use this option.

*HEAVYUSAGE and *LIGHTUSAGE

Specify that the compiled RDML function should use the HEAVY usage option or the LIGHT usage option regardless of what option the associated process uses.

For details of the heavy and light usage options, refer to Anticipated Usage.

Note that RDMLX functions will, by default, retain their state between invocations. If the state is not to be retained, then use components that are *DYNAMIC.

*DBOPTIMIZE or *DBOPTIMISE

Portability Considerations

Will be ignored with no known effect to the application, if used in Visual LANSA and RDMLX code.

 

Specifies that the RDML function should not use I/O modules to access database files, but rather OPTIMIZE database access by using direct I/O techniques.

Using this option can enhance application performance. However, many additional considerations and restrictions apply to using this option.

It is strongly recommended that  you read Using *DBOPTIMIZE / *DBOPTIMIZE_Batch in the LANSA for i User Guide before attempting to use this option.

*DBOPTIMIZE_BATCH or *DBOPTIMISE_BATCH

Portability Considerations

Will be ignored with no known effect to the application, if used in Visual LANSA and RDMLX code.

Specifies that the RDML function should not use I/O modules to access database files, but rather OPTIMIZE database access by using direct I/O techniques best suited to batch processing involving large volumes of update or delete operations.

Using this option can enhance batch application performance. However, many additional considerations and restrictions apply to using this option.

It is strongly recommended that you read Using *DBOPTIMIZE / *DBOPTIMIZE_Batch in the LANSA for i User Guide before attempting to use this option.

*PGMCOMMIT

Portability Considerations

Will be ignored with no known effect to the application, if used in Visual LANSA and RDMLX code. A build warning will be generated.

 

Specifies that individual program level commitment control is required for all files opened for any type of update activity by this RDML function.

Using this option overrides and supersedes any individual database file's definition or RDML command with regard to commitment control status and/or autocommit options.

Additionally, the operating system's commitment control facility will be started and ended automatically by the RDML function. See User Exit F@BGNCMT - Start Commitment Control and User Exit F@ENDCMT - End Commitment Control in the LANSA for i User Guide for details.

The issuing of COMMIT and ROLLBACK commands at the appropriate transaction boundary is the responsibility of the user.

This facility is primarily intended for batch processing.

It is strongly recommended that Commitment Control in the LANSA for i User Guide be read in full before attempting to use this option.

Using *PGMCOMMIT implies the use of *DBOPTIMIZE, regardless of whether or not the *DBOPTIMIZE option is actually specified.

*NOPGMCOMMIT

Portability Considerations

Will be ignored with no known effect to the application, if used in Visual LANSA and RDMLX code. A build warning will be generated.

Specifies that individual program level commitment control is NOT required for all files opened for any type of update activity by this RDML function.

Using this option overrides and supersedes any individual database file's definition or RDML command with regard to commitment control status and/or autocommit options.

Using *NOPGMCOMMIT implies the use of *DBOPTIMIZE, regardless of whether or not the *DBOPTIMIZE option is actually specified.

*NOIGCCNV

Portability Considerations

Will be ignored with no known effect to the application, if used in Visual LANSA code.

 

Specifies that the IGCCNV DDS keyword (for IGC conversion) should not be enabled for any display file created to support this function, regardless of the setting of the "IGCCNV required" flag in the definition of the current language.

Normally, any display file created for a function, under a language that has the "IGCCNV required" flag set, has the IGCCNV DDS keyword generated into it automatically.

Using this option suppresses the automatic enabling of the IGCCNV keyword in all display file DDS generated for this function.

*NO_RLTB_MIRROR

Specifies that the automatic "mirroring" of field positions on screen panels and report layouts should not be enabled in this function, regardless of whether or not the function is being compiled under a right-to-left language.

The automatic "mirroring" facility, and this parameter value, only apply to functions being compiled under right-to-left languages. This parameter is ignored for all other language groups.

*DIRECT

Specifies that this function should be made eligible for potential direct calling from another function, or to directly service a prompt key request.

Note: All RDMLX Functions must use *DIRECT. This ensures that migrated IBM i RDML Functions are unique.

By using this option you are indicating that this function may be directly invoked by another caller function, or to directly service a prompt key request.

Whether or not this is a completely valid way to invoke this function is not important at this stage. This option just indicates that, should the need arise, the function may be directly called.

It is recommended that all functions include a FUNCTION command containing this option, and that any application template created before this option became available, should be modified to automatically generate a FUNCTION command using this option.

Refer to the CALL command for more details of how a direct mode call is made and the restrictions that exist when using this type of call operation.

*CLOSE_DISPLAY

Portability Considerations

Will be ignored with no known effect to the application, if used in Visual LANSA code.

This option indicates that even though the function may remain active as a HEAVY usage process, or a *HEAVYUSAGE function, its display file should be closed when it terminates, and re-opened when it is activated again.

This option is primarily intended for use in pop-up window prompt key functions that suffer from "restored" displays that are out of date, or that "flash" onto the screen.

If this option is used, ensure that all browse lists are specifically cleared (CLR_LIST command) at each entry or (re)entry to the function. This ensures that any counter fields are reset to zero to match the current number of entries in the list, which will be zero because the display file was closed on any previous termination.

*MLOPTIMIZE or *MLOPTIMISE

Portability Considerations

Will be ignored if used in Visual LANSA and RDMLX code.

Specifies that an RDML function using multilingual support (which is defined at the partition level) should be optimized for multilingual application support of five or less languages.

Using this option can enhance application performance where typically five or less languages are being supported.

When an RDML function is compiled a main program object results.

When the RDML function is in a multilingual partition an "extra" program object is also produced.

The main RDML compiled function declares a storage area to contains all "literal" values that may be subject to dynamic change by language.

When it is invoked it calls the extra program to initialize the storage area with the literal values that are correct for the current language.

This is an efficient approach when quite a large number of languages are involved because the main program only has to declare storage sufficient for one language set.

When the extra program is invoked it temporarily uses storage sufficient for all languages, copies the correct language details into the main programs storage area, then ends, freeing all the extra (and now unneeded) language storage areas.

This approach also has two disadvantages. Firstly, it means that the RDML function takes longer to compile because two compiled program objects must be produced. Secondly, it means that the main RDML function must place a call to the extra initializing program during function startup.

By using *MLOPTIMIZE (or *MLOPTIMISE) the existence of the extra initializing function can be suppressed. The storage required for all languages is declared in the main program and the storage area used for the current language is initialized directly by the main program.

Using *MLOPTIMIZE in a function means more storage requirements in the main program, but less resource usage during compiles and during function invocation.

Since more storage is used, it is recommended that *MLOPTIMIZE is only used in functions that are supporting 5 or less languages.

However, the value 5 is a recommendation only, and the option can be used in functions supporting more languages, at the discretion of the application designer.

The following points about *MLOPTIMIZE should also be noted:

Use of *MLOPTIMIZE in any situation where these conditions are not all met does no harm. A warning message is issued and the *MLOPTIMIZE request is ignored.

*ALP_SYSTEM_VARIABLE

Specifies that this function is to be a system variable evaluation function (for alphanumeric variables only).
Option *DIRECT must also be used when this option is used.

*NUM_SYSTEM_VARIABLE

Specifies that this function is to be a system variable evaluation function (for numeric system variables only).
Option *DIRECT must also be used when this option is used.

*ALP_FIELD_VALIDATE

Specifies that this function is to be a complex logic check function (for alphanumeric fields only).

Refer to the Complex Logic Rule in the LANSA for i User Guide for further information. Option *DIRECT must also be used when this option is used.

*NUM_FIELD_VALIDATE

Specifies that this function is to be a complex logic check function (for numeric fields only).

Refer to the Complex Logic Rule in the LANSA for i User Guide for further information. Option *DIRECT must also be used when this option is used.

Technical notes for *ALP_FIELD_VALIDATE and *NUM_FIELD_VALIDATE

Complex logic validation functions can handle fields of different lengths and decimal precision but not of different types. The FUNCTION command option of *ALP_FIELD_VALIDATE will indicate that this is a function to validate an alphanumeric field. The FUNCTION command option of *NUM_FIELD_VALIDATE will indicate that this is a function to validate a numeric field.

In order to access the field name, length and the field value within the validation function it is necessary to define the following fields in the data dictionary:

Note that this implementation effectively prohibits validating numeric fields that have more than 21 significant digits.

If option *ALP_FIELD_VALIDATE or *NUM_FIELD_VALIDATE are used within the function, return the calculated return code in field VALFLD$RT. This should be returned by the validation function as '1' (good return) or '0' (bad return).

If either *ALP_FIELD_VALIDATE or *NUM_FIELD_VALIDATE have been entered as a function option the following design constraints (rather than technical constraints) exist to ensure the correct use of the facility:

*MINI_SCREEN

Portability Considerations

Do not use this option unless the application is IBM i based and it is using "miniature" or "palm top" devices that have a screen panel size smaller than the normal 24 line x 80 column devices.

Do not use this option in functions that contain normal full panel DISPLAY or REQUEST commands.

Do not use this option in functions that are GUI enabled. If used in Visual LANSA code it will be ignored. A build warning will be generated.

Specifies that POP_UP commands used within this function are to be used for "mini screen" display devices that may be attached to an IBM i system. When this option is used the following changes to the normal way that the POP_UP commands function are activated:

 

*OS400_EXT_PRINT

Portability Considerations

Not supported in Visual LANSA and RDMLX code. A build warning will be generated if used.

 

specifies that LANSA should generate and use IBM i specific External Printer files for the RDML function. By itself there is no advantage in using this option, but it must be specified to utilize User Define Reporting Attributes within the RDML function.

The use of this Option makes the function IBM i PLATFORM DEPENDENT.

When *OS400_EXT_PRINT is specified there are certain restrictions:

If any of these restrictions are broken then a fatal error will result when function Checking.

More information on User Defined Reporting Attributes and External Printer files, is supplied in User Defined Reporting Attributes in the LANSA for i User Guide.

*BUILTIN

Specifies that this function is to be a Built-In Function.

Refer to Create your Own Built-In Functions in the LANSA Application Design Guide for more details. *DIRECT must also be used when this option is used.

*STRICT_NULL_ASSIGN

Specifies that it is an error to assign an *SQLNULL into a non-nullable field.

The default is not to be strict and in simple terms treat an *SQLNULL value as *NULL when assigning into a non-nullable field. For a definition of the *NULL value for each of the field types, refer to 7.12.1 CHANGE Parameters.

Refer to Assignment, Conditions, and Expressions with Fields allowing SQL Null for full details on strict null assignment versus the default behaviour.

RCV_DS

Allows up to 20 different data structure names to be specified which can be received by the function. The following points should be noted when using this parameter:

Each data structure name should be the name of a physical file which has been defined to LANSA.

FUNCTION OPTIONS(*DIRECT) must be specified when this parameter is used.

A function receiving data structure(s) is flagged as being not directly accessible from a process menu (or an action bar) during its compilation, unless the special *EXCHANGE option is used.

Such a function has to be called from another function that will pass the correct data structures (in the correct order) rather than being called directly from a process menu or action bar.

To be able to receive fields within the named physical file (ie: data structure), the fields must be referenced at some point within the function, otherwise they will not be received. This applies to the calling function also. Only real fields from the file can be passed, not virtual fields.

It is important to note that the order in which the data structures are specified on the PASS_DS parameter of the CALL command and the order in which they are specified on the RCV_DS on the FUNCTION command of the called function is significant - the data structures must appear in the same order in the called and calling functions, otherwise errors could occur.

Likewise, when the layout of a data structure is changed, all functions that reference it in a RCV_DS or PASS_DS parameter should be recompiled after the changed data structure has been made operational.

A specialized option called *EXCHANGE may be used as the first argument of the RCV_DS parameter ( e.g.: RCV_DS(*EXCHANGE CUSMST PRODMST) ). This indicates that the named data structures are to be passed and returned via an "exchange list" type of structure, rather than as actual parameters.

This facility is highly specialized and designed for use only in functions that exactly match the following criteria. DO NOT USE this option unless your function exactly matches these criteria:

The processing logic used in a function using RCV_DS(*EXCHANGE) is like this:

Some technical considerations when using this option are:

RCV_LIST

Allows up to 20 different working list names to be specified. The following points should be noted when using this parameter:

Each working list specified must be a defined working list within the function.

FUNCTION OPTIONS(*DIRECT) must be specified when this parameter is used.

A function receiving a working list will be flagged as being not accessible from the main menu when it is compiled. It will have to be called from another function passing in the correct working lists, rather than from a menu.

The working lists must have been defined with the same attributes in both the called and calling function otherwise errors could occur.

It is also important to note that the order in which the working lists are specified on the PASS_LST parameter of the calling function and the order in which they are specified on the RCV_LIST of the called function is significant - the working lists must appear in the same order in the called and calling functions, otherwise errors could occur.

TRIGGER

is used to specify that this function is to act as a "trigger" for a data dictionary field or a database file.

*NONE, which is the default value, indicates that this function is not a trigger function.

*FIELD indicates that this function is to act as a data dictionary level trigger. The associated data dictionary field name must also be specified in this parameter.

*FILE indicates that this function is to act as a database level trigger. The associated database file name must also be specified in this parameter. The file specified must be a physical file.

For further details, refer to Triggers.

When a function is defined as a trigger function you must follow these guidelines:

When a function is defined as a trigger function you should follow these guidelines in most situations: