OpenROAD Client 4GL RemoteServer System Class
In an OpenROAD client, the complexities of driving the COM interface are hidden within a 4GL system class, RemoteServer. The RemoteServer system class lets you invoke procedures on an active OpenROAD Server by providing a required procedure name and optional parameters. When the procedure is complete, you can view the status returned. A value of ER_OK indicates that the procedure was called successfully.
Methods
Within OpenROAD 4GL code, the Remote Server COM object is wrapped by a RemoteServer system class. The methods the OpenROAD RemoteServer system class provides are:
• Initiate
• Call4GL
• JsonRpcRequest
• Release
Attributes
The attributes that the OpenROAD RemoteServer system class provides are:
• ServerType
• Flags
• Location
• Routing
• Image
• Errorcode
• Errortext
These methods and attributes are described in the following sections.
Initiate Method
The Initiate method connects to an appropriate server process that hosts the specified OpenROAD application image. An Initiate must be done once—and only once—prior to using the Call4GL method.
This method has the following syntax:
integer = RemoteServer.Initiate(image = imagepath, type = rptype
[, flags = startflags][ , location = locationname ]
[ , routing = routingstring])
imagepath
Specifies the OpenROAD image file to be loaded
rptype
Specifies one of the following types:
• RP_LOCAL
• RP_PRIVATE
• RP_SHARED
The RP_LOCAL type is useful for development and debugging. When initiated in RP_LOCAL mode, all Call4GL calls on the RemoteServer object are forwarded to a local instance of the named 4GL procedure (within the current application or its included applications) and not sent to an OpenROAD Server.
startflags
Specifies a string containing OpenROAD application startup flags
locationname
Identifies the location where the OpenROAD Server is started
routingstring
Specifies a routing string. The following values are supported:
unauthenticated
Specifies that COM or DCOM will be used to communicate from the client to the OpenROAD Server. The client can, however, be an ANONYMOUS user.
unauthenticated-compressed
Specifies that COM or DCOM will be used to communicate from the client to the OpenROAD Server. When this value is passed, the client can be ANONYMOUS and will use a more efficient method of passing the parameters from the client to the OpenROAD Server. For more information, see the following description about the compressed value.
compressed
Specifies that COM or DCOM will be used to communicate from the client to the OpenROAD Server. When this value is passed, a more efficient technique is used to pass parameters when the Call4GL/CallProc method is invoked from the client to the OpenROAD Server.
When the Call4GL method is invoked, the client initially builds a set of COM SAFEARRAYs used to encapsulate the parameters. A binary string is generated from the SAFEARRAYs, implementing a simple encoding and compression of the parameters. DCOM sends this binary string to the OpenROAD Server. There, the string is not decoded; only the header is examined to determine how the parameters should be routed to the correct destination. The binary string is then routed to the appropriate OpenROAD Server Slave process through COM/DCOM. In the OpenROAD Server Slave, the binary string is decoded and used to populate the 4GL variables that the Service Call Procedure then processes.
Using the compressed method, you can achieve significant reductions in the total number of bytes passed by COM/DCOM. These numbers are typically in the range of 40% to 80% depending on the data content of the parameters being passed from the client to the OpenROAD Server.
http
Specifies that HTTP will be used to communicate from the client to a .NET or Java OpenROAD Server Gatekeeper. The request is always passed as compressed when using HTTP transport. The OpenROAD Server Gatekeeper examines the binary string and then passes it by DCOM to the OpenROAD Server Pooler for processing. The string passed is always a compressed string.
http-jsonrpc
Specifies that a connection will be established through an OpenROADJSONRPC servlet (the Call4GL() method is not available in the connection)
empty string (no value)
Specifies that COM or DCOM will be used to communicate from the client to the OpenROAD Server. The parameters passed when the Call4GL/CallProc method is invoked are encoded as COM SAFEARRAYs and are passed ByValue and ByReference from the client to the OpenROAD Server.
These SAFEARRAY parameters are marshaled from the client to the OpenROAD Server Pooler over COM/DCOM. In the OpenROAD Server Pooler the parameters are re-materialized temporarily and examined to determine how to route the request to the appropriate OpenROAD Server Slave process. The request is then marshaled again into COM SAFEARRAYs and passed by COM/DCOM to the appropriate OpenROAD Server Slave process.
In the OpenROAD Server Slave process, the marshaled parameters are materialized into OpenROAD variables and control is passed to OpenROAD Runtime in the OpenROAD Server Slave process.
Note: If the Initiate method is invoked directly to make a connection, the Name Server is bypassed. To use the Name Server from an OpenROAD client, see uc_name_server_client Class on page 158.
Call4GL Method
The Call4GL method allows the client to call a specified 4GL procedure within the Initiated application, passing named parameters that are expressed as COM VARIANT SAFEARRAY structures.
This method has the following syntax:
integer = RemoteServer.Call4GL(procname,
[parameter = expression | byref(variable)
{, parameter = expression | byref(variable)}])
procname
Specifies the name of the procedure to be called (varchar(32)). If the Call method is successful, it returns ER_OK; otherwise, it returns ER_FAIL.
The syntax of the OpenROAD 4GL RemoteServer system class Call4GL method is simple. While it seems to imply that a referenced object is being sent to the OpenROAD Server as an object, this is not the case. Only a snapshot of the data contained in the object is being sent.
For example, sending a StringObject from an OpenROAD 4GL client to the OpenROAD Server is not a complete transfer of the object itself. The text contained in the StringObject is extracted, sent, and then inserted into a default instance of a StringObject in the OpenROAD Server. Only the text is transferred. Other attributes of the StringObject (such as FileHandle or DBHandle) are not transferred.
When a StringObject is sent through ByRef from an OpenROAD 4GL client to the OpenROAD Server, only the text and no other attributes come back. The returned StringObject may or may not be the same instance that was originally referenced. The 4GL client should make no assumptions about this and should rely only on the text value that was returned, not on any other attributes of the StringObject.
The mapping of "one-dimensional array of VT_UI1" to and from LongByteObject is a direct mapping of the binary byte stream. As with StringObject, only the data stream is transferred and no other attributes. The byte stream contained in the LongByteObject is extracted, sent, and then inserted into a default instance of a LongByteObject in the OpenROAD Server.
When a LongByteObject is sent through ByRef from an OpenROAD 4GL client to the OpenROAD Server, only the byte stream value and no other attributes come back. The returned LongByteObject may or may not be the same instance that was originally referenced. The 4GL client should make no assumptions about this and should rely only on the binary value stream that is returned, not on any other attributes of the LongByteObject.
The mapping to and from BitmapObject is indirect, using LongByteObject as an intermediate step. The semantics are identical to using the BitmapObject LoadLong method to convert LongByteObject data into a BitmapObject, or using the LongByteObject LoadValue method to transfer BitmapObject data into a LongByteObject. Only the raw data stream is sent (or returned) from the OpenROAD Server. No other attributes of the BitmapObject are transferred.
Note: User class structures passed to the RemoteServer Call4GL method must be hierarchical. Circular references and multiple references to the same object instance are not supported. The COM automation array structures allow only a hierarchical nesting.
JsonRpcRequest Method
The JsonRpcRequest method can be used to directly pass a JSON-RPC request to the server. This method internally invokes the JsonHandler.JsonRpcRequest() method.
This method has the following syntax:
StringObject = RemoteServer.JsonRpcRequest(request = StringObject)
request
Specifies the StringObject containing the JSON-RPC 2.0 request.
Release Method
The Release method disconnects from the server and allows the RemoteServer instance to be initiated again. When a RemoteServer instance is destroyed, a Release is done implicitly.
This method has the following syntax:
RemoteServer.Release( )
This method takes no arguments.
ServerType Attribute
ServerType is set during the Initiate call according to the type parameter.
Data Type: One of the following:
Flags Attribute
OpenROAD startup flags are passed into the Initiate call with the flags parameter.
Data Type: readonly varchar(256)
Location Attribute
The OpenROAD Server location is passed into the Initiate call with the location parameter.
Data Type: readonly varchar(256)
Routing Attribute
The string is passed into the Initiate call with the routing parameter.
Data Type: readonly varchar(256)
Image Attribute
The path of the loaded OpenROAD image file is passed into the Initiate call with the image parameter.
Data Type: readonly varchar(256)
Errorcode Attribute
This attribute is the internal COM HRESULT value resulting from the most recently invoked RemoteServer method. This value, when converted to hexadecimal, can be looked up in Winerror.h for the Microsoft description of the error.
Data Type: integer
Errortext Attribute
Certain COM errors are generated by the OpenROAD Server. These errors have a text message associated with them. If a COM error has an associated text message, that message is placed in the Errortext attribute.
Data Type: readonly varchar(256)