Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	http://www.oracle.com/technology/documentation/index.html   |   Search   |   PDF Files   |   Contact   |
eLink Adapter for Portal Infranet Doc Home   |   eLink Adapter for Portal Infranet User Guide   |   Previous Topic   |   Next Topic   |   Contents   |

The eLink Adapter for Portal Infranet advertises services that represent operations to be performed on business objects executing in the Portal Infranet billing system. These services allow access to account and billing information that is maintained by Portal Infranet. In order to invoke these services. eLink Platform clients create FML32 buffers and invoke the service of interest with tpcall() or tpacall(). The FML fields that must be supplied for each service are documented in Appendix A, "Portal Infranet Service Interfaces" of this User Guide.

This section describes how to create request buffers for the Portal Infranet services advertised by the adapter. It also describes how to interpret the responses received from these service invocations and the enumerated fields, date/time fields, and the hierarchical nature of Portal Infranet messages.

This chapter contains the following topics:

• Enumerations

• Date/Time Values

• Hierarchical Data

• Creating a Request Buffer

• Traversing a Response Buffer

Certain fields that are sent to or received from the eLink Adapter for Portal Infranet contain enumerated data. These enumerations are documented in Appendix B, "Portal Infranet Enumerations" of this User Guide and are supplied in a C include file prtconst.h with the eLink Adapter for Portal Infranet. These enumerated values must be specified by eLink Platform clients for the FML fields that are listed in Appendix A as an enumeration field.

For example, the Create Account interface descried in Appendix A, "Portal Infranet Service Interfaces" of this User Guide denotes a field named DELIVERY_PREFER. This field is listed as a type of `enumeration.' In Appendix B, "Portal Infranet Enumerations" of this User Guide, the numerated values for DELIVERY_PREFER are listed as shown in listing 4-1.

DELIVERY_PREFER    PIN_INV_EMAIL_DELIVERY = 0
                   PIN_INV_USP_DELIVERY = 1
                   PIN_INV_FAX_DELIVERY = 2

When a eLink Platform client wishes to invoke the Create Account service, the FML32 buffer that is created needs to populate the field DELIVERY_PREFER with one of the enumerated values (0, 1, or2) as documented in Appendix B, "Portal Infranet Enumerations". The sample applications provided with the eLink Adapter for Portal Infranet also illustrate this concept.

For fields that are defined as TIMESTAMP in Appendix B, "Portal Infranet Enumerations" of this User Guide, the string for this FML field must be of the correct format. Timestamp values are represented in FML as strings in the following format `mm/dd/yyyy HH:MM:SS". An explanation of these formats appears in Table 4-1.

Format	Description
mm	Two-digit months
dd	Two-digit day of the month
yyyy	Four-digit year
HH	Two-digit hour
MM	Two-digit minute
SS	Two-digit seconds

For example, 09/11/199913:01:25 represents September 11, 1999 1:01:25 p.m. In Appendix A, "Portal Infranet Service Interfaces" of this User Guide, the Create Account interface defines a field LAST_STATUS_T as a TIMESTAMP filed. When this field is received in a response from the Create Account service, it will be a string representing the date and time the account was last modified. This string will be of the format "mm/dd/yyyy HH:MM:SS."

The major difficulty in using Portal business objects is that the messages that can be sent to or received from the Portal Infranet system are hierarchical in nature. Applications within the Portal Infranet system communicate using hierarchical messages that can have nested structures, and arrays are embedded at any level. The eLink Platform system does not have a native hierarchical buffer type that allows structures to be embedded within structures.

The eLink Adapter for Portal Infranet has adopted a scheme of flattening hierarchical structured data into a tag/value FML32 buffer. An implicit order is used to retain the hierarchical order. Examples of this concept are included with the eLink Adapter for Portal Infranet that further illustrate how messages must be passed to the adapter and how to interpret responses received from Portal Infranet.

Listing 4-2 illustrates a message that can be sent to the Portal Infranet system in order to create a customer account. Each level of indentation represents a level in the hierarchical structure.

