Sample ASP Client Code Fragments
Most of the following code fragments would be found in an ASP. The session startup and closedown calls are made only once in the Session_OnStart and Session_OnEnd sections of the global.asa file.
Other Active Server Pages forming the body of the application would contain other SCP and GSCP calls. Here are the sample steps:
1. Connect to the server machine.
This is usually done automatically in the Session_OnStart procedure in the supporting global.asa file. You must edit the application name to be the Name Server registration name configured using the Server Manager. In this example, we use an application registered with the name 'Demo App 1'.
This is the line that should be edited in the supporting global.asa file:
objOR.Connect "Demo App 1"
The preceding statement in global.asa creates a COM or DCOM connection with the server machine that 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 Server Manager.
A call to system SCP CreateASOSession also occurs automatically if the application has been registered as using ASOlib in the Server Manager. (A call to system SCP DestroyASOSession also occurs automatically when the ASOSession object is released).
All calls to GSCPs must pass OSCA data through BYREF into an OpenROAD object of user class uc_osca. The ASOSession COM class automates the addition of an OSCA structure to the BYREF parameters, and fatal errors are handled automatically by ASOSession. (HRESULT error handling is performed, and behavior can be modified in most client languages if required). OSCA is a standard communication link between client and server applications, and it contains, among other things, a session context_id token and error messages.
Note: The OSCA data is used in both the client and the server.
For completeness, skeleton HTML and VB variable declarations are included:
<%@ LANGUAGE = VBScript %>
<% Option Explicit %>
<HTML>
<HEAD>
<TITLE>Author List.</TITLE>
</HEAD>
<BODY>
<%
'#------------------------------------------------------------------------#
'# Define VB variables used in the calls and set local object ObjOR to #
'# point at the session-level object that was used to connect to the #
OpenROAD Server #
'#------------------------------------------------------------------------#
Dim rows, i, v_arr, byrefPDO, OSCA
Dim objOR
Set objOR = Session("objOR")
'#----------------------------------------------#
'# Define the required BPM #
'#----------------------------------------------#
2. Declare an OpenROAD Server control user class to use:
objOR.DefineBPM "uc_authors_pm"
A BPM is a normal user class whose methods have been exposed as 4GL procedures. These procedures are called GSCPs. A BPM can be written to implement business policy, create and use 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, which can be used to generate GSCPs that expose selected BPM methods or wrap 4GL procedures.
DefineBPM is a system SCP which instantiates an object of the named user class, and associates it with the client's session. Subsequent method GSCP calls will be effectively translated into method calls of the current BPM object.
3. Invoke methods (GSCPs) of the user class:
Set byrefPDO = Server.CreateObject("OpenROAD.ParameterData")
'#--------------------------------------#
'# Declare the byref #
'# parameters for this SCP call #
'#--------------------------------------#
byrefPDO.DeclareAttribute "b_arr_author" , "UCARRAY"
byrefPDO.DeclareAttribute "b_arr_author.v_name", "STRING" '# Author name #
byrefPDO.DeclareAttribute "b_arr_author.i_age", "INTEGER" '# Author age #
'#--------------------------------------#
'# Do the call and check for errors. #
'#--------------------------------------#
objOR.CallPROC "SCP_GetAuthorList",,byrefPDO
The preceding example is of a GSCP call that invokes a method of the current BPM. Parameters can be passed by value or through BYREF. One structure handles by value parameters and another handles BYREF parameters. Nested user classes and arrays are supported, but only supported data types will be passed.
4. Make additional GSCP calls, as required:
'#------------------------------------------------------------------------#
'# Output the details if no error occurred. #
'#------------------------------------------------------------------------#
If objOR.i_error_no = 0 Then
%>
<H1>Author List</H1>
<P>
The list of authors is:
</P>
<TABLE>
<TR>
<TH>Author Name</TH>
<TH>Age</TH>
</TR>
<%
rows = byrefPDO.LastRow( "b_arr_author" )
For i = 1 To rows
v_arr = "b_arr_author[" & i & "]" '# Current row #
%>
<TR>
<TD><%= byrefPDO.GetAttribute( v_arr + ".v_name" ) %></TD>
<TD><%= byrefPDO.GetAttribute( v_arr + ".i_age" ) %></TD>
</TR>
<%Next%>
</TABLE>
<%
End If
Set byrefPDO = Nothing
%>
</BODY>
</HTML>
5. Destroy the session context and release the COM connection.
A call to system SCP DestroyASOSession occurs automatically in the Session_OnEnd procedure in the supporting global.asa file by releasing objOR.