9.11 CALL_SERVER_FUNCTION

Note: Built-In Function Rules     Usage Options

Calls (executes) a LANSA application on the nominated server and waits until it completes execution. The function must be a *DIRECT function.

Arguments

No Type Req/ Opt Description Min Len Max Len Min Dec Max Dec 1 A Req SSN of defined server. 1 10       2 A Req Name of function to be called. 1 7       3 A Opt Pass Exchange List Y= Pass exchange list. other = do not pass exchange list. The default is N. 1 1       4 A Opt Return Exchange List Y= Return exchange list. other = do not return exchange  list. The default is N. 1 1       5 - 14 L Opt Working Lists 1 through 10 to be passed to the function on the server.

Return Values

No Type Req/ Opt Description Min Len Max Len Min Dec Max Dec 1 A Req Return Code. OK - Call Completed ER - Error during call and error message(s) issued. 2 2

Technical Notes

• The server function that is called is strictly a "batch" job on the server. It cannot execute DISPLAY/REQUEST/POP_UP commands in any form (e.g., via Windows) because it is not logically connected to any form of user interface. Likewise it cannot successfully use other IBM i products that need to be logically connected to a user interface (e.g., STRSEU, WAF/400).
  
  This point needs to be understood very clearly because it may influence application design. Client functions "talk" to the user via DISPLAY/REQUEST/POP_UP commands. Server functions are actually executing on the server and thus have no direct or logical way by which they can "talk" to the user.
  
  A server function is typically a "subroutine" of a client function that just happens to be executed on another platform.

• Fields exchanged or passed in working lists are automatically converted from ASCII to EBCDIC (and back again). The conversions are invisible to client and server functions. It is just as if the function was being called on the same machine via the RDML CALL command.

• The same rules that apply to the RDML CALL command for working list passing / receiving apply to this Built-In Function.
  
  For example: All working lists must have identical definitions in the caller and receiver at all times. If the list definition changes, both must be recompiled.

• Fields can be exchanged to, and back from, the server function.

• Working lists can be passed to, and received back from, the server function.

• Alphanumeric fields with DBCS attributes are translated to/from ASCII and EBCDIC DBCS. This type of translation only occurs when the field has DBCS attributes (e.g., J, E, O) and the server has been connected with the "DBCS Capable" option set to Y.

• When the working list details only need to be passed to the server function, make the server function clear the working list before it completes. This saves having to send the list back to the client again and reduces communications traffic.

• When a working list only needs to be returned by the server function, clear it before calling the server function. This saves having to send the list details to the server and thus reduces communications traffic.
  It may also prevent accidental "overfilling" when the server function assumes that it is receiving an empty or cleared list. See the following points for more details about "overfilling".

• Message information routed from the server machine (in any form) arrives in a text format. It is displayed and accessible to RDML functions in the normal manner (e.g., GET_MESSAGE) as pure text. The message identifier and message file name details are not available for messages that have been routed from a server. You should not design client applications that rely on reading specific message identifiers from the applications message queue.

Portability Considerations

Servers defined with DEFINE_OS_400_SERVER:  The aggregate byte length of a working list passed to a server cannot exceed 32,000 bytes. The aggregate byte length is the entry byte length multiplied by the current number of entries. As 1 to 10 working lists can be passed to the function on the server, the total number of bytes that can be passed to the Server is 320,000, that is, 10 working lists of 32,000 bytes each. This Built-In Function will cause a fatal error message if a client function passes a list that is too large. However, the server function is a different matter. The working list it receives as a parameter is in memory allocated by its caller (i.e. the IBM i based server controller). If it attempts to add too many entries to the working list it may "zap" the server controller and cause an application failure. Please do not ignore this warning. Server (i.e. IBM i based) functions that receive working lists from Client (e.g. Windows) functions via this Built-In Function must take great care not to "overfill" the working list(s) that they are passed. If an unexpected failure of CALL_SERVER_FUNCTION occurs, and working lists are involved, then look to this point as the first possible cause ..... the server function may be overfilling the working list(s).

 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.