9.37 DEFINE_DB_SERVER
Note: Built-In Function Rules Usage Options
Defines details of a database that is to be used for files that are specifically redirected to use this database.
Primarily, this is for the purpose of supporting Other Files and SQL Views in Other databases. Other Files and SQL Views are loaded into LANSA using Load Other Files on the File Control menu.
It can also be used to access LANSA User Files in a different partition or in an external database. These file definitions must be exported from the repository for the external database into the current repository. Whenever the file definition is changed in the external repository it will need to be re-imported to the current repository and the OAM re-built.
The definition details are not persistent and only exist while the LANSA environment remains active.
The time taken to define a database is minimal.
Note 1: This BIF has a similar purpose to DEFINE_OTHER_SERVER except that the OAMs still reside on the local PC and database I/O is used to access the server. See Database Connection.
Note 2: This BIF requires a local database connection established, otherwise it will return an error.
Arguments
|
No
|
Type
|
Req/ Opt
|
Description
|
Min Len
|
Max Len
|
Min Dec
|
Max Dec
|
|
1
|
A
|
Req
|
SSN (Server Symbolic Name) This is the name that will be used in all future references to this server by this and other RDML functions.
|
1
|
10
|
|
|
|
2
|
A
|
Req
|
Database Identifier.
|
1
|
32
|
|
|
|
3
|
A
|
Opt
|
Connection Parameter Overrides (may be blank).
|
1
|
256
|
|
|
|
4
|
A
|
Opt
|
RRN Path Override (may be blank). If it is specified, it must end with a path separator - on MS Windows, this is a back slash.
|
1
|
256
|
|
|
|
5
|
A
|
Opt
|
Database Type Override (may be blank). Specify a valid database type from The X_DBMENV.DAT File.
|
1
|
32
|
|
|
|
6
|
A
|
Opt
|
ODBI= Override to specifically set the transaction isolation level for this database. May be 0-4 or blank. 0 means the default setting for the database. Blank means the same as the ODBI= parameter. For more information, refer to The ODBI=Parameter.
|
1
|
1
|
|
|
|
7
|
A
|
Opt
|
ODBA= This parameter has been deprecated. For more information, refer to The ODBA=Parameter.
|
1
|
1
|
|
|
|
Return Values
|
No
|
Type
|
Req/ Opt
|
Description
|
Min Len
|
Max Len
|
Min Dec
|
Max Dec
|
|
1
|
A
|
Req
|
Return Code.
OK - Server Defined
ER - Server not defined and error message(s) issued.
|
2
|
2
|
|
|
|
Technical Notes
- The Database Identifier must be a valid ODBC database name, defined in the 32-bit ODBC Administrator. It would normally be the same as the ODBC database name that was used to load the OTHER File into LANSA.
- It is very strongly recommended that your server definition and connection 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.
- It is recommended that you use SSN values that are meaningful to end users (e.g. CHICAGO, BOSTON, CHARLIE1, etc.) as they may appear in messages from time to time.
- SSN names must be unique and start with a character in the English language alphabet (uppercase 'A' through 'Z').
- A server may be repeatedly defined and re-defined when it is not connected. If you attempt to re-define a server that is currently connected a fatal error will result.
- By default, the same connection parameters will be used as when the OTHER File was loaded.
- The Connection Parameter overrides may be used to augment and replace the parameters used when connecting to this database. Existing parameters are only replaced on a parameter by parameter basis. Thus, the parameters that pre-exist and are not specified in the override parameter remain as they are.
- If this database is to be connected to by using the CONNECT_SERVER BIF, ALL the connection parameters will need to be specified in the Connection Parameter Overrides, otherwise ODBC will prompt for missing parameters. (Note: the following ODBC connection parameters are not required, and are ignored: DSN=, FILEDSN=, DRIVER=). Also, the Database Type Override must be specified, as the default Database Type is held in the OAM, which is not known when the CONNECT_SERVER BIF is used.
- When a Function or Component uses an OTHER File, if it has not been connected to a different server or database using CONNECT_FILE, the default database is used. The system checks if the database has been defined by this BIF. If it has, the Connection parameter Overrides are applied before an automatic connection is made.
- When a LANSA File is to be connected to this database and AUTO_RRN is not used, it is mandatory that the RRN Path be specified.
- The database type has been provided for future use in supporting OTHER Files in Linux servers when the table definition is loaded into LANSA using ODBC Oracle, but executes using native Oracle. If it is used to change from one ODBC database type to another a fatal error will occur when the OAM is executed. That is, the database type specified in this BIF must match the database type in the OAM, except for the special Oracle case.
- The details defined via this Built-In Function are not persistent. They are lost when the X_RUN command completes. You may choose to define your own set of SQL based tables to hold server details and actually read the table(s) to get values to be passed on to this Built-In Function.
- If the Connection parameter Overrides cause the user to be prompted for connection information (for example, a database login and password), the Connection parameter Overrides that were defined with this BIF may be updated with the actual connection string that was used to connect to the database. This feature is to save the user from being prompted for each new ODBC connection to this SSN (for example, SQL Server requires an update connection and multiple read connections), or where a DISCONNECT_SERVER is used, followed by a later CONNECT_SERVER. If you want to execute DISCONNECT_SERVER to force the user to be prompted again for connection details, you should call this BIF again to replace your original values.
- Please experiment with these facilities first and then design some sort of server architecture for your organization that has these characteristics:
- It matches your organization's requirements.
- It is quick and easy to change.
- Do this before launching into any large-scale design or development project.
Example
The following example defines a database server called CHICAGO that connects to the database MYDATABASE and sets the user id and password to null so that ODBC prompts for the user id and password.
USE BUILTIN(DEFINE_DB_SERVER) WITH_ARGS(CHICAGO MYDATABASE "UID=;PWD=;") TO_GET(#RETCOD)
The connection will be made when the first file that is associated with MYDATABASE is used.
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 into 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.
