Sample OpenROAD Client Code Fragments
The following code fragments would be found in a regular OpenROAD GUI application or an OpenROAD Server application that is a client to an additional application. The session startup and closedown calls are made once in the entry and exit source codes, respectively, of the client application.
Frames, procedures, and methods are code components in the body of the application, which contain application SCP and GSCP calls. The following steps exemplify how you could use ASOLib to enable interaction between a TCA and an OpenROAD application.
1. To connect to the server, you would enter the following code:
ASONameServer.Connect (p_v_name = 'Demo App 1');
This code creates a COM or DCOM connection to the server machine, and loads and prepares the 4GL OpenROAD Server application image. It uses the Name Server to request a registered application connection signature. Name Server configuration details are maintained using the Visual OSA utility.
2. Create a session context in the OpenROAD Server 4GL image:
i_status = CurRemoteServer.Call4GL ('CreateASOSession',
b_osca = BYREF(OSCA),
p_UCClientinfo = MyClientInfo);
i_status = OSCA.CheckAndHandleError (p_i_aso_retval = i_status);
The Call4GL method of the OpenROAD RemoteServer class is how you execute code in Visual OSA. These Visual OSA entry procedures are called SCPs. CreateASOSession is a system SCP that creates a session context object in the OpenROAD Server. You must define basic client identification details in the mandatory parameter, p_UCClientInfo.
OSCA is a global variable of class uc_osca. The CheckAndHandleError method takes care of the majority of error handling after an OpenROAD Server call.
All calls to system SCPs and calls to method and procedure GSCPs must pass an object of user class uc_osca. User class uc_osca is a standard communication link between client and server applications, and it contains a session context_id token and error messages. You cannot directly access the contents of OSCA apart from the public attribute v_msg_txt.
Note: The OSCA object is used in both the client and the server. It has methods that are relevant in a server context and methods that are relevant in a client context. (In a 4+ tiered architecture where an OpenROAD Server application acts as both a server and a client, all methods are relevant.)
3. Declare an OpenROAD Server control user class:
i_status = CurRemoteServer.Call4GL ('DefineBPM',
b_osca = BYREF(OSCA),
p_v_bpm = 'myUserClassName');
i_status = OSCA.CheckAndHandleError (p_i_aso_retval = i_status);
A BPM is a normal user class whose methods have been exposed automatically as 4GL procedures. These procedures are called GSCPs . A BPM can be written to implement business policy, create and use Business Objects (BOs), control transactions and police rogue GSCP calls. It must be a subclass of uc_bus_pol_mgr. An existing user class can be used as a BPM by making it a subclass of uc_bus_pol_mgr.
A process called SCPGen is built into OpenROAD Workbench. This process can be used to generate GSCPs, which exposes selected BPM methods. For more information, see the Workbench User Guide.
DefineBPM is a system SCP which instantiates an object of the user class named in parameter p_v_bpm, and associates it with the client's session. Subsequent GSCP calls are translated into method calls of the current BPM object.
4. Invoke methods (GSCPs) of the user class:
i_status = CurRemoteServer.Call4GL ('MyGSCP_Methodname_1',
b_osca = BYREF(OSCA),
myGSCPparam1 = myByvalValue,
myGSCPparam2 = BYREF(myByrefValue),
myGSCPparam3 = myByvalRefVar,
myGSCPparam4 = BYREF(myByrefRefVar));
i_status = OSCA.CheckAndHandleError(p_i_aso_retval = i_status);
The preceding code provides an example of a GSCP call that invokes a method of the current BPM. Parameters can be passed by value or through BYREF. Nested user classes and arrays are supported, but only supported data types will be passed. For example, a reference variable of class FrameExec would be ignored.
5. Invoke additional methods:
i_status = CurRemoteServer.Call4GL ('MyGSCP_Methodname_2',
b_osca = BYREF(OSCA));
i_status = OSCA.CheckAndHandleError(p_i_aso_retval = i_status);
The preceding code provides another example of a GSCP call. It accesses the same BPM object instance as the first GSCP. If the first GSCP method altered attributes of the BPM, including objects attached to it, these changes will be visible to the second GSCP method.
When a different BPM is required, the new BPM can be specified by calling DefineBPM again.
Note: There is only one BPM instantiated per session context. This is not restrictive because a given client can create an unlimited number of ASO)sessions (using CreateASOSession) each of which can have an instantiated user class BPM. Alternatively (and preferably), existing BPMs can be grouped and controlled by a master BPM.
You can also call user-written SCPs and procedure GSCPs that wrap regular 4GL procedures. Such stateless calls can be interleaved with stateful method GSCP calls.
6. Destroy the session context and release the COM connection:
i_status = CurRemoteServer.Call4GL ('DestroyASOSession',
b_osca = BYREF(OSCA));
i_status = OSCA.CheckAndHandleError(p_i_aso_retval = i_status);
CurRemoteServer.Release();
The DestroyASOSession system SCP is issued when the session is finished. It cleans up the session context information in the OpenROAD Server application and releases memory allocated during the session. The Release method terminates the COM or DCOM connection with the server machine.