The Create Account message at the highest level consists of an EA_PLAN_NAME filed, an array of SERVICES and an array of PAYINFO. A SERVICE structure is composed of a DEAL_NAME, SERVICE_TYPE, LOGIN, and PASSWD_CLEAR field. The PAYINFO structure consists of a NAME field, an OBJ_TYPE field, an array of INV_INFO (invoice information) and an array of CC_INFO (credit card information).

Field EA_PLAN_NAME
Array  SERVICES
	Fields	
             DEAL_NAME
             SERVICE_TYPE
             LOGIN
             PASSWD_CLEAR
Array  PAYINFO
       Fields
             NAME
             OBJ_TYPE
             Array  INV_INFO
                    Fields
                          NAME
                          ADDRESS
                          CITY
                          STATE
                          ZIP
                          COUNTRY
                          EMAIL_ADDR
                          DELIVERY_PREFER
                          DELIVERY_DESCR
                          INV_TERMS
                          INV_INSTR
                          PO_TYPE
                          PO_OPTIONS
                          PO_AMOUNT
                          PO_BAL_THRESHOLD
                          PO_EXP
                          PO_EXP_THRESHOLD
                          PO_ORDER_NO
                          PO_TERMS
              Array CC_INFO
                    Fields
                          NAME
                          ADDRESS
                          CITY
                          STATE
                          ZIP
                          COUNTRY
                          DEBIT_NUM
                          DEBIT_EXP

An FML32 buffer is a tag/value structured buffer of data that only maintains the fields that are in the buffer and the number of occurrences of each field exist in the buffer. Grouping of fields, the fact that multiple fields are part of a structure, is not maintained. In order to represent structured data in an FML32 buffer, two constraints are used to maintain the hierarchical groupings of fields:

1. Fields must be added to an FML 32 buffer in pre-order traversal. Fields must be added to an FML32 buffer in the order listed for the service in Appendix A, "Portal Infranet Service Interfaces" of this User Guide. Substructures must be traversed, and their fields must be added as listed. In the example above, the fields must be added to the FML32 buffer in the following order:

   • PLAN_NAME

   • DEAL_NAME

   • SERVICE_TYPE

   • LOGIN

   • PASSWD_CLEAR

   • NAME

   • OBJ_TYPE

   • NAME

   • ADDRESS

The first occurrence of the NAME field relates to the PAYINFO structure, and the next occurrence of NAME should be associated with the INVINFO structure. This relationship can only be maintained by agreeing upon the order that the fields are `flattened' into an FML32 buffer.

1. The number of occurrences of each group must be explicitly specified in the FML32 buffer. For each `group' of fields, an extra FML32 field must be added to the data to denote how many occurrences of this group exist in the FML32 data. In the example above, an extra field SERVICES_OCC would indicate how many occurrences of the SERVICES information exist in the FML32 buffer.

The constraints described in the Enumerations, Date/Time Values, and Hierarchical Data sections of this chapter are best illustrated in an example. The following example provides pseudocode to create an FML32 buffer to request the Create Account service. This sample client, shown below, is provided with the eLink Adapter for Portal Infranet, and it also illustrates how to create an FML32 buffer for the Create Account service. To create an FML32 buffer for a Create Account service, follow these instructions:

1. Allocate and FML32 buffer using tpalloc().

2. Initialize FML32 buffer using Finit32().

3. Add PLAN_NAME FIELD for this account.

4. Add SERVICES_OCC field to indicate how many services were subscribed by this account.

5. Add DEAL_NAME, SERVICE_TYPE, LOGIN, PASSWD_CLEAR fields for each service.

6. Add PAYINFO_OCC field to indicate how many payment info records are associated with this account.

7. Add NAME and OBJ_TYPE fields for payment information.

8. Add INV_INFO_OCC field to indicate how many invoice info records are associated with this payment information.

9. Add NAME, ADDRESS, CITY, STATE, ZIP, COUNTRY, EMAIL_ADDR for each invoice information record.

