Page History
9.26 CONNECT_FILE
| Note | ||
|---|---|---|
| title | Note: | Built-In Function Rules Usage Options |
...
file to a server that is different to the one that it is currently connected.
LANSA File (not an OTHER File or SQL View) that does not have AUTO_RRN set on to a database that requires an RRN path defined.
Arguments
No | Type | Req/ Opt | Description | Min Len | Max Len | Min Dec | Max Dec |
|---|---|---|---|---|---|---|---|
1 | A | Req | Physical File\Table Name. The name must be specified using uppercase characters. No check is made for the validity or existence of the name specified. The name may be specified as a generic name. The '*' symbol is used as the generic delimiter. | 1 | 10 | ||
2 | A | Req | SSN of defined server. | 1 | 10 | ||
3 | N | Opt | Selection Using the CONNECT_FILE Block Size. Default = 50. Note 1: For files used in SELECT loops with the RETURN_RRN parameter, you should use block size 1. Note 2: For files used in SELECT loops and altered by DELETE or UPDATE commands that do not have WITH_KEY or WITH_RRN parameters (i.e. update or delete of the last record read) you should use block size 1. Note 3: If any of the fields to be selected is a BLOB or a CLOB and therefore might require a file to be send from the server to the client, the behavior will be as if you have used block size 1 for the SELECT process. | 1 | 10 | 0 | 0 |
4 | N | Opt | Selection limit. This option does not programmatically limit a selection loop to 'n' rows. It should not be used for this purpose. It is designed to stop a runaway (that is, out of control) select loop from attempting to transfer too much data. Exceeding the selection limit value will cause a fatal application error. The number of rows returned in this error situation is unspecified. Default = 10000 | 1 | 10 | 0 | 0 |
Return Values
No return values.
Technical Notes
Connecting a file while it is "in use" (e.g: in the middle of a SELECT loop when the file being selected is not connected to a server or connected to another server) will cause application failure and/or unpredictable results.
You cannot, under any circumstances, connect the LANSA for i DC@Fnn internal database files to your application via this Built-In Function. This rule is not checked, but it should not be violated.
The entire LANSA SuperServer facility does not support multi-membered files in any way, shape or form. You may be able to devise a strategy that will actually allow you to execute or call server functions that access multi-membered files, but you should remember that you are using an unsupported and totally IBM i dependent facility. When an IBM i based I/O module is invoked via this facility it opens the required file member(s) via the current library list (*LIBL) and as the IBM i logically first member (usually symbolically named *FIRST).
If you attempt to interleave a Client based function (using library *LIBL member *FIRST) and a Server based function (using a POINT command to a library and/or member), and both functions access the same file(s) you may cause the associated I/O module to fail with message IOM0033. This will happen regardless of any POINT commands present in the Client function. POINT commands are ignored in all Visual LANSA (i.e. Client) environments.It is very strongly recommended that all "connect" logic is coded in one and only one function, rather than scattered and repeated through many RDML functions. This approach will isolate your application from future changes to the server(s) that are being used.
Attempting to connect a file that is already connected (to the same server) does not cause an error. When the file you are attempting to connect is already connected, the selection block and limit values are updated. This technique may be used to dynamically alter the selection block/limit values, but not while I/O operations are pending (e.g: within a select loop).
Do not attempt to connect a blank file name.
When using generic file names (e.g. LM*, GL*, *) be extremely careful not to overlap any generic names. Failure to observe this rule will cause unpredictable results. This rule means that name "*" (any name) can only be used by itself, as any other file name connected before or after the "*" will overlap with it.
Message information routed from the server machine (in any form) arrives in a text format. It is displayed and accessible to RDML functions in the normal manner (e.g. GET_MESSAGE) as pure text. The message identifier and message file name details are not available for messages that have been routed from a server. You should not design client applications that rely on reading specific message identifiers from the applications message queue.
...
It is very strongly recommended that you avoid building complex error handling schemes into your applications. Use a very simple trap like this at all levels of your application.
if (#retcode *ne OK)
...
abort msgtxt('Failed to .............................')
endif
Let the standard error handling Built-In Function to every generated application take care of the problem. Situations have arisen where user defined error handling logic has become so complex as to consume 40 - 50% of all RDML code (with no obvious benefit to the application). Do not fall into this trap.
...
Because of this, using either the relative record number or the last record read has inherent dangers.
Consider this code:
SELECT FIELDS(...) FROM_FILE(FILEA) RETURN_RRN(#RRN)
...
UPDATE FIELDS(...) IN_FILE(FILEA) WITH_RRN(#RRN)
ENDSELECT
This is acceptable on an IBM i server. However, in a client/server environment, the value of RRN after the select will be the relative record number of the 50th record. The OAM on the server has performed one read action, and therefore has returned the LAST RRN it is aware of.
The same applies to this code:
SELECT FIELDS(...) FROM_FILE(FILEA) RETURN_RRN(#RRN)
...
UPDATE FIELDS(...) IN_FILE(FILEA)
ENDSELECT
As far as the OAM is concerned, the last record read is the 50th record. Any attempted UPDATE or DELETE will be performed on the last record read.
...