Note: This topic does not apply to the following types of server messages:
A server message created using the OS 2200 Open DTP View Data Source Wizard
A server message created using the OS 2200 Open DTP X OCTET Data Source Wizard
A server message created using the AB Suite/EAE Ispec Import Dialog
If you have not already done so, review the following topics:
"Identifying an Output Server Message" in ClearPath ePortal Overview
For output data received from the ClearPath server, ePortal must determine the server message that corresponds to the data. If you did not provide a unique identifier when you created the server message, then you must use orchestration to identify the particular server message that you expect ePortal to receive.
There are two possible methods to identify a server message:
Identifying a specific message to receive
Identifying a server message format to use for unrecognized data
Identifying a Specific Message
You can use the orchestration activities InvokeServer or ReceiveServer to explicitly identify the server message you want to receive. Refer to Orchestration Toolbox Selections for more information on the InvokeServer and ReceiveServer activities.
To specify the exact message, perform the following steps:
Add either an InvokeServer or ReceiveServer activity to your orchestration.
Navigate to the Properties window.
Set the Receive property to the particular server message that you expect to receive.
ePortal uses the server message that you identified to interpret the data it receives, however ePortal may fail to interpret the message if:
The selected server message has one or more identification fields and the data received does not match the identification fields
The selected server message does not have any identification fields, and the length of the data received does not match the length of the identified server message.
The length of the data received matches, but the data is not formatted correctly. For example, for COBOL data, the selected server message indicates that a PIC 9 field starts at position 10 in the record; however, the bytes at position 10 are alphabetic characters.
If a failure occurs, ePortal throws an exception. Your orchestration can catch and handle this exception, if desired.
Identifying a Server Message Format for Unrecognized Data
Default Receives
As an alternative to identifying a specific server message to receive, you can use the orchestration activity InvokeServer or ReceiveServer to orchestrate when to receive a server message, but without specifying a particular type of server message that you expect to receive.
To perform an explicit receive operation without specifying the particular server message that you plan to receive, perform the following steps:
Add either an InvokeServer or ReceiveServer activity to your orchestration.
Navigate to the Properties window.
Set the Receive property to Orch.Message.
Note: Orch.Message is the default setting.
Similarly, if you do not orchestrate a particular "On <client message name>" event handler, but instead rely on the map and forward behavior, ePortal performs an implicit InvokeServer activity with the receive message set to Orch.Message. When ePortal performs a receive operation with a server message of Orch.Message, this is called a default receive operation.
Unrecognized Receives
Note: The UnrecognizedReceive property does not apply to T27 projects.
Whenever orchestration performs a default receive operation, ePortal attempts to match the data received against each of the server records in your data source project that have one or more identification fields. If the data received from the ClearPath system does not match any server records in your data source project, this is called an Unrecognized receive.
You can set the UnrecognizedReceive orchestration property to one particular output server message that is used when orchestration gets an unrecognized receive. Refer to Orchestration Properties for more information on the UnrecognizedReceive property.
To set the UnrecognizedReceive property, perform the following steps:
Click the root node of your orchestration.
Navigate to the properties window.
Set the UnrecognizedReceive property as follows:
leave it blank if you do not want a message format to use for unrecognized receives. In this case, an unrecognized receive causes a failure.
select an output server message format to use for unrecognized receives. In this case, ePortal attempts to interpret the data it receives, using the server message that you selected (known as the selected server message). You may specify one of the predefined unrecognized receive server messages, or you may specify a server message created using the COBOL import wizard. If you use one of the COBOL server messages, it may fail, if:
The selected server message has one or more identification fields and the data received does not match the identification fields
The selected server message does not have any identification fields, and the length of the data received does not match the length of the identified server message.
The length of the data received matches, but the data is not formatted correctly. For example, for COBOL data, the selected server message indicates that a PIC 9 field starts at position 10 in the record; however, the bytes at position 10 are alphabetic characters.
If a failure occurs, ePortal throws an exception. Your orchestration can catch and handle this exception, if desired.
Predefined Unrecognized Receive Server Messages
The following predefined server messages are included when you create a new MCP COBOL, OS 2200 Open DTP, or OS 2200 TIP data source project:
_unrecognized_receive_string: This is a server message that consists of a single field of type string. You can specify this predefined message for the property UnrecognizedReceive. In this case, when ePortal performs an unrecognized receive, it interprets all of the data received as a single string, and places it in the _unrecognized_receive_string server message.
_unrecognized_receive_bytes: This is a server message consisting of a single field of type byte[ ], that is, byte array. You can specify this predefined message for the property UnrecognizedReceive. In this case, when ePortal performs an unrecognized receive, it interprets all of the data received as a byte array, and places it in the _unrecognized_receive_bytes server message.
Note: If you plan to use binary data, you cannot use a Web application presentation; you are restricted to the presentation project types which implement a Web Service. Refer to Creating Web Service Application Projects for more information.