PeopleTools 8.52: PeopleCode Developer's Guide

PeopleCode and PeopleSoft Pure Internet Architecture

The chapter discusses how to:

Using PeopleCode in PeopleSoft Pure Internet Architecture.
Using PeopleCode with PeopleSoft Pure Internet Architecture
Call dynamic link library (DLL) functions on the application server.
Update the Installation and PSOPTIONS tables.

Considerations Using PeopleCode in PeopleSoft Pure Internet Architecture

Consider the following points when writing PeopleCode programs for PeopleSoft Pure Internet Architecture:

To help your application run efficiently, avoid using field-level PeopleCode events (FieldEdit and FieldChange).

Each field-level PeopleCode program requires a trip to the application server.

The majority of PeopleCode programs run on the application server as part of the component build and save process. Do not hesitate to use PeopleCode for building and saving components.
If a user changes a field but nothing on that field will cause a trip to the server, then default processing and FieldFormula PeopleCode do not run.

This processing occurs only when another event causes a trip to the server.

Other fields that depend on the first field using FieldFormula or default PeopleCode are not updated until the next time a server trip occurs.
In applications that run on the PeopleSoft portal, external dynamic link information must be placed in RowInit PeopleCode.

If external dynamic link information is placed in FieldChange PeopleCode, it will not work.
Trips to the server are reduced when a component runs in deferred processing mode.

Each trip to the server results in the page being completely refreshed on the browser, which may cause the display to flicker. It can also slow down your application. Deferred processing mode results in better performance.

See Also

Deferred Processing Mode

Using PeopleCode with PeopleSoft Pure Internet Architecture

This section discusses how to:

Use internet scripts.
Use the field object Style property.
Use the HTML area.
Use HTML definitions and the GetHTMLText function.
Use HTML definitions and the GetJavaScriptURL method.
Use PeopleCode to populate key fields in search dialog boxes

Using Internet Scripts

An internet script is a specialized PeopleCode function that generates dynamic web content. Internet scripts interact with web clients (browsers) using a request-response paradigm based on HTTP.

See Also

Internet Script Classes (iScript)

Using the Field Object Style Property

In PeopleSoft Application Designer, on the Use tab of the page definition properties, you can associate a page with a style sheet component.

The style sheet has several classes of styles defined for it. You can edit each style class to change the font, the color, the background, and so on. Then, you can dynamically change the style of a field using the Style field class property. The style sheet does not change, only the style class associated with that field changes.

The following example changes the style class of a field depending on a value entered by the user. This code is in the FieldChange event.

Local Field &field; 
 
&field = GetField(); 
 
If TESTFIELD1 = 1 Then; 
   &field.Style = "PSHYPERLINK"; 
End-If; 
 
If TESTFIELD1 = 2 Then; 
   &field.Style = "PSIMAGE"; 
End-If;

The following examples show the fields with different styles:

Field with PSHYPERLINK style

Field with PSIMAGE style

See Also

Creating Style Sheet Definitions

Field Class

Using the HTML Area

Two methods are used to populate an HTML area control. Both require accessing the HTML area in the PeopleSoft Application Designer. One method is to select Constant on the HTML tab of the HTML page field properties dialog and enter HTML directly into the page field dialog.

The other method is to select Value on the HTML tab of the HTML page field properties dialog and associate the control with a record field. At runtime, populate that field with the text that you want to appear in the HTML area.

If you are using an HTML area to add form controls to a page, you can use GetParameter request class method in PeopleCode to get the user input from those controls.

Note. When you associate an HTML area control with a field, make sure the field is long enough to contain the data you want to pass to it. For example, if you associate an HTML area control with a field that is only 10 characters long, only the first 10 characters of your text will appear.

The following code populates an HTML area with a simple bulleted list. This code is in the RowInit event of the record field associated with the HTML control.

Local Field &HTMLField; 
 
&HTMLField = GetField(); 
&HTMLField.Value = "<ul><li>Item one</li><li>Item two</li></ul>";

The following code is in the FieldChange event of a button. It populates an HTML area (associated with the record field CHART_DATA.HTMLAREA) with a simple list.

Local Field &HTMLField; 
 
&HTMLField = GetRecord(Record.CHART_DATA).HTMLAREA; 
&HTMLField.Value = "<ul><li>Item one</li><li>Item two</li></ul>";

The following code populates an HTML area (associated with the record DERIVED_HTML and the field HTMLAREA) with the output of the GenerateTree function:

DERIVED_HTML.HTMLAREA = GenerateTree(&TREECTL);

The following tags are unsupported by the HTML area control:

Body
Frame
Frameset
Form
Head
HTML
Meta
Title

See Also

Using the GenerateTree Function

Creating HTML Definitions

Using HTML Definitions and the GetHTMLText Function

If you are using the same HTML text in more than one place or if it is a large, unwieldy string, you can create an HTML definition in PeopleSoft Application Designer, and then use the GetHTMLText function to populate an HTML area control.

The following is the HTML string to create a simple table:

<P> 
<TABLE> 
   
  <TR bgColor=#008000> 
    <TD> 
      <P><FONT color=#f5f5dc face="Arial, Helvetica, sans-serif"  
      size=2>message 1 </FONT></P></TD></TR> 
  <TR bgColor=#0000cd> 
    <TD> 
      <P><FONT color=#00ffff face="Arial, Helvetica, sans-serif"  
      size=2>message 2</FONT></P></TD></TR> 
   </TABLE></P>

This HTML is saved to an HTML definition called TABLE_HTML.

This code is in the RowInit event of the record field associated with the HTML area control:

Local Field &HTMLField; 
 
&HTMLField = GetField(); 
&string = GetHTMLText(HTML.TABLE_HTML); 
&HTMLField.Value = &string;

