7.72.1 OPEN Parameters
ALWCPYDTA, OPTIMIZE, SEQONLY, COMMIT and TYPE
ALWCPYDTA, OPTIMIZE, SEQONLY, COMMIT and TYPE
ALWCPYDTA, OPTIMIZE, SEQONLY, COMMIT and TYPE
ALWCPYDTA, OPTIMIZE, SEQONLY, COMMIT and TYPE
ALWCPYDTA, OPTIMIZE, SEQONLY, COMMIT and TYPE
Specifies the file(s) to be opened or controlled. Individual files can be specified or the default of *ALL can be nominated. For more information, refer to .
Note: The combination of parameters FILE(*ALL) and USE_OPTION(*OPNQRYF) is invalid. To open a query file, a specific file must be nominated in the FILE parameter.
|
Portability Considerations |
FILE (library) is not supported in Visual LANSA. A build warning will be generated if used in Visual LANSA code. |
Specifies the open or control option that LANSA is to use when opening this file. The allowable values for this parameter are:
*FIRSTSCREEN(FSS), which is the default value and is a "declarative" form of the command. This value indicates that the nominated file open(s) should be "overlapped" with the first screen interaction with the user. This means that the first screen is presented to the user, and while he/she is keying in data, the file(s) are opened.
*IMMEDIATE(IMD), which is an "executable" form of the command. This value indicates that the nominated file(s) should be opened immediately (ie: when the OPEN command is executed).
*ONDEMAND(OND), which is a "declarative" form of the command. This value specifies that the nominated file(s) should be opened as required (ie: on a demand basis). This means that the first I/O request to the file will cause it to be automatically opened. If no I/O request is ever made to the file it will not be opened.
*OPNQRYF(UOQ), which is an "executable" form of the command. This value indicates that the IBM i operating system command OPNQRYF should be used during the file open to select and/or order the data in the file. The file is opened when the OPEN command is executed.
OPNQRYF is a very powerful and useful command. However, it can cause significant performance degradation in some situations. Refer to the appropriate IBM supplied manuals for more details of the OPNQRYF command, its associated parameter values and performance impact.
*KEEPOPEN(KPO), which is an "executable" form of the command. This value indicates that the file(s) should be opened immediately (i.e., when the OPEN command is executed) and then left open until such time as they are closed by issuing a specific CLOSE command. Once a file has been opened this way it can only be closed from within LANSA by issuing a specific CLOSE command.
The automatic close logic used by LANSA when an RDML program terminates, cannot close a file that has been opened with this option.
This option is normally used for performance reasons to ensure that a frequently used file is left open at all times.
|
Portability Considerations |
*FIRSTSCREEN ignored with no known effect to the application. *ONDEMAND ignored with no known effect to the application. *OPNQRYF is only supported for execution on IBM i. On all other platforms an execution error will occur, but execution of the code can be made conditional. *KEEPOPEN ignored. Testing of application required. A build warning will be generated when used in Visual LANSA. |
Specifies the name of a field that is to receive the "return code" that results from the I/O operation.
If the default value of *STATUS is used the return code is placed into a special field called #IO$STS which can be referenced in the RDML program just like any other field.
If a user field is nominated to receive the return code it must be alphanumeric with a length of 2. Even if a user field is nominated the special field #IO$STS is still updated.
Specifies what action is to be taken if an I/O error occurs when the command is executed.
An I/O error is considered to be a "fatal" error. Some examples are file not found, file is damaged, file cannot be allocated. These types of errors stop the function from performing any processing at all with the file involved.
If the default value of *ABORT is used the function will abort with error message(s) that indicate the nature of the I/O error.
*NEXT indicates that control should be passed to the next command. The purpose of *NEXT is to permit you to handle error messages in the RDML, and then ABORT, rather than use the default ABORT. (It is possible for processing to continue for LANSA on IBM i and Visual LANSA, but this is NOT a recommended way to use LANSA.)
ER returned from a database operation is a fatal error and LANSA does not expect processing to continue. The IO Module is reset and further IO will be as if no previous IO on that file had occurred. Thus you must not make any presumptions as to the state of the file. For example, the last record read will not be set. A special case of an IO_ERROR is when a trigger function is coded to return ER in TRIG_RETC. The above description applies to this case as well.
Therefore, LANSA recommends that you do NOT use a return code of ER from a trigger function to cause anything but an ABORT or EXIT to occur before any further IO is performed.
*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.
|
Portability Considerations |
Not supported in the current release of Visual LANSA unless using LANSA/SuperServer to an IBM i server. Use of QRYSLT('=EXCHANGE') only supports RDML fields. Note that when fields are put on the exchange list in RDMLX, trailing blanks are stripped from the value put on the exchange list. |
This parameter is only valid when used with the USE_OPTION(*OPNQRYF) parameter. It is ignored in all other cases. It is used to specify the selection criteria that should be used by the OPNQRYF command when building an access path to the data in the file.
It may be specified as an alphanumeric literal like this:
OPEN FILE(STATES) USE_OPTION(*OPNQRYF) QRYSLT('STATE *EQ "NSW"')
or as the name of a field that contains the selection criteria, like this:
CHANGE FIELD(#SELECTION) TO('STATE *EQ "NSW"')
OPEN FILE(STATES) USE_OPTION(*OPNQRYF) QRYSLT(#SELECTION)
or, making use of the exchange list, like this:
OPEN FILE(STATES) USE_OPTION(*OPNQRYF) QRYSLT('=EXCHANGE')
The second version indicates that the RDML program can change the selection criteria at execution time. By modifying the content of field #SELECTION the actual data selected by the program can be modified. This is one of the powerful facilities available with the OPNQRYF command. Note that Visual LANSA has similar behavior to this with the SELECT_SQL command, although it is only available with RDMLX objects on IBM i. Following is an example of cross-platform code. Great care must be taken to construct the query in a cross-platform manner, in particular, single quotes must be used around literals and the file must be closed on IBM i:
EXECUTE SUBROUTINE(QUOTE) WITH_PARMS('NSW' #QUOTED)
USE BUILTIN(BCONCAT) WITH_ARGS('STATE =' #QUOTED) TO_GET(#SELECTION)
IF COND('*CPUTYPE *NE AS400')
SELECT_SQL FIELDS(#STATE) FROM_FILES((#STATES)) WHERE(#SELECTION)
DISPLAY FIELDS(#STATE)
ENDSELECT
ELSE
OPEN FILE(STATES) USE_OPTION(*OPNQRYF) QRYSLT(#SELECTION)
SELECT FIELDS(#STATE) FROM_FILE((#STATES))
DISPLAY FIELDS(#STATE)
ENDSELECT
CLOSE FILE(STATES)
ENDIF
SUBROUTINE NAME(QUOTE) PARMS((#TEXT1 *RECEIVED) (#TEXT2 *RETURNED))
USE BUILTIN(TCONCAT) WITH_ARGS(*QUOTE #TEXT1 *QUOTE) TO_GET(#TEXT2)
ENDROUTINE
The third version allows you to specify up to 256 characters in length per field and as many exchange fields as required to define a query select. '=EXCHANGE' is used in conjunction with the EXCHANGE command. This would be a better option than the second version if the query select is complicated and requires more than 256 characters to define. This third version is only supported when executed locally on an IBM i. If you want to use it from Visual LANSA, an IBM i function MUST be executed via LANSA/SuperServer as shown in this example:
Note: The use of the " (double quote) symbols within the QRYSLT parameter. The " (double quote) symbol can be used interchangeably with the ' (single quote) symbol by OPNQRYF. When using OPNQRYF through LANSA the " symbol is preferable because it is easier to code into alphanumeric literals.
The field name STATE is not preceded by a # (hash) symbol in this example. This is because the actual selection request is being made to the OPNQRYF command, not to LANSA.
Refer to the OPNQRYF command in the appropriate IBM supplied manuals for more details of the QRYSLT parameter and the values, operations and options that it supports.
This parameter is only valid when used with the USE_OPTION(*OPNQRYF) parameter. It is ignored in all other cases.
It is used to specify the key fields that should be used by the OPNQRYF command when building an access path to the data in the file. This then allows access to the data in the file in the requested key order. It may be specified as an alphanumeric literal like this:
OPEN FILE(STATES) USE_OPTION(*OPNQRYF)
KEYFLD('STATE POSTCD')
or as the name of a field that contains the key field names, like this:
CHANGE FIELD(#ORDER_BY) TO('STATE POSTCD')
OPEN FILE(STATES) USE_OPTION(*OPNQRYF) KEYFLD(#ORDER_BY)
The second version indicates that the key fields (and thus the order of processing data from the file) can be changed by the program at execution time. By modifying the content of field #ORDER_BY the order records are processed from file STATES, can be dynamically modified. This is another of the powerful facilities available with the OPNQRYF command.
Also note that the field names STATE and POSTCD are not preceded by a # (hash) symbol in this example. This is because the actual key/order request is being made to the OPNQRYF command, not to LANSA.
Refer to the OPNQRYF command in the appropriate IBM supplied manuals for more details of the KEYFLD parameter and the values, operations and options that it supports.
|
Portability Considerations |
Not supported in the current release of Visual LANSA unless using LANSA/SuperServer to an IBM i server. |
ALWCPYDTA, OPTIMIZE, SEQONLY, COMMIT and TYPE
These parameters are only valid when used with the USE_OPTION(*OPNQRYF) parameter. They are ignored in all other cases.
Refer to the OPNQRYF command in the appropriate IBM supplied manuals for more details of these parameters and the values, operations and options that they support.
|
Portability Considerations |
These parameters are not supported in the current release of Visual LANSA unless using LANSA/SuperServer to an IBM i Server. |