9.36 DEFINE_ANY_SERVER
Note: Built-In Function Rules Usage Options
Defines the details of a LANSA system that is to be used as a Server.
The definition details are not persistent and only exist while the LANSA environment remains active.
The time taken to define a server is minimal.
Platform Considerations
|
IBM i Server
|
This Built-In Function must be used for I/O commands to RDMLX files or to call an RDMLX function on the server. It may also be used instead of DEFINE_OS_400_SERVER to access non-RDMLX objects, if they have been recompiled since enabling the partition for RDMLX.
If the partition has not been enabled for RDMLX or the non-RDMLX objects have not been recompiled, DEFINE_OS_400_SERVER must be used to access non-RDMLX objects.
|
| Other Servers
|
Either this Built-In Function or DEFINE_OTHER_SERVER may be used to access any object on the server.
|
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
|
|
0
|
|
2
|
A
|
Req
|
LU Partner Name
|
1
|
20
|
|
0
|
|
3
|
A
|
Req
|
Ignored on non-IBM i Servers (Always Y)
Y or 1 - Start commitment control on the server. Once this server is connected it will receive a "commit" or "rollback" request whenever the client issues an RDML level COMMIT or ROLLBACK command.
other - do not use commitment control
|
1
|
1
|
|
|
|
4
|
A
|
Opt
|
X_RUN exceptional arguments.
|
1
|
256
|
|
0
|
|
5
|
A
|
Opt
|
Divert LOCK_OBJECT requests to this server.
If this option is used all subsequent LOCK_OBJECT requests will be diverted to this server. Multiple servers will receive the same LOCK_OBJECT request if multiple servers have this option enabled concurrently.
In such cases, a lock must be granted on all participating servers for the LOCK_OBJECT to complete normally. Where one server fails to grant the lock an UNLOCK_OBJECT request is made to all servers that have already granted the object lock.
Note that *AUTONUM, *AUTOALP, and *DTAssslllxxxxxxxxxx system variables are also retrieved from the server if locks are diverted to the server. Refer to *AUTONUM and *AUTOALP System Variables (Data Areas) and *DTASSSLLLXXXXXXXXXX System Variables (Data Areas) in the LANSA Application Design Guide.
Y or 1 - Divert LOCK_OBJECT requests.
Z - Divert LOCK_OBJECT requests and also divert authority checking requests to this server (only one server should be nominated as the diversion target for authority checking requests).
R - Route lock requests AND authority requests AND repository data requests (if not found locally). Refer also to the Notes of the X_RUN parameter PSRR.
Other- do not divert LOCK_OBJECT requests.
The default value is Z.
|
1
|
1
|
|
0
|
|
6
|
A
|
Opt
|
Show "Please Wait" message while connecting.
Y or 1 - Show wait message.
Other - do not show message.
Default value is Y.
|
1
|
1
|
|
0
|
|
7
|
A
|
Opt
|
Ignored on non-IBM i Servers
Execution priority. Default value is '20'. Specify other values as per the IBM i command CHGJOB parameter RUNPTY. User should be authorized to change to the nominated value.
|
1
|
2
|
|
|
|
8
|
A
|
Opt
|
Ignored on non-IBM i Servers
Client-to-Server conversion table name to be used. No library name can be specified Defaults to *JOB, meaning the translation table will be generated based on the client code page and the IBM i server job's CCSID.
If this argument is *JOB then the Server-to-Client table must also be *JOB.
|
1
|
10
|
|
0
|
|
9
|
A
|
Opt
|
Ignored on non-IBM i Servers
Server-to-Client conversion table name to be used. No library name can be specified. Defaults to *JOB, meaning the translation table will be generated based on the client code page and the IBM i server job's CCSID.
If this argument is *JOB then the Client-to-Server table must also be *JOB.
|
1
|
10
|
|
0
|
|
Return Values
|
No
|
Type
|
Req/Opt
|
Description
|
Min Len
|
Max Len
|
Min Dec
|
Max Dec
|
|
1
|
A
|
Req
|
Return Code:
OK - Server Defined
|
2
|
2
|
|
0
|
|
Technical Notes
- To use this BIF you must set x_run parameter CDLL to LCOMGR32.DLL and x_run parameter CMTH must be C or T.
- The Server Network Name you specify when invoking this Built-In Function should be identical to the Partner LU Name under which the server was (or will be) enrolled within the LANSA Communications Administrator.
- 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.
- The X_RUN exceptional argument may be used to override the parameters used on the X_RUN command started on the server system.
By default, the following client X_RUN parameter values are passed to (and inherited by) the X_RUN command started on the server system:CMTH=, CDLL=, DATF=, DATS=, DBCF=, DBCL=, DBLK=, DBTC=, DBUS=, DEVE=, FXQF=, FXQM=, HSKC=, INIT=, ITHP=, ITRC=, ITRL=, ITRM= , ITRO=, LANG=, PART=, PRTR=, PSPW=, PSTC=, PSWD=, TASK=, TERM=, USER=, XAFP= and XCMD=. The following client X_RUN parameter values are only inherited by the server if the client and the server are using the same operating system: DBID=, DBII=, DBIT=, DBUT=, ODBI= and WPEN (and related Windows Printing Extension parameters).
All other X_RUN parameter values on the server system are defaulted (on the server system) in the usual manner (that is, from a profile file, from system environment settings, and so on). Refer to the definition of the X_RUN command for details of all parameter values and the methods by which they can be specified and defaulted.
- You may override any server X_RUN parameter (via the X_RUN exceptional argument value) except for CDLL=, CMTH=, DATF=, DATS=, DBUG=, DEVE=, LANG=, MODE=, PART=, PROC=, PSPW=, USER= and XAFP=. These X_RUN arguments are unconditionally inherited from the client system. However, some of these parameters may be altered by calling SET_SESSION_VALUE before invoking CONNECT_SERVER.
Override parameters may be given a specific value, or the special value *SERVER, which indicates that the server default should be used. As an example, a Windows client using DBII=*NONE might connect to a Windows Server running Oracle. By default, Windows uses the database type MSSQLS (SQL Server), so DBUT needs to be overridden. The X_RUN exceptional argument value could be set to either DBUT=ODBCORACLE or DBUT=*SERVER.
- 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.
- 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.
- 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
- 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 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.
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_ANY_SERVER function when the current language 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_ANY_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 current language 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.
