9.27 CONNECT_SERVER
Þ Note: Built-In Function Rules.
Connects an executing function to a server. The connection remains in effect until explicitly terminated by using the DISCONNECT_SERVER Built-In Function or by exiting from the Visual LANSA environment.
A server can be any SSN defined by one of the BIFs: DEFINE_OS_400_SERVER, DEFINE_ANY_SERVER, DEFINE_OTHER_SERVER and DEFINE_DB_SERVER. It can also be the special SSN *LOCALDB which refers to the local database server. Refer to Database Connection for more details.
The time taken to establish a connection is relatively long.
You should design your applications so that a single entry point connect is required rather than using many connects and disconnects.
A request to connect to a server that is already connected will be ignored. No error will result.
For use with
|
Arguments
|
Return Values
|
Technical Notes
- 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.
- By default this Built-In Function will connect to a partition on the server system that has the same identifier as the partition currently being used on the client system. For information on how to connect to a partition with a different identifier refer to the CONNECT_PARTITION option in the Built-In Function SET_SESSION_VALUE.
- When using Kerberos authentication to an IBM i server, the Kerberos Principal Name of the Windows domain user under whose authority the application is running, must be associated with a LANSA User. This association is made using the IBM i Enterprise Identity Mapping (EIM) facility.
Technical Notes (IBM i Specific)
Kerberos works without further configuration directly to a server with no access outside that server, say to SQL Server or a file share.
If access outside of that one server is required – so called "multi-hop" – then this is what is supported:
1.Trust whole computer to *any* services – We have tested and proved this is working
2.Trust a specific domain user to *any* services – We have tested and proved this is working (this requires setting up listener properly to run as a specific user, see the attached document. This should be verified first using lcoecho)
If your environment does not allow one of these configurations then multi-hop cannot be used.
Technical Notes (IBM i Specific)
- You may be concurrently connect to multiple different IBM i servers.
- You may be concurrently connected to the same IBM i server multiple times (with different SSN names).
- Database server connections are usually simpler to setup than communication servers are. The "first time" connection to communication servers is the most difficult. It is the time that causes frustration when a series of complex and often meaningless (without the Host Integration Server 2000 Error Major/Minor error codebook) error message numbers may appear
- The actual configuration and maintenance of communications between workstation clients and IBM i servers is actually beyond the scope of this reference guide, however the following tips and techniques may aid you in determining the cause of your problem.
Make sure that the user profile you are using is:
- Defined to IBM i.
- Authorized to use the LANSA partition required.
- 10 characters or less in length.
- Has a job description associated with it that has an initial library list that includes the LANSA program library (often DC@PGMLIB) and library QGPL.
- That the same job description has LOG(4 00 *SECLVL) logging if you are trying to solve a problem. This will ensure any IBM i job the profile starts will produce an IBM i job log. This job log will almost always yield useful error information.
- Enrolled in Office Services via the ADDDIRE and ADDOFCENR commands.
- Verify the IBM i user profile being used by signing on at a dumb terminal and then immediately typing a LANSA PARTITION(xxx) command. Does anything surprising happen?
Remove the cause of any errors or authority problems that are apparent before trying the profile through a communications link.
- Use the IBM i command WRKSBSJOB QCMN to display the active jobs in subsystem QCMN. Repeatedly use F5=Refresh, to refresh the list as the communication job starts.
Is subsystem QCMN active?
|
NO: |
Start it and try the operation again |
|
YES: |
Does an IBM i "server" job appear in the QCMN subsystem?
|
|
If YES |
Immediately use "5=Work with" to trace this Job. Wait until it completes and then check its resulting spooled job log file for details. If it does not produce a log, alter the job description associated with the user profile you are using to LOG(4 00 *SECLVL) until you trace the cause of the problem. Do you have an "LXX" (i.e. LANSA SuperServer) license installed in the IBM i system? Is it current? Use the command LANSA REQUEST(LICENSE) to check. |
|
If NO |
Have you started communications manager, PC Support, or other communications router on the PC? Does the communications manager "Display Messages" option show any error information? Does the IBM i DSPLOG (display log) command show any communications error information? |
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.