3 Using Services

This chapter discusses how to use services and provides an example of a custom service. It covers the following topics:

• "Service Overview"

• "Custom Application Example"

• "Redirecting Template Page for Response Output"

3.1 Service Overview

A service is a function or procedure that is performed by the Oracle Content Server. Calling a Oracle Content Server service (making a service request) is the only way a client can communicate with the Oracle Content Server or access the database.

This section covers the following topics:

• "Service Requests and Responses"

• "Page Retrieval"

• "Oracle Content Server Search Services"

• "Integration Methods"

• "Calling Services Using Persistent URLs"

• "Customizing Locale Parameters"

3.1.1 Service Requests and Responses

Any service can be called either externally (from outside the Oracle Content Server) or internally (within the Oracle Content Server itself). Typically, client services are called externally, while administrative services are called internally. When a service is requested, any applicable parameters are passed to the service. The service uses its attributes and actions to execute the request based on the specified parameters. The service then returns a response either externally or internally, as applicable. This section covers the following topics:

• "Internal Service Requests"

• "External Service Requests"

• "Request Parameters"

• "Date and Time Formatting"

• "Case Sensitivity Considerations"

3.1.1.1 Internal Service Requests

Although any service can be called internally, typically only administrative services are called internally. Internal service requests are made from within the Oracle Content Server itself, and results are returned only to the Oracle Content Server. For example, you can use the START_SEARCH_INDEX service to update or rebuild the search index automatically in a background thread.

3.1.1.2 External Service Requests

Any external program or HTML page can call any Oracle Content Server service to request information from the Oracle Content Server or perform a specified function, such as full-text and metadata searching, library services, workflow services, subscription notifications, and content conversion capabilities. Typically, only client services are called externally (administrative services are typically called internally). For example, when you click a Search link on a Oracle Content Server Web page, the standard search page is delivered to your Web browser by the GET_DOC_PAGE service using the following URL segment:

IdcService=GET_DOC_PAGE&Action=GetTemplatePage&Page=STANDARD_QUERY_PAGE

External requests are sent from a client (for example, a Web browser) to the Web server using one of many protocols. The service call must include any parameters that the service requires. The Web server routes the service request to the Oracle Content Server, along with any required and optional parameters. The Oracle Content Server then executes the service using the provided parameters. In the case of search services, this involves sending a search request to the search engine. The Oracle Content Server then returns the results to the Web server, and the Web server returns the results to the Web browser client.

Figure 3-1 External Requests and Responses Between Content Management System Elements

3.1.1.3 Request Parameters

A service request must include every parameter that the service requires. For example, when calling the DOC_INFO service to obtain information about a content item, the service call must provide the dID (generated content item revision identifier) to the service. The following segment shows how this would be done through a persistent URL:

http://cs.company.com/cs/idcplg?
IdcService=DOC_INFO&dID=194

3.1.1.4 Date and Time Formatting

Default date and time formatting are determined using the Localization tab on the System Properties. The general format for date and time is:

MM/DD/{yy} {hh:mm[:ss] {aa} [zzz]} !mAM,PM!zTimezoneCity

• The date/time format is a grouping of Y, D, M for Year, Day, and Month, and h, m, and s for hours, minutes, and seconds. The number of times the letter repeats designates the minimum number of digits used (for example, YY/MM/DD hh:mm could designate 04/12/09 12:12 or MM/DD/YYYY hh:mm:ss would be 09/12/2004 04:12:33).

• The a represents the meridian symbol (for example, AM or PM).

• The m represents minutes.

• Braces ({ }) indicate that the item is optional when in the input data, but will always appear in the output.

• The exclamation mark (!) is used to separate additional date format specifications. For example, !mXXX,YYY could designate the meridian symbols (where XXX is the symbol meaning "before noon" and YYY is the symbol meaning "after noon"). Everything after the exclamation point passes the meridian and time zone symbols along with the date format.

3.1.1.5 Case Sensitivity Considerations

Case sensitivity is important when calling standard Content Server services.

• Parameters: Parameters are case sensitive. For example, when specifying the IdcService parameter you must use IdcService, not IDCSERVICE.

