7.6.1 CALL Parameters
Specifies the name of a 3GL program which is to be invoked. This parameter is a qualified name. Either a program name or a process name (but not both) must be specified on this command. If required the library in which the program resides can also be specified. If no library name is specified, library *LIBL is assumed which indicates the execution time library list of the job should be searched to find the program.
The use of library names in a CALL command is not recommended. For further information, refer to Specifying File Names in I/O Commands.
|
Portability Considerations |
Calls of 3GL programs are only supported in RDMLX programs on IBM i for compatibility with existing RDML code. As such, only RDML fields and lists are supported in the parameters PARM, PGM_EXCH, PASS_DS and PASS_LIST that may be used for 3GL program calls. A build warning will be generated if used in Visual LANSA code. An error will occur at execution time. Code using this facility can be conditioned so that it is not executed in this environment. For further information refer to Calling 3GL Programs in the . |
Specifies the name of the LANSA process which is to be invoked. Either a 3GL program name or a process name (but not both) must be specified.
When calling a function there are large performance benefits to be gained from using a "direct" call.
To use a direct call simply specify the name *DIRECT in this parameter, in place of the actual process name, and then nominate the function name in the FUNCTION parameter.
Note:- A *DIRECT call does not perform security checking in the same way that a process controlled call does. This is one of the major reasons for its superior performance. Read the comments section before using the *DIRECT option.
- On IBM i, *DIRECT calls must be used when calling between RDML and RDMLX functions.
- Full RDMLX Forms cannot call a Process. Only a Function can be called.
- Forms that are NOT enabled for full RDMLX can call a Process.
Optionally specifies the function within the nominated process that should be invoked. If this parameter is not specified a default value of *MENU is assumed that indicates that the main menu of the nominated process should be displayed for the user to select the desired function.
Is optional and if specified will define a list of parameters which are to be passed to the called program. The parameters must correspond to the expected parameters in the called program. This is NOT checked by LANSA. For further information, refer to Quotes and Quoted Strings. This parameter allows expandable group expressions.
|
Portability Considerations |
Not supported in the current release of Visual LANSA and not expected to be supported in future releases. |
Is valid when calling another process only. This parameter is ignored when calling another program. Specifies what is to happen when the called process is ended by use of the EXIT function key or the EXIT command. The EXIT_USED parameter will only take effect if the EXIT function key or the EXIT command were used to end the called process.
*EXIT indicates that this function should itself terminate and request an exit from the entire LANSA system.
*MENU indicates that this function itself should terminate and request that the process main menu be re-displayed.
*NEXT indicates that control should be passed to the next command.
*RETURN specifies that in a program mainline control is to be returned to the caller and in a subroutine control is to be returned to the caller routine or the program mainline.
If none of the previous values are used you must nominate a valid command label to which control should be passed.
Specifies the name of the WEBROUTINE to call. You can specify another WAM, in this case WAM name followed by a WEBROUTINE name separated by a dot (for example #MyWAM.MyWebRtn).
A Service Name can also be specified, if prefixed with *SERVICE modifier.
The value can also be provided from a field, if prefixed with *EVALUATE modifier.
Is valid when calling another WEBROUTINE only. For WEBROUTINE information, refer to WEBROUTINE.
Used for mapping incoming fields and list into the target WEBROUTINE.
Can be one of:
*MAP_NONE does not map any fields or lists).
*MAP_ALL maps all required fields and lists.
*MAP_LOCAL only fields and lists on WEBROUTINE's WEB_MAPs are mapped.
*MAP_SHARED only WAM level WEB_MAP fields and lists are mapped, not WEBROUTINE level.
The default value is *MAP_ALL.
Is valid when calling another WEBROUTINE only.
Used for mapping outgoing fields from the target WEBROUTINE.
Can be one of:
*MAP_NONE does not map any fields or lists.
*MAP_ALL maps all required fields and lists.
*MAP_LOCAL only fields and lists on WEBROUTINE's WEB_MAPs are mapped.
*MAP_SHARED only WAM level WEB_MAP fields and lists are mapped, not WEBROUTINE level.
The default value is *MAP_ALL.
Is valid when calling another process only. This parameter is ignored when calling another program. Specifies what is to happen when the called process is ended by use of the MENU function key or the MENU command. The MENU_USED parameter will only take effect if the MENU/CANCEL function key or the MENU command were used to end the called process.
*EXIT indicates that this function should itself terminate and request an exit from the entire LANSA system.
*MENU indicates that this function itself should terminate and request that the process main menu be re-displayed.
*NEXT indicates that control should be passed to the next command.
*RETURN specifies that in a program mainline control is to be returned to the caller and in a subroutine control is to be returned to the caller routine or the program mainline.
If none of the previous values are used you must nominate a valid command label to which control should be passed.
Specifies the length to be used when passing numeric fields or literals as parameters when calling a user program.
*ALL15 is the default and indicates that all numeric parameters should be passed with length packed 15,N (where N = number of decimal places defined as per the data dictionary or DEFINE command).
*DEFINED indicates that all numeric parameters should be passed with length as per the data dictionary or DEFINE command.
Specifies whether or not the program specified by the PGM parameter will require access to the LANSA exchange list that is normally only used to communicate information between LANSA processes and functions.
This parameter has no meaning when placing a call to a LANSA process or function (i.e: PROCESS or FUNCTION parameters used). In this context it is totally ignored, no matter what value it has.
*NO, which is the default value, specifies that the program nominated in the PGM parameter, or programs that it in turn may call, do not require access to the LANSA exchange list.
*YES specifies that the program nominated in the PGM parameter, or programs that it in turn may call, do require access to the LANSA exchange list by placing calls to program M@EXCHL.
The use of program M@EXCHL is described in detail in the section that describes the EXCHANGE command and exchange list processing.
Is valid when calling a program or a process/function.
This parameter specifies what is to happen when the called program or process/function terminates with an error.
*ABORT, which is the default value, indicates that this function itself should terminate with an error.
*NEXT indicates that control should be passed to the next command.
*RETURN specifies that in a program mainline control is to be returned to the caller and in a subroutine control is to be returned to the caller routine or the program mainline.
If none of the previous values are used you must nominate a valid command label to which control should be passed.
Allows up to 20 different data structures to be passed from an RDML function into another RDML function or 3GL program. The following points should be noted before attempting to use this parameter:
Each data structure name should be the name of a physical file which has been defined to LANSA and made operational.
CALL PROCESS(*DIRECT) must be specified when this parameter is used (and the call is being made to a LANSA function).
To be able to pass fields within the named physical file, the fields must be referenced at some point within the function, otherwise they will not be passed to the caller. This applies to the function being called also. Only real fields in the file can be passed, not virtual fields.
This point needs to be well understood. Say a file definition contained 3 numeric real fields called A, B and C.
An RDML function is written and it sets fields A and C to zero, then calls another RDML function that receives the structure.
If the called function started with the command "IF (B = 17)" it would fail because field B does not contain valid numeric data. It does not contain valid numeric data because the first function made no "reference to" or "mention of" field B at all.
The "reference" does not have to be a specific "CHANGE FIELD(B) TO(0)" type of command, it can be any reference at all in any command. It just needs to tell LANSA that it is "interested" in field B, and therefore needs to map the current value of field B into and out of the contiguous data structure storage area before and after the call to the other function.
It is also important to note that the order in which the data structures are specified on the PASS_DS parameter of the calling function and the order in which they are specified on the RCV_DS parameter of the called function (see FUNCTION command) is significant - the data structures must appear in the same order in the called and calling functions, otherwise errors may occur.
Avoid using this facility in conjunction with the EXCHANGE command data transfer facility, particularly where a field is in both the exchange list and the data structure.
If a 3GL program is being called the data structures should be defined as received parameters in the same order as they are defined in the RDML CALL command.
A 3GL call can involve: parameters (PARM), data structures (PASS_DS) and working lists (PASS_LST). Parameters are always passed first, then all data structures, then all working lists.
The use of this facility with 3GL programs is not recommended unless the developer has extensive 3GL experience.
Allows up to 20 different working list names to be passed into an RDML function or 3GL program. The following points should be noted before using this parameter:
Each working list specified must be a defined working list within the function.
CALL PROCESS(*DIRECT) must be specified when this parameter is used (and the call is to an RDML function).
The working lists must have been defined with the same attributes in both the calling and called function/program 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 on the CALL command 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 will occur.
If a 3GL program is being called the receiving data structures should be defined as received parameters in the same order as they are defined in the RDML CALL command.
A 3GL call can involve: parameters (PARM), data structures (PASS_DS) and working lists (PASS_LST). Parameters are always passed first, then all data structures, then all working lists.
Under IBM i each working list is actually passed as three 3GL level parameters:
1. Under IBM i this is the storage area representing the working list at maximum size.
2. A numeric (IBM i packed 7,0) value representing the count of the number of list entries that exist within the list area.
3. A numeric (IBM i packed 7,0) value representing the "current" list entry being processed by the caller.
The use of this facility with 3GL programs is not recommended unless the developer has very extensive 3GL experience.