Business Interlink Class

This chapter provides an overview of Business Interlink class and discusses the following topics:

• Using the Interlink object

• Deciding which methods to use

• Using the incoming Business Interlink methods and properties

• Understanding the state of an Interlink object

• Using Business Interlink with Application Engine

• Using the Data Type of a Business Interlink object

• Understanding the scope of a Business Interlink object

• Business Interlink class built-in function

• Business Interlink class reference

• Configuration parameters

Note. PeopleSoft Business Interlinks is a deprecated product. The Business Interlinks class currently exists for backward compatibility only. For new integrations, use Integration Broker instead.

See Also

Message Classes

Understanding Business Interlink Class

The PeopleSoft Business Interlink framework provides a gateway for PeopleSoft applications to the services of any external system. This framework enables any PeopleSoft component (that is, a page, an Application Engine program, and so on) to integrate with any external system in near real-time and batch modes.

This framework enables a PeopleCode program to map the input and outputs of a Business Interlink definition to PeopleCode variables and record fields, then, using an Interlink object, call the Interlink plug-in, which in turn calls the external system, passes the information to the external system, and returns values to the PeopleCode program.

This documentation describes only the Interlink object portion of the PeopleSoft Business Interlink framework.

Each Interlink object is based on a Business Interlink definition, which is created in Application Designer. An Interlink object can be based on only a single Business Interlink definition.

See Also

See additional Business Interlink documentation available on PeopleSoft Customer Connection.

Using the Interlink Object

After you instantiate an Interlink object, use the Interlink object to:

• Populate the input buffer

• Send the data to the Interlink plug-in (by using the Execute method)

• Fetch the outputs from the buffer

• Check for status and error messages

After the Business Interlink object is instantiated, you can assign values from constants, PeopleSoft variables, or record fields to the inputs of that Business Interlink object.

When you execute the Business Interlink object, it loads the appropriate Business Interlink Plug-in and passes itself to that Business Interlink Plug-in. The Business Interlink Plug-in processes the input data, passing the input values of the Business Interlink object to the external system and then fills the output values of the Business Interlink object (if there are outputs).

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 this section, we discuss how to:

• Execute the Business Interlink object.

• Support batch input and output.

• Support rowsets.

• Use the flat table methods.

• Support dynamic output.

• Use hierarchical data (BIDocs).

See Also

See additional Business Interlink documentation available on PeopleSoft Customer Connection.

Executing the Business Interlink Object

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.

Supporting Batch Input and Output

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.

Supporting Rowsets

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.

Using the Flat Table Methods

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.

Supporting Dynamic Output

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.

Using Hierarchical Data (BIDocs)

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:

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:

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");

Using the Incoming Business Interlink Methods and Properties

The incoming Business Interlink methods enable you to parse an XML request and build an XML response.

The incoming Business Interlink uses a set of methods and functions.

The GetContentBody Request object method converts the request content into an XML string. You can then use this string with the GetBiDoc function to create a BiDocs structure from it that is the same shape and contains the same data as the XML document contained in the XML string.

After you have the BiDocs structure containing the XML request, you can:

• Use the GetNode method to get one of the XML elements.

• Use the NodeType method to get the type of the node (element, processing instruction, comment).

• Use the NodeName property to get the name of the element.

• Use the NodeValue property to get the value of the element.

You can also use the standard BiDocs methods (such as GetDoc, GetValue) to retrieve information from this BiDocs object.

When an XML element contains attributes, the AttributeCount property gets the number of attributes, the GetAttributeName method gets the name of an attribute, and the GetAttributeValue method gets the value of an attribute.

To build an XML response, you can use the GetBiDocs function to create a blank BiDocs structure. To create the XML structure within that BiDocs, use CreateElement to create an XML tag, AddComment to add an XML comment, AddAttribute to add an attribute to an XML tag, and AddProcessInstruction to add a processing instruction (the first tag of the XML response).

Use the GenXMLString method to create an XML string from the BiDocs structure. Then you can use the Write Response method to write the response to the HTTP response string.

See Also

See additional Business Interlink documentation available on PeopleSoft Customer Connection.

Understanding the State of an Interlink Object

PeopleSoft Business Interlink API that are run on the application server should be stateless, that is, if you want to save information from one call of the Interlink object to the next, you have to do it yourself by writing the relevant information to the database. If you use the Execute method more than once within a single PeopleCode event (that is, if you have the Execute method in some sort of loop) the state is preserved. After you leave the event, any state associated with the Interlink object is lost.

You should create only one Business Interlink object, that is, you should only use the GetInterlink function once. After that, you can load it with data, pass the data to the Interlink plug-in (using Execute) and fetch output data as many times as you need.

Using Business Interlink with Application Engine

In a regular PeopleCode program, you can only declare a Business Interlink object as local. However, in an Application Engine program, you can declare a Business Interlink object as global. Instantiating a Business Interlink object once as a global saves on the significant overhead of reinstantiating a local object for every iteration of PeopleCode called in a loop.

• Global Business Interlink objects can only be used in Application Engine PeopleCode programs because PeopleCode that runs on an application server must be stateless.

• When a restartable Application Engine program abends, global Business Interlink objects that were instantiated before the last checkpoint are automatically reinstantiated at restart. So the object will be available, even though no call has been made to GetInterlink in the restarted process. However, the associated Business Interlink data buffers are not recovered, so the Application Engine program must be written such that these buffers are empty whenever a checkpoint is taken.

• Business Interlink objects should not be declared as global unless they are used in several PeopleCode actions, or in a PeopleCode action that is called in a loop. Only in these instances is the overhead of doing a checkpoint worthwhile.

Using the Data Type of a Business Interlink Object

You should declare a Business Interlink object using the data type Interlink. For example,

Local Interlink &MYBI;

Declare hierarchical data as type BIDocs. For example:

Local BIDocs &OutlistDoc; 

Note. BIDocs and Interlink objects used in PeopleCode programs run on the application server can be declared only as type Local. You can declare Interlinks as Global only in an Application Engine program.

Understanding the Scope of a Business Interlink Object

A Business Interlink object can be instantiated from PeopleCode.

This object can be used anywhere you have PeopleCode, that is, in an application class, Application Engine PeopleCode, record field PeopleCode, and so on.

Business Interlink Class Built-in Functions

GetBiDoc

GetInterlink

Business Interlink Class Methods

In this section, we discuss the Business Interlink class methods. The methods are discussed in alphabetical order.

AddDoc

Syntax

AddDoc(docname)

Description

The AddDoc method adds a document to an input structure. The added document is an input parameter for a Business Interlink object that is not of simple type (such as integer or string). You must add the document to the input structure before you can add values to its members with AddValue.

Parameters

Returns

The document added to the BIDocs input document.

Example

In the following example, the input structure for Calculate Cost, or the root level document, is created with the GetInputDocs method. (To create, or add, more input structures, use AddNextDoc.) The Calculate Cost input parameter From is a document, so the AddDoc method adds it to the input document.

Local Interlink &QE_COST; 
Local BIDocs &CalcCostIn; 
Local BIDocs &FromDoc, &ToDoc, &PackageDoc, &AccountDoc; 
Local number &ret, &retinput; 
 
 
&QE_COST = GetInterlink(Interlink.QE_COST_EX); 
 
&CalcCostIn = &QE_COST.GetInputDocs(""); 
 
&ret = &CalcCostIn.AddValue("input_param1","value"); 
​&FromDoc = &CalcCostIn.AddDoc("From"); 
​&ret = &FromDoc.AddValue("OriginCountry", "United States"); 
&ret = &FromDoc.AddValue("OriginPostal_Code", &ORIGIN); 
&ret = &FromDoc.AddValue("Ship_Date", &SHIPDATE); 
 
/* Call AddDoc and AddValue for To, Package_Info, and Account_Info_List (code not⇒
 shown) */

The following shows the input structure for this example. It contains five input parameters: input_param1, From, To, Package_Info, and Account_Info_List. This is a version of the Federal Express plug-in that was modified for this example (input_param1 was added, Account_Info was modified to be a list).

Example input structure

See Also

Business Interlink class: GetInputDocs method, AddValue method, AddNextDoc method.

AddInputRow

Syntax

AddInputRow(inputname, value)

where inputname and value are in matched pairs, in the form:

inputname1, value1 [, inputname2, value2] . . .

Description

The AddInputRow method adds a row of input data (value) from PeopleCode variables or record fields for the Business Interlink object executing the method. These must be entered in matched pairs, that is, every input name must be followed by its matching value.

Note. The input name, not the input path, of the interface definition is used for this method.

There must be an input name for every input parameter defined in the interface definition used to instantiate the Business Interlink object.

If you specify a record field that is not part of the record the PeopleCode program is associated with, you must use recname..fieldname for that value.

You can specify default values for every input name in the interface definition (created in Application Designer.) These values are used if you create a PeopleCode "template" by dragging the interface definition from the Project window in Application Designer to an open PeopleCode editor window.

Parameters

Returns

A Boolean value: True if the input values were successfully added. Otherwise, it returns False.

Example

