uc_osca (OpenROAD Server)
The Object Server Communications Area (OSCA) user class is used to communicate between an OpenROAD client and an OpenROAD Server application. An instance of this class must be passed using BYREF whenever a GSCP is called. This passes a context token from client to server and errors from server to client. A system variable of this class called OSCA is available.
For more information about OSCA in an OpenROAD client application, see
uc_osca (OpenROAD Client).
Attribute
Methods
v_msg_txt Attribute
Data Type: varchar(512)
This attribute contains message text from the OpenROAD Server application. It could be user error text, fatal error text, or information text.
CheckAndHandleError Method (OpenROAD Client)
This error handler method is invoked immediately after making a call to a GSCP. Its behavior depends on the type of error (or message) raised by the OpenROAD Server application. Error details are contained within the uc_osca instance.
Fatal Error
The error text is written to the trace file and the application is closed down. If necessary, an exit trap can be used to perform further fatal error handling. Also, if global variable GV_V_OSCA_FATALERROR_PROC has been set to a 4GL procedure name, that procedure will be called before an exit is performed. (The procedure must expect no parameters and must have no return code.) Control is not returned to the caller.
User Error
Usually the error text is displayed to the user and GC_I_RESUME is returned. If global variable GV_V_OSCA_USERERROR_PROC has been set to a 4GL procedurename, that procedure will be called instead of displaying the error text. (The procedure expects no parameters and must have an integer returncode; the returned value will be returned from this CheckAndHandleError method.) In a 4+ tiered system the current client program may itself be an OpenROAD Server application in which case method ReturnWithUserError() is automatically invoked to pass the error back to the calling client.
Information Message
No action is taken and GC_I_PROCEED is returned. Public attribute v_msg_txt can be accessed directly.
No Error
No action is taken and GC_I_PROCEED is returned.
Call4GL return codes can also be checked at the same time (see p_i_aso_retval in the following example). A non-zero value is considered fatal and is preceded with the text, "RemoteServer CALL Failed."
Parameters:
(p_i_aso_retval = integer,
p_rs = REMOTESERVER)
Note: Parameter p_i_aso_retval is required; p_rs is optional and defaults to CurRemoteServer.
Note: Return Data Type: integer
• GC_I_RESUME
• GC_I_PROCEED
Examples—CheckAndHandleError Method:
1.
i_status = CurRemoteServer.Call4GL ('MyGSCP', b_osca = BYREF(OSCA));
IF OSCA.CheckAndHandleError (p_i_aso_retval = i_status) = GC_I_RESUME THEN
RESUME;
ELSE
CurFrame.StatusText = OSCA.v_msg_txt;
ENDIF;
2.
i_status = MyRS.Call4GL ('MyGSCP', b_osca = BYREF(OSCA));
IF OSCA.CheckAndHandleError (p_i_aso_retval = i_status, p_rs = MyRS) = GC_I_RESUME THEN
RESUME;
ELSE
CurFrame.StatusText = OSCA.v_msg_txt;
ENDIF;
GetErrorNo Method (OpenROAD Client)
This error handler method can be invoked at any time—typically after making a call to a GSCP. It can be used in conjunction with the CheckAndHandleError() method; for example, it can be called from within GV_V_OSCA_FATALERROR_PROC and GV_V_OSCA_USERERROR_PROC. It returns the error number currently in the referenced instance of uc_osca. Zero means no error occurred. Negative error numbers are reserved for use by ASOLib.
Parameters: None
Return Data Type: integer
Example—GetErrorNo Method:
i_retval = OSCA.GetErrorNo();
GetErrorType Method (OpenROAD Client)
This error handler method can be invoked at any time—typically after making a call to a GSCP. It can be used in conjunction with the CheckAndHandleError() method. It returns the integer error type currently in the referenced instance of uc_osca. One of the following values is returned:
0
Specifies that there is no error or message
1
GC_I_ER_FATAL (integer value 1)
2
GC_I_ER_USER (integer value 2)
3
GC_I_ER_INFO (integer value 3—not an error—attribute v_msg_txt contains a message)
Parameters: None
Return Data Type: integer
Example—GetErrorType Method:
i_retval = OSCA.GetErrorType();
ReturnWithUserError Method (OpenROAD Server)
This method is invoked when the OpenROAD Server program needs to report an application error (a soft error) to the calling client. Error details are stored within the uc_osca instance, and the application is exited immediately.
Note: The entry SCP is protected by an exit trap to prevent the OpenROAD Server from shutting down completely. (All GSCPs are automatically protected by such an exit trap.)
Parameters:
(p_i_error_no = integer,
p_v_msg_txt = varchar(512))
Return Data Type: Not applicable—this method causes the application to exit.
Example—ReturnWithUserError Method:
IF i_bank_balance < 0 THEN
OSCA.ReturnWithUserError (p_i_error_no = 101,
p_v_msg_txt = 'Account is overdrawn');
/* control never reaches here */
ENDIF;
ReturnWithFatalError Method (OpenROAD Server)
This method is invoked when the OpenROAD Server program needs to report a fatal application error (a hard error) to the calling client. Error details are stored within the uc_osca instance, and the application is exited immediately.
Note: The entry SCP is protected by an exit trap to prevent the OpenROAD Server from shutting down completely (all GSCPs are automatically protected by such an exit trap).
Parameters:
(p_i_error_no = integer,
p_v_msg_txt = varchar(512))
Return Data Type: Not applicable—this method will cause the application to exit.
Example—ReturnWithFatalError Method:
IF i_world_ended = TRUE THEN
OSCA.ReturnWithFatalError (p_i_error_no = 911,
p_v_msg_txt = 'A serious system error has occurred');
/* control never reaches here */
ENDIF;
Info Method (OpenROAD Server)
This method can be invoked when the OpenROAD Server program needs to record a message for later interrogation by the client. Message details are stored within the uc_osca instance in public attribute p_v_msg_txt.
Invoking this method causes any existing message text to be overwritten. Invoking methods ReturnWithUserError or ReturnWithFatalError also overwrites existing message text.
Parameters:
(p_v_msg_txt = varchar(512))
Return Data Type: None
Example—Info Method:
OSCA.Info (p_v_msg_txt = 'Changes have been saved ');
OSCA.Info (p_v_msg_txt = OSCA.v_msg_txt + 'successfully');