• Parameter values: Parameter values are typically case sensitive. The value for the IdcService parameter is always case sensitive, and the convention used for standard Content Server services is all capital letters. For example, when specifying the value for the IdcService parameter you must use DOC_INFO, not Doc_Info.

• Databases: The database you are using with Content Server might affect the case sensitivity of parameters and parameter values. For example, some databases do not have case-sensitive column names and other databases are case-insensitive by default. So a database may have stored "DDOCNAME", but the value that Oracle Content Server expects is still "dDocName". Also, some databases store values in uppercase, but they perform case-insensitive queries. For example, if you store the dDocName "BouncyCaps", a query for "bouncycaps" would find that row.

3.1.2 Page Retrieval

When a Web page is requested from the Oracle Content Server, one of the following page types is returned:

• static page: The content of a static Web page is pre-formatted, and does not change from one request to the next. In a typical Oracle Content Server Web site, the only static page is the guest home page (DomainHome/ucm/cs/weblayout/portal.htm).

• dynamic page: A dynamic Web page is assembled at the time of the Web server request, using Oracle Content Server services and templates to determine the content and formatting. For example, each user's portal design page is generated using a Oracle Content Server service called GET_PORTAL_PAGE and a template called PNE_PORTAL_DESIGN_PAGE.

3.1.3 Oracle Content Server Search Services

A search request is a special kind of Oracle Content Server service. When the Oracle Content Server receives a search request, it sends the request on to the search engine using a search engine API. This allows different search engines to be used with the Oracle Content Server.

3.1.4 Integration Methods

Service requests can be made by any external program or HTML page using a wide variety of protocols. Content Server can be integrated with other enterprise applications using a wide variety of integration methods. One common integration method is to reference content that is managed within the Oracle Content Server by persistent URL. For more information, see Section 3.1.5, "Calling Services Using Persistent URLs".

The following are other possible integration methods:

• Oracle Weblogic Server Web Services (WS) using integrated Weblogic JAXP and SAML support.

• Oracle UCM Web services component for the Oracle Content Server and Remote Intradoc Client (RIDC) component for clients.

• Java API (IdcCommand) integration using the IdcCommand Java Command Utility

• Java Server Page (JSP) integration from a JSP running in Oracle Content Server, a JSP through the Oracle Content Server JavaBean, or a JSP through the Oracle Content Server Enterprise JavaBean (EJB) deployed on your J2EE application server

• Java 2 Enterprise Edition API (J2EE) integration by deploying the Oracle Content Server Enterprise JavaBean on your J2EE-compliant application server

• Simple Object Access Protocol (SOAP) integration using the SOAP protocol

• Virtual Folders integration using the Folders component

• Web Distributed Authoring and Versioning (WebDAV) integration using the WebDAV component

• Component Object Model (COM) integration using the ActiveX utility or the IntradocClient OCX component

Note:

For more detailed information on available integration methods, see the Oracle Fusion Middleware Developer's Guide for Oracle Universal Content Management.

3.1.5 Calling Services Using Persistent URLs

In this integration method, all of the necessary information for the service call is sent to the Oracle Content Server through the URL. The following is a typical URL; in this case, it is the URL for the Home page:

http://cs.company.com/cs/idcplg?
IdcService=GET_DOC_PAGE&Action=GetTemplatePage&Page=HOME_PAGE

• http://cs.company.com/ is the Web address of the Oracle Content Server instance.

• cs/idcplg is the path to the Web server filter.

• IdcService=GET_DOC_PAGE tells the Oracle Content Server to execute the GET_DOC_PAGE service.

• Action=GetTemplatePage tells the Oracle Content Server to return the results using a specified template page. This parameter is specific to the GET_DOC_PAGE service example.

• Page=HOME_PAGE tells the Oracle Content Server which template page to use. This parameter is specific to the GET_DOC_PAGE service example.

• The question mark (?) indicates the end of the Web server path and the beginning of Oracle Content Server parameters.

• Ampersands (&) are used as separators between Oracle Content Server parameters.

• You can include certain Idoc Script variables in a URL to affect page display at the time of the page request. This is useful for troubleshooting or for customizing your Oracle Content Server pages. For example:

Troubleshooting Examples