In the following example, the Business Interlink object name is SRA_ALL_1, and the input name, such as ship_site_name, are being bound to record fields, such as QE_RP_SITENAME or VENDOR_INFO.QE_RP_PROMISEDATE, to variables like &PARTNAME, or to literals, like 10 for quantity.

&SRA_ALL_1.AddInputRow("ship_site_name", QE_RP_SITENAME,  
   "promise_date", VENDOR_INFO.QE_RP_PROMISEDATE,  
   "request_date", QE_RP_ORDERREQDATE,  
   "subline_site_name", QE_RP_SITENAME,  
   "quantity", 10,  
   "part_name", &PARTNAME,  
   "site_name", INV_LOCATIONS.QE_RP_SITENAME);

See Also

Business Interlink class: Execute method.

GetInterlink

AddNextDoc

Syntax

AddNextDoc()

Description

The AddNextDoc method adds a document to one of the following levels:

• The root level of the input structure for a Business Interlink object. You create a reference to this level with the GetInputDocs method.

• When a document within the input structure is a list, AddNextDoc adds another document to the list. If you use AddNextDoc on a document that is not a list, AddNextDoc fails and returns an error.

Parameters

None.

Returns

This method returns an integer. The values are:

Example

In this example, the input structure for Calculate Cost, or the root level document, is accessed with the GetInputDocs method. The AddNextDoc method adds another BIDocs input document. The Calculate Cost input parameter Account_Info_List is a document, so the AddDoc method adds it to the BIDocs input document. Account_Info_List is also a document list, so AddNextDoc method adds another Account_Info_List document.

Local Interlink &QE_COST; 
Local BIDocs &CalcCostIn; 
Local BIDocs &FromDoc, &ToDoc, &PackageDoc, &AccountDoc; 
Local number &ret, &retinput; 
 
 
&QE_COST = GetInterlink(Interlink.QE_COST_EX); 
 
&CalcCostIn = &QE_COST.GetInputDocs(""); 
 
For &n = 1 to &number_of_input_sets 
/* Get values for inputs, such as &ORIGIN (code not shown) */ 
 
   &ret = &CalcCostIn.AddValue("input_param1","value"); 
   &FromDoc = &CalcCostIn.AddDoc("From"); 
   &ret = &FromDoc.AddValue("OriginCountry", "United States"); 
   &ret = &FromDoc.AddValue("OriginPostal_Code", &ORIGIN); 
   &ret = &FromDoc.AddValue("Ship_Date", &SHIPDATE); 
 
   /* Call AddDoc and AddValue for To and Package_Info 
      (code not shown) */ 
 
   /* Call AddDoc and AddNextDoc for the AccountDoc document list */ 
   &AccountDoc = &CalcCostIn.AddDoc("Account_Info_List"); 
   For &m = 1 to &number_of_AccountDocs 
      &ret = &AccountDoc.AddValue("Account_Number", &ACCOUNT); 
      &ret = &AccountDoc.AddValue("Meter_Number", &METER); 
      &ret = &AccountDoc.AddValue("Service_Type", &SVCTYPE); 
      ​&retinput = &AccountDoc.AddNextDoc(); 
   ​End-For; 
 
   ​&retinput = &CalcCostIn.AddNextDoc(); 
​ 
End-For;

The following shows the input structure for this example. It contains five input parameters: input_param1, From, To, Package_Info, and Account_Info_List.

From, To, and Package_Info are not lists, so if you try to use AddNextDoc with these parameters, such as the following line of code, AddNextDoc will fail and return an error message.

&retinput = &To.AddNextDoc();

Example input structure

See Also

Business Interlink class: GetInputDocs method, AddDoc method, AddValue method.

AddValue

Syntax

AddValue(paramname, value)

Description

The AddValue method adds a value to a member of a document within the input structure for a Business Interlink object.

Parameters

Returns

This method returns an integer. The values are:

Example

In the following example, the Business Interlink object name is QE_COST.

In the following example, the input structure for Calculate Cost, or the root level document, is accessed with the GetInputDocs method. (To create, or add, more input structures, use AddNextDoc.) The Calculate Cost input parameter From is a document, so the AddDoc method adds it to the input structure. Then the AddValue method adds values to each of the From document members.

Local Interlink &QE_COST; 
Local BIDocs &CalcCostIn; 
Local BIDocs &FromDoc, &ToDoc, &PackageDoc, &AccountDoc; 
Local number &ret; 
 
&QE_COST = GetInterlink(Interlink.QE_COST_EX); 
 
/* Get some values for input, such as &ORIGIN (code not shown) */ 
 
&CalcCostIn = &QE_COST.GetInputDocs(""); 
​&ret = &CalcCostIn.AddValue("input_param1","value"); 
​ 
&FromDoc = &CalcCostIn.AddDoc("From"); 
​&ret = &FromDoc.AddValue("OriginCountry", "United States"); 
&ret = &FromDoc.AddValue("OriginPostal_Code", &ORIGIN); 
&ret = &FromDoc.AddValue("Ship_Date", &SHIPDATE); 
​ 
/* Call AddDoc, AddValue for Package, Account_Info_List, and also call AddNextDoc⇒
 for Account_Info_List (code not shown) */

The following shows the input structure for this example. It contains five input parameters: input_param1, From, To, Package_Info, and Account_Info_List.

Example input structure

See Also

Business Interlink class: GetInputDocs method, AddDoc method, AddNextDoc method.

BulkExecute

Syntax

BulkExecute(RECORD.inputrecname [, RECORD.outputrecname] [, {user_process_inst | user_operid}])

Description

The BulkExecute method uses the data in the specified record to populate the input buffer, copying like-named fields. Then the method executes, and, optionally, fills the record specified by outputrecname with data from the Business Interlink output buffer. BulkExecute results in significantly faster performance for transactions that process large amounts of data. Instead of adding one input row at a time, then fetching the values one at a time, you might write the data to a staging table, use the BulkExecute method and then read the data from the output table. This would be especially effective in Application Engine programs that process sets of data rather than individual rows.

This method assumes that the names of the fields in the record match the names of the inputs (or outputs) defined in the Business Interlink Definition. If there is no field in the inputrecname for a Business Interlink input parameter, the parameter’s default value is used. If no default is specified, an empty string is passed. You must ensure that this default value is legitimate.

Fields in the output buffer are matched against the fields specified in the output record. You do not have to specify an output record. If you don’t specify an output record, the output buffers are not be populated.

If you specify an output record, and if you have fields in the output record that are not specified as output parameters, they aren't populated with the BulkExecute method. In addition, they shouldn’t be set as NOT NULL, otherwise inserts fail.

Note. Before you use this method, you should flush the record used for output and remove any residual data that might exist in it.

If you specify an output record, and you want to use the output record for error checking, you must add the following fields to your output record:

• RETURN_STATUS

• RETURN_STATUS_MSG

Note. The field names in the output record must match these names exactly.

Then you must mark one or more input parameters as "key fields" in the Business Interlink definition (using the BulkExecute ID check box.) The value of these key fields are copied to the output record, and you can use these fields to match error messages with input (or output) rows.

To order your input (and output) rows, you must add the following column to both the input and output table:

• BI_SEQ_NUM

•  

Note. The field name in your input and output records must match this name exactly.

The input rows are read in the order of numbers in BI_SEQ_NUM, and the output rows are generated using the same order number.

This method automatically executes, so you don’t need to use the Execute method with this method.

Whether this method halts on execution depends on the setting of the StopAtError configuration parameter. The default value is True, that is, stop if the error number returned is something other than a 1 or 2. This configuration parameter must be set before using the BulkExecute method.

Parameters

Returns

The following are the valid returns:

Example

Here are two PeopleSoft records that could be used as input and output records for BulkExecute. The key fields in the input record, which need to have the BulkExecute ID check box checked in Application Designer, are QE_RP_PO_NUMBER and QE_RP_SITENAME. These key fields are used both for input and output.

Example input record for BulkExecute

Example output record for BulkExecute

Here are the corresponding inputs and outputs for a Business Interlink that has had its inputs and outputs renamed to match the field names in the records. The inputs and outputs have been renamed where necessary to match the record field names.

Example Business Interlink inputs for BulkExecute

Example Business Interlink inputs for BulkExecute

The PeopleCode program using these records could contain the following code to run BulkExecute.

Local Interlink &CREATE_PO; 
Local number &EXECRSLT; 
 
&CREATE_PO = GetInterlink(INTERLINK.QE_RP_CREATEPO1); 
 
/* The next three lines set configuration parameters, which are not shown in the⇒
 previous examples. */ 
&CREATE_PO.SERVER_NAME = "bc1"; 
&CREATE_PO.RSERVER_HOST = "4.3.4.3"; 
&CREATE_PO.RSERVER_PORT = "2200"; 
 
&EXECRSLT = &CREATE_PO.BulkExecute(RECORD.QE_RP_PO, RECORD.QE_RP_PO_OUT1);

See Also

Business Interlink class: StopAtError property.

Clear

Syntax

Clear()

Description

