Business Interlink Class Methods and Properties

This chapter provides an overview of the Business Interlink class methods and properties and discusses how to:

• Decide which methods to use.

• Use the state of a Business Interlink object.

• Declare a Business Interlink object.

• Scope a Business Interlink object.

• Use Business Interlink object methods.

• Use BIDocs hierarchical methods.

• Use the Interlink property.

• Use configuration parameters.

• Use the Business Interlink function.

Understanding the Business Interlink Object Methods

After you instantiate a Business Interlink object, you’ll use the Business Interlink object methods to:

• Add input values to the Business Interlink object.

• Execute the Business Interlink object.

• Get the output values from the Business Interlink object.

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

This section discusses how to:

• Instantiate a Business Interlink object.

• Execute a Business Interlink object.

• Support standard input and output with the BIDocs methods.

• Support batch input and output.

• Support rowsets.

• Use flat table input/output methods.

Instantiating a Business Interlink Object

You’ll need to write a PeopleCode program to instantiate the Business Interlink object from the Business Interlink definition, using the GetInterlink function.

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 Standard Input/Output with BIDocs Methods

A Business Interlink object can use hierarchical input and output data. The BIDocs methods are the methods that you will most often use to access this data. When you generate a PeopleCode template, these methods are used in that template.

You use BIDocs methods to add input to a Business Interlink object, then you call the Execute method, then you use BIDocs methods to get output from the Business Interlink object.

Note. To better illustrate the BIDocs methods, the examples were created from a modified version of a PScustomer plug-in. The input parameter input-param1 and output parameters output_param1 and output_param2_list were added to this example, and the Account_Info input parameter was modified to be a list, Account_Info_List.

See Supporting Standard Input/Output with BIDocs Methods.

You can think of the Input Doc and the Output Doc that stores the hierarchical data as a tree, with a root doc, node docs, and values.

Using Input Docs

The following shows an example of an Input Doc:

Example Input Doc

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 the following:

• 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 Input Docs with the following methods.

• GetInputDocs

• AddDoc

• AddValue

• AddNextDoc

The GetInputDocs method creates an Input Doc and returns a reference to its root doc. From the above example, it returns a reference to Calculate Cost(Domestic).

Use the AddDoc BIDocs method to return a reference to the node docs. From the above example, you would use AddDoc to access the From, To, Package_Info and Account_Info_List node docs. If any of these nodes contain nodes, you use AddDoc to access those as well.

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

Use the AddNextDoc BIDocs method to access the following:

• Use AddNextDoc to return a reference to the next root doc.

• If a node doc is a list, use AddNextDoc to return a reference to the next node doc in the list.

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 */
 
&Account_Doc = &Account_Doc.AddNextDoc();
&ret = &Account_Doc.AddValue("Account_Number", "CT-8002");
&ret = &Account_Doc.AddValue("Meter_Number", &METER);
&ret = &Account_Doc.AddValue("Service_Type", &MODE);

Using Output Docs

The following shows an example of an Output Doc:

Example Output Structure

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

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

• 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

• GetCount

• MoveToDoc

The GetOutputDocs method creates an Output Doc and returns a reference to its root doc. From the above example, it returns a reference to Calculate Cost(Domestic).

Use the GetDoc BIDocs method to return a reference to the node docs. From the above 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 BIDocs method to retrieve the values. From the above 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 and GetPreviousDoc BIDocs methods to access the following:

• Use GetNextDoc/GetPreviousDoc to return a reference to the next/previous root doc.

• If a node doc is a list, use GetNextDoc/GetPreviousDoc to return a reference to the next/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 either 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_Output = &QE_COST.GetOutputDocs("");
 
&Service_Rate_Doc = &Calc_Output.GetDoc("Service_Rate");
&ret = &Service_Rate_Doc.GetValue("Service_Type", &Type);
&ret = &Service_Rate_Doc.GetValue("Rate", &Rate);
 
&Out_Param_Doc = &Calc_Output.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);