• IsJava=1

• IsPageDebug=1

Customization Examples

• StdPageWidth=1000

• dDocType=HRForm

Example

The following example describes the steps that occur when a persistent URL is used to request a dynamic page from the Oracle Content Server.

1. When a user clicks the Administration link in the navigation area, a request for the GET_ADMIN_PAGE service is sent to the Web server. The URL of the Administration link contains the following commands:

   IdcService=GET_ADMIN_PAGE&Action=GetTemplatePage&Page=ADMIN_LINKS
   

2. The Web server recognizes this request as a Oracle Content Server function and sends the specific request to the Oracle Content Server.

3. When the Oracle Content Server has processed the request, it passes the result back to the Web server. In the case of the Administration link, the GET_ADMIN_PAGE service:

   • Provides a login prompt if the user is not currently logged in.

   • Verifies that the user has admin permission.

   • Assembles the Administration page using the ADMIN_LINKS template.

   • Returns the assembled Web page to the Web server.

4. The Web server delivers the results of the Oracle Content Server service to the originating Web browser client.

Example

The following example describes the steps that occur when a persistent URL is used to perform a search request.

1. When a user clicks the Search button on the standard Search page, a request for the GET_SEARCH_RESULTS service is sent to the Web server. The URL for the search request specifies the service to execute, the search criteria, and the result parameters:

   IdcService=GET_SEARCH_RESULTS&QueryText=stellent&ftx=1
   &AdvSearch=True&ResultCount=25&SortField=dInDate&SortOrder=Desc
   

2. The Web server recognizes the request as a Oracle Content Server function, and sends the specific request to the Oracle Content Server.

3. The Oracle Content Server passes the request to the search engine.

4. The search engine returns the search results to the Oracle Content Server.

5. Based on the user login and security permissions, the Oracle Content Server assembles the search results page and returns it to the Web server.

6. The Web server delivers the results to the originating Web browser client.

3.1.6 Customizing Locale Parameters

When using the Oracle Content Server in a client server operation mode, you can use several parameters to improve the handling of locale-sensitive data, helping to avoid date and encoding incompatibility problems.

In the following descriptions, it is assumed that an HDA formatted request is being made to the Oracle Content Server using an operation such as IdcClient, IdcCommandUX, IdcServerBean, or a custom server communication.

The following parameters are available:

• UserDateFormat: Specifies the date/time format for dates in the incoming request and any dates produced in the response to the request. If not specified, the response format always uses the login user's date locale. If that is unavailable, it uses the Oracle Content Server system locale date. Do not use the ODBC date/time format used internally by the Oracle Content Server for archiver batch load files; that can create time zone ambiguity errors.

  UserDateFormat=M/D/YYYY hh:mm[:ss]{aa}!mAM,PM!zUTC
  

• blDateFormat: Specifies the format of dates in the body of the incoming request. It does not affect the format of the response. If set, this overrides values set with UserDateFormat. If not specified, the incoming request format uses the login user's locale date format. If that is unavailable, it uses the Oracle Content Server system locale date format. This parameter is not available except if one of the headers that precedes the request is a REQUEST_METHOD header with a POST value. GET style requests do not support this parameter.

• ClientEncoding: Specifies the character encoding to be used in the response. If no HDA header line exists with either the charset or jcharset specification, this parameter also dictates the encoding used to decode the body of the request.

  ClientEncoding=cp1252
  

• HEADER_ENCODING: Used in the header that precedes the body of the HDA request. This allows the requesting agent to specify the encoding of headers. This functionality is useful for dictating the encoding of the HTTP_INTERNETUSER and REMOTE_USER header entities.

• blFieldTypes: Specifies a field type (date or message) during the translation of a response. A 'message' is a formatted string, usually an error message, that has not been localized. You can use this parameter to ensure that ODBC formatted fields are parsed and returned in the format specified by blDateFormat or UserDateFormat and will be applied even if the field is only in the response and not in the request. If the field types are not specified in biFieldTypes, then fields are treated like plain strings and no localization is performed on them.

  The only fields that typically need such translation are ones created by customized extensions of Oracle Content Server behavior (such as those created using Idoc Script, for example). This is only available for POST style requests (REQUEST_METHOD header with value POST). This is normally used to specify additional date fields and is best used in combination with UserDateFormat or blDateFormat to indicate that a field needs special handling as a date.

  blFieldTypes=xNewDate date, xComment message
  

