PeopleTools 8.52: PeopleCode API Reference

Session Class

This chapter provides an overview of Session class and discusses the following topics:

Error handling.
Regional settings.
Trace settings.
Session object declaration.
Scope of a Session object.
Session class built-in function.
Session class reference section.

Understanding Session Class

PeopleTools provides a family of APIs for external access into the PeopleSoft system. The Session class is the root of the APIs. It controls access to the PeopleSoft system, controls the environment, and enables you to do error handling for all APIs from a central location.

The PeopleSoft APIs are intended to be used, and are supported, in the following environments.

PeopleSoft Windows client with either an existing two-tier connection or an existing connection to an application server.
Application Engine batch program.
Non-PeopleSoft program connecting to an application server.

The PeopleSoft APIs are exposed to the following language environments:

PeopleCode
OLE/COM
C/C++
Java

The APIs that are accessible using a session object are:

Component Interface Classes
PortalRegistry Classes
Query Classes
Search Class
Tree Classes

Note. Tree Classes are accessible only through PeopleCode.

A session object controls the following:

Security and access to the PeopleSoft system.
Errors and error handling .
Regional settings (that is, internationalization) for language, dates, times, and numbers.
Tracing.

See Also

Component Interface Classes

Portal Registry Classes

Query Classes

Session Class

Tree Classes

Security and Access to the PeopleSoft System

A session object controls security and access to the PeopleSoft system. You must "sign-on" to the PeopleSoft session with a valid user ID and password when you use the Connect method. In addition, there’s an external authentication parameter that you can use with the connect.

Note. Additional authentication will be available after this release.

Error Handling

The session object handles error processing for all the APIs, such as Component Interfaces, the Query API, and so on. From the session object, you can check if there have been any errors.

Note. The exception to this is Subscription PeopleCode. All errors for Subscription PeopleCode get logged to the application message error table.

Error messages include system error messages or messages from the message catalog (a common set of error messages used by all PeopleSoft applications.) For a Component Interface, the session object level errors also contain any text errors that may have occurred from running ExecuteEdits.

On the session object, you can use the following properties to initially check for errors:

ErrorPending indicates whether there are API errors
WarningPending indicates whether there are API warnings

All errors are contained in the PSMessages collection. (The PSMessages property on a Session object returns this collection.)

Each item in this collection is a PSMessage object. A PSMessage object contains information about the specific error that has occurred, such as the explain text for the error, the message set number, and so on. (The type of information depends on the type of error.)

If the error was caused by a Component Interface, a contextual string is attached to the end of the Text property of the PSMessage object. This contextual string contains the exact location of the error, that is, which field in which data collection, on which row, caused the error. This string is also accessible (by itself) using the Source property.

When errors are loaded into the PSMessages collection depends on the type of error. System errors (that is, errors in the connection to the PeopleSoft Session) are logged as they occur. When an API error is logged depends on the API, as some APIs can be run in either interactive mode (meaning errors are logged as they happen) or in non-interactive mode (so errors are logged only when a particular method is run.)

If you are using Visual Basic or another COM environment, the PeopleSoft API system raises a COM exception the first time ErrorPending changes from False to True. It will not raise another exception until the PSMessages collection is cleared, which sets ErrorPending back to False.

Note. If you’ve called an API from an Application Engine program, all errors are also logged in the Application Engine error log tables.

See Also

Accessing a PSMessages Collection

Displaying Error Messages

Use the following PeopleCode to display messages from the PSMessage collection:

Local ApiObject &Session, &PSMessages;
   &Session = %Session;
   &PSMessages = &Session.PSmessages;
   If (&Session <> Null ) Then
       If &PSMessages.Count > 0 Then
               For &i = 1 To &PSMessages.Count
                  &MsgSetNbr = &PSMessages.Item(&i).MessageSetNumber;
                  &MsgNbr = &PSMessages.Item(&i).MessageNumber;
                  MessageBox( 0 , " ", &MsgSetNbr, &MsgNbr, "Message not found");
               End-For;
         &PSMessages.DeleteAll();
            End-If;
End-If;

Regional Settings

Regional settings enable the user to set the display of numbers, dates, times, and currencies to comply with usage in a specific locale. The session object exposes some of these values to the API through the RegionalSettings property. This property returns a regional settings object that has properties you can use to change these settings.

