9 26 CONNECT

You are here:

9.26 CONNECT_FILE

Note: Built-In Function Rules Usage Options

Prepares LANSA so that all following I/O requests to the nominated physical file (and any views based on it) are rerouted to the server. Refer to Database Connection for more details.

The time taken to establish a file connection is very fast. It simply updates a routing table and does not communicate to the server at all.

The connection remains in effect until it is explicitly terminated by use of the Built-In Function DISCONNECT_FILE or by the ending of the LANSA environment.

You should design your applications so that a minimal number of connection and disconnection points are used.

Different files may be connected to different server systems at the same time, but a single file cannot be connected to more than one server at a time.

The word "File" here refers to the base physical file (or table) and all logical files (or views) that are based on it.

A request to connect a file to a server that it is already connected to will be ignored, apart from resetting the selection block size and selection limit. No error will result.

A fatal error is caused by a request to connect a:

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. Larger block sizes will result in unpredictable values being returned in the RETURN_RRN value. 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.

A Note on Error Handling

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.

Using the CONNECT_FILE Block Size

By default, the Block size parameter is the value 50. This means that 50 records will be returned to the client end of the application for each trip to the server. The data will still be processed in the sequence in which it exists in the particular file, and debug will show the code looping through 50 records, but only one trip has been made to the server to retrieve the data.

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.

Updating with a key to the file used in the SELECT loop is not allowed. Therefore, the only possible solution is to set the block size to 1. This will ensure that the data is returned one record at a time.

The down side of this is that the performance of the application is significantly decreased. It should be noted at this point that the most efficient way to update multiple records on the server is to run the update code on the server using the CALL_SERVER_FUNCTION Built-In Function.

A similar issue occurs in maintenance applications that allow multiple detail records to be opened. For example, a Visual LANSA application displays a list of employees. The user can double click on an item in the list, and a maintenance form is opened. This receives the employee number from the list, and uses FETCH to read the data. FETCH causes the OAM to read only one record. Before saving the changes, the user opens another employee detail as well. The last record read value is stored in the OAM on the server, and as far as it is concerned, it was the second employee.

So, even though it was a FETCH that was performed, the employee maintenance form MUST update with a key. Any attempt to update the last record read will OVERWRITE the last record read.