Supporting Batch Input and Output

The methods discussed in this chapter, 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 will take a standard rowset object to populate the inputs for the Business Interlink object. You can use the FetchIntoRowset method to repopulate the rowset with output from the Business Interlink object.

Using the Flat Table Input/Output 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.

Using the State of a Business Interlink Object

Your PeopleSoft Business Interlink API should be stateless, that is, if you want to save information from one call of the Business Interlink object to the next, you will 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 will be preserved. Once you leave the event, any state associated with the Business Interlink object is lost.

You should only create 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 Business Interlink plug-in (via Execute) and fetch output data as many times as you need.

Declaring a Business Interlink Object

You should declare a Business Interlink object using the data type Interlink. 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 as 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 checkpointing them worthwhile.

Scoping 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 message subscription PeopleCode, Application Engine PeopleCode, record field PeopleCode, etc.

Using Business Interlink Object Methods

This section describes the PeopleCode methods you use to instantiate a Business Interlink object and execute that object. You can instantiate an instance of a named Business Interlink object using the PeopleCode GetInterlink function and then use methods (AddInputRow, Execute, FetchNextRow) on that instance to add data to the object, execute the object, and fetch output data from the object. If any of these methods fail due to error, either an error is displayed and execution of the PeopleCode stops, or the error is logged and processing continues, depending on the setting of the StopAtError property.

The BIDocs methods support hierarchical data. Use them if your input and output is in hierarchical form.

See Using BIDocs Hierarchical Methods.

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 to the specified input names (inputname) 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 inputname 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 the Application Designer.) These values will be used if you generate a PeopleCode template by dragging the interface definition from the Project window in the Application Designer to an open PeopleCode editor window.

See Generating the PeopleCode Template.

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 QE_COST, and the input names, such as OriginPostal_Code, are being bound to variables like &ORIGIN, or to literals, like 10 for quantity. The input names could also be bound to record fields.

Local Interlink &QE_COST;
&QE_COST = GetInterlink(Interlink.QE_COST_EX);
 
&QE_COST.AddInputRow("OriginCountry", "United States", 
   "OriginPostal_Code", &ORIGIN, 
   "Ship_Date", &SHIPDATE, 
   "DestCountry", "United States", 
   "DestPostal_Code", &DESTINATION, 
   "Weight", &WEIGHT, 
   "Weight_Type", "LBS", 
   "Declared_Value", &VALUE, 
   "Account_Number", &ACCOUNT, 
   "Meter_Number", &METER, 
   "Service_Type", &SVCTYPE);

See Also

Execute, FetchNextRow, AddDoc.

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 will result 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. It’s up to the programmer to ensure that this default value is legitimate.

Fields in the output buffer are matched against the fields in the 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 will not be populated.

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 will be copied to the output record, and you can use these fields to match error messages with input (or output) rows.

See Setting Business Interlink Inputs.

If you want to order your input (and output) rows, you must add a column called BI_SEQ_NUM to both the input and output table.

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

The input rows will be read in the order of numbers in BI_SEQ_NUM, and the output rows will be 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 or not 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.

See BulkExecute, Setting Business Interlink Inputs.

Parameters

Returns

A number representing the return status.

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 the Application Designer, are QE_RP_PO_NUMBER and QE_RP_SITENAME. These key fields are used both for input and output.

The following record is the input record.

Example input record for BulkExecute

The following record is the output record.

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.

Following are the inputs.

Example inputs for BulkExecute

Following are the outputs.

Example outputs 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);

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, you want to 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

BulkExecute, Execute.

Execute

Syntax

Execute()

Description

When a Business Interlink object executes the Execute method, the transaction associated with the Business 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 only have to call Execute once to execute all the rows of the input buffer.

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

See Generating the PeopleCode Template.

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

Whether this method halts on execution or not 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

A number representing the return status.

Example

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

Using New Status Codes for the pshttpenable (Generic) Runtime Plug-In