• extraFieldTypes: Specifies a field type during the translation of a response to HDA formatted requests, used in place of blFieldTypes. It is best used inside an Idoc script expression that is executed when fulfilling a Oracle Content Server request. It cannot be used in Idoc script when generating the format of the response because the response is in a data format (such as HDA). It can, however, be used in other places where Idoc script is evaluated when executing the logic of a request, such as the processing of an HCSP form, or determining the effects of a document profile.

  extraFieldTypes=xNewDate date, xComment message
  

• convertDatabaseDate: Ensures that blFieldTypes or extraFieldTypes are used to convert the ODBC date format to the desired response date format. This variable is necessary when using the blFieldTypes or extraFieldTypes variables.

  If this variable is not set, the ODBC date formats may not be converted to the desired response date format. ODBC dates can still be converted even if this variable is not set. This occurs if the Oracle Content Server determines that the response needs a full coercion from one date format to another. This typically happens only if the incoming date format is different from the outgoing date format.

  convertDatabaseDate=1
  

• SuppressResultLocalization: Suppresses localization conversions performed before the response is sent back. Conversions done on incoming data can still be performed.

  This parameter is useful to prevent messages from being localized or dates being fully converted. An example of usage is when the response is to be forwarded to another Oracle Content Server to be processed or when the data is to be persistently stored and replayed back to the original Oracle Content Server as needed.

  SuppressResultLocalization=1
  

  All of the parameters that affect date and message processing can be used with this parameter, but the other parameters are only used when the data is replayed against another Oracle Content Server or the current Oracle Content Server.

Note:

The operation making the HDA request may set values for these parameters; therefore, users may find that the values they set do not change the behavior as expected.

3.1.7 Forcing Authentication Challenges

It is sometimes necessary that a user be re-authenticated for a Oracle Content Server service or for other activities. For example, during a workflow, it might be necessary to acquire a 'digital signature' for a user at a specific step in the workflow process. This can be done using the isRepromptLogin configuration variable. See the Oracle Fusion Middleware Idoc Script Reference Guide for details about its usage.

To force re-authentication of any service, perform the following steps:

1. Add checkForRevalidateLogin as a service definition function.

2. Add revalidateLoginID as a parameter to the service call being made, with a randomly generated value.

These two actions cause the Oracle Content Server to refuse to accept the currently supplied credentials until the AllowedLoginID cookie is set with the same value as the parameter to revalidateLoginID. The cookie is set during the redundant challenge to the current credentials.

Note that this clears the current credentials so the user will need to login again to access any Oracle Content Server functionality.

3.2 Custom Application Example

This example application calls five services and defines six private functions.

• Services Called

• Private Functions

• Sample Code

3.2.1 Services Called

These services are called and a serialized HDA string is built for each:

• CHECKOUT_BY_NAME

• CHECKIN_UNIVERSAL

• DOC_INFO

• GET_FILE

These parameters for CHECKIN_UNIVERSAL are defined:

• doFileCopy

• dDocName

• dDocTitle

• dDocType

• dSecurityGroup

• dDocAuthor

• dDocAccount

• primaryFile

The GET_TABLE service is called and this parameter is defined:

• tableName

3.2.2 Private Functions

These private functions are defined:

• getNativeFilePath

• checkOutByName

• checkinUniversal

• getDocInfo

• getFile

• parseResultSet

3.2.3 Sample Code

This sample is in Visual Basic.

' Defines a private function.
Private Function getNativeFilePath() As String
Dim idccmd As IdcCommandX
Dim str As String
Dim res
Dim dID As String, dExtension As String, dDocType As String, dDocAccount As String

dID = "2"
dExtension = "pdf"
dDocType = "acc"
dDocAccount = ""

' Builds a serialized HDA string.
str = "@Properties LocalData" + vbCrLf
str = str + "dID=" + dID + vbCrLf
str = str + "dExtension=" + dExtension + vbCrLf
str = str + "dDocType=" + dDocType + vbCrLf
str = str + "dDocAccount=" + dDocAccount + vbCrLf
str = str + "@end" + vbCrLf

