Using the OrchExtensions Class

OrchExtensions.cs

<datasourcename>Extensions project includes the OrchExtensions.cs file that implements the OrchExtensions class. This class implements ExternalProcesses activities. When you save the orchestration, ePortal verifies that methods for each ExternalProcess activity exist in OrchExtensions and if not found, then ePortal adds stubs to OrchExtenstions.

Methods are never removed automatically from this class. You must manually remove the methods whose defined signature is changed in the orchestration. You can add members to this class, or add classes to this project as needed. Class members, such as Fields and Properties, persist for the duration of the session. Static members are shared by all sessions running on the same instance of the application.

The constructor of the OrchExtensions class includes a parameter called context of type ProcessOrchestration. ProcessOrchestartion is a class that contains the session declaration variables and messages, and the methods of orchestration. The syntax of the constructor is:

public OrchExtensions(ProcessOrchestration context)
        {
            this.context = context;
        }

The tasks performed in the OrchExtensions class are:

Accessing session declarations defined in the orchestration
Interacting with the data source connector
Interacting with the client
Accessing orch.Message

Accessing Session Declarations in the Orchestration

The context parameter is used to access the global declarations defined in the orchestration in the session declarations section. You can use context.Session.Server., context.Session.Client., and context.Session.Local. to access global server messages, client messages, and global variables respectively.

For example,

To access the session client message Login, use context.Session.Client.Login.
To refer the Orch.Message, use context.Orch.Message. Orch.Message is of type EISRecord.

Interacting with the Data Source Connector

The following table describes the methods that are used to interact with the data source connector. These methods are accessed through the context object.

