COM (Non-OpenROAD) Client Remote Server Object
A non-OpenROAD client has two alternative driver objects that lets a client connect to a desired OpenROAD application image, and to call 4GL procedures in that application image. These are the RemoteServer Object and the ASO Session Object. The first of these is implemented as an in-process server Dynamic Link Library (DLL) and registered under the COM PROGID OpenROAD.RemoteServer.
Methods
Methods provided by the Remote Server COM object include the following:
• Initiate
• Connect
• GetInitiateParameters
• CallProc
• Disconnect
• JsonRpcRequest
• Terminate
Properties
Properties of the Remote Server COM object include the following:
• AkaName
• ImageFile
• CmdFlags
• Location
• Routing
• UseASOLib
• PrivateOrShared
• Options
Each of these methods and properties is described in the sections that follow.
Initiate Method
The Initiate method bypasses the Name Server and connects to an appropriate server process that hosts the specified OpenROAD application image. To make a connection using the Name Server, use the Connect method instead.
HRESULT Initiate
(
[in] BSTR ImageFile,
[in, optional] BSTR CmdFlags,
[in, optional] BSTR Location,
[in, optional] BSTR Routing,
[in, optional] LONG PrivateOrShared,
[in, optional] VARIANT * Options
);
An Initiate must be done once—and only once—prior to using the CallProc or Call4GL methods.
This method uses the following parameters:
ImageFile
Contains the image file name of the OpenROAD file to be initiated
CmdFlags
Contains command line flags to be passed to that application on startup
Location
Identifies the location where the OpenROAD Server is started. Contains the machine name (or Domain Name Server [DNS] name or Internet Protocol [IP] address) of the machine on which the OpenROAD Server is to be run. If no location is specified, the DCOM settings on the client machine are used to determine where to locate the server.
Routing
Specifies a routing string. Specifying “unauthenticated” enables an explicitly unauthenticated connection to the Name Server. This overrides the default authentication level currently set for the client process.
PrivateOrShared
Specifies whether to launch a private server or connect to a shared server. A zero value indicates a shared server; a non-zero value indicates a private server.
Default: shared server
The requested server “application signature” (that is, the combination of the ImageFile string and the CmdFlags string) determines which clients may share a server instance. A shared server is shared only by clients that have specified the same signature.
Options
Reserved for future use
Typically, the Connect method should be used to connect to the server process. This makes a connection through the Name Server, which is configured using the Server Manager. For more information, see
Managing and Monitoring the OpenROAD Server.
Connect Method
The Connect method uses the Application Known As Name (AKA Name) parameter to request Initiate parameters from a Name Server. It then uses these parameters to make a connection to a server installation and process that hosts the OpenROAD application image.
HRESULT Connect
(
[in, optional] BSTR AKAName,
[in, optional] BSTR Location,
[in, optional] BSTR Routing
);
A Connect must be done once—and only once—prior to using the CallProc or Call4GL methods.
If required, the Initiate parameters can be requested from the Name Server using the GetInitiateParameters method and inspected before invoking the Connect method. In this case, the AKAName parameter should not be passed to the Connect method.
This method uses the following parameters:
AKAName
Contains the name of the Application Known As Name registered with Visual OSA. It is required when it is not preceded by a call to method GetInitiateParameters.
Location
Identifies the location where the OpenROAD Server is started. Contains the machine name (or DNS name or IP address) of the machine on which the Name Server is located. If no location is specified, the DCOM settings on the client machine are used to determine where to locate the Name Server.
Routing
Specifies a routing string. Specifying “unauthenticated” enables an explicitly unauthenticated connection to the Name Server. This overrides the default authentication level currently set for the client process.
Typically, the Connect method should be used to connect to the required server process. This makes a connection using the Name Server, which is configured using Visual OSA. Alternatively, the Initiate method can be used to bypass the Name Server.
GetInitiateParameters Method
The GetInitiateParameters method uses the Application Known As Name (AKA Name) parameter to request Initiate parameters from a Name Server. A subsequent Connect method (with AKAName parameter omitted) uses these parameters to make a connection to a server installation and process that hosts the OpenROAD application image.
HRESULT GetInitiateParameters
(
[in] BSTR AKAName,
[in, optional] BSTR Location,
[in, optional] BSTR Routing
);
GetInitiateParameters is an optional method. If the Initiate parameters do not need to be inspected, method Connect should be used alone, passing the required AKAName as a parameter.
The Initiate parameters can be requested from the Name Server using the GetInitiateParameters method and inspected before invoking the subsequent Connect method. In this case, the AKAName parameter should not be passed to the Connect method.
This method uses the following parameters:
AKAName
(Required.) Contains the name of the Application Known As Name registered with Visual OSA
Location
Identifies the location where the OpenROAD Server is started. Contains the machine name (or DNS name or IP address) of the machine on which the Name Server is located. If no location is specified, the DCOM settings on the client machine are used to determine where to locate the Name Server.
Routing
Specifies a routing string. Specifying “unauthenticated” enables an explicitly unauthenticated connection to the Name Server. This overrides the default authentication level currently set for the client process.
Typically, the Connect method alone should be used to connect to the required server process.
CallProc Method
The CallProc method allows the client to call a specified 4GL procedure within the Initiated application, passing named parameters by value or by reference, using PDOs:
HRESULT CallProc
(
[in] BSTR ProcName,
[in, optional] VARIANT * ByValDataObj,
[in, optional] VARIANT * ByRefDataObj
);
This method uses the following parameters:
ProcName
Contains the name of the 4GL procedure to be invoked
ByValDataObj
References a PDO containing parameter data to be passed as named parameters to the 4GL procedure. The data contained in the ByValDataObj is passed by value and cannot be modified by the 4GL procedure.
ByRefDataObj
References a PDO containing parameter data to be passed as named parameters to the 4GL procedure. The data contained in the ByRefDataObj is passed by reference and may be modified by the 4GL procedure. After the CallProc returns, the content of the ByRefDataObj can be examined (using the PDO methods described in
OpenROAD Parameter Data COM Object) to obtain the changed data.
If the call returns an error, the ByRefDataObj is not modified.
Both the ByValDataObj and ByRefDataObj references are optional. For the benefit of languages that cannot easily construct the standard “missing” VARIANT representation (that is, VT_ERROR, with V_ERROR = DISP_E_PARAMNOTFOUND), a VARIANT containing VT_NULL, or a NULL pointer to a VARIANT, are also interpreted as missing parameters.
Disconnect Method
The Disconnect method is a synonym for the Terminate method.
JsonRpcRequest Method
The JsonRpcRequest method enables the client to call a specified 4GL procedure within the initiated application using a string in JSON-RPC 2.0 format:
BSTR JsonRpcRequest
(
[in] BSTR request
);
This method returns a string containing the JSON-RPC 2.0 response message.
It uses the following parameters:
request
Specifies the string containing the JSON-RPC 2.0 request.
Terminate Method
The Terminate method releases any connection that may have been established by a prior Initiate or Connect call, and returns the RSO to its initial state. After calling Terminate, a new Initiate or Connect call can be made.
This method is optional. Simply releasing the RSO and creating a new instance of it achieves the same result as calling Terminate, and the difference in cost is negligible:
HRESULT Terminate
(
);
The Terminate method takes no parameters.
AkaName Property
This is the Application Known As Name passed to the Connect method or the GetInitiateParameters method.
Data Type: readwrite BSTR
ImageFile Property
This is the OpenROAD Server image file name returned from the Name Server. This property is also set after a successful connection is made to the application.
Data Type: readwrite BSTR
CmdFlags Property
This contains OpenROAD Server startup connection flags returned from the Name Server. It is also set after a successful connection is made to the application.
Data Type: readwrite BSTR
Location Property
This is the OpenROAD Server location string returned from the Name Server. It is also set after a successful connection is made to the application.
Data Type: readwrite BSTR
Routing Property
OpenROAD Server routing string returned from the Name Server. Also set after a successful connection is made to the application.
Data Type: readwrite BSTR
UseASOLib Property
Returned from the Name Server:
1
ASOLib is used.
0
ASOLib is not used.
Data Type: readwrite LONG
PrivateOrShared Property
The OpenROAD Server type returned from the Name Server:
1
A private ASO instance is launched and accessed.
0
A shared instance is used.
Default: 0
Data Type: readwrite LONG
This property is also set after a successful connection is made to the application.
Options Property
Reserved for future use.
Data Type: readwrite VARIANT