The Clear method clears the input and output buffers. If you're using Business Interlinks in a batch program, every time after you use the Execute method, use the Clear method to flush out the input and output buffers.

Parameters

None.

Returns

None.

Example

For &n = 1 to x 
   &myinterlink.AddInputRow("input1", value1, "input2", value2);  
   &myinterlink.Execute(); 
   &myinterlink.FetchNextRow("output1", value1, "output2", value2);  
      /* do processing on data */ 
   &myinterlink.Clear(); 
   ​&n = &n + 1; 
End-for;

See Also

Business Interlink class: Execute method, BulkExecute method.

Execute

Syntax

Execute()

Description

When an Interlink object executes the Execute method, the transaction associated with the Interlink object is executed.

If there is only one row, after appropriate substitution is made, the transaction is executed only once. Otherwise, the data is "batched up" and sent once. You have to call Execute only once to execute all the rows of the input buffer.

Generally, you would only use the Execute method after using the AddInputRow method. If you create a PeopleCode "template" by dragging the Business Interlink definition from the Project window in Application Designer to an open PeopleCode editor window, the usual order of the execution of methods is shown in the template.

If you're using Business Interlinks in a batch program, every time after you use the Execute method, use the Clear method to flush out the input and output buffers.

Whether this method halts on execution depends on the setting of the StopAtError configuration parameter. The default value is True, that is, stop if the error number returned is something other than a 1 or 2. This configuration parameter must be set before using the Execute method.

Parameters

None.

Returns

The following are the valid returns:

Example

Local number &EXECRSLT; 
.  .  . 
&EXECRSLT = &SRA_ALL_1.Execute();
If (&EXECRSLT <> 1) Then 
/* The instance failed to execute */ 
/* Do Error Processing */ 
End-If; 

See Also

Business Interlink class: BulkExecute method, Clear method.

GetInterlink

FetchIntoRecord

Syntax

FetchIntoRecord(RECORD.recname, [, {user_process_inst | user_operid}])

Description

The FetchIntoRecord method copies the data from the output buffer into the specified record (SQL table) copying like-named fields. This method assumes that the names of the fields in the record match the names of the outputs defined in the Business Interlink definition.

You can use the FetchIntoRecord method to perform a transaction on a large amount of data that you want to receive from your system. Instead of executing your Business Interlink and then fetching one output row at a time, you might execute your Business Interlink, then use the FetchIntoRecord method to write the data returned from the Business Interlink to a staging table.

Note. Before you use this method, you should flush the record used for output and remove any residual data that might exist in it.

If your data is hierarchical, that is, in a rowset, and you want to preserve the hierarchy, use FetchIntoRowset instead of this method.

To order your output rows, you must add the BI_SEQ_NUM column to the record.

This column is populated with a sequence number that corresponds to the order in which each row of the record was written to by the method.

Parameters

Returns

Number of rows fetched if one or more non-empty rows are returned.

If an empty row is returned, that is, every if field is empty except the return_status and return_status_msg fields, this method returns one of the following error messages:

Example

&RSLT = &QE_SM_CONCAT.FetchIntoRecord(RECORD.PERSONAL__VENDR_DATA);
                
If &RSLT = 0 Then 
/* no rows fetched */ 
Else 
   /* do processing */ 
End-If;

See Also

Business Interlink class: BulkExecute method.

FetchIntoRowset

Syntax

FetchIntoRowset(&Rowset)

Description

The FetchIntoRowset method copies the data from the output buffer into the specified rowset, copying like-named fields. This method assumes that the names of the fields in the rowset match the names of the outputs defined in the Business Interlink definition, and that the structure is the same.

Note. Before you use this method, you should flush the rowset used for output and remove any residual data that might exist in it.

Use this method only if you have a hierarchical data structure and you want to preserve the hierarchy. Otherwise, use BulkExecute or FetchIntoRecord.

Parameters

Returns

Number of rows fetched if one or more non-empty rows are returned.

If an empty row is returned, that is, every if field is empty except the return_status and return_status_msg fields, this method returns one of the following error messages:

Example

The example uses the rowset on level one from the EMPLOYEE_CHECKLIST page. A PeopleCode program running in a field on level zero in that page can access the level one (child rowset).

EMPLOYEE_CHECKLIST Page order

EMPL_CHECKLIST is the primary database record for the level one scrollbar on the EMPLOYEE_CHECKLIST page. The following PeopleCode accesses the level one rowset using EMPL_CHECKLIST. The Business Interlink object name is QE_BI_EMPL_CHECKLIST. This Business Interlink object uses the level one rowset as its input and its output.

The InputRowset method uses this rowset as input for QE_BI_EMPL_CHECKLIST. Then a blank duplicate of the rowset is created with CreateRowset, and then the output of QE_BI_EMPL_CHECKLIST is fetched into the blank rowset with FetchIntoRowset.

&MYROWSET = GetRowset(SCROLL.EMPL_CHECKLIST); 
&ROWCOUNT = &QE_BI_EMPL_CHECKLIST.InputRowset(&MYROWSET);
&RSLT = &QE_BI_EMPL_CHECKLIST.Execute();
/* do some error processing */
&WorkRowset = CreateRowset(&MYROWSET);
&ROWCOUNT = &QE_BI_EMPL_CHECKLIST.FetchIntoRowset(&WorkRowset); 
 
If &ROWCOUNT = 0 Then 
/* do some error processing */ 
Else 
   /* Process the rowset from QE_BI_EMPL_CHECKLIST. Check it for errors. */ 
   For &I = 1 to &WorkRowset.RowCount 
      For &K = 1 to &WorkRowset(&I).RecordCount 
         &REC = &WorkRowset(&I).GetRecord(&K); 
         &REC.ExecuteEdits(); 
         For &M = 1 to &REC.FieldCount 
            If &REC.GetField(&M).EditError Then  
            /* there are errors */ 
            /* do other processing */ 
            End-If; 
         End-For; 
      End-For; 
   End-for; 
End-if;

See Also

Business Interlink class: InputRowset method.

Accessing the Data Buffer

FetchNextRow

Syntax

FetchNextRow(outputname, value)

where outputname and value are in matched pairs, in the form:

outputname1, value1 [, outputname2, value2] .  .  .

Description

After the Business Interlink object executes the method Execute, the FetchNextRow method can be used to retrieve a row of output and store the values of the output name (outputname) to PeopleCode variables or record fields (value). These must be entered in matched pairs, that is, every output name must be followed by its matching value.

Note. The output name, not the output path of the interface definition is used for this method.

There must be an outputname for every output name defined in the interface definition used to instantiate the Business Interlink object.

If you specify a record field that is not part of the record the PeopleCode program is associated with, you must use recname.fieldname for that value.

You can specify default values for every output name in the interface definition (created in Application Designer.) These values are used if you create a PeopleCode "template" by dragging the interface definition from the Project window in Application Designer to an open PeopleCode Editor window.

Parameters

Returns

A Boolean value: True if the row of output parameters was fetched. Otherwise, it returns False.

Example

In the following example, the Business Interlink object name is SRA_ALL_1, and the output names, such as costs, are being bound to record fields, such as STR_COST.

&RSLT = &SRA_ALL_1.FetchNextRow("costs", &STR_COST,  
          "unit_costs", &STR_UNIT_COST,  
          "customer_ship_dates", &STR_SHIP_DATE,  
          "quantities", &STR_QUANTITY,  
          "so_numbers", &STR_SO_NUM,  
          "so_names", &STR_SO_NAME,  
          "line_numbers", &STR_LINE_NUM,  
          "ship_sets", &STR_SHIP_SET,  
          "customer_receipt_dates", &STR_RECPT_DATE); 

See Also

Business Interlink class: Execute method.

GetInterlink

GetCount

Syntax

GetCount(docname)

Description

The GetCount method returns the number of documents within a document list contained within an output structure for a Business Interlink object.

Parameters

Returns

The number of documents in the list.

Example

In the following example, the output structure for Calculate Cost, or the root level document, is accessed with the GetOutputDocs method. The Calculate Cost output parameter output_param2_List is a document, so the GetDoc method gets it from the output structure. Because output_param2_List is a document list, GetCount gets the number of documents in the list.

Local Interlink &QE_COST; 
Local number &count; 
Local BIDocs &CalcCostOut; 
Local BIDocs &OutlistDoc; 
Local number &ret; 
 
&QE_COST = GetInterlink(Interlink.QE_COST_EX); 
/* Get inputs, execute. (code not shown) */
 
&CalcCostOut = &QE_COST.GetOutputDocs(""); 
 
/* Call GetValue for output_param1, call GetDoc, GetValue for 
Service_Rate (code not shown) */ 
 
&OutlistDoc = &CalcCostOut.GetDoc("output_param2_List"); 
​&count = &CalcCostOut.GetCount("output_param2_List"); 
​ 
&I = 0; 
While (&I < &count) 
   &ret = &OutlistDoc.GetValue("output_member1", &VALUE1); 
   &ret = &OutlistDoc.GetValue("output_member2", &VALUE2); 
   If &ret = 0 Then 
      /* Process output values */ 
      &I = &I + 1; 
      &retoutput = &OutlistDoc.GetNextDoc(); 
   End-If; 