Set idccmd = New IdcCommandX
res = idccmd.init("sysadmin", "c:\st ellent\bin")
res = idccmd.computeNativeFilePath(str)

Open "c:\newdoc.txt" For Binary Access Write As #1
Put #1, , str
Put #1, , res
Close #1
MsgBox (res)
End Function

' Defines a private function.
Private Function checkOutByName(ByVal dDocName As String) As String
Dim idccmd As IdcCommandX
Dim idcService As String, str As String
Dim res

' Calls a service and builds a serialized HDA string.
idcService = "CHECKOUT_BY_NAME"
str = "@Properties LocalData" + vbCrLf
str = str + "IdcService=" + idcService + vbCrLf
str = str + "dDocName=" + dDocName + vbCrLf
str = str + "@end" + vbCrLf

' In an actual application the return codes need to be handled. For this example, the service is called while there is no content with that specific dDocName.
Set idccmd = New IdcCommandX
res = idccmd.init("sysadmin", "c:\stellent\bin")
res = idccmd.executeCommand(str)
End Function

' Defines a private function.
Private Function checkinUniversal(ByVal doFileCopy As String, ByVal dDocName As String, ByVal dDocTitle As String, ByVal dDocType As String, ByVal dSecurityGroup As String, ByVal dDocAuthor As String, ByVal dDocAccount As String, ByVal primaryFile As String) As String

' Builds a serialized HDA string.
Dim idccmd As IdcCommandX
Dim idcService, res, str As String

' Calls a service and builds a serialized HDA string.
idcService = "CHECKIN_UNIVERSAL"
str = "@Properties LocalData" + vbCrLf
str = str + "IdcService=" + idcService + vbCrLf
str = str + "doFileCopy=" + doFileCopy + vbCrLf
str = str + "dDocName=" + dDocName + vbCrLf
str = str + "dDocTitle=" + dDocTitle + vbCrLf
str = str + "dDocType=" + dDocType + vbCrLf
str = str + "dSecurityGroup=" + dSecurityGroup + vbCrLf
str = str + "dDocAuthor=" + dDocAuthor + vbCrLf
str = str + "dDocAccount=" + dDocAccount + vbCrLf
str = str + "primaryFile=" + primaryFile + vbCrLf
str = str + "@end" + vbCrLf

' exec hda...
Set idccmd = New IdcCommandX
res = idccmd.init("sysadmin", "c:\stellent\bin")
res = idccmd.executeCommand(str)
MsgBox (CStr(res))
End Function

' Defines a private function.
Private Function getDocInfo(ByVal dID As String) As String
Dim idccmd As IdcCommandX
Dim idcService As String, str As String
Dim res

' Calls a service and builds a serialized HDA string.
idcService = "DOC_INFO"
str = "@Properties LocalData" + vbCrLf
str = str + "IdcService=" + idcService + vbCrLf
str = str + "dID=" + dID + vbCrLf
str = str + "@end" + vbCrLf

' exec hda....
Set idccmd = New IdcCommandX
res = idccmd.init("sysadmin", "c:\stellent\bin")
res = idccmd.executeCommand(str)
MsgBox (res)
End Function

' Defines a private function.
Private Function getFile(ByVal dID As String, ByVal dDocName As String, ByVal RevisionSelectionMethod As String, ByVal Rendition As String)
Dim idccmd As IdcCommandX
Dim idcService, str As String

Dim res As Variant
Dim fileName As String
Dim fileSize As Long
Dim indexStop As Integer

' Calls a service and builds a serialized HDA string.
idcService = "GET_FILE"
str = "@Properties LocalData" + vbCrLf
str = str + "IdcService=" + idcService + vbCrLf
str = str + "dDocName=" + dDocName + vbCrLf
str = str + "dID=" + dID + vbCrLf
If (RevisionSelectionMethod = "Specific" Or RevisionSelectionMethod = "Latest" Or RevisionSelectionMethod = "LatestReleased") Then

