Deciding Which Methods to Use

After you create your Business Interlink definition, you must use PeopleCode to instantiate an Interlink object and execute the Business Interlink plug-in. This PeopleCode can be long and complex. Rather than write it directly, you can drag and drop the Business Interlink definition from the Application Designer Project View into an open PeopleCode edit pane. Application Designer analyzes the definition and generates initial PeopleCode as a template, which you can modify.

In most cases, you must use the Execute method to execute the Business Interlink object. However, for bulk input, you can use the BulkExecute method instead.

The Execute and BulkExecute methods return a value you can use for status and error checking.

The methods discussed in this section, except for BulkExecute, add input values to the Business Interlink object one set, or row, at a time. The call to the Business Interlink Plug-in occurs only once. All the input data is passed with the single Execute. All output is returned as batch as well. The methods then get the output values one set, or row, at a time.

If you’re sending a large amount of data to the input buffers, instead of adding one input row at a time, you might write the data to a staging table, then use the BulkExecute method. This method automatically executes; that is, you don’t have to use the Execute method. It also automatically fills the output record specified with the method with all the output values in every row in the output buffer if you’ve specified an output record.

If your data is mapped into rowsets, you may want to use the InputRowset method. This method takes a standard rowset object to populate the inputs for the Business Interlink object. You can use the FetchIntoRowset method to repopulate the rowset with new data.

If your data is in a flat table structure, you can use the flat table methods. AddInputRow adds rows of input to the Business Interlink object; FetchNextRow fetches rows of output from the Business Interlink object.

A Business Interlink can have dynamic output, meaning that the outputs for a Business Interlink object are changeable in data type or number of outputs.

Business Interlinks supplies a set of methods to support dynamic output. These methods enable you to interrogate the output buffer programmatically to determine the number of fields (columns), their types, and their values.

The following methods support dynamic output:

  • GetFieldCount

  • GetFieldType

  • GetFieldValue

  • MoveFirst

  • MoveNext

Use the MoveFirst method to move to the first column, first row of the output buffer, and within a loop, use the MoveNext method to move to each row on the output buffer.

Within a MoveFirst (or MoveNext) loop, use the GetFieldCount method to get the number of columns in the output buffer, which is also the number of outputs for this Business Interlink object. Then you can extract the outputs from the buffer in a loop.

Within the GetFieldCount loop, use GetFieldName to get the name of the output, GetFieldValue to get the value of the output (which will be returned as a string), and GetFieldType to get the type of the output (if the output is not a string type, you will convert it to this type).

See GetFieldCount, GetFieldType, GetFieldValue, MoveFirst, MoveNext.

A Business Interlink can have hierarchical data. Think of the structure as a tree, with a root doc, node docs, and values. The hierarchical data methods and objects are also referred to as BIDocs.

Input Structures

The following shows an example of an input structure:

Image: Example input structure

This example illustrates the fields and controls on the Example input structure. You can find definitions for the fields and controls later on this page.

Example input structure

The root doc is Calculate Cost(Domestic). A root doc can contain both values and node docs.

The node docs are From, To, Package_Info and Account_Info_List. Each node can contain both values and child nodes. Node docs can be further described as either:

  • Simple node docs have only one set of values for a single instance of a root doc. From, To, Package_Info are all simple node docs.

  • List node docs can contain more than one set of values for a single instance of a root doc. Account_Info_List is a list node doc.

The values in the From node are OriginCountry, OriginPostal_Code, and Ship_Date. The value within the root node is input_param1. Notice that there are values both within the root doc and within node docs.

Business Interlinks support hierarchical input structures with the following methods:

  • GetInputDocs

  • AddDoc

  • AddValue

  • AddNextDoc

The GetInputDocs method returns a reference to the root doc of an input structure. From the previous example, it returns a reference to Calculate Cost(Domestic).

Use the AddDoc method to access the node docs. From the previous example, you would use AddDoc to access the From, To, Package_Info, and Account_Info_List node docs. If any of these nodes contained nodes, you could use AddDoc to access those as well.

Use the AddValue method to set values. From the previous example, you would use AddValue to set the value for input_param1, OriginCountry, OriginPosta_Code, and Ship_date. You must call AddDoc on a node before you can call AddValue for its values.

Use the AddNextDoc method to access the following:

  • If a node doc is a list, that is, it can contain more than one set of values, use AddNextDoc to reference the next set of values.

  • To add another copy of the entire input structure, use AddNextDoc to return a reference to the next root doc.