End-While;

The following shows the output structure for this example. It contains three output parameters: output_param1, Service_Rate, and output_param2_List.

Example output structure

GetDoc

Syntax

GetDoc(docname)

Description

The GetDoc method gets a document from an output structure. The document is an output parameter for a Business Interlink object that is not of simple type (such as integer or string). You must get the document from the output structure before you can get values from its members with GetValue.

You can call GetDoc using dot notation, to access documents that are "nested" within other documents. For example, the following accesses a document nested three levels deep:

&Docs3 = &CalcCostOut.GetDoc("Doc1.Doc2.Doc3");

Parameters

Returns

A reference to the document received from the output structure.

Example

In the following example, the Output structure for Calculate Cost(Domestic), or the root level document, is created with the GetOutputDocs method. (To create, or get, more Output structures, call GetNextDoc.) The Calculate Cost output parameter Service_Rate is a document, so the GetDoc method gets it from the Output structure.

Local Interlink &QE_COST; 
Local number &count; 
Local BIDocs &CalcCostOut; 
Local BIDocs &ServiceRateDoc; 
Local number &ret; 
 
&QE_COST = GetInterlink(Interlink.QE_COST_EX); 
// Get inputs, execute. (code not shown) 
 
&CalcCostOut = &QE_COST.GetOutputDocs(""); 
&ret = &CalcCostOut.GetValue("output_param1",&VALUE); 
​&ServiceRateDoc = &CalcCostOut.GetDoc("Service_Rate"); 
​&ret = &ServiceRateDoc.GetValue("Service_Type", &SERVICE_TYPE); 
&ret = &ServiceRateDoc.GetValue("Rate", &RATE); 
/* Call GetDoc, GetValue, GetNextDoc for output_param2_List (code not shown) */ 
If &ret = 0 Then 
   /* Process output values */ 
End-If; 
 

The following illustration shows the Output structure for this example. It contains three output parameters: output_param1, Service_Rate, and output_param2_List. This is a version of the Federal Express plug-in that was modified for this example (output_param1 and output_param2_List were added).

Example output structure

In the following example, GetDoc is used to access a document that is nested more deeply. To access a document that is more deeply nested, you can either call GetDoc for each nesting, or you can call GetDoc once using the nesting feature.

Calling GetDoc with the nesting feature:

Local Interlink &QE_4GETDOC; 
Local BIDocs &CalcCostOut, &Docs3; 
Local number &ret; 
 
&QE_4GETDOC = GetInterlink(Interlink.QE_4GETDOC_EX); 
// Get inputs, execute. (code not shown) 
 
&CalcCostOut = &QE_4GETDOC.GetOutputDocs(""); 
​&Docs3 = &CalcCostOut.GetDoc("Doc1.Doc2.Doc3"); 
​&ret = &Docs3.GetValue("output_member3", &VALUE); 
 

Calling GetDoc without the nesting feature:

Local Interlink &QE_4GETDOC; 
Local BIDocs &CalcCostOut, &Docs1, &Docs2, &Docs3; 
Local number &ret; 
 
&QE_4GETDOC = GetInterlink(Interlink.QE_4GETDOC_EX); 
// Get inputs, execute. (code not shown) 
 
&CalcCostOut = &QE_4GETDOC.GetOutputDocs(""); 
​&Docs1 = &CalcCostOut.GetDoc("Doc1"); 
&Docs2 = &Docs1.GetDoc("Doc2"); 
&Docs3 = &Docs2.GetDoc("Doc3"); 
​&ret = &Docs3.GetValue("output_member3", &VALUE);

Example output structure with nested documents

GetFieldCount

Syntax

GetFieldCount()

Description

Use the GetFieldCount method to support dynamic output. It returns the number of columns in the output buffer, which is the same as the number of outputs in each row of the output buffer.

Note. This method can also be used with hierarchical doc data.

Parameters

None.

Returns

The number of columns in the output buffer, which is the same as the number of outputs in each row of the output buffer.

Example

The following example moves to the first column, first field of the output buffer. The Repeat loop goes through every row in the output buffer. The For loop processes every field in every row.

If (&MYBI.MoveFirst()) Then 
   Repeat 
      For &I = 1 to &MYBI.GetFieldCount 
         ​&TYPE = &MYBI.GetFieldType(&I); 
         Evaluate &TYPE 
         Where = 1 
            /* do processing */ 
         .  .  . 
         End-Evaluate; 
      End-For; 
   Until Not (&MYBI.MoveNext()); 
Else 
   /* do error processing - output buffer not returned */ 
End-If;

See Also

Business Interlink class: GetFieldType method, GetFieldValue method, MoveFirst method, MoveNext method, Using Hierarchical Data (BIDocs) .

GetFieldType

Syntax

GetFieldType(index)

Description

Use the GetFieldType method to support dynamic output. It returns the type of field specified by index. You can use this method only after you have used the MoveFirst method: otherwise the system doesn’t know where to start.

Note. This method can also be used with hierarchical doc data.

Parameters

Returns

A number indicating the type of the field. The values are:

Example

In the following example, the Business Interlink object name is &MYBI. The example uses MoveFirst to move to the first row of the output buffer, and to the first column, or first field, in that row. The Repeat loop uses MoveNext to go through every row in the output buffer. The For loop processes every field in every row, using the GetFieldCount method to get the number of fields, or outputs, in the row. Within the For loop, GetFieldType gets the type of the field data (string, integer, and so on.)

/* Add inputs to the Business Interlink object, then call Execute 
to execute the Business Interlink object. 
You are then ready to get the outputs using the following code. */ 
 
If (&MYBI.MoveFirst()) Then  
   Repeat 
      For &I = 1 to &MYBI.GetFieldCount 
         &TYPE = &MYBI.GetFieldType(&I); 
         Evaluate &TYPE 
         Where = 1 
            &STRING_VARIABLE = &MYBI.GetFieldValue(&I); 
         /* test for and process other field types */ 
         End-Evaluate; 
      End-For; 
   Until Not(&MYBI.MoveNext()); 
Else 
   /* Process error - no output buffer */ 
End-If;

See Also

Business Interlink class: GetFieldCount method, GetFieldValue method, MoveFirst method, MoveNext method.

GetFieldValue

Syntax

GetFieldValue(index)

Description

Use the GetFieldValue method to support dynamic output. It returns the value of the field specified by index. You can use this method only after you have used the MoveFirst method: otherwise the system doesn’t know where to start.

Note. This method can also be used with hierarchical doc data.

Parameters

Returns

A string containing the value of the field.

Example

In the following example, the Business Interlink object name is &MYBI. The example uses MoveFirst to move to the first row of the output buffer, and to the first column, or first field, in that row. The Repeat loop uses MoveNext to go through every row in the output buffer. The For loop processes every field in every row, using the GetFieldCount method to get the number of fields, or outputs, in the row. Within the For loop, GetFieldValue gets the value of the field data.

/* Add inputs to the Business Interlink object, then call Execute to execute 
the Business Interlink object. You are then ready to get the 
outputs using the following code. */ 
 
If (&MYBI.MoveFirst()) Then  
   Repeat 
      For &I = 1 to &MYBI.GetFieldCount 
         &TYPE = &MYBI.GetFieldType(&I); 
         Evaluate &TYPE 
         Where = 1 
            &STRING_VARIABLE = &MYBI.GetFieldValue(&I); 
         /* test for and process other field types */ 
         End-Evaluate; 
      End-For; 
   Until Not(&MYBI.MoveNext()); 
Else 
   /* Process error - no output buffer */ 
End-If;

See Also

Business Interlink class: GetFieldCount method, GetFieldType method, MoveFirst method, MoveNext method.

GetInputDocs

Syntax

GetInputDocs("")

Description

The GetInputDocs method gets the top input document at the root level for a Business Interlink object. This is a hierarchical structure that contains the values for the inputs for this Business Interlink object. The methods that you use to put the input values into this document are the hierarchical data methods.

Parameters

A null string.

Returns

An input document. This is the document at the top of the root level of the input document for a Business Interlink object.

Example

Local Interlink &QE_COST; 
Local BIDocs &CalcCostOut, &CalcCostIn; 
 
&QE_COST = GetInterlink(Interlink.QE_COST_EX); 
&CalcCostIn = &QE_COST.GetInputDocs(""); 
 
/* You can now insert the input values and execute the BI object */

See Also

Using Hierarchical Data (BIDocs).

GetNextDoc

Syntax

GetNextDoc()

Description

The GetNextDoc method gets a document from one of the following levels:

• The root level of the Output structure for a Business Interlink object. This level was accessed with the GetOutputDocs method.

• When a document within the Output structure is a list, GetNextDoc gets another document from the list. If you use GetNextDoc on a document that is not a list, GetNextDoc fails and returns an error.

Parameters

None.

Returns

The following are the valid returns:

Example