There are new status codes for the execute method relating to using an XML design-time plug-in that uses the generic Business Interlink (pshttpenable runtime plug-in). These status codes cover when a business interlink is called to pull in external data from a non-valid address.

To write your PeopleCode to take the status codes into account:

1. When you use the PeopleCode BIDocs Execute method with a Business Interlink definition created from such a design-time plug-in, check the return status for success (=1). Failure at this point is rare, and is most likely to be failure to find the Business Interlink object.

2. After the Execute call, use the GetValue method on the output document to get the values of the outputs return_status and return_status_msg.

3. If return_status = 200, the HTTP completed successfully. However, you should check the response to see if it has proper content; a successful HTTP does not mean that the transaction successfully returned content. Within the output doc, run GetDoc and GetStatus on a doc that you know must be returned. Many merchants provide an error code doc; use this if available, and read its value with GetValue to see if the service was able to complete the transaction.

4. If return_status = -1, the URL you provided is likely to be malformed. If return_status is 1, you used a simulated response file instead of doing HTTP. These status codes mean that no HTTP was performed. If return_status is 400 or greater, the HTTP failed in some way; you can look up these HTTP status codes on the following website: http://www.w3.org/Protocols/rfc2616/rfc2616.html. There is also a table at the end of this section containing some of these status codes.

Following is a pseudocode example of performing these steps.

&MyBI = GetInterlink(Interlink.SomeBI);
/* change the config parameters if needed*/
&MyBI.Method = "POST";
/*get the input doc */
&inDoc = &MyBI.GetInputDocs("");
/*create docs and input values*/
&ReqDoc = &inDoc.AddDoc("postreq");
&ret = &postReqDoc.AddValue("userid", "24");
/* ===> Step 1: Check the status of Execute. */
&EXECRSLT = &QE_GETSV_1.Execute();
If (&EXECRSLT <> 1) Then
   /* The instance failed to execute */
Else
/* ===> Step 2: Get the value of return_status. */
   &ret = &outDoc.GetValue("return_status", &return_status);
   if(&ret = 200) then 
      &outDoc = &MyBI.GetOutputDocs("");
/* ===> Step 3: Get a document (error) within the output doc (response), and if?
 it is an error code supplied by the merchant, get the?
 value of the error code and preform appropriate action. */
      &errorDoc = &outDoc.GetDoc("response.error");
      &docret = &errorDoc.GetStatus();
      if (&docret =0) then
         &errorDoc.GetValue("errorcode", &errorcode);
         if (no error) then 
             ............
            /*Get Docs and values*/
            &userDoc = &outDoc.GetDoc("postreqresponse.candidates.user");
            &userDoc.GetValue("conid", &conid);
         else
            /* flag the error and take appropriate action */
         End-if; 
      else
         /* error processing for not response doc returned */
      end-if;
   else 
      /* ===> Step 4: process for HTTP status codes. */

   End-if;
end-if;   

The following table contains the values for return_status and return_status_msg.

The values of 0 and 200-206 for return_status mean a response was successfully read. Values of −1 and 0 are specific to pshttpenable; values of 200 or greater are standard Hypertext Transfer Protocol. You can see the following URL for return_status values of 200 or greater.

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, i.e., in a rowset, and you want to preserve the hierarchy, use FetchIntoRowset instead of this method.

If you want to order your output rows, you must add the following column to the record: BI_SEQ_NUM.

This column will be 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, if every field is empty except the return_status and return_status_msg fields, this method returns one of the following error messages:

Example

Here is a PeopleSoft record that could be used as an output record for FetchIntoRecord.

Example output record for FetchIntoRecord

Here are the corresponding outputs for a Business Interlink that has had its outputs renamed to match the field names in the records.

Example outputs for FetchIntoRecord

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

Local Interlink &RP_QRY_SO_EXAMPLE_1;
Local number &RSLT;
 
&RP_QRY_SO_EXAMPLE_1 = GetInterlink(INTERLINK.RP_QRY_SO_EXAMPLE);
 
