Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 3 Tools : @SERVERERROR

@SERVERERROR
Invokes special parsing and handling of the last message, which resulted from a request to the TIBCO Object Service Broker external DBMS server. (C)
Invocation
CALL @SERVERERROR(return_message)
 
Prerequisites
@SERVERERROR can be invoked only in handling the SERVERERROR exception.
Usage Notes
All TIBCO Service Gateway error messages have the following format:
S6Bss###E serverid serveruid source: msg text
 
The server ID of the TIBCO Service Gateway that returned the error.
The server user ID (IDPREFIX + ###) of the TIBCO Service Gateway that returned the error.
The code portion of the server trapped the error and returned the message (for example, CSECT, rule, or function).
If a message from a server has some information that is required to process the error, the table-driven approach to the execution of @SERVERERROR causes a rule (specified for that error by the developer using @SERVERERROR) to execute. The error message is interpreted in the @SERVERERROR processing and put into a temporary table until required. For information on server startup parameters, refer to the Service Gateway manuals.
Updating Control Tables
To customize error handling, data in specific control tables must be updated:
CA‑Datacom
CA‑IDMS
The definition of these tables is owned by TIBCO Object Service Broker and must not be modified. The data is owned by the users. The tables are used in the following manner:
1.
The message identifier handlers from @SERVERMSGCNTL do a lookup in the server control tables for the external error codes.
2.
3.
@SERVERERROR can be called at any time, although it is useful only for parsing external server messages generated due to external DBMS errors.
The original message can always be retrieved using @SE_MSG after @SERVERERROR is called.
The information parsed by @SERVERERROR has transaction scope.
Functions for Parsing Messages
Along with @SERVERERROR, you can use the following functions to parse the message:
 
Returns the message identifier or UNKNOWN if message identifier or its prefix is not in @SERVERMSGCNTL.
Returns the source of the message (DB2, DAT, IDM, IMS and so on) or indicates if the source is unknown.
Returns the table name where the message text was parsed (for example, @SERVERERRORDB2).
Refer to the appropriate TIBCO Service Gateway manual for more information.
@SE_MSGHEADER ('MSGIDPREFIX')
@SE_MSGHEADER (SERVERID)
Returns the server ID of the TIBCO Service Gateway that returned the message.
@SE_MSGHEADER (SERVERUSERID)
Returns the server user ID of the TIBCO Service Gateway that returned the message.
 
Exceptions
None are raised unless so arranged in the processing associated with that error for particular error situations. This error-specific processing is activated at pre-specified exit points.
Examples
Handling an Error Message
The following example shows the GET_EMPLOYEE rule:

 
RULE EDITOR ===> SCROLL: P
GET_EMPLOYEE;
_
_ ---------------------------------------------------------------------------
_ ------------------------------------------------------------+--------------
_ GET IDMS_EMPLOYEE WHERE EMP_ID = 467; ¦ 1
_ ---------------------------------------------------------------------------
_ ON SERVERERROR :
_ CALL @SERVERERROR(RETURN_MESSAGE);
_ ON IDMS0966 :
_ CALL SCREENMSG(SCREEN, IDMSUSERMSG);
_ ON IDMSGLOBALERROR :
_ CALL SCREENMSG(SCREEN, @SE_MSG);

 
Suppose a GET on the table IDMS_EMPLOYEE returns the following message:
S6BID034E serverid IDMS01: IDMS ERROR STATUS 0966 RECORD ORG-DEMO-AREA
The SERVERERROR exception is raised and the @SERVERERROR rule is called. @SERVERERROR reads the following @SERVERMSGCNTL table looking for a matching entry. It scans any user-defined tables by using the $@SERVERMSGCNTL parameter value(PRM) table first, and if no match is found it scans the @HURON parameter value table.

 
===============================================================================
@SERVERMSGCNTL(@HURON)
MSG_ID HANDLER MSG_TABLE MSG_SOURCE
_ --------- ---------------- ---------------- ---
_ AD @SERVERERRORADA @SERVERERRORADA ADA
_ AD010E @SERVERERRORADAS @SERVERERRORADA ADA
_ AD011E @SERVERERRORADAS @SERVERERRORADA ADA
_ DM016E @SERVERERRORDAT @SERVERERRORDAT DAT
_ D2 DB2
_ D2002E @SERVERERRDB2CAF @SERVERERRORDB2 DB2
_ D2033E @SERVERERRDB2SQO @SERVERERRORDB2 DB2
_ D2034E @SERVERERRDB2SQO @SERVERERRORDB2 DB2
_ D2036E @SERVERERRDB2SQN @SERVERERRORDB2 DB2
_ IM211I @SERVERERRORIMS2 @SERVERERRORIMS IMS
===============================================================================
 
 
The data for owner @HURON is owned by TIBCO Object Service Broker and must not be updated. Customers can add their own instances in @SERVERMSGCNTL provided that the OWNER specified begins with letters A to Z. The key values in their instance are message identifiers in the form ss###E mentioned above.
The ability to add user-specific entries in @SERVERMSGCNTL is provided, with the understanding that TIBCO Object Service Broker can modify the text of any message and that it is the responsibility of users to update their own handlers. It is recommended that you customize using only the specific server control tables.
Saving the Original Message
When the @SERVERERROR rule is called, it saves the original message in its own storage. This message can be retrieved at any time using function @SE_MSG when @SERVERERROR is done or within any handlers that @SERVERERROR calls through the control tables. Refer to Functions for Parsing Messages.
Example 2: Parsing a Message
If an entry is found, the HANDLER associated with it is executed to parse the external message. Information from the parsed message is stored in the temporary (TEM) table specified in MSG_TABLE. The developer can use the information placed in this table to determine further action.

 
=================================================================================
BROWSING TABLE : @IDMSTATUSCODES
COMMAND ==> SCROLL: P
ERROR_STATUS SIGNALRULE MEANINGFUL_MSG
_ ---- ---------------- -----------------------------------------------
_ 0308 SIGNAL_IDMSERR1 Invalid record name or set name.
_ 0966 SIGNAL_IDMSERR1 Area not available for update.
_ 1410 SIGNAL_IDMSERR1 Attempted privacy breach. User not authorized.
_ 1469 SIGNAL_IDMSERR1 Run unit not connected or connection broken.
_ 1474 SIGNAL_IDMSERR1 Invalid DMCL, subschema or procedure name.

 
In this example, the message ID034E is found and the IDMS_STATUS_CODE rule is executed to parse the message looking for the CA‑IDMS status code. Upon finding the status code, the @IDMSTATUSCODES table is searched using the status code. If an entry is found the SIGNALRULE is executed. The SIGNALRULE, SIGNAL_IDMSERR1, sets the appropriate signal depending on the status code:

 
=================================================================================
RULE EDITOR ===> SCROLL: P
SIGNAL_IDMSERR1;
_
_ ---------------------------------------------------------------------------
_ IDMSSTATUSCODE = 966; | Y N N N N
_ IDMSSTATUSCODE = 1469; | Y N N N
_ IDMSSTATUSCODE = 1474; | Y N N
_ IDMSSTATUSCODE = 1410; | Y N
_ ------------------------------------------------------------+--------------
_ SIGNAL IDMS0966; | 1
_ SIGNAL IDMS1469; | 1
_ SIGNAL IDMS1474; | 1
_ SIGNAL IDMS1410; | 1
_ SIGNAL IDMSGLOBALERROR; | 1
_ ---------------------------------------------------------------------------

 
Overview of Process Flow

 
_ ON SERVERERROR:
_ CALL @SERVERERROR(RETURN_MESSAGE);
|
+-> GET @SERVERMSGCNTL(@HURON) WHERE MSG_ID = @SE_MSGID;
|
V
+-----------+------------------+
| MSG_ID | HANDLER |
+-----------+------------------+
| xx999E | xxx_PARSE_MSG |
+-----------+------------------+
| ID034E | IDMS_STATS_CODE |
+-----------+--------|---------+
V
parse message for ERROR STATUS
GET @IDMSTATUSCODES WHERE ERROR_STATUS = status
|
V

 

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved