Transcription
PeopleTools 8.4:PeopleSoft Component Interfaces
PeopleTools 8.4: PeopleSoft Component InterfacesSKU Tr84CPI-B 0302PeopleBooks Contributors: Teams from PeopleSoft Product Documentation andDevelopment.Copyright 2002 PeopleSoft, Inc. All rights reserved.Printed in the United States.All material contained in this documentation is proprietary and confidential to PeopleSoft,Inc. ("PeopleSoft"), protected by copyright laws and subject to the nondisclosure provisionsof the applicable PeopleSoft agreement. No part of this documentation may be reproduced,stored in a retrieval system, or transmitted in any form or by any means, including, but notlimited to, electronic, graphic, mechanical, photocopying, recording, or otherwise without theprior written permission of PeopleSoft.This documentation is subject to change without notice, and PeopleSoft does not warrant thatthe material contained in this documentation is free of errors. Any errors found in thisdocument should be reported to PeopleSoft in writing.The copyrighted software that accompanies this document is licensed for use only in strictaccordance with the applicable license agreement which should be read carefully as itgoverns the terms of use of the software and this document, including the disclosure thereof.PeopleSoft, the PeopleSoft logo, PeopleTools, PS/nVision, PeopleCode, PeopleBooks,PeopleTalk, and Vantive are registered trademarks, and "People power the internet." and PureInternet Architecture are trademarks of PeopleSoft, Inc. All other company and productnames may be trademarks of their respective owners. The information contained herein issubject to change without notice.
ContentsPeopleSoft Component Interfaces PrefaceAbout This PeopleBook. viiBefore You Begin. viiPeopleSoft Application Fundamentals . viiiRelated Documentation . viiiHard-copy Documentation. viiiPeopleBooks Standard Field Definitions. ixTypographical Conventions and Visual Cues. xPage and Panel Introductory Table. xiiComments and Suggestions. xiiChapter 1Understanding Component InterfacesComponent Interfaces. 1-1Component Interface Architecture . 1-1Component Interface Attributes . 1-3Name . 1-3Keys . 1-3Properties . 1-3Collections . 1-4Methods. 1-4Component Interface Definitions and Views . 1-4Chapter 2Developing the Component InterfaceCreating the Component Interface Definition . 2-1Creating a New Component Interface. 2-2Naming the Component Interface Definition. 2-3Associating a Component Interface With a Menu . 2-3Determining Which Fields to Expose . 2-4Working With Keys. 2-5Understanding Keys. 2-5Adding and Deleting Keys. 2-7Working With Properties. 2-7PEOPLESOFT PROPRIETARYANDCONFIDENTIALCONTENTSiii
PEOPLESOFT COMPONENT INTERFACESUnderstanding Standard Properties. 2-7Creating User-Defined Properties . 2-11Deleting User-Defined Properties . 2-12Renaming User-Defined Properties. 2-12Reference Properties . 2-13Making Properties Read-Only. 2-13Working With Collections. 2-14Working With Methods . 2-15Working with Session Functions and Methods. 2-15Understanding Standard Methods . 2-16Understanding Collection Methods. 2-19Enabling and Disabling Standard Methods. 2-23Creating User-Defined Methods . 2-24Validating the Component Interface. 2-25Setting Component Interface Security. 2-25Testing the Component Interface. 2-27Testing the Component Interface . 2-27Determining ItemByKeys Parameters. 2-32Understanding Synchronization. 2-33Writing a Component Interface Program. 2-34Understanding Runtime Considerations for Component Interface Programs. 2-34General Considerations . 2-34Scope Conflicts . 2-35Interactive Mode . 2-35Chapter 3Programming Component Interfaces in JavaBuilding the Component Interface APIs in Java. 3-1Setting Up the Java Environment . 3-2Generating a Java Runtime Code Template. 3-2Understand the Java Template. 3-4Chapter 4Programming Component Interfaces in C Building the Component Interface APIs for C . 4-1Setting Up the C Environment . 4-2Setting Up a Client Machine to Access the Component Interface API Using C . 4-2Configuring a Compiler for the C Project . 4-3Generating a C Runtime Code Template . 4-4Understanding the C Template. 4-5CONTENTSivPEOPLESOFT PROPRIETARYANDCONFIDENTIAL
PEOPLESOFT COMPONENT INTERFACESChapter 5Programming Component Interfaces in COMBuilding the Component Interface APIs for COM. 5-1Setting Up the COM Environment . 5-2Generating a Visual Basic Runtime Code Template . 5-3Understanding the Visual Basic Template . 5-4Chapter 6Using the Component Interface Software Development Kit (SDK)Component Interface SDK . 6-1Component Interface SDK Samples . 6-1Setting SDK Prerequisites . 6-2Using the SDK BUS EXPENSES Test Page. 6-2Testing the SDK BUS EXP Component Interface . 6-3Using the Component Interface SDK Java Sample. 6-4Running the Java Sample. 6-4Understanding the Java Sample Code. 6-7Using the Component Interface SDK C Sample. 6-13Building the C Sample. 6-14Running the Component Interface SDK C Sample . 6-14Understanding the C Sample Code. 6-17Using the Component Interface SDK COM Excel Sample. 6-23Running the COM Excel Sample. 6-23Understanding the COM Excel Sample Code. 6-25Using the Component Interface SDK COM ASP Sample. 6-29Running the COM ASP Sample. 6-29Understanding the COM ASP Sample Code . 6-31Chapter 7Programming Component Interfaces in PeopleCodeUnderstanding PeopleCode Behavior and Limitations. 7-1PeopleCode Event and Function Behavior . 7-1Limitations of Client-Only PeopleCode. 7-3Generating a PeopleCode Template . 7-3Understanding the PeopleCode Template . 7-4GlossaryIndexPEOPLESOFT PROPRIETARYANDCONFIDENTIALCONTENTSv
PeopleSoft Component InterfacesPrefaceThis book describes PeopleSoft Component Interfaces. A component interface is a PeopleSoftPeopleTools definition that you create in PeopleSoft Application Designer. It enablessynchronous access to a PeopleSoft component from another application. This PeopleBook iswritten for programmers who will be accessing PeopleSoft components, usually using externalsystems.The “About This PeopleBook” section contains general product line information, such asrelated documentation, common page elements, and typographical conventions. This bookalso contains a glossary with useful terms that are used in PeopleBooks.See PeopleSoft Glossary.About This PeopleBookThis book provides you with the information that you need for implementing and usingPeopleTools 8.4 applications. Complete documentation for this release is provided on the CDROM PT84PBR0.Note. Your access to PeopleSoft PeopleBooks depends on which PeopleSoft applicationsyou've licensed. You may not have access to all of the PeopleBooks.This section contains information that you should know before you begin working withPeopleSoft products and documentation, including PeopleSoft-specific documentationconventions, information specific to each PeopleSoft product line, and information onordering additional copies of our documentation.Before You BeginTo benefit fully from the information covered in this book, you should have a basicunderstanding of how to use PeopleSoft applications. We recommend that you complete atleast one PeopleSoft introductory training course.You should be familiar with navigating the system and adding, updating, and deletinginformation by using PeopleSoft windows, menus, and pages. You should also becomfortable using the World Wide Web and the Microsoft Windows or Windows NTgraphical user interface.Because we assume that you already know how to navigate the PeopleSoft system, much ofthe information in these books is not procedural. That is, these books do not typically providestep-by-step instructions on using tables, pages, and menus. Instead, we provide you with theinformation that you need to use the system most effectively and to implement yourPEOPLESOFT PROPRIETARYANDCONFIDENTIALPREFACEvii
PEOPLESOFT COMPONENT INTERFACESPeopleSoft application according to your organizational or departmental needs. PeopleBooksexpand on the material covered in PeopleSoft training classes.PeopleSoft Application FundamentalsEach PeopleSoft application PeopleBook provides implementation and processing informationfor your PeopleSoft database. However, there is additional, essential information describingthe setup and design of your database contained in a companion volume of documentationcalled PeopleSoft Application Fundamentals.PeopleSoft Application Fundamentals contains important topics that apply to many or allPeopleSoft applications across each product line. Whether you are implementing only onePeopleSoft application, some combination of products within a product line, or an entirePeopleSoft system, you should be familiar with the contents of this central PeopleBook. Itcontains fundamental information such as setting up control tables and administering security.The PeopleSoft Applications Fundamentals PeopleBook contains common informationpertinent to all applications in each product line, such as defining general options. If you'reupgrading from a previous PeopleSoft release, you may notice that we've removed sometopics or topic headings from the individual application PeopleBooks and consolidated themin this single reference book. You’ll now find only application-specific information in yourindividual application PeopleBooks. This makes the documentation as a whole lessredundant. Throughout each PeopleBook, we provide cross-references to PeopleSoftApplication Fundamentals and other PeopleBooks.Related DocumentationYou can order printed, bound versions of the complete PeopleSoft documentation delivered onyour PeopleBooks CD-ROM and additional copies of the PeopleBooks CDs through theDocumentation section of the PeopleSoft Customer Connection pYou can find updates and additional documentation for this release, as well as previousreleases, on PeopleSoft Customer Connection (http://www.peoplesoft.com/corp/en/login.asp ).Through the Documentation section of Customer Connection, you can download files to addto your PeopleBook library. You'll find a variety of useful and timely materials, includingupdates to the full PeopleSoft documentation delivered on your PeopleBooks CD.Important! Before you upgrade, it is imperative that you check PeopleSoft CustomerConnection for updates to the upgrade instructions. We continually post updates as we refinethe upgrade process.Hard-copy DocumentationTo order printed, bound volumes of the complete PeopleSoft documentation delivered on yourPeopleBooks CD-ROM, visit the PeopleSoft Press website from the Documentation section ofPREFACEviiiPEOPLESOFT PROPRIETARYANDCONFIDENTIAL
PEOPLESOFT COMPONENT INTERFACESPeopleSoft Customer Connection. The PeopleSoft Press website is a joint venture betweenPeopleSoft and Consolidated Publications Incorporated (CPI), our book print vendor.We make printed documentation available for each major release shortly after the software isshipped. Customers and partners can order printed PeopleSoft documentation by using any ofthe following methods:From the main PeopleSoft Internet site, go to theDocumentation section of Customer Connection. You canfind order information under the Ordering PeopleBookstopic. Use a Customer Connection ID, credit card, orpurchase order to place your order.InternetPeopleSoft Internet site: http://www.peoplesoft.com/.TelephoneContact Consolidated Publishing Incorporated (CPI) at800 888 3559.EmailSend email to CPI at callcenter@conpub.com.PeopleBooks Standard Field DefinitionsThroughout our product documentation, you will encounter fields and buttons that are used onmany application pages or panels. This section lists the most common fields and buttons andprovides standard definitions.FieldDefinitionAs of DateThe last date for which a report or process includes data.Business UnitAn identification code that represents a high-level organizationof business information. You can use a business unit to defineregional or departmental units within a larger organization.DescriptionFreeflow text up to 30 characters.Effective DateDate on which a table row becomes effective; the date that anaction begins. For example, if you want to close out a ledger onJune 30, the effective date for the ledger closing would be July1. This date also determines when you can view and change theinformation. Pages or panels and batch processes that use theinformation use the current row.For more information about effective dates, seeUnderstanding Effective Dates in Using PeopleSoftApplications.EmplID (employee ID)PEOPLESOFT PROPRIETARYANDCONFIDENTIALUnique identification code for an individual associated withyour organization.PREFACEix
PEOPLESOFT COMPONENT INTERFACESFieldDefinitionLanguage or Language CodeThe language in which you want the field labels and reportheadings of your reports to print. The field values appear as youenter them.Language also refers to the language spoken by an employee,applicant, or non-employee.Process Frequency group boxDesignates the appropriate frequency in the Process Frequencygroup box:Once executes the request the next time the batch process runs.After the batch process runs, the process frequency isautomatically set to Don't Run.Always executes the request every time the batch process runs.Don't Run ignores the request when the batch process runs.Report IDThe report identifier.Report ManagerThis button takes you to the Report List page, where you canview report content, check the status of a report, and see contentdetail messages (which show you a description of the report andthe distribution list).Process MonitorThis button takes you to the Process List page, where you canview the status of submitted process requests.RunThis button takes you to the Process Scheduler request page,where you can specify the location where a process or job runsand the process output format.For more information about the Report List page, theProcess List page, and the Process Scheduler, see ProcessScheduler Basics in the PeopleTools documentation.Request IDA request identification that represents a set of selection criteriafor a report or process.User IDThe system identifier for the individual who generates atransaction.SetIDAn identification code that represents a set of control tableinformation or TableSets. A TableSet is a group of tables(records) necessary to define your company’s structure andprocessing options.Short DescriptionFreeflow text up to 15 characters.Typographical Conventions and Visual CuesWe use a number of standard conventions and visual cues in our online documentation.The following list contains our typographical conventions and visual cues:PREFACExPEOPLESOFT PROPRIETARYANDCONFIDENTIAL
PEOPLESOFT COMPONENT INTERFACES(monospace font)Indicates a PeopleCode program or other programexample.BoldIndicates field names and other page elements, such asbuttons and group box labels, when these elements aredocumented below the page on which they appear. Whenwe refer to these elements elsewhere in thedocumentation, we set them in Normal style (not in bold).We also use boldface when we refer to navigational paths,menu names, or process actions (such as Save and Run).ItalicsIndicates a PeopleSoft or other book-length publication.We also use italics for emphasis and to indicate specificfield values. When we cite a field value under the page onwhich it appears, we use this style: field value.We also use italics when we refer to words as words orletters as letters, as in the following: Enter the number 0,not the letter O.KEY KEYIndicates a key combination action. For example, a plussign ( ) between keys means that you must hold down thefirst key while you press the second key. For ALT W,hold down the ALT key while you press W.Cross-referencesThe phrase For more information indicates where youcan find additional documentation on the topic at hand.We include the navigational path to the referenced topic,separated by colons (:). Capitalized titles in italicsindicate the title of a PeopleBook; capitalized titles innormal font refer to sections and specific topics within thePeopleBook. Here's an example:For more information, see Documentation on CDROM in About These PeopleBooks: AdditionalResources.Note. Text in this bar indicates information that you should pay particular attention to as youwork with your PeopleSoft system. If the note is preceded by Important!, the note is crucialand includes information that concerns what you need to do for the system to functionproperly.Text in this bar indicates cross-references to related or additional information.Warning! Text within this bar indicates a crucial configuration consideration. Pay veryclose attention to these warning messages.PEOPLESOFT PROPRIETARYANDCONFIDENTIALPREFACExi
PEOPLESOFT COMPONENT INTERFACESPage and Panel Introductory TableIn the documentation, each page or panel description in the application includes anintroductory table with pertinent information about the page. Not all of the information will beavailable for all pages or panels.UsageDescribes how you would use the page or process.Object NameGives the system name of the panel or process as specified in the PeopleToolsApplication Designer. For example, the Object Name of the Detail Calendarpanel is DETAIL CALENDAR1.NavigationProvides the path for accessing the page or process.PrerequisitesSpecifies which objects must have been defined before you use the page orprocess.AccessRequirementsSpecifies the keys and other information necessary to access the page. Forexample, SetID and Calendar ID are required to open the Detail Calendarpage.Comments and SuggestionsYour comments are important to us. We encourage you to tell us what you like, or what youwould like to see changed about our documentation, PeopleBooks, and other PeopleSoftreference and training materials. Please send your suggestions to:PeopleSoft Product Documentation ManagerPeopleSoft, Inc.4460 Hacienda DrivePleasanton, CA 94588Or send comments by email to the authors of the PeopleSoft documentation at:DOC@PEOPLESOFT.COMWhile we cannot guarantee to answer every email message, we will pay careful attention toyour comments and suggestions. We are always improving our product communications foryou.PREFACExiiPEOPLESOFT PROPRIETARYANDCONFIDENTIAL
CHAPTER 1Understanding Component InterfacesThis chapter provides overviews of: Component interfaces. The component interface architecture. Component interface concepts, such as names and properties. The component interface definition in PeopleSoft Application Designer.Component InterfacesA component interface is a PeopleTool to enable exposure of a PeopleSoft component (a set ofpages grouped together for a business purpose) for synchronous access from anotherapplication (PeopleCode, Java, C/C , COM, or XML). Component interfaces can be viewedas "black boxes" that encapsulate PeopleSoft data and business processes, and hide the detailsof the structure and implementation of the underlying page and data. Component interfacescan be used to integrate PeopleSoft with another PeopleSoft application or with externalsystems.A component interface maps to one, and only one, PeopleSoft component. A componentinterface is created in the PeopleSoft Application Designer by selecting the PeopleSoftcomponent. Record fields on the PeopleSoft component are mapped to the keys andproperties of the Component Interface. Methods are used to find, create, modify or deletedata.See AlsoPeopleTools PeopleBook: PeopleSoft Application Designer, “Creating ComponentDefinitions”Component Interface ArchitectureThere are three fundamental elements to the overall component interface architecture—components, component interfaces, and the component interface API.PEOPLESOFT PROPRIETARYANDCONFIDENTIALINTRODUCTIONTOCOMPONENT INTERFACES1-1
PEOPLESOFT COMPONENT INTERFACESElementDescriptionComponentsOne or more pages performing a business transaction.Component InterfaceExposed aspect of a component.Component interfaces are readily accessible by internal (PeopleCode)and external (Java, C/C , or COM) applicationsComponent Interface APIApplication programming interfaces for PeopleSoft applications(PeopleCode) and external applications (Java, C/C , or COM.)The following illustration shows the relationship between the basic elements of the componentinterface architecture.PeopleSoft Component Interface architectureEvery component interface has the following main attributes: Component interface name. Keys (get keys, create keys, and find keys). Properties and collections (fields and records). Methods.Note. In most cases, component interfaces behave the same as their associated components.This means that PeopleCode events typically trigger in the same order as the component.However, several runtime considerations cause exceptions to this behavior relate both toPeopleCode processing and search dialog box processing.See AlsoUnderstanding Runtime Considerations1-2INTRODUCTIONTOCOMPONENT INTERFACESPEOPLESOFT PROPRIETARYANDCONFIDENTIAL
PEOPLESOFT COMPONENT INTERFACESComponent Interface AttributesThis section discusses: Name Keys Properties Collections MethodsNameEach component interface requires a name. The calling programs use the name of thecomponent interface to access properties and methods.KeysKeys are special properties containing values that retrieve an instance (get keys) or a list ofinstances (find keys) of the component interface. When you create a new componentinterface, get and find keys are created based on the search record definition for the underlyingcomponent. However, you can add, remove, or change keys in PeopleSoft ApplicationDesigner. Create keys get created for component that have the “Add” action enabled.PropertiesProperties provide access to component data and component interface settings and status whenthey’re exposed through component interface. Component interfaces include two types ofproperties: Standard properties (InteractiveMode, GetHistoryItems, and EditHistoryItems) areassigned automatically when a component interface is created.Standard properties can be set to true or false. These properties are not displayed in thePeopleSoft Application Designer. User-Defined Properties map to record fields on the PeopleSoft component. Theseproperties are displayed in the PeopleSoft Application Designer. A property cancorrespond to a field or a scroll (collection).Note. Every PeopleSoft Application Designer definition—including the componentinterface—has a definition properties dialog box in which you make design-time settings forthe definition. Those properties should not be confused with the runtime properties that arediscussed here.PEOPLESOFT PROPRIETARYANDCONFIDENTIALINTRODUCTIONTOCOMPONENT INTERFACES1-3
PEOPLESOFT COMPONENT INTERFACESSee AlsoPeopleTools PeopleBook: Peoplesoft PeopleCode Reference, “Component Interface Classes”“Developing the Component Interface,” Understanding Standard Properties“Developing the Component Interface,” Creating User-Defined PropertiesCollectionsA component interface collection is a special type of property that corresponds to a scroll. Itcontains fields and subordinate scrolls as defined in its underlying component. By default,each collection uses the name of the primary record for the underlying scroll.S
This book describes PeopleSoft Component Interfaces. A component interface is a PeopleSoft PeopleTools definition that you create in PeopleSoft Application Designer. It enables synchronous access to a PeopleSoft component from another application. This PeopleBook is