In this example, the Output structure for Calculate Cost, or the root level document, is accessed with the GetOutputDocs method. The GetNextDoc method gets another Output structure, assuming that there is more than one of them. The Calculate Cost output parameter output_param2_List is a document, so the GetDoc method gets it to the Output structure. output_param2_List is also a document list, so GetNextDoc method gets the next output_param2_List document.

Local Interlink &QE_COST; 
Local number &count1, &count2; 
Local BIDocs &CalcCostOut; 
Local BIDocs &OutlistDoc; 
Local number &ret1, &ret2; 
 
&QE_COST = GetInterlink(Interlink.QE_COST_EX); 
// Get inputs, execute. (code not shown) 
 
&CalcCostOut = &QE_COST.GetOutputDocs(""); 
 
&ret1 = 0; 
While (&ret1) 
   &ret1 = &CalcCostOut.GetValue("output_param1",&VALUE); 
   &ServiceRateDoc = &CalcCostOut.GetDoc("Service_Rate"); 
   &ret1 = &ServiceRateDoc.GetValue("Service_Type", &SERVICE_TYPE); 
   &ret1 = &ServiceRateDoc.GetValue("Rate", &RATE); 
   /* Process output values */ 
 
   &OutlistDoc = &CalcCostOut.GetDoc("output_param2_List"); 
   &count2 = &CalcCostOut.GetCount("output_param2_List"); 
   While (&I < &count2) 
      &ret2 = &OutlistDoc.GetValue("output_member1", &VALUE1); 
      &ret2 = &OutlistDoc.GetValue("output_member2", &VALUE2); 
      If &ret2 = 0 Then 
         /* Process output values */ 
         &I = &I + 1; 
         ​&ret2 = &OutlistDoc.GetNextDoc(); 
      ​End-If; 
   ​&ret1 = &CalcCostOut.GetNextDoc(); 
​End-While; 
 

The following shows the Output structure for this example. It contains three output parameters: output_param1, Service_Rate, and output_param2_List.

Example output structure

GetOutputDocs

Syntax

GetOutputDocs("")

Description

The GetOutputDocs method gets the top output document at the root level for a Business Interlink object. This is a hierarchical structure that contains the values for the outputs for this Business Interlink object. The methods that you use to get output values from this document are the hierarchical data methods.

Parameters

A null string.

Returns

An output document. This is the document at the top of the root level of the output document for a Business Interlink object.

Example

Local Interlink &QE_COST; 
Local BIDocs &CalcCostIn, &CalcCostOut; 
 
&QE_COST = GetInterlink(Interlink.QE_COST_EX); 
 
&CalcCostOut = &QE_COST.GetOutputDocs(""); 
 
/* You can now execute the Business Interlink object and get the output values. */

See Also

Using Hierarchical Data (BIDocs).

GetPreviousDoc

Syntax

GetPreviousDoc()

Description

The GetPreviousDoc method gets the previous document from either the root level of the Output structure for a Business Interlink object, or from a document within the Output structure. When these documents are in a list, GetPreviousDoc gets the previous document in the list. You must get the document before you can get its values with GetValue.

Parameters

None.

Returns

The following are the possible returns:

Example

In this example, the Output structure for Calculate Cost, or the root level document, is accessed with the GetOutputDocs method. It contains one output parameter, output_param2_List, which is also a list. The GetCount and MoveToDoc methods point to the last output_param2_List document in the list. The GetPreviousDoc method is used in a loop to cycle through the output_param2_List list, starting with the last and ending with the first in the list, and get each output_param2_List document and its values.

Local Interlink &QE_COST; 
Local number &count; 
Local BIDocs &CalcCostOut; 
Local BIDocs &OutlistDoc; 
Local number &ret; 
 
&QE_COST = GetInterlink(Interlink.QE_COST_EX); 
// Get inputs, execute. (code not shown) 
 
&CalcCostOut = &QE_COST.GetOutputDocs(""); 
 
/* Call GetValue for output_param1, call GetDoc, GetValue for Service_Rate (code⇒
 not shown) */ 
 
&OutlistDoc = &CalcCostOut.GetDoc("output_param2_List"); 
&count = &CalcCostOut.GetCount("output_param2_List"); 
&ret = &OutlistDoc.MoveToDoc(&count-1); 
&I = &count; 
While (&I > 0) 
   &ret = &OutlistDoc.GetValue("output_member1", &VALUE1); 
   &ret = &OutlistDoc.GetValue("output_member2", &VALUE2); 
   If &ret = 0 Then 
      /* Process output values */ 
      &I = &I - 1; 
      ​&retoutput = &OutlistDoc.GetPreviousDoc(""); 
   ​End-If; 
End-While; 
 

The following shows the Output structure for this example. It contains three output parameters: output_param1, Service_Rate, and output_param2_List.

Example output structure

GetStatus

Syntax

GetStatus()

Description

The GetStatus method tests the BIDocs document. To find the status for any BIDocs method that does not return a status value, call GetStatus just after you call that BIDocs method.

Parameters

None.

Returns

The following are the possible returns:

GetValue

Syntax

GetValue(paramname, value)

Description

The GetValue method gets a value from an output parameter within a document of the Output structure for a Business Interlink object.

Parameters

Returns

The following are the possible return values:

Return Status for Integer

Example

In the following example, the Business Interlink object name is QE_COST.

In the following example, the Output structure for Calculate Cost, or the root level document, is created with the GetOutputDocs method. (If you wanted to create, or get, more Output structures, you would call GetNextDoc.) The Calculate Cost output parameter Service_Rate is a document, so the GetDoc method gets it from the Output structure. Then the GetValue method gets values from each of the Service_Rate document members.

Local Interlink &QE_COST; 
Local BIDocs &CalcCostOut; 
Local BIDocs &ServiceRateDoc; 
Local number &ret; 
 
&QE_COST = GetInterlink(Interlink.QE_COST_EX); 
 
// Get inputs, execute. (code not shown) 
 
&CalcCostOut = &QE_COST.GetOutputDocs(""); 
​&ret = &CalcCostOut.GetValue("output_param1",&PARAM1); 
​ 
&ServiceRateDoc = &CalcCostOut.GetDoc("Service_Rate"); 
​&ret = &ServiceRateDoc.GetValue("Service_Type", &SERVICE_TYPE); 
&ret = &ServiceRateDoc.GetValue("Rate", &RATE); 
​ 
/* Call GetDoc, GetValue, GetNextDoc for output_param2_List (code not shown) */ 
 

The following illustration shows the Output structure for this example. It contains three output parameters: output_param1, Service_Rate, and output_param2_List. This is a version of the Federal Express plug-in that was modified for this example (output_param1 and output_param2_List were added).

Example output structure

InputRowset

Syntax

InputRowset(&Rowset)

Description

The InputRowset method uses the data in the specified rowset to populate the input buffer, copying like-named fields in the appropriate structure. This method assumes that the names of the fields in the rowset match the names of the inputs defined in the Business Interlink definition, and that the structure of both rowsets are the same.

Use this method only if you have a hierarchical data structure and you want to preserve the hierarchy. Otherwise, use BulkExecute or AddInputRow.

Parameters

Returns

An optional value: the number of rows inserted into the output buffer.

Example

The example uses the rowset on level one from the EMPLOYEE_CHECKLIST page. A PeopleCode program running in a field on level zero in that panel can access the child rowset (level one), shown below from Scroll Bar 1 to Scroll Bar 2.

EMPLOYEE_CHECKLIST Page structure

EMPL_CHECKLIST is the primary database record for the level one scrollbar on the EMPLOYEE_CHECKLIST page. The following PeopleCode access the level one rowset using EMPL_CHECKLIST. The Business Interlink object name is QE_BI_EMPL_CHECKLIST. This Business Interlink object uses the level one rowset as its input and its output.

The InputRowset method uses this rowset as input for QE_BI_EMPL_CHECKLIST. Then a blank duplicate of the rowset is created with CreateRowset, and then the output of QE_BI_EMPL_CHECKLIST is fetched into the blank rowset with FetchIntoRowset.

&MYROWSET = GetRowset(SCROLL.EMPL_CHECKLIST); 
&ROWCOUNT = &QE_BI_EMPL_CHECKLIST.InputRowset(&MYROWSET);
&RSLT = &QE_BI_EMPL_CHECKLIST.Execute();
/* do some error processing */
&WorkRowset = CreateRowset(&MYROWSET);
&ROWCOUNT = &QE_BI_EMPL_CHECKLIST.FetchIntoRowset(&WorkRowset); 
 
If &ROWCOUNT = 0 Then 
/* do some error processing */ 
Else 
   /* Process the rowset from QE_BI_EMPL_CHECKLIST. Check it for errors. */ 
   For &I = 1 to &WorkRowset.RowCount 
      For &K = 1 to &WorkRowset(&I).RecordCount 
         &REC = &WorkRowset(&I).GetRecord(&K); 
         &REC.ExecuteEdits(); 
         For &M = 1 to &REC.FieldCount 
            If &REC.GetField(&M).EditError Then  
            /* there are errors */ 
            /* do other processing */ 
            End-If; 
         End-For; 
      End-For; 
   End-for; 
End-if;

See Also

Business Interlink class: FetchIntoRowset method.

