9.50 DISCONNECT_FILE
Note: Built-In Function Rules Usage Options
Disconnects a file previously connected to a server.
Warning:
- Using this Built-In Function during pending I/O operations to the file (e.g. in the middle of a SELECT loop) will cause unpredictable results.
- A request to disconnect a file that is not currently connected will be ignored. No error will result.
Arguments
|
No
|
Type
|
Req/ Opt
|
Description
|
Min Len
|
Max Len
|
Min Dec
|
Max Dec
|
|
1
|
A
|
Req
|
Physical File\Table Name
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
|
|
|
|
Return Values
No return values.
Technical Notes
- When a generic name is specified it must exactly match a generic name previously defined by using the CONNECT_FILE Built-In Function.
- For example connecting file name A* and then disconnecting file name AB* does not mean that all files starting with A (except those starting with AB) are currently connected. The disconnect of AB* will not find a match in the connected files list and be ignored. All files that start with A will continue to be connected.
- Disconnecting 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.
- It is very strongly recommended that all "disconnect" 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.
- Do not attempt to disconnect 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 disconnected before or after the "*" will overlap with it.
- There is no real need to disconnect file(s). As the X_RUN command is terminating it will automatically disconnect any connected files.
- 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.