See Also

Regional Settings Class Properties

Trace Settings

The PeopleSoft debug pages enables you to control the environment in which your PeopleTools session is running. These pages include:

Trace PeopleCode
Trace SQL
Trace Page

These pages enable you to select the SQL trace options and the PeopleCode trace options that you want. The TraceSettings object (assessable from a session object) lets you control many of the same options during your session.

Not every option on the debug pages is represented with a trace settings property.

See Also

Using Debug Utilities

Session Object Declaration

All session objects are declared as type ApiObject. For example,

Local ApiObject &MYSESSION;
Global ApiObject &PSMessage;

The following session objects can be declared as Global or Component:

Session
PSMessages Collection
PSMessage

All other session objects must be declared as Local.

In this section, we discuss the following topics:

State considerations.
Considerations for declaring conditions.

State Considerations

In the PeopleSoft Pure Internet Architecture, all processing occurs on the server. If you do something in your PeopleCode program that causes a trip back to the user before the end of your PeopleCode program, the PeopleCode program cannotregain its state, that is, it can't reset local variables, and so on. This applies to all APIs that use the Session object.

If you must go back to the user before the end of your PeopleCode program, you must set all your objects to NULL before you go, or else you receive a runtime error.

For example, the following code causes an error:

&Session = %Session;
Rem &Session = Null;
WinMessage("Hello");

The following example does not cause an error:

&Session = %Session;
&Session = Null;
WinMessage("Hello");

Considerations for Declaring Collections

You must declare all collections for C/C++ and COM as objects, or else you receive errors at runtime.

For example if you're using RegionalSettings, include the following your declarations for a VB program:

Dim oRegionalSettings As Object

Then, use the following code to populate this variable:

Set oRegionalSettings = oCISession.RegionalSettings oRegionalSettings.LanguageCd = "GER"

Scope of a Session Object

A Session can be instantiated from PeopleCode, from a Visual Basic program, from C++, COM, and so on.

See the example section in Connect for more details.

This object can be used anywhere you have PeopleCode, that is, in Application Engine PeopleCode, record field PeopleCode, and so on.

Session Class Built-in Function

%Session

GetSession

Session Class Methods

In this section, we discuss the Session class methods. The methods are discussed in alphabetical order.

Connect

Syntax