Accessing the Data Buffer

MoveFirst

Syntax

MoveFirst()

Description

Use the MoveFirst method to support dynamic output. This method moves your cursor to the first column, first row of the output buffer. You must use this method before you try to access any data.

Parameters

None.

Returns

Boolean: True if successfully positioned cursor at the first column, first row of the output buffer, False otherwise.

Example

In the following example, the Business Interlink object name is &MYBI. The example uses MoveFirst to move to the first row of the output buffer, and to the first column, or first field, in that row. The Repeat loop uses MoveNext to go through every row in the output buffer. The For loop processes every field in every row, using the GetFieldCount method to get the number of fields, or outputs, in the row.

/* Add inputs to the Business Interlink object, then call Execute to execute the⇒
 Business Interlink object. You are then ready to get the outputs using the⇒
 following code. */ 
 
If (&MYBI.MoveFirst()) Then  
   Repeat 
      For &I = 1 to &MYBI.GetFieldCount 
         &TYPE = &MYBI.GetFieldType(&I); 
         Evaluate &TYPE 
         Where = 1 
            &STRING_VARIABLE = &MYBI.GetFieldValue(&I); 
         /* test for and process other field types */ 
         End-Evaluate; 
      End-For; 
   Until Not(&MYBI.MoveNext()); 
Else 
   /* Process error - no output buffer */ 
End-If;

See Also

Business Interlink class: GetFieldCount method, GetFieldType method, GetFieldValue method, MoveNext method.

MoveNext

Syntax

MoveNext()

Description

Use the MoveNext method to support dynamic output. This method moves your cursor to the first column of the next row of the output buffer. You can use this method only after you have used the MoveFirst method: otherwise, the system doesn’t know where to start.

Parameters

None.

Returns

Boolean: True if successfully positioned cursor at the next row of the output buffer, False otherwise.

Example

In the following example, the Business Interlink object name is &MYBI. The example uses MoveFirst to move to the first row of the output buffer, and to the first column, or first field, in that row. The Repeat loop uses MoveNext to go through every row in the output buffer. The For loop processes every field in every row, using the GetFieldCount method to get the number of fields, or outputs, in the row.

/* Add inputs to the Business Interlink object, then call Execute to execute the⇒
 Business Interlink object. You are then ready to get the outputs using the⇒
 following code. */ 
 
If (&MYBI.MoveFirst()) Then  
   Repeat 
      For &I = 1 to &MYBI.GetFieldCount 
         &TYPE = &MYBI.GetFieldType(&I); 
         Evaluate &TYPE 
         Where = 1 
            &STRING_VARIABLE = &MYBI.GetFieldValue(&I); 
         /* test for and process other field types */ 
         End-Evaluate; 
      End-For; 
   Until Not(&MYBI.MoveNext()); 
Else 
   /* Process error - no output buffer */ 
End-If;

See Also

Business Interlink class: GetFieldCount method, GetFieldType method, GetFieldValue method, MoveFirst method.

MoveToDoc

Syntax

MoveToDoc(list_number)

Description

Within a list of documents in the Output structure, the MoveToDoc method moves to the documents given by the parameter list_number. After using MoveToDoc, the GetValue method gets the values of the document that is in the list_number+1 location in the list.

Parameters

Returns

This method returns an integer. The values are:

Example

The following example gets the values of the last document in the output_param2_List list. It uses GetCount to get the number of documents in the list, and then uses MoveToDoc to move to the last document in the list.

Local Interlink &QE_COST; 
Local number &count; 
Local BIDocs &CalcCostOut; 
Local BIDocs &OutlistDoc; 
Local number &ret; 
 
&QE_COST = GetInterlink(Interlink.QE_COST_EX); 
// Get inputs, execute. (code not shown) 
 
&CalcCostOut = &QE_COST.GetOutputDocs(""); 
&OutlistDoc = &CalcCostOut.GetDoc("output_param2_List"); 
&count = &CalcCostOut.GetCount("output_param2_List"); 
​&ret = &OutlistDoc.MoveToDoc(&count-1); 
​&ret = &OutlistDoc.GetValue("output_member1", &VALUE1); 
&ret = &OutlistDoc.GetValue("output_member2", &VALUE2); 
 

The following illustration shows the Output structure for this example. It contains three output parameters: output_param1, Service_Rate, and output_param2_List. This is a version of the Federal Express plug-in that was modified for this example (output_param1 and output_param2_List were added).

Example output structure

ResetCursor

Syntax

ResetCursor()

Description

The ResetCursor method resets the cursor in the Output structure for a Business Interlink object to the top. After you call this method, the next time you call GetValue, you get an output value from the first document of the Output structures for a Business Interlink object.

Parameters

None.

Returns

None.

Example

The following code uses ResetCursor to reset the cursor in the Output structure to the top.

Local Interlink &QE_COST; 
Local BIDocs &CalcCostOut; 
 
&QE_COST = GetInterlink(Interlink.QE_COST_EX); 
 
// Get inputs, execute. (code not shown) 
 
&CalcCostOut = &QE_COST.GetOutputDocs(""); 
 
// Perform actions on the output documents (code not shown) 
 
​&CalcCostOut.ResetCursor();

Incoming Business Interlink Methods

This section describes the PeopleCode methods you use with Incoming Business Interlinks.

AddAttribute

Syntax

AddAttribute(attributename, attributevalue)

Description

The AddAttribute method adds an attribute name and its value to an XML element referenced by a BiDocs object.

Parameters

Returns

Number. The return status. NoError, or 0, means the method succeeded.

Example

Here is a set of XML response code.

<?xml version="1.0"?> 
   <postreqresponse> 
      <candidate> 
         <user> 
            ​<location scenery="great" density="low" blank="eh?"> 
            ​</location> 
         </user> 
      </candidate> 
   </postreqresponse>

Here is the PeopleCode that builds it.

Local BIDocs &rootDoc, &postreqresponse; 
Local BIDocs &candidates, &location, &user; 
Local number &ret; 
 
&rootDoc = GetBiDoc(""); 
&ret = &rootDoc.AddProcessInstruction("<?xml version=""1.0""?>"); 
&postreqresponse = &rootDoc.CreateElement("postreqresponse"); 
&candidates = &postreqresponse.CreateElement("candidates"); 
&user = &candidates.CreateElement("user"); 
&location = &user.CreateElement("location"); 
​&ret = &location.AddAttribute("scenery", "great"); 
&ret = &location.AddAttribute("density", "low"); 
&ret = &location.AddAttribute("blank", "eh?");
​

See Also

Business Interlink class: GetStatus method.

AddComment

Syntax

AddComment(comment)

Description

The AddComment method adds an XML comment after the beginning tag of an XML element referenced by a BiDoc object.

Parameters

Returns

Number. The return status. NoError, or 0, means the method succeeded.

Example

Here is a set of XML response code.

<?xml version="1.0"?> 
   <postreqresponse>    
      <error> 
         ​<!--this is a comment line--> 
         ​<errorcode>1</errorcode> 
         <errortext></errortext> 
      </error> 
   </postreqresponse>

Here is the PeopleCode that builds it.

Local BIDocs &rootDoc, &postreqresponse, &error, &errorcode, &errortext; 
Local string &blob; 
Local number &ret; 
&rootDoc = GetBiDoc(""); 
 
/* add a processing instruction*/ 
&ret = &rootDoc.AddProcessInstruction("<?xml version=""1.0""?>"); 
/* create an element and add text*/ 
&postreqresponse = &rootDoc.CreateElement("postreqresponse"); 
&error = &postreqresponse.CreateElement("error"); 
​&ret = &error.AddComment("this is a comment line"); 
​&errorcode = &error.CreateElement("errorcode"); 
&ret = &errorcode.AddText("1"); 
&errortext = &error.CreateElement("errortext");

See Also

Business Interlink class: GetStatus method.

AddProcessInstruction

Syntax

AddProcessInstruction(instruction)

Description

The AddProcessInstruction method adds an XML processing instruction to a BiDocs object. Use this method at the root level of the BiDocs object for Incoming Business Interlinks before you add anything else to the BiDocs object.

Parameters

Returns

Number. The return status. NoError, or 0, means the method succeeded.

Example

Here is a set of XML response code.

<?xml version="1.0"?> 
   ​<postreqresponse>    
      <error> 
         <!--this is a comment line--> 
         <errorcode>1</errorcode> 
         <errortext></errortext> 
      </error> 
   </postreqresponse>

Here is the PeopleCode that builds it.

Local BIDocs &rootDoc, &postreqresponse; 
Local BIDocs &error, &errorcode, &errortext; 
Local number &ret; 
&rootDoc = GetBiDoc(""); 
 
/* add a processing instruction*/ 
​&ret = &rootDoc.AddProcessInstruction("<?xml version=""1.0""?>"); 
​/* create an element and add text*/ 
&postreqresponse = &rootDoc.CreateElement("postreqresponse"); 
&error = &postreqresponse.CreateElement("error"); 
&ret = &error.AddComment("this is a comment line"); 
&errorcode = &error.CreateElement("errorcode"); 
&ret = &errorcode.AddText("1"); 
&errortext = &error.CreateElement("errortext");