The resulting FML 32 buffer is shown in Listing 4-3.

PLAN_NAME[0]			"ISP Plan"
SERVICES_OCC[0]			1
DEAL_NAME[0]			"ISP-1"
SERVICE_TYPE[0]			"Internet Dial-up"
LOGIN[0]			"jdoe"
PASSWD_CLEAR[0]			"abcdefg"
PAYINFO_OCC[0]			1
NAME[0]			"Credit account"
OBJ_TYPE	[0]		"Payment"
INV_INFO_OCC[0]			1
NAME[1]			"John Doe"
ADDRESS[0]			"101 Doe Ln"
CITY[0]			Denver
STATE[0]			Colorado
ZIP[0]			99999
COUNTRY[0]			United States
EMAIL_ADDR[0]			jdoe@email.org

After a request is sent to a service advertised by the eLink Adapter for Portal Infranet, the response buffer is returned. This response message (depending on the invoked service) can contain hierarchical data. The information that follows demonstrates how you can retrieve this data and the implied hierarchical structure of that data. Listing 4-4 shows an example of the response buffer for Create Account.

ACCOUNT NO[0]			123456789
SERVICES_OCC[0]			1
LASTSTAT_CMNT[0]			"Account Created"
LAST STATUS[0]			
STATUS FLAGS[0]			0
STATUS[0]			10100
LOGIN[0]			"jdoe"
PASSWD_CLEAR[0]			"abcdef1"
PAYINFO_OCC	[0]		1
NAME[0]			"Credit account"
OBJ_TYPE			"Payment"
INV_INFO_OCC[0]			1
NAME[0]			"John Doe"
ADDRESS[0]			"101 Doe Ln"
CITY[0]			Denver
STATE[0]			Colorado
ZIP[0]			99999
COUNTRY[0]			United States
EMAIL_ADDR[0]			jdoe@email.org

The interface description in Appendix B, "Portal Infranet Enumerations" of this User Guide lists the fields that are present in a Create Account response message. To retrieve this data from the FML buffer, it is important to know which occurrence of a field belongs to which group (payment info, invoice info, etc.) The following algorithm retrieves data from the FML buffer and deletes each field as it is retrieved. This algorithm does not keep track of the occurrence of an FML field. Successive occurrences are shifted upward, and then they become first occurrence (NAME[0]). This algorithm is also demonstrated in the supplied sample applications. To traverse a response buffer, follow these instructions:

1. Use Fget32() to retrieve ACCOUNT_NO data.

2. Use Fdel32() to delete this occurrence of ACCOUNT_NO data.

3. Use Fget32() to retrieve SERVICES_OCC data.

4. Use Fdel32() to delete this occurrence of the field SERVICES_OCC.

   1. For all occurrences of SERVICES (the value retrieved in SERVICES_OCC)

   2. For all fields of the SERVICES group (LASTSTAT_CMNT, LAST_STATUS_T, STATUS_FLAGS, SATATUS, LOGIN, PASSWD_CLEAR)

   3. Use Fget32() to retrieve the data.

   4. Use Fdel32() to delete the occurrence of this field.

5. Use Fget32() to retrieve PAYINFO_OCC data.

6. Use Fdel32() to delete this occurrence of the field PAYINFO_OCC.

   1. For all occurrences of PAYMENT INFO (the value retrieved in PAYINFO_OCC).

7. Use Fget32() to retrieve the NAME field.

8. Use Fdel32() to delete this occurrence of the NAME field.

9. Use Fget32() to retrieve the OBJ_TYPE field.

10. Use Fdel32() to delete this occurrence of the OBJ_TYPE field.

11. Use Fget32() to retrieve INV_INFO_OCC data.

12. Use Fdel32() to delete this occurrence of the field INV_INFO_OCC).

    1. For all fields of the INVOICE INFO group (NAME, ADDRESS, CITY, STATE, ZIP, COUNTRY, EMAIL_ADDR).

    2. Use Fget32() to retrieve the data.

    3. Use Fdel32() to delete this occurrence of this field.