/* ===> Add Criteria inputs (RHS): */
&RP_QRY_SO_EXAMPLE_1.AddInputRow("IN1_customer.display_name",  "Joe Blow" ,?
 "IN2_order_number",  "199" , "IN3_order_date",  "09/18/99" ,?
 "IN4_order_date",  "10/18/96"  );
 
&EXECRSLT = &RP_QRY_SO_EXAMPLE_1.Execute();
If ( &EXECRSLT <> 1 ) Then
   /* The instance failed to execute */
Else
   &RSLT = 
      &RP_QRY_SO_EXAMPLE_1.FetchIntoRecord(RECORD.QE_RP_SO_OUT1);
End-If; /* If NOT &RSLT ... */

See Also

AddInputRow, Execute.

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. You can use the FetchIntoRowset method to repopulate the rowset with output from the Business Interlink object.

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 1 from the EMPLOYEE_CHECKLIST page. A PeopleCode event running on level 0 in that page can access the child rowset (level 1), shown below from Scroll Bar 1 to Scroll Bar 2.

EMPLOYEE_CHECKLIST

EMPL_CHECKLIST is the primary database record for that scrollbar on the EMPLOYEE_CHECKLIST page. The following PeopleCode access the level 1 rowset using EMPL_CHECKLIST. The Business Interlink object name is QE_BI_EMPL_CHECKLIST. This Business Interlink object uses the level 1 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

Execute, GetInputDocs, 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 that the PeopleCode program is associated with, you must use recname.fieldname for that value.

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 QE_COST, and the output names, such as Service_Type, are being bound to variables, such as &SVCTYPESTR.

&RSLT = &QE_COST.FetchNextRow(
   "Service_Type", &SVCTYPESTR, 
   "Rate", &RATESTR, 
   "return_status", &STATUSSTR, 
   "return_status_msg", &MSGSTR);

See Also

AddInputRow, Execute.

GetInputDocs

Syntax

GetInputDocs("")

Description

The GetInputDocs method gets the top BIDocs input document at the root level for a Business Interlink object. This is a hierarchical structure that will contain 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 BIDocs methods.

See Using BIDocs Hierarchical Methods.

Parameters

None.

Returns

A BIDocs input document. This is the document at the top of the root level of the BIDocs 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 Business Interlink object. */

GetOutputDocs

Syntax

GetOutputDocs("")

Description

The GetOutputDocs method gets the top BIDocs 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 BIDocs methods.

See Using BIDocs Hierarchical Methods.

Parameters

None.

Returns

A BIDocs output document. This is the document at the top of the root level of the BIDocs 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. */

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 is the same.

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

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

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 1 from the EMPLOYEE_CHECKLIST page. A PeopleCode event running on level 0 in that page can access the child rowset (level 1), shown below from Scroll Bar 1 to Scroll Bar 2.

EMPLOYEE_CHECKLIST page

EMPL_CHECKLIST is the primary database record for that scrollbar on the EMPLOYEE_CHECKLIST page. The following PeopleCode access the level 1 rowset using EMPL_CHECKLIST. The Business Interlink object name is QE_BI_EMPL_CHECKLIST. This Business Interlink object uses the level 1 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;

Using BIDocs Hierarchical Methods

This section describes the BIDocs methods that are used for hierarchical input and output data.

See Supporting Standard Input/Output with BIDocs Methods.

AddDoc

Syntax

AddDoc(docname)

Description