See Also

Business Interlink class: GetStatus method.

AddText

Syntax

AddText(text)

Description

The AddText method adds text to an XML element referenced by a BiDocs object.

Parameters

Returns

Number. The return status. NoError, or 0, means the method succeeded.

Example

Here is a set of XML response code.

<?xml version="1.0"?> 
   <postreqresponse> 
      <error> 
         <!--this is a comment line--> 
         ​<errorcode>1</errorcode> 
         ​<errortext></errortext> 
      </error> 
   </postreqresponse>

Here is the PeopleCode that builds it.

Local BIDocs &rootDoc, &postreqresponse; 
Local BIDocs &error, &errorcode, &errortext; 
Local number &ret; 
&rootDoc = GetBiDoc(""); 
 
/* add a processing instruction*/ 
&ret = &rootDoc.AddProcessInstruction("<?xml version=""1.0""?>"); 
/* create an element and add text*/ 
&postreqresponse = &rootDoc.CreateElement("postreqresponse"); 
&error = &postreqresponse.CreateElement("error"); 
&ret = &error.AddComment("this is a comment line"); 
&errorcode = &error.CreateElement("errorcode"); 
​&ret = &errorcode.AddText("1"); 
​&errortext = &error.CreateElement("errortext");

See Also

Business Interlink class: GetStatus method.

CreateElement

Syntax

CreateElement(elementname)

Description

The CreateElement method creates an XML element with the given name within a BiDoc object.

Parameters

Returns

BiDocs. The reference to the created element.

Example

Here is a set of XML response code.

<?xml version="1.0"?> 
   <postreqresponse> 
      <error> 
         <errorcode>1</errorcode> 
         <errortext></errortext> 
      </error> 
   </postreqresponse>

Here is the PeopleCode that builds it.

Local BIDocs &rootDoc, &postreqresponse; 
Local BIDocs &error, &errorcode, &errortext; 
Local number &ret; 
 
&rootDoc = GetBiDoc(""); 
 
/* add a processing instruction*/ 
&ret = &rootDoc.AddProcessInstruction("<?xml version=""1.0""?>"); 
/* create an element and add text*/ 
​&postreqresponse = &rootDoc.CreateElement("postreqresponse"); 
&error = &postreqresponse.CreateElement("error"); 
&errorcode = &error.CreateElement("errorcode"); 
​&ret = &errorcode.AddText("1"); 
​&errortext = &error.CreateElement("errortext");

GenXMLString

Syntax

GenXMLString()

Description

The GenXMLString method creates an XML string from a BiDocs object. The BiDocs object must contain the shape and data needed for an XML string. This is part of the Incoming Business Interlink functionality, which enables PeopleCode to receive an XML request and return an XML response.

Parameters

None.

Returns

String. The XML string containing the shape and data of the BiDocs object. For example, you can use this method to create an XML string containing an XML response.

Example

The following example takes a BiDocs structure that contains an XML response and puts that into a text string. After this is done, the %Response.Write function can send this as an XML response.

Local BIDocs &rootDoc; 
Local string &xmlString; 
 
/* Create a BiDoc structure containing the data and shape of your XML response ⇒
(code not shown) */ 
 
/* Generate the XML string containing the data and shape of your XML response from⇒
 the BiDoc structure */ 
​&xmlString = &rootDoc.GenXMLString(); 
​%Response.Write(&xmlString);

GetAttributeName

Syntax

GetAttributeName(attributenumber)

Description

The GetAttributeName method gets the name of an attribute within an XML element referenced by a BiDocs object.

Parameters

Returns

String. The name of the attribute.

Example

Here is a set of XML request code.

<?xml version="1.0"?> 
   <postreq> 
      <email>joe_blow@peoplesoft.com</email> 
      <location scenery="great" ​density="low" blank="eh?"> 
         <city>San Rafael</city> 
         <state>CA</state> 
         <zip>94522</zip> 
         <country>US</country> 
      </location> 
   </postreq>

Here is the PeopleCode that gets the name of the second attribute in the location node. &attrName is density.

Local BIDocs &rootInDoc, postreqDoc, &locationDoc; 
Local string &blob, &attrName; 
&blob = %Request.GetContentBody(); 
    
&rootInDoc = GetBiDoc(&blob); 
&postreqDoc = &rootInDoc.GetNode("postreq"); 
&locationDoc = &postreqDoc.GetNode("location"); 
​&attrName = &locationDoc.GetAttributeName(2);

GetAttributeValue

Syntax

GetAttributeValue({attributename | attributenumber})

Description

The GetAttributeValue method gets the value of an attribute within an XML element referenced by a BiDocs object.

Parameters

Returns

String. The value of the attribute.

Example

Here is a set of XML request code.

<?xml version="1.0"?> 
   <postreq> 
      <email>joe_blow@peoplesoft.com</email> 
      <location scenery="great" ​density="low" blank="eh?"> 
         <city>San Rafael</city> 
         <state>CA</state> 
         <zip>94522</zip> 
         <country>US</country> 
      </location> 
   </postreq>

Here is the PeopleCode that gets the value of the second attribute in the location node. &attrValue is low.

Local BIDocs &rootInDoc, &postreqDoc, &locationDoc; 
Local string &blob, &attrValue; 
&blob = %Request.GetContentBody(); 
    
&rootInDoc = GetBiDoc(&blob); 
&postreqDoc = &rootInDoc.GetNode("postreq"); 
&locationDoc = &postreqDoc.GetNode("location"); 
​&attrValue = &locationDoc.GetAttributeValue(2);

GetNode

Syntax

GetNode({nodename | nodenumber})

Description

The GetNode method returns a BiDocs reference to a child XML node (element or comment). Use the GetNode method upon a BiDocs reference to an XML element to access the child nodes for that element.

Parameters

Returns

BiDocs. The returned XML element within a BiDocs object.

Example

Here is a set of XML request code.

<?xml version="1.0"?> 
   ​<postreq> 
      ​<email>joe_blow@peoplesoft.com</email> 
      ​<projtitle> 
         ​<projsubtitle>first_subtitle</projsubtitle> 
         <projsubtitle>second_subtitle</projsubtitle> 
         ​<projsubtitle>third_subtitle</projsubtitle> 
      ​</projtitle> 
   </postreq>

Here is the PeopleCode that gets the postreqDoc element and the projtitle element.

Local BIDocs &rootInDoc, &postreqDoc, &projtitleDoc; 
Local string &name, &blob; 
&blob = %Request.GetContentBody(); 
    
&rootInDoc = GetBiDoc(&blob); 
​&postreqDoc = &rootInDoc.GetNode("postreq"); 
&projtitleDoc = &postreqDoc.GetNode("projtitle");

Here is the PeopleCode that gets the postreqDoc element, the projtitle element, and the third projsubtitle element.

Local BIDocs &rootInDoc, &postreqDoc, &projtitleDoc, &projsubtitleDoc; 
Local string &name, &blob; 
&blob = %Request.GetContentBody(); 
    
&rootInDoc = GetBiDoc(&blob); 
​&postreqDoc = &rootInDoc.GetNode(1); 
&projtitleDoc = &postreqDoc.GetNode(2); 
&projsubtitleDoc = &projtitleDoc.GetNode(3);

To parse a list of elements like <projsubtitle>, where elements have the same name, you must call GetNode using an index number rather than the element name.

ParseXMLString

Syntax

ParseXMLString(XMLstring [, DTDValidation])

Description

The ParseXMLString methods fills an existing BiDocs object with the data and shape from an XML string. This is part of the Incoming Business Interlink functionality, which enables PeopleCode to receive an XML request and return an XML response.

Parameters

Returns

Number. The return status. NoError, or 0, means the method succeeded.

Example

The following example gets an XML request, creates an empty BiDoc, and then fills the BiDoc with the data and shape contained in the XML string. After this is done, the GetDoc method and the GetValue method can get the value of the skills XML element, which is contained within the postreq element in the XML request.

Local BIDocs &rootInDoc, &postreqDoc; 
Local string &blob; 
Local number &ret; 
 
&blob = %Request.GetContentBody(); 
/* process the incoming xml(request)- Create a BiDoc and fill with the request*/ 
&rootInDoc = GetBiDoc(""); 
​&ret = &rootInDoc.ParseXMLString(&blob); 
​&postreqDoc = &rootInDoc.GetDoc("postreq"); 
&ret = &postreqDoc.GetValue("skills", &skills);

See Also

Business Interlink class: GetStatus method.

Incoming Business Interlink Properties

This section describes the PeopleCode properties you use with Incoming Business Interlinks.

AttributeCount

Description

The AttributeCount property gets the number of attributes within an XML element referenced by a BiDocs object.

This property is read-only.

Example

Here is a set of XML request code.

<?xml version="1.0"?> 
   <postreq> 
      <email>joe_blow@peoplesoft.com</email> 
      ​<location scenery="great" density="low" blank="eh?"> 
         ​<city>San Rafael</city> 
         <state>CA</state> 
         <zip>94522</zip> 
         <country>US</country> 
      </location> 
   </postreq>

