9.39 DEFINE_OS_400_SERVER
Þ Note: Built-In Function Rules.
Defines details of an IBM i system that is to be used as a server to the current RDML function.
The definition details are not persistent and only exist while the LANSA environment remains active.
The time taken to define a server is minimal.
You must use BIF DEFINE_ANY_SERVER for I/O commands to RDMLX files or to call an RDMLX function on the server.
For use with
|
Arguments
|
Return Values
|
Technical Notes
- It is very strongly recommended that server definition 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.
- The LU partner name specified must be either:
- The fully qualified Partner LU (Logical Unit) name that has been previously defined to the Communications Router.
This is usually formatted "Network Name.Control Point Name" and corresponds to the IBM i DSPNETA values of "Local Network ID" and "Local control point name".
Normally any Communications Router that allows 5250 emulation sessions to work will have these details already configured ready for use.
e.g. APPN.SYDASD25
- Or, if you have configured an "alias" name for the LU name it may be used in place of the fully qualified LU Name.
e.g. 5250PLU
- The translation tables specified are actually uploaded from the IBM i server during a connect. The initial connect phase needs to translate the initial connection details via a default translation table as the tables you specify have not yet been uploaded.
The initial connect details (sent to the server) include:
- The partition
- The language code
- The task identifier
- The client to server conversion table name
- The server to client conversion table name
Use only English alphabetic characters A through Z and the numbers 0 through 9 in the names of the objects listed above to avoid potential problems in this area.
- 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.
- The details defined 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.
- Please experiment with these facilities first and then design some server architecture for your organization that has these characteristics:
- It matches your organization's requirements.
- It is quick and easy to change.
- It is extendible.
Do this before launching into any large scale design or development project.
- The client's date format will be automatically passed to the server. If the date formats are different (e.g. MDY vs DMY), the server will automatically return data in the client's format.
The client's date format can be changed from the default by specifying the x_run parameter DATF=. Please refer to Standard X_RUN Parameters for more information about this parameter.
Note that if the client and server date formats are different, Date format validation rules specifying exact formats (e.g. DDMMYY) will fail (as the data may be returned as MMDDYY). Date format SYSFMT is recommended where clients need to use different date formats (e.g. USA and UK clients).
Notes on Commitment Control
- If Start Commitment Control is Y, LANSA will automatically start and end commitment control. See User Exit F@BGNCMT - Start Commitment Control and User Exit F@ENDCMT - End Commitment Control in the for details.
- When the server has been indicated as having commitment control started, it will effect all subsequent COMMIT and ROLLBACK commands issued.
When a COMMIT or ROLLBACK command is issued the routine involved loops through all currently connected servers.
To each one that has commitment control active, it issues a "commit" or "rollback" request and then waits for the server to respond before proceeding.
This is done after a commit/rollback has been issued correctly to the local/client database management system.
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.
DBCS Considerations
When the server is indicated as being DBCS capable an additional translation table must be locatable on the client PC.
This table must be named X_CT<language code>.DAT and must be located in the X_LANSA\EXECUTE directory.
A version of this table named X_CTJPN.DAT for <language code> "JPN" (Japanese) is available to all Japanese customers.
This translation file contains the following notes:
- This table is shipped in an "as is" condition to support customer tailoring. No warranty is expressed or implied. It is the customer's responsibility to maintain and verify this table.
- This table is loaded by the Visual LANSA DEFINE_OS_400_SERVER function when it has been indicated that the server has DBCS capability.
- The name of the table loaded is derived from "x_ct" combined with the current language code (e.g. jpn) and the suffix ".dat". Thus if language code jpn was being used, the table name would have to be "x_ctjpn.dat". For language code tchi the table name would be "x_cttchi.dat".
- The table must reside in the <drive>:\x_lansa\execute directory where <drive> is whatever local or server disk drive onto which Visual LANSA has been installed.
- This conversion table is only used for the double byte parts of any string. Single byte parts of any string at all (DBCS allowed or not) are always converted by using the IBM i single byte tables specified in the DEFINE_OS_400_SERVER Built-In Function call.
- This means that a field containing mixed double and single byte characters is partially converted by this table and partially by the single byte conversion table that is used by both DBCS and non-DBCS conversions.
- DBCS conversion of data within an individual field only occurs when the field is indicated as being DBCS capable (e.g. dictionary keyboard attributes j, e, o, etc.) and when the DEFINE_OS_400_SERVER Built-In Function has indicated that the server is DBCS capable. If both these conditions are not met the entire field is converted as a single byte string by the single byte conversion tables previously mentioned.
- An * in column 1 indicates a comment line.
- All values are specified in hexadecimal format.
- Separate values with a single comma (,) only.