This code produces the following:

See Also

GetHTMLText

Using HTML Definitions and the GetJavaScriptURL Method

HTML definitions can contain JavaScript programs in addition to HTML. If you have an HTML definition that contains JavaScript, use the GetJavaScriptURL Response method to access and execute the script.

This example assumes the existence in the database of a HTML definition called HelloWorld_JS that contains some JavaScript:

Function IScript_TestJavaScript() 
 
   %Response.WriteLine("<script src= " | 
%Response.GetJavaScriptURL(HTML.HelloWorld_JS) | "></script>");

End-Function;

See Also

GetJavaScriptURL

Creating HTML Definitions

Using PeopleCode to Populate Key Fields in Search Dialog Boxes

In a PeopleSoft Pure Internet Architecture application, you typically want users to directly access their own data. To facilitate this, you may want to use SearchInit PeopleCode to populate standard key fields in search page fields and then make the fields unavailable for entry. You might assign the search key field a default value based on the user ID or alias the user entered when signing in.

You must also call the AllowEmplIdChg function, which enables users to change their own data. This function takes a single Boolean parameter in which you pass True to allow employees to change their own data.

Here is a simple example of such a SearchInit program, using %EmployeeId to identify the user:

EMPLID = %EmployeeId;
                
Gray (EMPLID);
                
AllowEmplIdChg(True);

Calling DLL Functions on the Application Server

To support processes running on an application server, you can declare and call functions compiled in Microsoft Windows DLLs and in UNIX shared libraries (or shared objects, depending on the specific UNIX platform). You can do this either with a special PeopleCode declaration, or using the business interlink framework.

When you call out to a DLL using PeopleCode, on Microsoft Windows NT application servers, the DLL file has to be on the path. On UNIX application servers, the shared library file must be on the library path (as defined for the specific UNIX platform).

The PeopleCode declaration and function call syntax remains unchanged. For example, the following PeopleCode could be used to declare and call a function LogMsg in an external library Testdll.dll on a Microsoft Windows client or a Windows application server, or a libtestdll.so on an UNIX application server. The UNIX shared library’s extension varies by the specific UNIX platform.

Declare Function LogMsg Library "testdll" (string, string)
       Returns integer;

&res = LogMsg("\temp\test.log", "This is a test");

Sample Cross-Platform External Test Function

The following section describes and includes the C source code for a sample cross-platform test fucntion: LogMsg. It is a basic function that opens a log file and appends a line to it. If you compile the code using a C++ compiler, the functions must be declared using external C to ensure C-language linkage.

The sample program also contains an interface function (LogMsg_intf). Prior to PeopleTools 8.52, this interface function was required for all non-Microsoft Windows environments. The interface function references a provided header file, pcmext.h. The interface function is passed type codes that can be optionally used for parameter checking.

Starting with PeopleTools 8.52, the interface function is required for the following environments only:

HP-UX Itanium
Solaris x86_64
z/Linux

For all the other PeopleTools-supported UNIX platforms, the functions from the UNIX shared libraries can be used directly. To maintain backward compatibility, the interface functions are also supported on these UNIX platforms.

In the following sample test program, the interface function is compiled only when compiling for the specified non-Windows environments.

/*
 * Simple test function for calling from PeopleCode.
 * This is passed two strings, a file name and a message.
 * It creates the specified file and writes the message 
 * to it.
 */
#include <stdlib.h>
#include <stdio.h>
#include <string.h>

#ifdef _WINDOWS
#define DLLEXPORT __declspec(dllexport)
#define LINKAGE __stdcall
#else
#define DLLEXPORT
#define LINKAGE
#endif

DLLEXPORT int LINKAGE LogMsg(char * fname, char * msg);

/********************************************************
*  PeopleCode External call test function.              *
*                                                       *
*  Parameters are two strings (filename and message)    *
*  Result is 0 if error, 1 if OK                        *
*                                                       *
*                                                       *
*  To call this function, the following PeopleCode is   *
*  used                                                 *
*                                                       *
*  Declare Function LogMsg Library "testdll"            *
*  (string, string)                                     *
*       Returns integer;                                *
*                                                       *
*  &res = LogMsg("\temp\test.log", "This is a test");   *
*                                                       *
********************************************************/

DLLEXPORT int LINKAGE LogMsg(char * fname, char * msg)
{
    FILE *fp;

    fp = fopen(fname, "a");         /* append */
    if (fp == NULL) return 0;

    fprintf(fp, "%s\n", msg);
    fclose(fp);
    return 1;
}


#ifndef _WINDOWS

/********************************************************
*  Interface function.                                  *
*                                                       *
*  This is not needed for Windows....                   * 
*                                                       *
********************************************************/

#include  "pcmext.h"
#include  "assert.h"

/* This interface function is required only for the following platforms:
   - HP-UX Itanium 
   - Solaris x86_64 
   - z/Linux
*/

void LogMsg_intf(int nParam, void ** ppParams, EXTPARAMDESC * pDesc)
{
    int    rc;

    /* Some error checking */
    assert(nParam == 2);
    assert(pDesc[0].eExtType == EXTTYPE_STRING
       && pDesc[1].eExtType == EXTTYPE_STRING
       && pDesc[2].eExtType == EXTTYPE_INT);

    rc = LogMsg((char *)ppParams[0], 
         (char *)ppParams[1]);
    *(int *)ppParams[2] = rc;

}

#endif

Updating the Installation and PSOPTIONS Tables

When an application updates either the PSOPTIONS or the Installation table it must call UpdateSysVersion from the SavePreChange PeopleCode event. This way, updates take effect at the next page load. Otherwise, the change does not take effect at the client workstation until the user signs out and signs back in.

Important! Only a database administrator or the equivalent should change these tables.