Here is the PeopleCode that gets the number of attributes in the location XML element. &count should be 3, for scenery, density, and blank.

Local BIDocs &rootInDoc, &postreqDoc, &locationDoc; 
Local string &blob; 
Local number &count; 
&blob = %Request.GetContentBody(); 
    
&rootInDoc = GetBiDoc(&blob); 
&postreqDoc = &rootInDoc.GetNode("postreq"); 
&locationDoc = &postreqDoc.GetNode("location"); 
​&count = &locationDoc.AttributeCount;

ChildNodeCount

Description

The ChildNodeCount property returns the number of XML child nodes within the element referenced by the BiDocs object. Child nodes include XML elements, comments, and processing instructions.

This property is read-only.

Example

Here is a set of XML request code.

<?xml version="1.0"?> 
   <postreq> 
      <email>joe_blow@peoplesoft.com</email> 
      <projtitle> 
         <!--this is a comment line--> 
         <projsubtitle>first_subtitle</projsubtitle> 
         <projsubtitle>second_subtitle</projsubtitle> 
         <projsubtitle>third_subtitle</projsubtitle> 
      </projtitle> 
   </postreq>

Here is the XML code that gets the number of nodes within <postreq> and <projtitle>. &count1 is 2, for <email> and <projtitle>, and &count2 is 4, for the three <projsubtitle> nodes and the comment node.

Local BIDocs &rootInDoc, &projtitleDoc; 
Local string &blob; 
Local number &count1, &count2; 
&blob = %Request.GetContentBody(); 
    
&rootInDoc = GetBiDoc(&blob); 
&postreqDoc = &rootInDoc.GetNode("postreq"); 
​&count1 = &postreqDoc.ChildNodeCount; 
​&projtitleDoc = &postreqDoc.GetNode("projtitle"); 
​&count2 = &projtitleDoc.ChildNodeCount;

NodeName

Description

The NodeName property gets the name of an XML element referenced by a BiDocs object. Use this to get the name of an XML element when you used GetNode with an index number to retrieve it (meaning that you did not have the name of the XML element when you used GetNode).

This property is read-only.

Example

Here is a set of XML request code.

<?xml version="1.0"?> 
   <postreq> 
      ​<email>joe_blow@peoplesoft.com</email> 
      ​<projtitle> 
         <projsubtitle>first_subtitle</projsubtitle> 
         <projsubtitle>second_subtitle</projsubtitle> 
         <projsubtitle>third_subtitle</projsubtitle> 
      </projtitle> 
   </postreq>

Here is the PeopleCode that gets the name of the <email> element, email.

Local BIDocs &rootInDoc, &postreqDoc, &emailDoc; 
Local string &emailName, &blob; 
&blob = %Request.GetContentBody(); 
    
&rootInDoc = GetBiDoc(&blob); 
&postreqDoc = &rootInDoc.GetNode(1); 
&emailDoc = &postreqDoc.GetNode(1); 
​&emailName = &emailDoc.NodeName;

NodeType

Description

The NodeType property returns the type of an XML tag within a BiDocs object as an integer. The values are:

This property is read-only.

Example

Here is a set of XML request code.

<?xml version="1.0"?> 
   <postreq> 
      ​<email>joe_blow@peoplesoft.com</email> 
      ​<!--this is a comment--> 
      ​<projtitle> 
         <projsubtitle>first_subtitle</projsubtitle> 
         <projsubtitle>second_subtitle</projsubtitle> 
         <projsubtitle>third_subtitle</projsubtitle> 
      </projtitle> 
   </postreq>

Here is the PeopleCode that gets types: &xmlprocType is 7 for processing instruction, postreqDoc is 1 for element, and commentType is 8 for comment.

Local BIDocs &rootInDoc, &postreqDoc, &commentDoc; 
Local number &xmlprocType, &postreqType, &commentDoc; 
Local string &blob; 
&blob = %Request.GetContentBody(); 
    
/* <?xml version="1.0"?> */ 
&rootInDoc = GetBiDoc(&blob); 
​&xmlprocType = &rootInDoc.NodeType; 
​ 
/* <postreq> */ 
&postreqDoc = &rootInDoc.GetNode(1); 
​&postreqType = &postreqDoc.NodeType; 
​ 
/* <!--this is a comment--> */ 
&commentDoc = &postreqDoc.GetNode(2); 
​&commentType = &commentDoc.NodeType;

NodeValue

Description

The NodeValue property returns the value of a node within an XML document as a string.

This property is read-only.

Example

Here is a set of XML request code.

<?xml version="1.0"?> 
   <postreq> 
      <email>joe_blow@peoplesoft.com</email> 
      <projtitle> 
         <projsubtitle>first_subtitle</projsubtitle> 
         <projsubtitle>second_subtitle</projsubtitle> 
         ​<projsubtitle>third_subtitle</projsubtitle> 
      ​</projtitle> 
   </postreq>

Here is the PeopleCode that gets the value of the third <projsubtitle> element, third_subtitle.

Local BIDocs &rootInDoc, &postreqDoc, &projtitleDoc, &projsubtitleDoc; 
Local string &name, &blob; 
&blob = %Request.GetContentBody(); 
    
&rootInDoc = GetBiDoc(&blob); 
&postreqDoc = &rootInDoc.GetNode(1); 
&projtitleDoc = &postreqDoc.GetNode(2); 
&projsubtitleDoc = &projtitleDoc.GetNode(3); 
​&projsubtitleName = &projsubtitleDoc.NodeValue;

Business Interlink Class Property

This section explains the StopAtError property.

StopAtError

Description

The StopAtError property specifies whether the execution of the PeopleCode program stops when there’s an error, or if the PeopleCode program tries to capture the errors.

This property takes a Boolean value: True to halt execution of your PeopleCode program at an error, False to continue executing. The default value is True.

This property is read-write.

Example

&QE_RP_SRAALL_1.StopAtError = False;

Configuration Parameters

There are two types of configuration parameters: the ones defined by the Interlink plug-in the Business Interlink definition is based on, and the ones that are standard, that is, defined for every Business Interlink object.

All configuration parameters must be set before you add any data to the input buffers.

In this section, we discuss the following parameters:

• Interlink plug-in configuration parameters

• URL configuration parameter

• BIDocValidate configuration parameter

Interlink Plug-in Configuration Parameters

The configuration parameters defined by the Interlink plug-in are accessed as if they were properties on the Business Interlink object. That is, in PeopleCode, you assign the value of a configuration parameter by using the Business Interlink object followed by a dot and the configuration parameter, in this format:

&MYINTERLINK.parameter ​= ​value;

You can also return the value of a configuration parameter:

&MYVALUE = &MYINTERLINK.parameter;

Each Business Interlink plug-in has its own set of configuration parameters. For example, the email project uses configuration parameters of SMTP_MAIL_SERVER, POP3MAIL_SERVER, LOGIN_NAME, PASSWORD, SENDERS_EMAIL_ADDRESS and REPLY_EMAIL_ADDRESS, while the Red Pepper transaction driver uses SERVER_NAME, RSERVER_HOST, RSERVER_PORT, and TIMEOUT.

You can specify default values for every configuration parameter in the Business Interlink definition (created in Application Designer.) These values are used if you create a PeopleCode "template" by dragging the Business Interlink definition from the Project window in Application Designer to an open PeopleCode editor window.

In the following example, the Interlink object name is QE_RP_SRAALL_1, and the driver is the Red Pepper driver:

&QE_RP_SRAALL_1.SERVER_NAME = "server"; 
&QE_RP_SRAALL_1.RSERVER_HOST = "pt-sun02.peoplesoft.com"; 
&QE_RP_SRAALL_1.RSERVER_PORT = "9884"; 
&QE_RP_SRAALL_1.TIMEOUT = 999; 
&QE_RP_SRAALL_1.URL = "HTTP://www.PeopleSoft.com"; 
&QE_RP_SRAALL_1.StopAtError = False;

URL Configuration Parameter

Specifies the location and name of the Business Interlink plug-in to be used to connect to the external system. This configuration parameter takes a string value.

If the plug-in is located on a web server, you have to specify the name of the web server.

If you specify a file, you can specify either a relative or an absolute path:

• If you specify an absolute path, you must specify the drive letter:

  &MYBI.URL = "File://D:\TEMP.MYDLL";

• If you specify a relative path, just use the file name:

  &MYBI.URL = "File://TEMP.MYDLL";

If you specify a relative path, the system firsts looks for the file in the Location directory (specified by the user when the Business Interlink was first created), then it looks in the directory where PeopleTools is installed, in the PSTOOLS/Interface Drivers directory.

BIDocValidate Configuration Parameter

Specifies whether the system should verify whether the hierarchical data object (BIDoc) exists before adding or getting values from it. This configuration parameter takes a Boolean value: True if the system should verify before accessing the object, False otherwise.

The default value is True.

If this configuration parameter is specified as True, and the object specified doesn’t exist, the PeopleCode program halts execution and an error is displayed.