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.

Each of these methods and properties is described in the sections that follow.

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:

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.

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.

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.

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.

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 on page 95.

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:

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.

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.

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.

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:

(Required.) Contains the name of the Application Known As Name registered with Visual OSA

Typically, the Connect method alone should be used to connect to the required server process.

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:

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.

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.

The Disconnect method is a synonym for the Terminate 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:

This method returns a string containing the JSON-RPC 2.0 response message.

It uses the following parameters:

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:

The Terminate method takes no parameters.

This is the Application Known As Name passed to the Connect method or the GetInitiateParameters method.

Data Type: readwrite BSTR

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

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

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

OpenROAD Server routing string returned from the Name Server. Also set after a successful connection is made to the application.

Data Type: readwrite BSTR

Returned from the Name Server:

Data Type: readwrite LONG

The OpenROAD Server type returned from the Name Server:

Data Type: readwrite LONG

This property is also set after a successful connection is made to the application.