7 63 1 FUNCTION Parameters

You are here:

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:

You must be using OS/400 V2R1 (or higher).

The application must be in a multilingual partition.

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:

VALFLD$NM A(10) Name of Field being Validated

VALFLD$LN P(7,0) Length of Field being Validated

VALFLD$DP P(7,0) No. of decimals for Field being Validated
VALFLD$AV A(256) Current Field Value (Alphanumeric Field and only the first 256 bytes of *Char/ *String Field).
Note: The *SQLNULL special value can't be evaluated to the *Char/*String Field Type in the CALLBACK Function because the VALFLD$AV is *Alpha type.

VALFLD$NV P(30,9) Current Field Value (Numeric Field)

VALFLD$RT A(1) Return code

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

The following design constraints, rather than technical constraints, exist if either *ALP_FIELD_VALIDATE or *NUM_FIELD_VALIDATE have been entered as a function option. To ensure the correct use of the facility:

No DISPLAY, REQUEST or POP_UP command can be used within a complex logic validation function.

No CALL can exist to another process/function within a complex logic validation function. However, a call to a 3GL program can exist.

Complex logic validation functions cannot exist within an action bar process. This is not to say that they cannot be referenced from within an action bar, it just means that a complex logic function cannot be defined as part of a process that is of action bar type.

Complex logic validation functions cannot have options of RCV_DS or RCV_LIST.

The associated process must not have parameters.

The exchange list may not be used. This restriction ensures insulated modularity in the validation check.

Recursive implementations may be defined, but will fail to execute correctly. For instance, a validation checker function invoked during an insert to file A could attempt to insert data into file B, possibly causing itself to be invoked in a recursive situation, and thus to fail.

Use of options *DBOPTIMIZE and *NOMESSAGES are recommended for complex logic validation functions. The use of *HEAVYUSAGE may also be considered in heavily used validation functions.

The use of option *MLOPTIMIZE is strongly recommended in all multilingual applications of this 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:

No borders are presented.

The window can be located left as far as row 1, column 1.

The borderless window produces a representation of a "mini" full screen panel, rather than of a typical pop-up window.

Browselists presented within a pop-up window where all field column headings have been overridden to blanks values will not be spaced/separated from the header area by the normal separation line.

This means that manually defined text can be effectively specified for "apparent" column headings. This facility is only used where all fields in the browselist have their column headings overridden to blanks. It also means that it is hard to insert a whole new line of text into the design via the screen painter because the normal separation line cannot be used as a target position to "push" the browselist down the screen panel. To insert a new line of text return to the RDML editor and define a "dummy" field into the header area at the end of the FIELDS list and then re-invoke the screen painter. The dummy field should be positioned so as to "push" the browselist further down the screen panel. Add/move the necessary text and/or field onto the new line created and then optionally delete the "dummy" field.

Where large scale use of this feature is being made it is strongly recommended that an Application Template be constructed for invocation by the "ET" (Execute Template) editor action. This template can be used to construct a "standard layout" for every "mini-screen" including one or more initial "dummy" fields to push the browselist portion onto the required starting line and leave sufficient space for the insertion of fields and/or text into the header area.

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

*DIRECT must also be specified.

The SKIP command cannot be used.

Only Report Number 1 may be used.

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:

They are directly invoked from a menu or an action bar. This feature was provided to allow such functions to "exchange" a complete set of data structures amongst themselves, rather that having to use the EXCHANGE command to exchange many individual fields.

They are not called by other functions. Why use this option when the data structure can be directly passed in by the caller in the normal manner?

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

As the function is entered, the "exchange area" is searched for data structures (by data structure name, not by order of specification). When a match is found the content is copied into the data structure. When a match is not found the content of the data structure remains unchanged.

The "exchange area" is then cleared of all data structures.

The function then proceeds to do its normal processing.

When the function terminates normally (in any way) the contents of all the data structures nominated in the RCV_DS parameter are copied back into the "exchange area".

Some technical considerations when using this option are:

Only functions that use RCV_DS(*EXCHANGE .....) will search, clear and alter the exchange area. Functions that do not use this option have no impact at all on the exchange area.

The maximum length of the exchange area is 9999 bytes. Attempting to use a set of data structures with an aggregate length exceeding this limit will cause an application failure.

The actual storage of the exchange area is performed by a shipped program called M@EXCHDS. To optimize performance under the IBM i operating system and prevent PAG (Process Access Group) "holes" this program has an "open" and "close" option that can be used before LANSA is invoked (e.g.: during system sign on). The "open" and "close" option uses the LANSA convention of CALL M@EXCHDS (X'00') to open and CALL M@EXCHDS (X'FF') to close. Obviously the close operation clears the exchange area. Do not call M@EXCHDS from within LANSA RDML functions. These types of calls are not required to actually use this facility, only to OPTIMIZE its use.

Using RCV_DS(*EXCHANGE ....) is less efficient than using a normal RCV_DS(.....) parameter, but more efficient than using an EXCHANGE command with many fields.

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:

The parameter RCV_LIST(#TRIG_LIST) must be used.

The parameter RCV_DS must not be used.

Option *DIRECT must also be used.

Options xxx_SYSTEM_VARIABLE or xxx_FIELD_VALIDATE must not be used.

The list #TRIG_LIST must be defined by a DEF_LIST command as DEF_LIST NAME(#TRIG_LIST) TYPE(*WORKING) ENTRYS(2) and must not include any fields in the FIELDS parameter. The required fields will be automatically added.

No DISPLAY, REQUEST or POP_UP commands may be used. This is a deliberately imposed design/usage constraint that may be removed in later versions.

No CALL can exist to another process/function. This is a deliberately imposed design/usage constraint that may be removed in later versions.

If the Built-In Function CALL_SERVER_FUNCTION is used to call a function via SuperServer, you must not pass the list #TRIG_LIST to the server function.

Trigger functions cannot be defined within an action bar process. This is not to say that they cannot be referenced from within an action bar, it just means that a trigger function cannot be defined as part of a process that is of action bar type.

The associated process must not have any parameters.

The exchange list may not be used. This is a deliberately imposed design/usage constraint imposed to enforce insulated and modular design and use of trigger functions.

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

Understand how triggers are defined and how they should be used by also reading Triggers.

Use options *NOMESSAGES and *MLOPTIMIZE.

Options *HEAVYUSAGE and *DBOPTIMIZE may also be considered.

Do not directly or indirectly access the database file that the trigger is, or will be, linked to.

Where triggers are heavily and constantly invoked avoid resource intensive operations. Such operations will slow down access to the associated file.

Recursive implementations may be defined, but will fail to execute correctly. For instance a field trigger function invoked during an insert to file A could attempt to insert data into file B, possibly causing itself to be invoked in a recursive situation, and thus to fail.