COM (Non-OpenROAD) Client ASO Session Object
From a non-OpenROAD client, two alternative driver objects provide the methods that allow a client to 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. This section describes the ASO Session Object. It is implemented as an in-process server DLL and registered under the COM PROGID OpenROAD.ASOSession.
The ASO Session Object is a helper object that drives an instance of a RemoteServer Object (see
COM (Non-OpenROAD) Client Remote Server Object), but it also automates client-side OSCA-style error handling and ASOLib persistent session context handling. It enables OSCA error handling to be exploited with stateless applications and stateful ASOLib applications.
An existing Remote Server Object can be attached if required.
Methods
Methods provided by the ASOSession COM object include the following:
• Connect
• AttachRSO
• DefineBPM
• CallProc
• Disconnect
Properties
Properties of the ASOSession COM object include the following:
• RSO
• i_error_no
• i_error_type
• v_msg_txt
• i_client_type
• i_user_id
• i_user_name
• v_ip_address
Each of these methods and properties is described in the sections that follow.
Connect Method
The Connect method uses the required 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. If the Name Server parameters indicate that ASOLib should be used, a persistent session context is created in the server application.
An internal Remote Server Object instance is used to make the connection and it is exposed as a property of the ASOSession class.
HRESULT Connect
(
[in] BSTR AKAName,
[in, optional] BSTR Location,
[in, optional] BSTR Routing
);
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.
AttachRSO Method
The AttachRSO method attaches an existing active Remote Server Object to the ASOSession instance. If the Remote Server Object properties indicate that ASOLib should be used, a persistent session context is created in the server application.
The Remote Server Object is exposed as a property of the ASOSession class.
This method should be used only in exceptional situations when a Remote Server Object already exists and is already connected to an OpenROAD Server application. Usually, the Connect method described in
Connect Method should be used.
HRESULT AttachRSO
(
[in] VARIANT * RSO
);
This method uses the following parameter:
RSO
(Required) Specifies an instance of a Remote Server Object that must already be connected to an OpenROAD Server application
DefineBPM Method
The DefineBPM method invokes a system SCP in the remote application. It instantiates an object of the specified user class and associates it with the client's session context in the remote application instance. For further details about Business Policy Managers (BPMs), see
DefineBPM System Service Call Procedure.
HRESULT DefineBPM
(
[in] BSTR userclassname,
);
This method uses the following parameter:
Userclassname
Specifies the name of a BPM userclass in the remote application
Callproc Method
The Callproc method is similar to the Remote Server Object Callproc method. In addition, it automates client-side OSCA error handling and permits server side 4GL OSCA error handling to be used. Syntax and functionality are identical to the Remote Server Object Callproc method with the following additions:
• An OSCA error structure is passed through BYREF to the remote procedure.
• Fatal errors returned in the OSCA structure are handled automatically.
• Other errors and messages returned in the OSCA structure are exposed as properties of this ASOSession class.
Disconnect Method
If a remote persistent session context is associated with this ASOSession instance, it will be destroyed. Also, the RSO property is released. (If the RSO is no longer referenced by any other component it will also terminate.) See
Terminate Method.
This method is optional and is invoked automatically when the ASOSession instance is released. It takes no parameters.
HRESULT Disconnect
(
);
RSO Property
This is the RSO used to communicate with the server application. It was either created by the ASOSession Connect method or it was passed into the ASOSession AttachRSO method. Usually, this property would not be accessed directly. All calls to the server application can be made using ASOSession methods.
Data Type: readonly VARIANT
i_error_no Property
This is the error number in the OSCA structure returned by the previous call to the OpenROAD Server. A value of zero means no error was returned.
Data Type: readonly LONG
i_error_type Property
This is the error type in the OSCA structure returned by the previous call to the OpenROAD Server. Values are:
0
No error
1
Fatal error
2
User error
3
Information only
By default, fatal errors are handled automatically.
Data Type: readonly LONG
v_msg_txt Property
This is the message text in the OSCA structure returned by the previous call to the OpenROAD Server.
Data Type: readonly BSTR
i_client_type Property
This property is relevant when the server application is configured in Visual OSA to use ASOLib. Its value is defaulted when the ASOSession object is created but it can be changed before issuing a Connect or AttachRSO method.
The property value is used for identification when monitoring persistent context sessions using Visual OSA. It specifies what the client program type is, and it determines the session dormant timeout period. Valid values are:
1
Used when the client is an Active Server Page webserver
5
Used when the client is a Jasmine ii server
3
Used for other COM clients
Default: 3—OTHER COM
Most client types have an associated session dormant timeout value. These can be overridden by changing the associated global constant time value in the OpenROAD Server 4GL application. Default session timeout values for the previous client types are:
Active Server Page
Determined by 4GL global constant GC_V_ASP_DORMANT_LIMIT
Default value: 30 minutes
Jasmine ii
Determined by catch-all 4GL global constant GC_V_STOB_DORMANT_LIMIT
Default value: 24 hours
OTHER COM (default client type)
Determined by 4GL global constant GC_V_OTHERCOM_DORMANT_LIMIT
Default value: 30 minutes
Data Type: readwrite LONG
i_user_id Property
This property is relevant when the server application is configured in Visual OSA to use ASOLib. Its value is defaulted when the ASOSession object is created, but it can be changed before issuing a Connect or AttachRSO method.
The property value is used to specify a numeric user identifier. It is used for identification purposes only (for example, when using Visual OSA session monitoring). The default value is the client process number.
Data Type: readwrite LONG
v_user_name Property
This property is relevant when the server application is configured in Visual OSA to use ASOLib. Its value is defaulted when the ASOSession object is created, but it can be changed before issuing a Connect or AttachRSO method.
The property value can be used to specify a text user name. It is used for identification purposes only (for example, when using Visual OSA session monitoring). The default value is the client login name.
Data Type: readwrite BSTR
v_ip_address Property
This property is relevant when the server application is configured in Visual OSA to use ASOLib. Its value is defaulted when the ASOSession object is created but it can be changed before issuing a Connect or AttachRSO method.
The property value can be used to specify client machine identification, such as machine name, Net address, and so on. It is used for identification purposes only (for example, when using Visual OSA session monitoring).
Default: the client machine name
Data Type: readwrite BSTR