' Ignore dDocName and use dID instead.
str = str + "RevisionSelectionMethod=" + RevisionSelectionMethod + vbCrLf
End If
If (Revision = "Primary" Or Revision = "Web" Or Revision = "Alternate") Then
str = str + "Revision=" + Revision + vbCrLf
End If
str = str + "@end" + vbCrLf

' exec hda...
Set idccmd = New IdcCommandX
res = idccmd.init("sysadmin", "c:\stellent\bin")
res = idccmd.executeCommand(str)

Open "c:\newdoc.txt" For Binary Access Write As #1
Put #1, , res
Close #1
MsgBox (Len(res))

' chop at filename= and store fileName
indexStop = InStr(res, "filename=")
tmpStr = (Mid(res, indexStop))
indexStop = InStr(tmpStr, Chr(13))
fileName = Mid(tmpStr, 10, indexStop - 10)
MsgBox (fileName)
' MsgBox (CStr(Asc(Mid(tmpStr, 2, 1))))

' chop at Content-length: and store fileSize
tmpStr = Mid(tmpStr, indexStop)
indexStop = InStr(tmpStr, "Content-Length: ")
tmpStr = (Mid(tmpStr, indexStop))
indexStop = InStr(tmpStr, Chr(10))
fileSize = CLng(Mid(tmpStr, 17, indexStop - 17))
MsgBox (CStr(fileSize))
MsgBox (Len(res))
End Function

Private Sub cmdAddUser_Click()
frmAddUser.Show
End Sub

Private Sub cmdCheckin_Click()
Dim idcService As String, doFileCopy As String, dDocName As String
Dim dDocTitle As String, dDocType As String, dSecurityGroup As String
Dim dDocAuthor As String, dDocAccount As String, primayFile As String

' Calls a service and defined parameters.
idcService = "CHECKIN_UNIVERSAL"
doFileCopy = "1"
dDocName = "myDocNameNewh"
dDocTitle = "myDocTitleb"
dDocType = "ADACCT"
dSecurityGroup = "Public"
dDocAuthor = "Jennifer"
dDocAccount = ""
primaryFile = "c:/junk_b.doc"

' In an actual application check for errors.
' Lock the file in order to upload a new revision.
Call checkOutByName(CStr(dDocName))
' If the dDocName is not in the system, it gets added as first revision
' by the CHECKIN_UNIVERSAL call.
Call checkinUniversal(doFileCopy, dDocName, dDocTitle, dDocType, dSecurityGroup, dDocAuthor, dDocAccount, primaryFile)
End Sub

Private Sub cmdDocInfo_Click()
Call getDocInfo("269")
End Sub

Private Sub cmdDownload_Click()
Call ba
End Sub

Private Sub cmdGetFile_Click()
Call getFile("14", "", "", "")
End Sub

Private Sub cmdGetNativeFile_Click()
Call getNativeFilePath
End Sub

Private Sub Command1_Click()
Dim idccmd As IdcCommandX
Dim res, str
Open "c:\adduser.txt" For Append As #1
Set idccmd = New IdcCommandX
res = idccmd.init("sysadmin", "c:\stellent\bin")
str = "@Properties LocalData" + vbCrLf + "IdcService=ADD_USER" + vbCrLf + "dName=Jennifer" + vbCrLf + "dFullName=Jennifer Smith" + vbCrLf + "dPassword=password" + vbCrLf + "dEmail=[e-mail]" + vbCrLf + "dUserAuthType=LOCAL" + vbCrLf + "@end" + vbCrLf + "@ResultSet UserAttribInfo" + vbCrLf + "2" + vbCrLf + "dUserName" + vbCrLf + "AttributeInfo" + vbCrLf + "Jennifer" + vbCrLf + "role,admin,15" + vbCrLf + "@end" + vbCrLf
res = idccmd.executeCommand(str)
Print #1, res
Close #1
End Sub

Private Sub Command2_Click()
Dim idccmd As IdcCommandX
Dim res, str

Dim myRS As String
Dim idcService, tableName As String

idcService = "GET_TABLE"
tableName = "Accounts"

