9.27 CONNECT_SERVER
Note: Built-In Function Rules Usage Options
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.
Arguments
|
No
|
Type
|
Req/ Opt
|
Description
|
Min Len
|
Max Len
|
Min Dec
|
Max Dec
|
|
1
|
A
|
Req
|
SSN of a defined server.
|
1
|
10
|
|
|
|
2
|
A
|
Opt
|
Password to be used to connect to the server. This value is not stored and only exists for the duration of this function call.
If this value is not specified, Application server connections use the value from the x_run parameter PSPW= for the default password.
If this value is not specified, Database server connections use the password defined in the connection parameter overrides in DEFINE_DB_SERVER. You can let ODBC prompt for the password, as described in the 9.37 DEFINE_DB_SERVER example.
|
1
|
256
|
|
|
|
3
|
A
|
Opt
|
If this value is 'Y', then the password value is ignored, and the authority under which the Windows application is running is used for authentication with the server via the Kerberos protocol.
If this value is 'N', then the password argument is used for authentication.
If this value is not specified, then the default value is the current setting of the PSTC parameter. Refer to The PSXX Parameters .
|
1
|
1
|
|
|
|
4
|
A
|
Opt
|
User name to be used to connect to the server. This value is not stored and only exists for the duration of this function call.
If this value is not specified, Application server connections use the value from the X_RUN parameter USER= for the default user name.
This value is ignored in Database server connections.
|
1
|
256
|
|
|
|
5
|
A
|
Opt
|
Handle Server Error
If this value is set to 'Y', then the client X_Run session will not abort on errors returned from a Server. Instead the return code will be set to FE and server's error messages will be stored in the message queue.
If set to 'N', the client X_Run session will abort on errors returned from a Server.
Default Value is 'N'.
|
1
|
1
|
|
|
|
Return Values
|
No
|
Type
|
Req/ Opt
|
Description
|
Min Len
|
Max Len
|
Min Dec
|
Max Dec
|
|
1
|
A
|
Req
|
Return Code.
OK - Connection established
ER - Connection not established
FE – Fatal error.
|
2
|
2
|
|
|
|
2
|
A
|
Opt
|
Server Type.
If a SuperServer, one of:
AS400 (IBM i RPG)
RDMLX400 (IBM i RDMLX)
LINUX
WINDOWS
If a Database Server, one of:
DB_ODBCORACLE
DB_MSSQLS
DB_MSACCESS
DB_SQLANYWHERE
DB_XXXXX where XXXXX is a user-defined database type
Note: If the type cannot be determined, the server type will be returned as UNKNOWN.
|
3
|
15
|
|
|
|
3
|
N
|
Opt
|
Connection Error Code.
Zero if Return Code is OK or LANSA is unable to determine an error code.
If a SuperServer, this will be the Comms Error Code. The most common Error Codes are:
6 - Could not logon
17 - Unexpected error at client or server
20 - Could not locate server
If a Database Server, this may be the native database error, an ODBC/CLI API return code, or -9999 indicating an internal LANSA error.
|
10
|
10
|
0
|
0
|
|
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 that this is working. (This requires setting up the listener properly to run as a specific user. 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:
- 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 DCXPGMLIB) and library DCXCOMLIB.
- 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.