(version, {"EXISTING" | //PSoftApplicationServer:JoltPort}, UserID, Password, ExtAuth)

Description

The Connect method connects a session object to a PeopleSoft application server.

Note. This function remains for backward compatibility only. Use the %Session system variable to return a reference of a session object instead.

If you already have a PeopleSoft session running (you are already connected to a PeopleSoft application server and are running a component, and so on) you must specify EXISTING, and not the //PSoftApplicationServer:JoltPort. Typically, use the parameter value of EXISTING from PeopleCode, not from other language environments.

If you are using an existing connection to the application server, you cannotspecify a different user ID or password. If you don’t specify these values as NULL string, you must specify the exact same user ID (and password) as the one that originally started the session.

Parameters

version	Specify the API version that the client is expecting. Future releases will use this parameter. For now, you must use a 1.
EXISTING \| //PSoftApplicationServer:JoltPort	Specify EXISTING if you’re currently connected to an application server. Otherwise, specify the named application server machine and the IP port to connect to on an application server machine.
UserID	Specify the PeopleSoft user ID to use for the connection. This must be a valid user ID. If you are using an existing connection, you can specify a NULL string (that is, two quotation marks with no blank space between them ("")) for this parameter.
Password	Specify the password associated with the user ID to use for the connection. This must match the password assigned for this user ID exactly. If you are using an existing connection, you can specify a NULL string (that is, two quotation marks with no blank space between them ("")) for this parameter.
ExtAuth	This parameter is required, but it is unused in this release. You must enter a 0 for this parameter.

Returns

A Boolean value: True if the connection completed successfully, False otherwise.

Example

The following is an example of the code you would use if there is an existing connection to the application server:

Local ApiObject &MYSESSION;

&MYSESSION = GetSession();
&MYSESSION.Connect(1, "EXISTING", "", "", 0);

The following is an example connecting to a PeopleSoft system using a Visual Basic program. It first checks for error messages. If there are any errors, the text of the error is displayed to the user.

On Error GoTo eMessage

    Dim oSession As Object
    Dim oPSMessage As Object
           
    Dim oBC As Object
    
    Set oSession = CreateObject("PeopleSoft.Session")

    oSession.Connect 1, "//PSSOFTO061998:7000", "PTDMO", "PTDMO", 0

    &lsquo;Application Specific Processing

eMessage:
    If (oSession.PSMessages.Count > 0) Then
        For i = 1 To oSession.PSMessages.Count
           Set oPSMessage = oSession.PSMessages.Item(i)
           MsgBox (oPSMessage.Text)
        Next i
    End If

See Also

%Session.

Disconnect

Syntax

Disconnect()

Description

The Disconnect method disconnects the session associated with the session object executing the method from that PeopleSoft session.

This method returns a Boolean value: True if successfully disconnected, False otherwise.

API Instantiation Methods

The following is a list of the other methods used with the session object to instantiate an API object such as a Component Interface, a tree structure, and so on.

Component Interface:

FindCompIntfcs(partial_name): returns a collection of Component Interfaces based on the partial Component Interface name.
GetCompIntfc(COMPINTFC.componentname): returns a Component Interface object.

Portal Registry:

FindPortalRegistries(partial_name): returns a collection of PortalRegistry objects.
GetLocalNode(): returns a node object.
GetNodes(): returns a collection of node objects.
GetPortalRegistry(): returns a PortalRegistry object.
GetRemoteNodes(): returns a collection of node objects.
GetActualRemoteNodes(): returns a collection of remote node objects only.

Query:

FindQueryDBRecords():returns a reference to a QueryDBRecord collection, filled with zero or more records.
FindQueries():returns a reference to a Query collection, filled with zero or more queries.
FindQueriesDateRange(StartDateString, EndDateString): returns a reference to a Query collection, filled with zero or more queries that match the specified date range.
GetQuery(): returns a query object.
GetQuerySecurityProfile(): a QuerySecurityProfile object.
SearchQueryDBRecord(SearchType, Pattern, CaseSensitive): returns a QueryDBRecord collection.
SearchPrivateQueries(QueryType, SearchType, Pattern, CaseSensitive): a query collection.
SearchPublicQueries(QueryType, SearchType, Pattern, CaseSensitive): a query collection.

Search:

GetSearchIndexes(): returns a SearchIndexes collection.
GetSearchQuery(): returns a search query object.

Tree:

GetTree(): returns a tree object.
GetTreeStructure(): returns a tree structure object.

Session Class Properties

This section describes the Session class properties. The properties are discussed in alphabetical order.

ErrorPending

Description

This property indicates whether there are any error messages pending for the API that is currently running. After this property has been set, it returns True until the PSMessages collection is cleared (or deleted.)

This property is read-only.

Example

If &MYSESSION.ErrorPending Then
   &COUNT = &MYSESSION.PSMessages.Count;
   For &I = 1 To &COUNT
      &ERROR = &MYSESSION.PSMessages.Item(&I);
      &TEXT = &ERROR.Text;
      WinMessage("Error text " | &TEXT);
   End-For;

&MYSESSION.PSMessages.DeleteAll();

PSMessages

Description

This property returns a reference to a PSMessages collection object. If there are no messages, this property returns an object reference to PSMessages with a count of zero.

This property is read-only.

Example

If &SESSION.PSMessages.Count > NULL Then /* there are messages do processing */ End-if;

See Also

PSMessages Collection Methods.

PSMessagesMode

Description

This property is used to determine how messages are output. This property takes either a numeric value or a constant. The default value is 1 (%PSMessages_CollectionOnly).

You must set this property before you check the type of message, that is, you can't check the type of message, then decide how it's displayed.

This property sets the value for the session. You can change modes during a session, such as, if you're starting a Component Interface. However, after you run the Component Interface, you should set the value back. For example:

&OldMode = &Session.PSMessageMode;
&Session.PSMessagesMode = 1;
...
&Session.PSMessagesMode = &OldMode;

You can specify either a numeric value or a constant. The values are:

Numeric Value	Constant Value	Description
0	%PSMessages_None	None.
1	%PSMessages_CollectionOnly	PSMessage Collection only (default).
2	%PSMessages_MessageBoxOnly	Message box only.
3	%PSMessages_Both	Both collection and message box.

Note. If you set this property to 0 (%PSMessages_None), all messages are ignored. Use this option with caution.

This property is read-write.

Example

Local ApiObject &SESSION;

&SESSION = %Session;
&MMODE = &SESSION.PSMessagesMode;
&SESSION.PSMessagesMode = %PSMessages_MessageBoxOnly;

RegionalSettings

Description

This property returns a reference to a RegionalSettings collection object.

This property is read-only.

See Also

Regional Settings Class Properties.

Repository

Description

This property returns a reference to a Repository object.

See Also

API Repository

SuspendFormatting

Description

This property turns off the PeopleSoft automatic formatting when coercing a string into a field. Formatting is typically necessary for external Component Interface users (such as for a Visual Basic program,) yet should be suspended for a PeopleCode program. You should not typically need to set this value yourself, as it’s set appropriately based on where the session object is created.

This property takes a Boolean value: True means formatting is suspended, False means it isn’t suspended. If you start your session from a PeopleCode program, the default for this property is True. If you don’t start the session from a PeopleCode program, the default is False.

This property is read-write.

TraceSettings

Description

This property returns a reference to a TraceSettings collection object.

This property is read-only.

See Also

Trace Setting Class Properties.

WarningPending

Description

This property indicates whether there are any warning messages pending for the API that is currently running.

This property is read-only.

Accessing a PSMessages Collection

Use the PSMessages collection to return all of the messages that occur during the session. The following example finds all the messages listed in the PSMessages collections when the Component Interface Save methods fails. The example assumes that &CI is the Component Interface object reference.

If Not &CI.Save() Then
   /* save didn&rsquo;t complete */
   &COLL = &MYSESSION.PSMessages;
   For &I = 1 to &COLL.Count
      &ERROR = &COLL.Item(&I);
      &TEXT = &ERROR.Text;

      /* do message processing */

   End-For;
&COLL.DeleteAll(); /* Delete all messages in queue */
End-if;

As you evaluate each message, delete it from the PSMessages collection. Or, delete all the messages in the queue at once using DeleteAll.

If there are multiple errors when saving a Component Interface, all errors are logged to the PSMessages collection, not just the first occurrence of an error.

Considerations for Declaring Collections

You must declare all collections for C/C++ and COM as objects, or else you receive errors at runtime.

PSMessages Collection Methods

This section describes the PSMessages collection methods. The methods are discussed in alphabetical order.

DeleteAll

Syntax

DeleteAll()

Description

The DeleteAll method deletes all the PSMessage objects in the PSMessages collection executing the method. You should use this property after you have processed all the errors in the collection. This method also resets the status of ErrorPending to False.

Returns

This method returns a Boolean value: True if all PSMessages in the collection were successfully deleted, False otherwise.

See Also

Session class: ErrorPending property.

DeleteItem

Syntax

DeleteItem(number)

Description

The DeleteItem method deletes the PSMessage object that exists at the number position in the PSMessages collection executing the method.

Parameters

number

Specify the position number in the collection of the PSMessage object that you want to delete. All other items within the collection are renumbered.

Returns

This method returns a Boolean value: True if the PSMessage object was successfully deleted, False otherwise.

Example

&ERROR.DeleteItem(&I);

First

Syntax

First()

Description

The First method returns the first PSMessage object in the PSMessages collection object executing the method.

Example

&ERROR = &PSMESSAGE.First();

Item

Syntax

Item(number)

Description

The Item method returns a PSMessage object that exists at the number position in the PSMessages collection executing the method

Parameters

number

Specify the position number in the collection of the PSMessage object that you want returned.

Returns

A reference to a PSMessage object, NULL otherwise.

Example

&PSMSGCOL = &SESSION.PSMessages;
For &I = 1 to &PSMSGCOL.Count;
   &PSMESSAGE = &PSMSGCOL.Item(&I);
   /* do error processing */
End-For;

Syntax

Next()

Description

The Next method returns the next PSMessage object in the PSMessages collection object executing the method. You can use this method only after you have used either the First or Item methods: otherwise the system doesn’t know where to start.

PSMessages Collection Property

This section describes the PSMessages collection property.

Count

Description

This property returns the number of PSMessage objects in the PSMessages collection object.

This property is read-only.

Example

&COUNT = &PSMESSAGE.Count;

PSMessage Class Properties

This section describes the PSMessages class properties. The properties are discussed in alphabetical order.

ExplainText

Description

This property returns the explanation text (as a string) for the error message associated with the PSMessage object. You can use this property in conjunction with the MessageNumber property (which contains the error message number) and the MessageSetNumber property (which contains the error message set number.)

Note. ExplainText should be accessed only when necessary because it requires a second database read or application server roundtrip.

This property is read-only.

MessageNumber

Description

This property returns the error message number (as a number) for the error message associated with the PSMessage object. You can use this property in conjunction with the MessageSetNumber property (which contains the error message set number) and the ExplainText property (which contains text explaining the error.)

This property is read-only.

MessageSetNumber

Description

This property returns the error message set number (as a number) for the error message associated with the PSMessage object. You can use this property in conjunction with the MessageNumber property (which contains the error message number) and the ExplainText property (which contains text explaining the error.)

This property is read-only.

MessageType

Description

This property indicates the type of the message, whether it's from the message catalog, if it's a warning, error, or information error.

This property returns a numeric value. The values are:

Value	Description
0	Message is not a message catalog entry or there is no message.
1	Message has a severity of Error.
2	Message has a severity of Warning.
3	Message has a severity of Information.

This property is read-only.

Source

Description

This property returns a string indicating the actual field that’s in error. The syntax of the string that’s returned is as follows:

ComponentInterfaceName.[CollectionName(Row).[CollectionName(Row).[CollectionName⇒
(Row)]]].PropertyName

This string is also returned as part of the Text property.

For example, suppose you had a Component Interface named EMPL_CHKLST_CI.

Sample Component Interface

The following indicates that the first level field, EMPLID, has the error:

EMPL_CHKLST_CI.EMPLID

The Component Interface EMPL_CHKLST_BC has a data collection (scroll) called EMPL_CHKLST_ITM. Suppose that it has 3 rows, and the STATUS_DT field was in error. The Source property would return the following string:

EMPL_CHKLST_CI.EMPL_CHKLST_ITM(3).STATUS_DT

You can use the Source property in conjunction with the MessageNumber property (which contains the error message number), the MessageSetNumber property (which contains the error message set number), the ExplainText property (which contains text explaining the error), and the Text property (which contains the text of the message.)

This property is read-only.

Example

The following example code finds the error messages and displays them to the user. It finds the field that caused the error and displays that also.

Local ApiObject &PSMESSAGE;
Local Boolean &FIND;
Local string &SOURCE, &FIELD, &TEXT;
Local number &START, &LEN, &NSTART, &FLEN;
.
.
.
For &I = 1 to &SESSION.PSMessages.Count;
   &PSMESSAGE = &SESSION.PSMessages.Item(&I);
   /* only display errors, not warnings, to user */
   If &PSMESSAGE.Type = 1 Then
      &TEXT = &PSMESSAGE.Text;
      /* find name of field in error */
      &SOURCE = &PSMESSAGE.Source;
      &LEN = Len(&SOURCE);
      /* find last dot before field */
      &FIND = False;
      &START = Find(".", &SOURCE);
      While Not (&FIND)
         &NSTART = Find(".", &SOURCE, &START + 1);
            If &NSTART = 0 Then
               &FIND = True;
            Else
               &START = &NSTART;
            End-If;
         End-While;
         &FLEN = &LEN - &START;
         &FIELD = Substring(&SOURCE, &START + 1, &FLEN);
         /* display text and field to user */
         Winmessage("You received the following error: " | &TEXT | "For field " |⇒
 &FIELD);
   End-If;
End-For;

Text

Description

This property returns the text of the message (as a string) for the error message associated with the PSMessage object. It also includes a contextual string that contains the name of the field that generated the error. The contextual string has the following syntax:

{ComponentInterfaceName.[CollectionName(Row).[CollectionName(Row).[CollectionName⇒
(Row)]]].PropertyName}

The contextual string (by itself) is available using the Source property of the PSMessage.

You can use the Text property in conjunction with the MessageNumber property (which contains the error message number), the MessageSetNumber property (which contains the error message set number), and the ExplainText property (which contains text explaining the error.)

This property is read-only.

Example

Local ApiObject &MYSESSION, &COL, &ERROR;
Local string &TEXT;
.
.
.
If &MYSESSION.ErrorPending Then 
   /* received error */
   &COLL = &MYSESSION.PSMessages;
   For &I = 1 to &COLL.Count
      &ERROR = &COLL.Item(&I);
      &TEXT = &ERROR.Text;
         /* do error processing */
      End-For;
End-if;

This property specifies the character used to separate the fractional of the number from the whole. This property takes a string value. The default value for this property is ".".

Note. If you change the value of this property to a comma (,), you should adjust the DigitGroupingSymbol to a different character or some applications may not operate correctly.

This property is read-write.

DigitGroupingSymbol

Description

This property specifies the character used as a thousand or other grouping separator. This property takes a string value. The default value for this property is ",".

This property is read-write.

LanguageCD

Description

This property specifies the language to be used for the transaction. This property takes a string value. The default value for this property is the user’s base language.

This property is read-write.

Note. If you change this value dynamically using PeopleCode, this value will not change back to the original value when you disconnect. You must manually set it back to the original value.

Example

The following example sets the language code, then at the end of the program, sets it back to the original value.

Local ApiObject &SESSION;
Local ApiObject &CI;
 
/** Get Session ApiObject **/
&SESSION = %Session;

/** Get Message ApiObject **/
&MSG = %IntBroker.GetMessage();
&RS = &MSG.GetRowset();

/** Get Component Interface **/
&CI = &SESSION.GetCompIntfc(compIntfc.NAMES_CI);

&REG_LNG = &SESSION.RegionalSettings.LanguageCd;

For &TRANS_NUM = 1 To &RS.RowCount

/** Store Language Code in Temp Var **/
&LNG = &RS(&TRANS_NUM).PSCAMA.LANGUAGE_CD.Value;

/** Set the Language for this Transaction **/
If &LNG <> &REG_LNG Then 
&SESSION.RegionalSettings.LanguageCd = &LNG;
End-If;
/* application specific processing */

&SESSION.RegionalSettings.LanguageCd = &REG_LNG;
&SESSION.Disconnect();
End-For

UseLocalTime

Description

This property specifies whether the local time zone of the client should be used to format time fields. This property takes a Boolean value. The default value is True.

This property is read-write.

1159Separator

Description

This property specifies the morning designator. This property takes a string value up to five characters. The default value is AM.

Use the 2359Separator property to specify the afternoon designator.

This property is read-write.

Considerations Using the 1159Separator Property

You cannot use this property as you would other properties. You must use the ObjectGetProperty function for accessing the property. For example:

Local ApiObject &SESSION;
Local ApiObject &reg;

/** Get Session ApiObject **/
&SESSION = %Session;
&reg = &SESSION.RegionalSettings;

&REG_LNG = &SESSION.RegionalSettings.LanguageCd;
&MornDesigination = ObjectGetProperty(&reg, "1159Separator");

See Also

ObjectGetProperty

2359Separator

Description

This property specifies the afternoon designator. This property takes a string value up to five characters. The default value is PM.

Use the 1159Separator property to specify the morning designator.

This property is read-write.

Considerations Using the 2359Separator Property

You cannot use this property as you would other properties. You must use the ObjectGetProperty function for accessing the property. For example:

Local ApiObject &SESSION;
Local ApiObject &reg;

/** Get Session ApiObject **/
&SESSION = %Session;
&reg = &SESSION.RegionalSettings;

&REG_LNG = &SESSION.RegionalSettings.LanguageCd;
&AfternoonDesigination = ObjectGetProperty(&reg, "2359Separator");

This property is part of the SQL trace and sets the Sybase Fetch Information value.

This property takes a Boolean value: True means the trace will be run, False means it won’t.

This property is read-write.

TraceFile

Description

This property specifies the location of the trace file (that is, PeopleTools Trace File value.)

This property takes a string value.

This property is read-write.