Open "c:\a_getsec.txt" For Append As #1
Set idccmd = New IdcCommandX
res = idccmd.init("sysadmin", "c:\stellent\bin")
str = "@Properties LocalData" + vbCrLf + "IdcService=" + idcService + vbCrLf + "tableName=" + tableName + vbCrLf + "@end" + vbCrLf
myRS = idccmd.executeCommand(str)

' Parse out the results set.
Call parseResultSet(myRS, tableName)
Print #1, res
Close #1
End Sub

' Calls a private function.
Private Function parseResultSet(strResultsSet As String, strSearchString As String) As String
Dim indexStop As Integer
Dim tmpStr As String

Dim numberOfRows As Integer
Dim numberOfElementsInSet As Integer
Dim resultElement()
MsgBox (strResultsSet)

' Start of results set.
indexStop = InStr(strResultsSet, "@ResultSet " & strSearchString)

' Check for error (0 index) before moving on.
tmpStr = (Mid(strResultsSet, indexStop))
MsgBox (tmpStr)

' Determine how many data lines are in the HTA file.
indexStop = InStr(tmpStr, "@end")
For i = 1 To indexStop
If (Mid(tmpStr, i, 1) = Chr(10)) Then
numberOfRows = numberOfRows + 1
End If
Next i
numberOfRows = numberOfRows - 2 ' Remove the first line of data.

' Find first line that identifies the ResultsSet
indexStop = InStr(tmpStr, Chr(10))
tmpStr = (Mid(tmpStr, indexStop + 1))

' Get number of elements in record set, chop the line off the record set...
indexStop = InStr(tmpStr, Chr(10))
numberOfElementsInSet = CInt((Mid(tmpStr, 1, indexStop)))
tmpStr = (Mid(tmpStr, indexStop + 1))

' Set storage array.
ReDim resultElement((numberOfRows / numberOfElementsInSet), numberOfElementsInSet)
Dim junk As String
' Populate array from HTA dataset
For i = 1 To (numberOfRows / numberOfElementsInSet)
For j = 1 To numberOfElementsInSet
indexStop = InStr(tmpStr, Chr(10))
resultElement(i, j) = Mid(tmpStr, 1, indexStop - 1)
tmpStr = (Mid(tmpStr, indexStop + 1))
junk = junk + resultElement(i, j)
Next j
Next i
MsgBox (junk)
parseResultSet = "je"
End Function

' Set storage array.
Sub ba()
Dim b() As Byte 'This byte array will capture the file
Dim strURL As String ' URL string
Dim strDest As String ' Destination File

' Set the strURL to a valid address.
'strURL = "http://localhost/cs/idcplg?IdcService=GET_FILE&dID=14"
'strDest = "C:\myjunk.html"
strURL = "localhost"
b() = Inet1.OpenURL(strURL, icByteArray)
'Open strDest For Binary Access Write As #1
'Put #1, , b()
'Close #1
End Sub

3.3 Redirecting Template Page for Response Output

Sometimes it is desirable to display a page other than the default (change the delivery mechanism for the response template) after executing a CGI request (either a GET or a POST). For example, you might want to redirect the page after a login or after executing a search. One way to do this is by modifying the service call through the component architecture, and specifying a different template page. Another more flexible way to do this as needed is to specify the urlTemplate parameter, to redirect the response page to a HCSP or HCST, and reformat the results in any way you want.

This section covers the following topics:

• "Basic Concepts"

• "Creating a HCST Page"

• "Reformatting the Search Results Page"

• "Additional Options"

3.3.1 Basic Concepts

You should be somewhat familiar with IdocScript, and Dynamic Server Pages (HCST, HCSP, HCSF) before attempting this exercise. You should also be somewhat familiar with Component Architecture. It would also be helpful to be familiar with HTML FORM objects.

3.3.2 Creating a HCST Page

As an example, we will create a HCST page that can be used as a URL template to reformat the search results. We could also create a HCSP, but for simplicity, we will use a HCST. We will name the file test_result.hcst, and have it contain the following text:

