Your Synergy server routines must reside in one or more ELBs or shared images. (Although we use the term “ELB”, the information in this topic applies to both ELBs and shared images, except where noted.) When you define your routines in the Method Definition Utility or attribute your code, you will include the name of the ELB, so that xfServerPlus can find the routine. The ELBs are opened and closed by xfServerPlus.
|
When you are designing your xfServerPlus-xfNetLink application, the ideal approach is to group related routines into ELBs. For example, you might group your utility routines (such as string handling and date calculations) into one ELB, your order entry application logic into another ELB, and your order entry data access into yet another ELB. These routines can be called by any application that can make use of them, particularly if you do not maintain global or common data inside the ELB. With remote execution of ELBs, you can position each ELB where the application that uses it is located. |
Considerations and restrictions
- If you have a Synergy routine in one ELB that calls a routine in a second (dependent) ELB, the dependent ELB will not be opened by xfServerPlus. (Note that the dependent ELB may be your own ELB or an ELB distributed with Synergy/DE, such as tklib.elb.) To ensure that the dependent ELB is opened, do any of the following:
- (Windows and Unix) When you create the primary ELB, link it against the dependent ELB(s). The dependent ELBs will be opened when the primary ELB is opened. For details on linking ELBs, see Invoking the linker on Windows and Unix (dblink).
- (OpenVMS) When you create the primary shared image, link it against the secondary shared image. Note that if the call to the routine in the secondary shared image is made directly or with XCALL, you’ll get an error if the secondary shared image is not linked. However, if the call is made with XSUBR, you won’t get an error, and will simply have to remember to link the shared images or use one of the other options listed below to access the routine in the secondary shared image.
- Modify the routine in the primary ELB to open the dependent ELB before calling any routines in the dependent ELB.
- Call an initialization routine that opens all the ELBs that will be needed.
- Put all routines in a single ELB.
- You can include an initialization routine that sets up global data, as long as the global data is contained within the ELB.
- Do not chain from within an ELB.
- Do not use the EXEC subroutine to call a non-Synergy program from within an ELB.
- (OpenVMS) Routines in a shared image must not contain any XCALLs to routines that require the command line interpreter. These include PURGE, RUNJB (unless it creates another detached process, in which case it may be used), SETLOG, SHELL, SPAWN, VMCMD, and any OpenVMS library routine that requires a CLI be present.
- (OpenVMS) Due to a change in the Itanium kernel in OpenVMS version 8.3 and higher, shared images should not be installed as /RESIDENT, or the programs that use those images will crash. (Installing as /HEADER_RESIDENT is allowed.)
For more information on ELBs and shared images, see Building and Running Synergy Applications.
Defining logicals
If you use logicals to point to the directories that your ELBs or shared images reside in, and you use those logicals when defining routines in the Synergy Method Catalog, you must define the logicals so that xfServerPlus knows how to resolve them.
Defining logicals on Windows and Unix
On Windows and Unix, define logicals in the xfpl.ini file, which is located by default in DBLDIR. (It is possible to specify a different location for xfpl.ini, as well as to have more than one xfpl.ini file; see Using the xfpl.ini file.)
The maximum length for an XFPL_LOGICAL translation value is 1,024 characters.
|
If any of your ELBs are linked to dependent ELBs (see Considerations and restrictions), you must define the logicals for both the primary and the dependent ELBs in the xfpl.ini file. |
Define logicals like this:
XFPL_LOGICAL:LOGICAL_NAME=path
Optionally, you can include another logical in the logical definition. This logical may be defined earlier in xfpl.ini or in the environment at the system level. For example:
XFPL_LOGICAL:LOGICAL_NAME=MyLogical:new_path
|
Be sure there is a hard return (CRLF) at end of the final logical definition in your xfpl.ini file. You may want to just add a couple of blank lines at the end of the file. This will ensure that all logicals in the file are read. |
Defining logicals on OpenVMS
We recommend defining logicals in the file DBLDIR:SERVER_INIT.COM.
- To specify logicals for system-wide visibility:
$ DEFINE/SYS LOGICAL_NAME value
- To specify logicals for a specific instance of xfServerPlus:
$ DEFINE/TABLE=LNM$RSDMS$MGR_port /USER LOGICAL_NAME value
where port is the port number on which xfServerPlus is running.
For additional information about defining logicals on OpenVMS, see Defining logical names for xfServer processes.