The AddDoc method adds a document to a BIDocs input document. 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 BIDocs input document 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 BIDocs input document for Calculate Cost (the root level document) is created with the GetInputDocs method. (If you want to create or add more BIDocs input documents, call 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 figure below shows the BIDocs input document for this example. It contains five input parameters: input_param1, From, To, Package_Info, and Account_Info_List.

Example of a BIDocs input document

See Also

AddNextDoc, GetInputDocs.

AddNextDoc

Syntax

AddNextDoc()

Description

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

• The root level of the BIDocs input document for a Business Interlink object. This level was created with the method GetInputDocs.

• When a document within the BIDocs input document 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

A number representing the return status.

Example

In this example, the BIDocs input document for Calculate Cost (the root level document) is created 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 figure below shows the BIDocs input document 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 of a BIDocs input document

See Also

AddDoc, GetInputDocs.

AddValue

Syntax

AddValue(paramname, value)

Description

The AddValue method adds a value to an input parameter within a BIDocs document for a Business Interlink object.

Parameters

Returns

A number representing the return status.

Example

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

In the following example, the BIDocs input document for Calculate Cost (the root level document) is created with the GetInputDocs method. (If you want to create or add more BIDocs input documents, call AddNextDoc.) The Calculate Cost input parameter From is a document, so the AddDoc method adds it to the BIDocs input document. 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 figure below shows the BIDocs input document for this example. It contains five input parameters: input_param1, From, To, Package_Info, and Account_Info_List.

Example of a BIDocs input document

See Also

AddDoc, AddNextDoc, GetInputDocs.

Clear

Syntax

Clear()

Description

The Clear method clears the BIDocs document for a Business Interlink object. If you're using Business Interlinks in a batch program, every time after you use the Execute method, you want to use the Clear method to flush out the BIDocs document.

Parameters

None.

Returns

None.

Example

In the following example, the BIDocs output document for Calculate Cost (the root level document) is created with the GetOutputDocs method. The Calculate Cost output parameter output_param2_List is a document, so the GetDoc method gets it from the BIDocs output document. Since output_param2_List is a document list, GetCount gets the number of documents in the list.

After the output_param2_List document is processed, the BIDocs document is cleared with Clear.

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");
 
&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;
 
&CalcCostOut.Clear();

GetCount

Syntax

GetCount(docname)

Description

The GetCount method returns the number of documents within a document list or parameter list contained within a BIDocs output document for a Business Interlink object.

Parameters

Returns

The number of documents in the list.

Example

In the following example, the BIDocs output document for Calculate Cost (the root level document) is created with the GetOutputDocs method. The Calculate Cost output parameter output_param2_List is a document, so the GetDoc method gets it from the BIDocs output document. Since 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 figure below shows the BIDocs output document for this example. It contains three output parameters: output_param1, Service_Rate, and output_param2_List.

Example of a BIDocs output document

GetDoc

Syntax

GetDoc(docname)

Description

The GetDoc method gets a document from a BIDocs output document. 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 BIDocs output document before you can get values from its members with GetValue.

You can call GetDoc using a nesting feature. This feature allows you to access deeply nested documents with one call to GetDoc, rather than calling GetDoc for each nesting. See the Example section below for an example of this.

Parameters

Returns

The document received from the BIDocs output document.

Example

In the following example, the BIDocs output document for Calculate Cost(Domestic), (the root level document) is created with the GetOutputDocs method. (If you want to create or get more BIDocs output documents, call GetNextDoc.) The Calculate Cost output parameter Service_Rate is a document, so the GetDoc method gets it from the BIDocs output document.

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 figure below shows the BIDocs output document for this example. It contains three output parameters: output_param1, Service_Rate, and output_param2_List.

Example of a BIDocs output document

In the following example, GetDoc is used to access a document that is nested more deeply. If you want 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 of a BIDocs output document: nested documents

GetNextDoc

Syntax

GetNextDoc()

Description

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

• The root level of the BIDocs output document for a Business Interlink object. This level was created with the method GetOutputDocs.

• When a document within the BIDocs output document 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

A number representing the return status.

Example

In this example, the BIDocs output document for Calculate Cost (the root level document) is created with the GetOutputDocs method. The GetNextDoc method gets another BIDocs output document, 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 BIDocs output document. 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 figure below shows the BIDocs output document for this example. It contains three output parameters: output_param1, Service_Rate, and output_param2_List.

Example of a BIDocs output document

GetPreviousDoc

Syntax

GetPreviousDoc()

Description

The GetPreviousDoc method gets the previous document from either the root level of the BIDocs output document for a Business Interlink object, or from a document within the BIDocs output document. 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

A number representing the return status.

Example

In this example, the BIDocs output document for Calculate Cost (the root level document) is created 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 figure below shows the BIDocs output document for this example. It contains three output parameters: output_param1, Service_Rate, and output_param2_List.

Example of a BIDocs output document

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

A number representing the return status.

GetValue

Syntax

GetValue(paramname, value)

Number GetValue(paramname, value)

Description

The GetValue method gets a value from an output parameter within a BIDocs output document for a Business Interlink object.

Parameters

Returns

A number representing the return status.

The following table contains the return status values when the syntax is Number GetValue(name, value).

Example

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

In the following example, the BIDocs output document for Calculate Cost (the root level document) is created with the GetOutputDocs method. (If you want to create or get more BIDocs output documents,call GetNextDoc.) The Calculate Cost output parameter Service_Rate is a document, so the GetDoc method gets it from the BIDocs output document. 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 figure below shows the BIDocs output document for this example. It contains three output parameters: output_param1, Service_Rate, and output_param2_List.

Example of a BIDocs output document

MoveToDoc

Syntax

MoveToDoc(list_number)

Description

Within a list of documents in the BIDocs output document, 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

A number representing the return status.

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 figure below shows the BIDocs output document for this example. It contains three output parameters: output_param1, Service_Rate, and output_param2_List.

Example of a BIDocs output document

ResetCursor

Syntax

ResetCursor()

Description

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

Parameters

None.

Returns

None.

Example

The following code uses ResetCursor to reset the cursor in the BIDocs output document 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();

Using the Interlink Property

In this section, we discuss the Interlink property.

StopAtError

Description

Specifies whether the execution of the PeopleCode program will stop when there’s an error, or if the PeopleCode program will try 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;

Using Configuration Parameters

This section provides an overview of configuration parameters and discusses how to:

• Use the Business Interlink plug-in configuration parameters.

• Use the URL configuration parameter.

• Use the BIDocValidate configuration parameter.

There are two types of configuration parameters: the ones defined by the Business Interlink plug-in the Business Interlink definition is based on, and 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.

See Generating the PeopleCode Template.

Using Business Interlink Plug-in Configuration Parameters

The configuration parameters defined by the Business 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. You can specify default values for every configuration parameter in the Business Interlink definition (created in the Application Designer.) These values will be used if you create a PeopleCode template by dragging the Business Interlink definition from the Project window in the Application Designer to an open PeopleCode editor window.

In the following example, the Business Interlink object name is QE_RP_SRAALL_1:

&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;

Using the 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 will first look for the file in the Location directory (specified by the user when the Business Interlink was first created), then it will look in the directory where PeopleTools is installed, in the PSTOOLS/Interface Drivers directory.

Using the BIDocValidate Configuration Parameter

When set to ON, a BIDocs object is checked to see if it exists before adding/getting values from it. For example, if the BIDoc object “Rate” does not exist, and BIDocValidate is set to ON, then the following line of code will cause an error:

&ret = &biDocs.GetValue("Rate", &RATE);

Using the Business Interlink Function

This section lists the Business Interlink function.

GetInterlink

Syntax

GetInterlink(Interlink.interlinkname)

Description

The GetInterlink function instantiates a Business Interlink Object based on a Business Interlink created in the Application Designer. This function is part of the PeopleSoft Business Interlink framework, which can provide a gateway for PeopleSoft applications to the services of any external system.

Parameters

Returns

A Business Interlink Object.

Example

The following example instantiates a Business Interlink Object based on the Business Interlink Definition QE_RP_SRAALL.

Local Interlink &SRA_ALL_1;
&SRA_ALL_1 = GetInterlink(Interlink.QE_RP_SRAALL);