Method Name	Description	Syntax	Parameters	Exception
PerformConnect	Establishes a connection to the backend server. If a connection already exists it is closed. If successful, Orch.Message. name is set to Unisys.Common. Shared.Constants. GOOD_STATUS_ RECORD_NAME.	void PerformConnect (Message connect Message)	connectMessage – Optional message passed to the data source connector as name/value pairs. Value might be null.	Unisys.Common. EISConnectors. Connector Exception
PerformInvoke	Sends a message to the connector and waits for the response message. Variant 1 is provided for the case where the specific type of message which is received as a response might be known at the time of the InvokeServer operation. The message received is returned to Orch.Message. *Note:* This method does not invoke ServerReceive MessageFilter or ServerSend MessageFilter.	Variant 1: void PerformInvoke( Message inMessage, Message outMessage, bool useFor Unrecognized Receive, String functionName, int timeout) Variant 2: void PerformInvoke( Message message, String functionName, int timeout)	inMessage or message – Message sent to the ClearPath system. outMessage – Message format expected to be received from the ClearPath system. The outMessage is null for Variant 2 as it can accept any message format. useFor Unrecognized Receive – Flag is set to True if the outMessage is used and the message received from the ClearPath system is not recognized. The useFor Unrecognized Receive is set to False for Variant 2. functionName – Name of the function to be invoked on the ClearPath system. The functionName might be unused. timeout – Time defined in seconds to receive a response from the ClearPath system.	Unisys.Common. Runtime.Process Orch.Receive TimeoutException Unisys.Common. Runtime.Process Orch.Unrecognized MessageException Unisys.Common. Runtime.Process Orch.Message FormatException Unisys.Common. Runtime.Process Orch.InputData Overflow Exception Unisys.Common. Runtime.Process Orch.InvalidCast Exception Unisys.Common. Runtime.Process Orch.Connector Exception
PerformSend	Sends a message to the connector and does not wait for the response. *Note:* This method does not invoke ServerSend MessageFilter.	void PerformSend( Message message, String functionName)	message – Message sent to the ClearPath system. functionName – Name of the function to be invoked on the ClearPath system. The functionName might be unused.	Unisys.Common. Runtime.Process Orch.InputData OverflowException Unisys.Common. Runtime.Process Orch.InvalidCast Exception Unisys.Common. Runtime.Process Orch.Connector Exception
PerformReceive	Receives a message from the connector. Variant 1 is provided for the case where the specific type of message which is received as a response might be known at the time of the ReceiveServer operation. The message received is returned to Orch.Message. *Note:* This method does not invoke ServerReceive MessageFilter.	Variant 1: void PerformReceive( Message outMessage, bool useFor Unrecognized Receive, int timeout) Variant 2: void PerformReceive (int timeout)	outMessage – Message format expected to be received from the ClearPath system. The outMessage is null for Variant 2 as it can accept any message format. useFor Unrecognized Receive – Flag is set to True if the outMessage is used and the message received from the ClearPath system is not recognized. The useFor Unrecognized Receive is set to False for Variant 2. timeout – Time defined in seconds to receive a response from the ClearPath system.	Unisys.Common. Runtime.Process Orch.Receive TimeoutException Unisys.Common. Runtime.Process Orch.Unrecognized MessageException Unisys.Common. Runtime.Process Orch.Message FormatException Unisys.Common. Runtime.Process Orch.Connector Exception
InvokeServer	Sends a message to the connector and waits for the response message. This method invokes ServerReceive MessageFilter or ServerSend MessageFilter. Variant 1 is provided for the case where the specific type of message which is received as a response might be known at the time of the InvokeServer operation. The message received is returned to Orch.Message.	Variant 1: void InvokeServer( Message inMessage, Message outMessage, bool useFor Unrecognized Receive, String functionName, int timeout) Variant 2: void InvokeServer( Message message, String functionName, int timeout)	inMessage or message – Message sent to the ClearPath system. outMessage – Message format expected to be received from the ClearPath system. The outMessage is null for Variant 2 as it can accept any message format. useFor Unrecognized Receive – Flag is set to True if the outMessage is used and the message received from the ClearPath system is not recognized. The useFor Unrecognized Receive is set to False for Variant 2. functionName – Name of the function to be invoked on the ClearPath system. The functionName might be unused. timeout – Time defined in seconds to receive a response from the ClearPath system.	Unisys.Common. Runtime.Process Orch.Receive TimeoutException Unisys.Common. Runtime.Process Orch.Unrecognized MessageException Unisys.Common. Runtime.Process Orch.Message FormatException Unisys.Common. Runtime.Process Orch.InputData OverflowException Unisys.Common. Runtime.Process Orch.InvalidCast Exception Unisys.Common. Runtime.Process Orch.Connector Exception
SendServer	Sends a message to the connector and does not wait for the response. This method invokes the ServerSend MessageFilter.	void SendServer( Message message, String functionName)	message – Message sent to the ClearPath system. functionName – Name of the function to be invoked on the ClearPath system. The functionName might be unused.	Unisys.Common. Runtime.Process Orch.InputData OverflowException Unisys.Common. Runtime.Process Orch.InvalidCast Exception Unisys.Common. Runtime.Process Orch.Connector Exception
ReceiveServer	Receives a message from the connector. This method invokes the ServerReceive MessageFilter. Variant 1 is provided for the case where the specific type of message which is received as a response might be known at the time of the ReceiveServer operation. The message received is returned to Orch.Message.	Variant 1: void ReceiveServer( Message outMessage, bool useFor Unrecognized Receive, int timeout) Variant 2: void ReceiveServer (int timeout)	outMessage – Message format expected to be received from the ClearPath system. The outMessage is null for Variant 2 as it can accept any message format. useFor Unrecognized Receive – Flag is set to True if the outMessage is used and the message received from the ClearPath system is not recognized. The useFor Unrecognized Receive is set to False for Variant 2. timeout – Time defined in seconds to receive a response from the ClearPath system.	Unisys.Common. Runtime.Process Orch.Receive Timeout Exception Unisys.Common. Runtime.Process Orch. Unrecognized Message Exception Unisys.Common. Runtime.Process Orch.Message Format Exception Unisys.Common. Runtime.Process Orch.Connector Exception
PerformClose	Closes the connection to the ClearPath system. You can re-open the connection by calling PerformConnect method.	void performClose()
AssignField	Copies the dynamic metadata from a server message field to a client message field.	void AssignField(EIS Field dest, EISField source)	dest - Client message field to which the dynamic data needs to be copied. source – Server message field from which the dynamic data needs to be copied.
MapClientTo Server	Maps a client message to server message. Given a client message, creates the corresponding server message, and copies the common field values. It is useful when the MessageName is a variable.	Unisys.Message MapClient ToServer(Unisys. Message clientMessage)	clientMessage – Client message to be mapped to a server message.	Unisys.Common. Runtime.Process Orch. Unorchestrated Message Exception
MapServerTo Client	Maps a server message to a client message. Given a server message, creates the corresponding client message, and copies the common field values. It is useful when the MessageName is a variable.	Unisys.Message MapServer ToClient(Unisys. Message serverMessage)	serverMessage – Server message to be mapped to a client message.	Unisys.Common. Runtime.Process Orch. Unorchestrated Message Exception
CreateServer Message	Returns the equivalent server message for the given EISRecord. If the message cannot be constructed, the method returns message of type Unisys.Errror and the connection is closed. If you know the message already, you can use the server message constructor. For example, if the message name is Login, you can get equivalent server message as: Unisys.Message msg = new Server.Login (record)	Unisys.Message CreateServer Message (EISRecord record)	record – EISRecord that is used to construct the message.
CreateClient Message	Returns the equivalent client message for the given EISRecord. If the message cannot be constructed, the method returns message of type Unisys.Errror and the connection is closed. If you know the message already, you can use the client message constructor. For example, if the message name is Login, you can get equivalent client message as: Unisys.Message msg = new Client.Login (record)	Unisys.Message CreateClient Message( EISRecord record)	record – EISRecord that is used to construct the message.
LogException	Writes an entry to the trace log if the LogLevel is warning or higher. The log entry contains a time stamp, the process string, the session ID, and the exception message.	void LogException (Exception e, String process)	e – Exception that is to be logged. process – Name of the process or method to which the exception is associated with.
UserTrace	Used to write a message to the log. If you are debugging, the method writes to the Output Window and log, else, it writes to the log when the log level parameter is greater than or equal to the current log level.	void UserTrace(String msg, String level)	msg – String to be written to the log. level – Log level used to write the log. The value can be None, Error, Warning, Informational, and Verbose.

