Generating routine calls dynamically is useful when you need to adjust calls and/or the arguments passed to them based on changing conditions in your program. The routine call block API can be used to dynamically generate both local and remote routine calls at runtime. (If you are using this API remotely, you should be using xfNetLink Synergy Edition.)
In Synergy/DE, dynamic call generation requires creating and using a routine call block (RCB). An RCB is a block of memory that contains the information necessary (the routine name, ELB, and arguments) to make a routine call. Once you have created an RCB, it is identified by a memory handle known as the rcbid, the routine call block ID. An RCB can be used repeatedly, altered (for example, by inserting or changing arguments), or completely rebuilt for another call.
The routine call block API can also be used to improve performance in situations where many calls are being made to the same routine with the same arguments. By reducing the number of times that the RCB has to be created, performance is enhanced.
The Synergy routine call block API is not available in Synergy .NET. See ^VARARGARRAY for information on how to achieve similar functionality in that environment.
Making calls using a routine call block
This section explains how to create and use RCBs to generate routine calls dynamically. To use the RCB routines, you must .INCLUDE DBLDIR:rcbapi.def in your programs.
|
If you are making calls remotely, refer to Part II: xfNetLink Synergy Edition for more information about the RX_xxx routines and using xfServerPlus to make remote calls. |
Follow these steps:
| 1. | If you are making dynamically generated calls remotely, request an xfServerPlus session with %RX_START_REMOTE. |
| 2. | Create the RCB with %RCB_CREATE. When you create the RCB, you specify the size. %RCB_CREATE returns the rcbid, which identifies the call block. |
| 3. | Specify the Synergy routine to call: |
|
If you are making calls |
Do this |
|---|---|
|
Locally |
Set the routine name with RCB_SETFNC. This step sets the name of the routine that will be called when the RCB is passed to %RCB_CALL. |
|
Remotely |
Specify the remote routine to be called with RX_SETRMTFNC. |
| 4. | Set up the arguments with RCB_SETARG, RCB_SETARGS, and/or RCB_INSARG. You can add arguments one at a time with RCB_SETARG or in a group with RCB_SETARGS. To add more arguments later, use RCB_INSARG. To remove arguments later, use RCB_DELARG. |
| 5. | Make the call with %RCB_CALL and pass the rcbid. |
| 6. | Adjust and recall as necessary. You can add additional arguments with RCB_INSARG, overwrite a particular argument with RCB_SETARG, and remove a particular argument with RCB_DELARG. |
| 7. | Delete the block with RCB_DELETE. RCBs that are not explicitly deleted with RCB_DELETE are deleted when the runtime exits. However, we recommend that you delete the block when you’re finished using it to avoid tying up system resources. |
| 8. | If you are making calls remotely, close the xfServerPlus session with RX_SHUTDOWN_REMOTE. |
Figure 1 shows the general process flow for performing this procedure both locally and remotely.
|
|