<html>
<table width=300>
<tr bgcolor="#000000" style="color: #ffffff;">
<td><b>Name</b></td>
<td><b>Title (Author)</b></td>
</tr>
<$loop SearchResults$>
<tr <$if doShade$>bgcolor="#E5E7D4"<$endif$>>
<td><a href="<$URL$>"><$dDocName$></a></td>
<td><$dDocTitle$> (<$dDocAuthor$>)</td>
</tr>
<$if doShade$><$doShade=""$><$else$><$doShade="1"$><$endif$>
<$endloop$>
</table>
</html>

Next, we should check this file into the Oracle Content Server. For simplicity, we will check it into the Public security group, with a content type of ADACCT, and the Content ID test_result. Its URL will then be something like this:

http://myhost/oracle/groups/public/documents/document/test_result.hcst

3.3.3 Reformatting the Search Results Page

To test our new template, we will start by going to a search page. Enter in any search criteria and click Search. You should see the standard search page with your results contained in it.

Now, add this text to the end of the URL that brought you to the search results page:

&urlTemplate=/stellent/groups/public/documents/adacct/test_result.hcst

You should now see the same search results formatted in a minimalist HTML page. Note how the full URL is not used, but just the URL relative to your host computer.

If you would like the default search page to always format pages with this template, you can change the HTML FORM object on the search page to also have this field:

<input type=hidden name='urlTemplate'
value='/stellent/groups/public/documents/document/test_result.hcst'>

This can be done by creating a component that modifies the include query_results_options to contain the sample HTML. Alternatively, the value for urlTemplate can be calculated dynamically on the search page with JavaScript, to redirect to different pages based on the metadata entered by the user.

3.3.4 Additional Options

In addition to urlTemplate, you can also use the parameters docTemplateName, docTemplateID, or RedirectUrl to change the result page. These all have different behavior, as follows:

• urlTemplate: Set to the full relative URL of the hcst page you want to use. For example:

  IdcService=DOC_INFO&urlTemplate=/idc1/groups/public/documents/adacct/test_result.hcst
  

  Because RedirectURL doesn't work with all service calls, and pre-6.0 versions of Content Server have minor data pollution bugs with docTemplateName and docTemplateID, it's usually safest to use urlTemplate. However, if you change the Content Type or the Security Group of your template, then the URL will no longer be valid and will need to be updated. Also, this parameter is not recommended for overriding the template used for a 'POST' service.

• docTemplateName: Set to a dDocName of a template (for example, test_result). Like urlTemplate, but finds the location of the latest released Web-viewable for a document with dDocName of docTemplateName.

• docTemplateID: Set to a dID of a specific revision of a template (for example, 100). Like docTemplateName, but finds the Web-viewable of a specific dID revision.

• RedirectUrl: Set to the last part of a CGI URL back into the Oracle Content Server (for example, IdcService=DOC_INFO&dID=<$dID$>). This is only for the few dozen 'POST' services that execute the action prepareRedirect, such as CHECKIN_NEW and SUBMIT_HTML_FORM.

• By using a redirect after each HTML 'POST', the response page can be safely refreshed by the end user without reissuing the post. In the definition of each of these services there is a 3:prepareRedirect:….:0:null line. The RedirectUrl overrides the results of the prepareRedirect method and allows a different URL to be used as the location for redirects. The RedirectUrl can have Idoc script in it that will be executed just before the redirect is issued. This can create complex Idoc script nesting, because the RediretUrl assignment will typically occur in a resource includes. For example:

  … Standard Idoc form beginning …
  <input type=edit name=myparam value=''>
  <input type=hidden name=RedirectUrl
  value='<$HttpCgiPath$>?<$xml('IdcService=MY_RESPONSE_TEMPLATE&dID=<$dID$>&
  myparam=<$myparam$>')$>'>
  … Standard Idoc form closure …
  

Much of the Idoc script is nested inside an Idoc literal string. This delays the execution of the script until the redirect URL is being computed. That allows the RedirectUrl to pick up the value of 'myparam' even though the user has still to select its value.

A single quote is used on the outside and a double quote on the inside. This reduces confusion and because both HTML and Idoc script support both single and double quotes for quoting, it is sometimes a good idea to switch between the two for nesting constructs.

Note the usage of the 'xml' function. This guarantees that the input field's value is a well-formed HTML literal string construct. In this particular case, it is not needed. But for more complex constructs it can be helpful.