Interacting with the client

To send a message to the client, the equivalent of ReplyToClient activity, the ExternalProcess method returns a client message instead of null.

Accessing messages and EISRecords

Unisys.Message is the base type for all the client and server messages. The base class provides the members MessageClassName and toEISRecord. MessageClassName is a string that identifies the message. toESISRecord is a method that returns an EISRecord of the message.

Client and server messages are referenced using the namespace of the data source. For example: MyDatasource.Client.Login is the type declaration for the Login client message.

Messages have the following three constructors:

Default constructor: Returns a message initialized to its default values.
Constructor taking an EISRecord as a parameter: Returns a message with values taken from the EISRecord.
Constructor taking parameters for each field in the message: Returns a message with the values passed in.

For example:

MyDatasource.Client.Login login = new MyDatasource.Client.Login();

MyDatasource.Client.Login login = new MyDatasource.Client.Login(Orch.Mesage);

MyDatasource.Client.Login login = new MyDatasource. Client.Login(“MyUsercode”, “MyPassword”);

Message Fields

Each field in the message has an accessor to read and write the value of the field. Fields can be of simple types such as String, Int or Boolean, complex types such as sub records, or arrays of simple or complex types.

Simple fields have metadata stored in a member accessor called <fieldname>Field. This metadata is of type EISField. It is mostly used at design time, but some runtime dynamic data is in this class. When copying from a server message to a client message, this member should also be copied using the AssignField method.

A complex field references another record; hence the fields within the record are accessed with further dot notation.

Array fields are implemented as a generic List. An array of strings is defined as a List<string>. The list might be manipulated using List methods such as Add, AddRange, Remove, and so on. Individual elements of the List can be accessed and modified.