The following code example sets values for the node doc From, which is a simple node doc. It also sets the values for Account_Info_List, which is a list node doc.

&Calc_Input = &QE_COST.GetInputDocs(""); 
 
&FromDoc = &Calc_Input.AddDoc("From"); 
&ret = &FromDoc.AddValue("OriginCountry", "United States"); 
&ret = &FromDoc.AddValue("OriginPostal_Code", &ORIGIN); 
&ret = &FromDoc.AddValue("Ship_Date", &SHIPDATE); 
 
&Account_Doc = &Calc_Input.AddDoc("Account_Info_List"); 
&ret = &Account_Doc.AddValue("Account_Number", "CT-8001"); 
&ret = &Account_Doc.AddValue("Meter_Number", &METER); 
&ret = & Account_Doc.AddValue("Service_Type", &MODE); 
 
/* add next set of values in list */ 
 
&ret = &Calc_Input.AddNextDoc(); 
&ret = &Account_Doc.AddValue("Account_Number", "CT-8002"); 
&ret = &Account_Doc.AddValue("Meter_Number", &METER); 
&ret = &Account_Doc.AddValue("Service_Type", &MODE);

Output Structures

The following shows an example of an output structure:

Image: Example output structure

This example illustrates the fields and controls on the Example output structure. You can find definitions for the fields and controls later on this page.

Example output structure

The root doc is Calculate Cost(Domestic).

The node docs are Service_Rate and output_param2_List. Each node can contain both values and child nodes. Node docs can be further be described as either:

  • Simple node docs have only one set of values for a single instance of a root doc. Service_Rate is a simple node doc.

  • List node docs can contain more than one set of values for a single instance of a root doc. output_param2_List is a list node doc.

The values in the Service_Rate node are Service_Type, Rate, and in the output_param2_List node, output_member1 and output_member2, and within the root node, output_param1.

Business Interlinks support hierarchical output structures with the following methods:

  • GetOutputDocs

  • GetDoc

  • GetNextDoc

  • GetPreviousDoc

  • GetStatus

  • GetValue

  • GetCount

  • MoveToDoc

The GetOutputDocs method returns a reference to the root doc of an output structure. From the previous example, it returns a reference to Calculate Cost(Domestic).

Use the GetDoc method to access node docs. From the previous example, you would use GetDoc to access the Service_Rate or output_param2_List node docs. If any of these nodes contain nodes, you use GetDoc to access those as well.

Use the GetValue method to retrieve the values. From the previous example, you would use GetValue to retrieve the values for output_param1, and for the Service_Rate node, to get the values Service_Type, Rate, output_member1, and output_member2. You must call GetDoc on a node before you can call GetValue for its values.

Use the GetNextDoc (or GetPreviousDoc) method to access the following:

  • A reference to the next (or previous, respectively) root doc.

  • If a node doc is a list, that is, can contain more than one set of values, use GetNextDoc to reference the next node doc in the list (or GetPreviousDoc to access the previous node doc in the list.)

Use the GetCount method to return either the number of docs in a list node doc, or the number of root docs. In the example, you can count the number of Calculate Cost(Domestic) nodes or the number of output_param2_list nodes.

Use the MoveToDoc method to move to a particular doc at the root level or to a list node doc. In the example, you can move to a Calculate Cost(Domestic) node or to an output_param2_list_node.

The following code example gets values for the node docs Service Rate, which is a simple node doc. It also sets the values for output_param2_List, which is a list node doc.

&Calc_Input = &QE_COST.GetOutputDocs(""); 
 
&Service_Rate_Doc = &Calc_Input.GetDoc("Service_Rate"); 
&ret = &Service_Rate_Doc.GetValue("Service_Type", "Overnight"); 
&ret = &Service_Rate_Doc.GetValue("Rate", "50.00"); 
 
&Out_Param_Doc = &Calc_Input.GetDoc("output_param2_List"); 
&ret = &Out_Param_Doc.GetValue("output_member1", "value1"); 
&ret = &Out_Param_Doc.GetValue("output_member2", "value2"); 
 
/* get next set of values in list */ 
 
&Account_Doc = &Out_Param_Doc.AddNextDoc(); 
&ret = &Out_Param_Doc.GetValue("output_member1", "value3"); 
&ret = &Out_Param_Doc.GetValue("output_member2", "value4");