Message Class

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

• Application Message PeopleCode.

• Data type of a message object.

• Scope of a message object.

• Message object population.

• Error handling.

• Message class built-in functions.

• Message class methods.

• Message class properties.

Understanding Message Class

You can create the following types of messages in PeopleSoft Application Designer:

• Rowset-based messages, which use record definitions to create a hierarchical structure for the data. These are generally used for data from applications, pages, components, and so on.

• Nonrowset-based messages, which do not use record definitions. They are 'empty' structures, generally used for XML or SOAP messages.

Use the PeopleCode message class to create and access rowset-based messages. Rowset-based messages are self-describing messages that contain application data. They store the data passed between systems.

Message definitions are simply multi-level structures, consisting of records. Publising a message basically stores the message in a set of relational tables, the application messaging queue.

Messages can be published (created) using an Application Engine program or component. Subscription PeopleCode programs subscribe to messages and process the data.

The Message class is built on top of the Rowset, Row, Record, and Field classes, so the PeopleCode written to populate or access a Message looks similar to PeopleCode written to populate or access the Component buffer.

See Also

Defining Message Definitions

Accessing the Data Buffer

Messaging PeopleCode Events

The following PeopleCode events are associated with messages:

• OnRouteSend

• OnRouteReceive

• OnRequest

• Subscription

• OnAckReceive

• OnSend

OnRouteSend and OnRouteReceive: These PeopleCode events are used with routing rules to determine where the messages are routed to and received from.

OnRequest: This PeopleCode event is used with synchronous messages, when a message has been received and requires a reply.

Subscription: This PeopleCode event is used when the message is subscribed to. Use this for your subscription processing for validating and loading message data.

OnAckReceive: This PeopleCode event is used for asyncronous messages to change the status of the message (such as RETRY, DONE, or ERROR) based on the returned (successful) acknowledgement when it posted to the gateway. Use this when sending to a third party or when receiving a SOAP response, because though the delivery is successful, the content data could be in error.

OnSend: This PeopleCode event is used for both synchronous and asynchronous messages to overrride the connector properties before sending the message to the gateway.

See Also

Understanding Integration PeopleCode

Data Type of a Message Object

Messages are declared using the Message data type. For example,

Local Message &MSG;

Global Message &MyMessage;

Scope of a Message Object

A message object can only be instantiated from PeopleCode. This object can be used anywhere you have PeopleCode, that is, in message subscription PeopleCode, Component Interface PeopleCode, record field PeopleCode, and so on.

See Also

Defining Message Definitions

Message Object Population

After you’ve declared and instantiated your message object, you want to populate it with data. If your data is coming from Component buffers, populating your message is easy.

A message definition contains a hierarchy of records. A Component buffer contains a hierarchy of records. If you want to copy data from a Component buffer rowset to a message, the structure of the message and the component must be the same. That is, if you have a record at level two in your message and you want that data, you must have the same level zero and level one records in your message as in your component.

For example, suppose your component had the following structure (that is, that PO_INFO and PO_LINE are at the same level, and PO_DETAIL is the child of PO_INFO):

PO_HEADER
   PO_LINE
   PO_INFO
      PO_DETAIL

To include the information in the PO_DETAIL record, you must have at least the following record structure in your message:

PO_HEADER
   PO_INFO
      PO_DETAIL

Any records that are in the page that aren’t in the message (and vice-versa) are ignored.

After you get your message object, you can create a rowset from it. This rowset has the same structure as the message. If the message is empty, the rowset has no data. If the message has data, the rowset is automatically populated.

The following example is the simplest way of populating a message with data. This assumes that the structure of the message is the same as the structure of the page.

/* this gets all the data in the Component buffer */

&RS = GetLevel0();

/* this instantiates a message object */

&MSG = CreateMessage(MESSAGE.MY_MESSAGE);

   /* creates a rowset with the same structure as the message */

&MSG_RS = &MSG.GetRowset();

   /* this copies all the data from the page to the message */

&RS.CopyTo(&MSG_RS);

/* this publishes the message */

&MSG_RS.Publish();

A message rowset is the same as a Component buffer rowset, or any other rowset. It is composed of rows, records, and fields. Suppose you didn’t want to get all the data from the Component buffer, but instead wanted to populate just a particular record in your message.

To access a record in a message rowset is the same as accessing a record in a Component buffer rowset. You must instantiate the rowset, then specify the row before you can access the record.

The following selects values into a record, then uses the record method CopyFieldTo to copy from the Component buffer record to the message record.

Local SQL &LN_SQL;
Local Message &STOCK_MSG;
Local Rowset &HDR_RS, &LN_RS;
Local Record &LN_REC, &ln_rec_msg;

&STOCK_MSG = CreateMessage(Message.STOCK_REQUEST);
&HDR_RS = &STOCK_MSG.GetRowset();
&LN_REC = CreateRecord(Record.DEMAND_INF_INV);

&LN_SQL = CreateSQL("Select * from PS_DEMAND_INF_INV where  BUSINESS_UNIT= :1 and ORDER_NO = :2", &BUSINESS_UNIT, &ORDER_NO);

&J = 1;
While &LN_SQL.Fetch(&LN_REC)

  /* copy data into the Level 1 of &STOCK_MSG object */
	  &LN_RS = &HDR_RS(&I).GetRowset(1);

  If &J > 1 Then
    &LN_RS.InsertRow(&J - 1);
  End-If;

  &ln_rec_msg = &LN_RS.GetRow(&J).GetRecord(Record.DEMAND_INF_INV);
  &LN_REC.CopyFieldsTo(&ln_rec_msg);
  &J = &J + 1;
End-While;

This section also discusses items to keep in mind when:

• Populating a rowset from a message.

• Publishing and subscribing to partial records.

• Subscribing to character fields.

Considerations When Populating a Rowset From a Message

Suppose your message had two rowsets, one at level zero, a second at level one. In the message, only the level zero rowset contains any data. When you use GetRowset to create a rowset for the entire message, the rowset at level one will contain an empty row, even if there isn’t any data in it. (This is standard behavior for all rowsets.) However, you can use the IsChanged property on the record object to determine the status of the data.

The following subscription PeopleCode example traverse the Rowset. (Notice the use of ChildCount, ActiveRowCount, and IsChanged properties).

‘. . .’ is where application specific code would go.

&MSG_ROWSET = &MSG.GetRowset();
For &A0 = 1 To &MSG_ROWSET.ActiveRowCount

/***************************/
/* Process Level 1 Records */
/*-------------------------*/

  If &MSG_ROWSET(&A0).ChildCount > 0 Then
	  For &B1 = 1 To &MSG_ROWSET(&A0).ChildCount

	    &LEVEL1_ROWSET = &MSG_ROWSET(&A0).GetRowset(&B1);
	      For &A1 = 1 To &LEVEL1_ROWSET.ActiveRowCount
        If &LEVEL1_ROWSET(&A1).GetRecord(1).IsChanged Then
          . . .

/***************************/
/* Process Level 2 Records */
/*-------------------------*/

          If &LEVEL1_ROWSET(&A1).ChildCount > 0 Then
          For &B2 = 1 To &LEVEL1_ROWSET(&A1).ChildCount
            &LEVEL2_ROWSET = &LEVEL1_ROWSET(&A1).GetRowset(&B2);
              For &A2 = 1 To &LEVEL2_ROWSET.ActiveRowCount
                If &LEVEL2_ROWSET(&A2).GetRecord(1).IsChanged Then
                .  .  .

/***************************/
/* Process Level 3 Records */
/*-------------------------*/

                If &LEVEL2_ROWSET(&A2).ChildCount > 0 Then
                  For &B3 = 1 To &LEVEL1_ROWSET(&A2).ChildCount
                    &LEVEL3_ROWSET = &LEVEL2_ROWSET(&A2).GetRowset(&B3);
                    For &A3 = 1 To &LEVEL3_ROWSET.ActiveRowCount
                      If &LEVEL3_ROWSET(&A3).GetRecord(1).IsChanged Then
                      .  .  .

                      End-If; /* A3 - IsChanged */
                    End-For; /* A3 - Loop */
                  End-For; /* B3 - Loop */
                End-If; /* A2 - ChildCount > 0 */

/*--------------------------------*/
/* End of Process Level 3 Records */
/**********************************/

              End-If; /* A2 - IsChanged */
            End-For; /* A2 - Loop */
          End-For; /* B2 - Loop */
        End-If; /* A1 - ChildCount > 0 */

/*--------------------------------*/
/* End of Process Level 2 Records */
/**********************************/

      End-If; /* A1 - IsChanged */
    End-For; /* A1 - Loop */
   End-For; /* B1 - Loop */
  End-If; /* A0 - ChildCount > 0 */

/*--------------------------------*/
/* End of Process Level 1 Records */
/**********************************/

End-For; /* A0 - Loop */

Considerations for Publishing and Subscribing to Partial Records

If you've selected to not publish all the fields in the message, you must be careful when inserting that data into a record.

Deselecting the Include check box in the message definition means that the field is excluded from the message definition.

• The field won't be included when generating an XML document (when publishing a message.)

• If the field is present in the XML (that is, it wasn't excluded from the published message) it is ignored by the subscribing system.

When you insert the data from the message into the database, you must set the values for the fields that aren't in the message. You can use the SetDefault Record class method to do this. You could also use a Component Interface based on the component the message was created from to leverage the component defaults.

See the Designing Component Interface Subscribe EIP for more information about using Component Interfaces in subscription.

See Also

SetDefault

Considerations When Subscribing to Character Fields

If a message definition has character fields that are defined as uppercase, when the message is subscribed to, character data for those fields is automatically converted to uppercase.

Message Segments

To make processing more efficient, you can divide a large message into pieces using message segments. Generally, you only divide asynchronous messages into segments.

Message nodes can be specified as “segment aware”. If a node is not segment aware and you send an asynchronous message that is segmented to it, you received an error message when viewing the error message log in message details on the message monitor. No publication contracts are created. If you send a synchronous message that is segmented to a node that is not segment aware, you receive an error.

There are several methods for creating, updating, and deleting segments. There are also two properties that you need to take into consideration when working with segments.

If you specify the SegmentsByDatabase property as false, you can only have the configured number defined in PSADMIN (Message Segment From DB). If you specify this property as true, you can have as many segments as you need.

The SegmentsByDatabase property also specifies whether the segments are kept in memory or written to the database when they are received. If you specify true, the segments are automatically written to the database. If you specify false, the segments are held in memory. If you specify true, then cancel out of the program processing the segments, the changes are not committed to the database.

The SegmentUnOrder property is only applicable for asynchronous messages. If you specify the SegmentUnOrder property as true, the receiving node processes the segments in parallel.

Note. You should use DeleteSegment and UpdateSegment only when writing to memory, or when SegmentsByDatabase is set to False. These methods do not work when writing to the database, or when SegmentsByDatabase is set to True.

The following is an example of how to use the segment properties and methods to send a segmented message. Note that there are only two CreateNextSegment calls. By default the first segment is automatically created. The first time you use CreateNextSegment, the message is split into two segments. The next time, you add a third segment. You don't need to call CreateNextSegment to access the third segment, it's automatically generated.

Local Message &MSG;
Local Rowset &FLIGHT_PROFILE, &RS;
Local boolean &Bo, &Stuff;
Local string &lip;

&nodes = CreateArray("");
&nodes[1] = "QE_YO";
&nodes[2] = "QE_STUFF";

QE_FLIGHTDATA.QE_ACNUMBER.Value = QE_FLIGHTDATA.QE_ACNUMBER + 1;

&FLIGHT_PROFILE = GetLevel0();

&MSG = CreateMessage(Message.QE_FLIGHTPLAN);

/* the next lines copy the rowset into the first segment */

&MSG.CopyRowset(&FLIGHT_PROFILE);
&MSG.CreateNextSegment();

/* This copies the next portion of the rowset into the next segment */

&MSG.CopyRowset(&FLIGHT_PROFILE);
&MSG.CreateNextSegment();

/* This copies the last portion of the rowset into the third segment */

&MSG.CopyRowset(&FLIGHT_PROFILE);

/* This specifies that the message segments can be processed separately */

&MSG.IBInfo.SegmentsUnOrder = True;

&MSG.publish();

The following is an example of receiving a segmented message. This would be found in a subscription PeopleCode program:

Local Message &MSG;
Local Rowset &rs, &rs1;
Local Record &FLIGHTDATA, &REC;

Local string &acnumber_value, &msi_sensor_value, &ofp_value, &actype_value, &callsign_value, &squadron_value, &comm1_value,
&comm2_value, &ecm_value;

Local XmlDoc &xmldoc;
Local string &yo;
Local boolean &bo;

&CRLF = Char(13) | Char(10);

&MSG = GetMessage();

/* It is very important to set the rowset to null for every iteration */

/* Also, you may want to verify if the segment count is
greater than 10, and if it is, set the SegmentsByDatabase property to True */

For &i = 1 To &MSG.SegmentCount
   &rs = Null;
   &MSG.GetSegment(&i);
   
   &rs = &MSG.GetRowset();
   &REC = &rs(1).QE_FLIGHTDATA;
   
   &FLIGHTDATA = CreateRecord(Record.QE_FLIGHTDATA);
   &REC.CopyFieldsTo(&FLIGHTDATA);
   
   /* Parse out Message Data */
   &acnumber_value = &FLIGHTDATA.QE_ACNUMBER.Value;
   &msi_sensor_value = &FLIGHTDATA.QE_MSI_SENSOR.Value;
   &ofp_value = &FLIGHTDATA.QE_OFP.Value;
   &actype_value = &FLIGHTDATA.QE_ACTYPE.Value;
   &callsign_value = &FLIGHTDATA.QE_CALLSIGN.Value;
   &squadron_value = &FLIGHTDATA.QE_SQUADRON.Value;
   &comm1_value = &FLIGHTDATA.QE_COMM1.Value;
   &comm2_value = &FLIGHTDATA.QE_COMM2.Value;
   &ecm_value = &FLIGHTDATA.QE_ECM.Value;
   
   &outstring = "Send Async FLight test";
   
   /* Construct Output String */
   &outstring = &outstring | &acnumber_value | &CRLF | &msi_sensor_value | &CRLF | &ofp_value | &CRLF | &actype_value | &CRLF
| &callsign_value | &CRLF | &squadron_value | &CRLF | &comm1_value | &CRLF | &comm2_value | &CRLF | &ecm_value;
   
   /* Log Output String into page record */
   &FLIGHTDATA.GetField(Field.DESCRLONG).Value = &outstring;
   
   SQLExec("DELETE FROM PS_QE_FLIGHTDATA");
   &FLIGHTDATA.Insert();
   
End-For;

See Also

CreateNextSegment

SegmentsByDatabase

SegmentsUnOrder

Configuring Nodes and Transactions

Error Handling

In your subscription PeopleCode, you may want to validate the information received in the message. If you find that the data isn’t valid, use Exit(1) to end your PeopleCode program. This sets the status of the message to ERROR, logs any error messages to the Application Message Queues, and automatically rolls back any database changes you may have made.

There are many ways to validate the data and capture the error messages:

• Use ExecuteEdits on the message object

• Use ExecuteEdits on the record object

• Use a Component Interface

See Designing Component Interface Subscribe EIP for more details.

Write your own validation PeopleCode in the Subscription program:

The following example validates the Business Unit of a message against an array of valid BU's:

For &I = 1 To &ROWSET.RowCount;

  &POSITION = &BUArray.Find(&ROWSET(&I).GetRecord(1).BUSINESS_UNIT.Value);
  If &POSITION = 0 Then
    &Status = "ERROR: BU not Found or not Active";
    &ROWSET(&I).BCT_ADJS_MSG_VW.BUSINESS_UNIT.IsEditError = True;
    &ROWSET(&I).BCT_ADJS_MSG_VW.BUSINESS_UNIT.MessageSetNumber = 11100;
    &ROWSET(&I).BCT_ADJS_MSG_VW.BUSINESS_UNIT.MessageNumber = 1230;
/* The error message 11100-1230 reads: This Business Unit is */
/* not a valid, open, Inventory Business Unit */

  End-If;

End-For;

In the calling PeopleCode, the program calls Exit(1) based on the value of &Status.

Note. All errors for Subscription PeopleCode get logged to the application message error table, not to the PSMessages collection (on the session object.)

See Also

ExecuteEdits

ExecuteEdits

Processing Inbound Errors

Message Class Built-In Functions

AddSystemPauseTimes

ConnectorRequest

ConnectorRequestURL

CreateMessage

CreateWSDLMessage

DeleteSystemPauseTimes

GetMessage

GetSyncLogData

InboundPublishXmlDoc

IsMessageActive

PingNode

ReturnToServer

SetChannelStatus

SetMessageStatus

Message Class Methods

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

Clone

Syntax

Clone()

Description

The Clone method creates an identical copy of the message, copying the data tree of the message executing the method. The Clone function sets the following properties for the resulting message object, based on the values set for the message definition:

• Name

• ChannelName

• IsActive

Other properties are set when the message is published or subscribed to (PubID, SubName, and so on), or are dynamically generated at other times (Size, IsEditError, and so on.)

Clone creates a unique version of the message. If the original message changes, it is not reflected in the cloned object.

Parameters

None.

Returns

A message object.

Example

Clone could be used in a Hub and Spoke messaging environment. The Hub node uses this method during subscription processing to publish a copy of the messages it receives from the Spokes.

&Msg = GetMessage();
&Rowset = &Msg.GetRowset();
&Clone = &Msg.Clone();

&Clone.Publish();

The hub's publication routing rules are then used to determine which spokes receive the message.

See Also

Message class: CopyRowset method.

CreateMessage

Assigning Objects

CopyRowset

Syntax

CopyRowset(source_rowset [, record_list]);

Where record_list is a list of record names in the form:

RECORD.source_recname1, RECORD.target_recname1 

[, RECORD.source_recname2, RECORD.target_recname2]. . .

Description

The CopyRowset method copies all data from the source rowset to the like-named fields in the message object executing the method. This is an easy way to populate a message with data from a component.

Note. CopyRowset copies all the data, including rows that haven’t been modified. If you want to copy only data that has changed in some way, use the CopyRowsetDelta method.

See Message class: CopyRowsetDelta method.

When the record names in the message and component do not match exactly, use the optional record_list to specify the records to be copied from the component into the message.

When you use the CopyRowset method to copy the contents from the source rowset to the message object, you are creating a unique copy of the object. If you change the original rowset, the message object is not changed.

Note. You can execute CopyRowset against a message only once. After a message is populated, any other CopyRowsets are ignored. If you have to populate different levels of a message rowset separately, you can use the CreateRowset method to create a rowset that has the same structure as your message, populate the created rowset, then use CopyRowset to populate your message. You can also use the Rowset CopyTo method to populate a message rowset, then populate the PSCAMA record by hand.

Parameters

Returns

None.

Example

The following example copies an entire component into a message object.

&Msg = GetMessage();
&Rowset = &Msg.GetRowset()
&Component_Rowset = GetLevel0();
&Msg.CopyRowset(&Component_Rowset);

The following example copies a header/line page rowset into a header/line message object, using the record_list because the record names don't match:

&Msg = GetMessage();
&Rowset= &Msg.GetRowset();
&Component_Rowset = GetLevel0();
&Msg.CopyRowset(&Component_Rowset, RECORD.PO_HDR_VW, RECORD.PO_HDR, RECORD.PO_LINE_VW, RECORD.PO_LINE);

See Also

Message class: CopyRowsetDelta method.

GetRowset

Rowset Class

Fill

CopyRowsetDelta

Syntax

CopyRowsetDelta(source_rowset [, record_list]);

Where record_list is a list of record names in the form:

[RECORD.source_recname1, RECORD.target_recname1 

[, RECORD.source_recname2, RECORD.target_recname2]]. . .

Description

The CopyRowsetDelta method copies rows of data that have changed from the source rowset to the like-named records and like-named fields in the message object executing the method.

Note. CopyRowsetDelta copies all the like-named fields from the changed rowinto the message. It is not copying just the changed like-named fields.

When the record names in the message and component do not match exactly, use the optional record_list to specify the records to be copied from the component into the message. The specified target records must be records in your message, while the specified source records must be records in a rowset that exists in the data buffer and is populated.

This is an easy way to populate a message when the records in the message match the records in the component that the message is published from.

In addition, the CopyRowsetDelta method sets the AUDIT_ACTN field in the PSCAMA table for every row in the message. The subscription process can then use PSCAMA.AUDIT_ACTN to determine how to process every row that was published.

The set values match those used in audit trail processing, that is:

• A - Row inserted.

• D - Row deleted.

• C - Row changed (updated), but no key fields changed. The system copies the new value to the Message rowset.

• K - Row changed (updated), and at least one key field changed. The system copies the old value to the Message rowset and the new value (see "N").

• N - Row changed (updated), and at least one key field changed. The system copies the old value to the Message rowset and the new value (see "K").

• "" − blank value means that nothing on that row has changed. This is the default value, and is the value used to tag the parent rows of children that have changed.

Note. If a child row is inserted (or changed or deleted) CopyRowsetDelta also copies the parent row (and the parent row of that row, and so on, up to the top row) so the subscriber has a full picture of the transaction. A blank value is set in the AUDIT_ACTN field for these rows to let the subscriber know they don’t have to take action; the parent rows are there for reference only.

The Audit_Action values "A", "C", "D" are set when a record is added, changed, or deleted, respectively. In some cases such as effective-dated records, the user may change a key field value, such as Effective Date. In response to such an user action, two records are created, one with an Audit_Action value of "N", and the other with Audit_Action value "K". The "N" record has all the new values, while the "K" record retains the old values.

When you use the CopyRowsetDelta method to copy the contents from the source rowset to the message object, you are creating a unique copy of the object. If you change the original rowset, the message object is not be changed.

Note. You can execute CopyRowsetDelta against a message only once. After a message is populated, any other CopyRowsetDeltas are ignored. If you have to populate different levels of a message rowset separately, you can use the CreateRowset method to create a rowset that has the same structure as your message, populate the created rowset, then use CopyRowsetDelta to populate your message. You can also use the Rowset CopyTo method to populate a message rowset, then populate the PSCAMA record by hand.

Parameters

Returns

None.

Example

The following example copies all the changed rows of data from a component into a message object.

&Component_Rowset = GetLevel0();
&Msg.CopyRowsetDelta(&Component_Rowset);

See Also

CopyRowset

PSCAMA

Assigning Objects

Rowset Class

GetRowset

CopyRowsetDeltaOriginal

Syntax

CopyRowsetDeltaOriginal(source_rowset [, record_list]);

Where record_list is a list of record names in the form:

[RECORD.source_recname1, RECORD.target_recname1 

[, RECORD.source_recname2, RECORD.target_recname2]]. . .

Description

The CopyRowsetDeltaOriginal method copies rows of data that have changed from the source rowset to the like-named records and like-named fields in the message. It also copies the original value of the changed rows.

Note. CopyRowsetDeltaOriginal copies all the like-named fields from the changed and original rows into the message. It is not copying just the changed like-named fields.

When the record names in the message and component do not match exactly, use the optional record_list to specify the records to be copied from the component into the message. The specified target records must be records in your message, while the specified source records must be records in a rowset that exists in the data buffer and is populated.

The CopyRowsetDeltaOriginal method sets the AUDIT_ACTN field in the PSCAMA table for every row in the message. The subscription process can then use PSCAMA.AUDIT_ACTN to determine how to process every row that was published.

The set values match those used in audit trail processing, that is:

• A - Row inserted.

• D - Row deleted.

• C - Row changed (updated), but no key fields changed. The system copies the new value to the Message rowset and the original value (see "O" below).

• O - Prior value of changed row. The system copies the new value to the Message rowset and the original value (see "C").

• K - Row changed (updated), and at least one key field changed. The system copies the original value to the Message rowset and the new value (see "N").

• N - Row changed (updated), and at least one key field changed. The system copies the original value to the Message rowset and the new value (see "K").

• "" − blank value means that nothing on that row has changed. This is the default value, and is the value used to tag the parent rows of children that have changed.

Note. If a child row is inserted (or changed or deleted) CopyRowsetDeltaOriginal also copies the parent row (and the parent row of that row, and so on, up to the top row) so the subscriber has a full picture of the transaction. A blank value is set in the AUDIT_ACTN field for these rows to let the subscriber know they don’t have to take action; the parent rows are there for reference only.

The Audit_Action values "A", "C", "D" are set when a record is added, changed or deleted, respectively. When a row is changed, two records are created, one with an Audit_Action of "C", the other with Audit_Action value of "O". The "C" record has all the new values, while the "O" record retains the original values. In some cases such as effective-dated records, a user may change a key field value, such as Effective Date. In response to such an user action, two records are created, one with an Audit_Action value of "N", and the other with Audit_Action value "K". The "N" record has all the new values, while the "K" record retains the original values. The "N"/"K" combination is also created if both a key change and a non-key change is made on the same row of data.

The following table details the output from CopyRowsetDeltaOriginal:

When you use the CopyRowsetDeltaOriginal method to copy the contents from the source rowset to the message object, you are creating a unique copy of the object. If you change the original rowset, the message object is not changed.

Note. You can execute CopyRowsetDeltaOriginal against a message only once. After a message is populated, any other CopyRowsetDeltaOriginal PeopleCode statements are ignored. If you have to populate different levels of a message rowset separately, you can use the CreateRowset method to create a rowset that has the same structure as your message, populate the created rowset, then use CopyRowsetDeltaOriginal to populate your message. You can also use the Rowset CopyTo method to populate a message rowset, then populate the PSCAMA record manually.

Parameters

Returns

None.

Example

Function Update_Dir(&MSGName As string)

  &MSGName = "Message." | &MSGName;
  &MSG = CreateMessage(@(&MSGName));

  &PnlRowset = GetLevel0();
  &MSG.CopyRowsetDeltaOriginal(&PnlRowset);
  &MSG.Publish();

End-Function;

See Also

CopyRowset, CopyRowsetDelta.

PSCAMA

Assigning Objects

Rowset Class

CreateNextSegment

Syntax

CreateNextSegment()

Description

Use the CreateNextSegment method to divide a message into segments. You generally only divide asynchronous messages that contain a large amount of data. This method is used only when creating a message for publication, not after a message has been published.

Parameters

None.

Returns

None.

Example

See Message Segments.

See Also

CreateNextSegment, DeleteSegment, SegmentRestart, UpdateSegment, CurrentSegment, SegmentCount.

DeleteSegment

Syntax

DeleteSegment(SegmentNumber)

Description

Use the DeleteSegment method to delete the specified segment. This method is used only when creating a message for publication, not after a message has been published.

Note. You should use DeleteSegment and UpdateSegment only when writing to memory, or when SegmentsByDatabase is set to False. These methods do not work when writing to the database, or when SegmentsByDatabase is set to True.

Parameters

Returns

None.

See Also

CreateNextSegment, GetSegment, UpdateSegment, CurrentSegment, SegmentCount.

ExecuteEdits

Syntax

ExecuteEdits([editlevels]);

where editlevels is a list of values in the form:

editlevel1 [+ editlevel2] . . .]);

and where editleveln is one of the following system constants:

%Edit_DateRange

%Edit_OneZero

%Edit_PromptTable

%Edit_Required

%Edit_TranslateTable

%Edit_YesNo

Description

The ExecuteEdits method executes the standard system edits on every field for every record in the message executing the method. All edits are based on the record edits defined for the record that the message is based on. The types of edits performed depends on the editlevel. If no editlevel is specified, all system edits defined for the record definition are executed, that is:

• Reasonable Date Range (Is the date contained within plus or minus 30 days from the current date?)

• 1/0 (Do all 1/0 fields only contain 1 or 0?)

• Prompt Table (Is field data contained in the specified prompt table?)

• Required Field (Do all required fields contain data? For numeric or signed fields, it checks for NULL or 0 values.)

• Translate Table (Is field data contained in the translate table?)

• Yes/No (Do all yes/no fields only contain only yes or no data?)

If any of the edits fail, the status of the property IsEditError is set to True for the Message Object executing the method, and any Rowset, Row, Record, or Field Objects that could be instantiated from the same data as the Message Object. In addition, the Field class properties MessageNumber and MessageSetNumber are set to the number of the returned message and message set number of the returned message, for the field generating the error.

If you want to check the field values only for a particular record, you can use the ExecuteEdits method with a record object.

In addition, if you want to dynamically set the prompt tables used for a field (with the %EditTable function) you must use the SetEditTable method.

Considerations for ExecuteEdits and SetEditTable

If an effective date is a key on the prompt table, and the record being edited doesn’t contain an effective-dated field, the current datetime is used as the key value.

If a setID is a key on the prompt table, and the record being edited doesn’t contain a setID field, the system looks for the setID on the other records in the current row first, then search parent rows.

Considerations for ExecuteEdits and Numeric Fields

A 0 (zero) may or may not be a valid value for a numeric field. ExecuteEdits processes numeric fields in different ways, depending on whether the field is required and a prompt table is used:

• If the numeric field is required and there is no prompt edit: 0 is considered valid, so numeric fields never fail the required test.

• If the numeric field is required and there is a prompt edit: Prompt edit is run and the value must be valid.

• If the numeric field is not required and there is a prompt edit: 0 is considered valid, so the prompt edit is skipped.

Parameters

Returns

None.

Example

The following is an example of a call to execute Required Field and Prompt Table edits:

&MSG.ExecuteEdits(%Edit_Required + %Edit_PromptTable);

The following is an example showing how ExecuteEdits() could be used:

&MSG.ExecuteEdits();
If &MSG.IsEditError Then
  Exit(1);
End-If;

See Also

SetEditTable

EditError

MessageNumber

MessageSetNumber

IsEditError

ExecuteEdits

Processing Inbound Errors

GenXMLString

Syntax

GenXMLString()

Description

The GenXMLString method creates an XML string based on the message after it's loaded from the message buffer.

Note. This method does not support nonrowset-based messages.

Parameters

None.

Returns

An XML string.

Example

In the following example, the first thee lines of code creates the message object and copies the data from a Component buffer into the message object. The last line creates an XML string based on that message object.

&MSG = CreateMessage(MESSAGE.PO_INSERT);
&RS = GetLevel0();
&MSG.CopyRowset(&RS);
&XML_STRING = &MSG.GenXMLString();

See Also

Message class: LoadXMLString method.

GetQueryString

Syntax

GetQueryString(Parameter_Name)

Description

Use the GetQueryString method to obtain the parameter values of a query string.

Parameters

Returns

A string containing the value of the parameter.

Example

Local Message &request;
Local Rowset &Rowset;
Local String &emplid;

&request = GetMessage();
&Rowset = &request.GetRowset();
&emplid = &request.GetQueryString("EMPLID");

See Also

ConnectorInfo collection: GetQueryStringArgName method, GetQueryStringArgValue method, SetQueryString method.

GetRowset

Syntax

GetRowset([version])

Description

The GetRowset method returns a standard PeopleCode level zero rowset object for the specified message version. It creates an empty rowset for the specified message version if it doesn’t already exist. If no message version is specified, the default message version is used.

When you use the GetRowset method, you are not creating a unique copy of the object. You are making only a copy of the reference. If you change the rowset, the original message is changed.

Version Considerations

If you specify a version, GetRowset won't return a rowset that is populated with the data for the specified version unless you call one of the following functions first, specifying the version:

• GetPubHeaderMessage

• GetPubMessage

• GetSubMessage

Parameters

Returns

A Rowset object if successful.

Example

The following gets all the SET_CNTRL_REC rows related to the row on the page, then updates the field SETID with the value from the page. GetRowset is used to create a rowset based on the message structure, that is, an unpopulated rowset. Because the rowset is unpopulated, you can use the Fill method to populate with data from the page.

Local Message &MSG;
Local Rowset &MSG_ROWSET;

If FieldChanged(SETID) Then
  &MSG = CreateMessage(MESSAGE.SET_CNTRL_REC);
  &MSG_ROWSET = &MSG.GetRowset();
  &MSG_ROWSET.Fill("where SETCNTRLVALUE =:1 and REC_GROUP_ID =:2", SETCNTRLVALUE, REC_GROUP_ID);

  For &I = 1 To &MSG_ROWSET.ActiveRowCount
    &MSG_ROWSET.GetRow(&I).SET_CNTRL_REC.SETID.Value = SETID;
    &MSG_ROWSET.GetRow(&I).PSCAMA.AUDIT_ACTN.Value = "C";
  End-For;

  &MSG.Publish();

End-If;

See Also

Clone

CreateMessage

Rowset Class

Assigning Objects

GetSegment

Syntax

GetSegment(SegmentNumber)

Description

Use the GetSegment method to return the specified segment. This method doesn't actually return anything, but populates the current message object with the specified segment's data.

Parameters

Returns

None.

See Also

CreateNextSegment, DeleteSegment, UpdateSegment, SegmentCount.

GetXmlDoc

Syntax

GetXmlDoc()

Description

Use the GetXmlDoc method to retrieve the message data as an XmlDoc object.

Note. This method can only be used for a nonrowset-based message. If you use this method with a rowset-based message an error message is returned.

Parameters

None.

Returns

A XmlDoc object.

See Also

SetXmlDoc

XmlDoc Class

InBoundPublish

Syntax

InBoundPublish(PubNodeName)

Description

Use the InBoundPublish method to send an asynchronous message based on a message rowset to simulate an inbound asyncronous request from an external node.

Though you are sending a message to yourself, it goes through all the inbound message processing on PubNodeName.

Parameters

Returns

None.

See Also

InboundPublishXmlDoc

Applying Filtering, Transformation and Translation

LoadXMLString

Syntax

LoadXMLString(XMLstring)

Description

The LoadXMLString method loads the message object executing the method with the XML string XMLstring.

Parameters

Returns

None.

Example

&MSG = CreateMessage(MESSAGE.PO_HEADER);
&MSG.LoadXMLString(&XML_STRING);

See Also

Message class: GenXMLString method.

Publish

Syntax

Publish([NodeName] [, Deferred_Mode] )

Description

The Publish method publishes a message to the application message queue for the default message version. This method does not publish the message if the IsActive property for the message definition, set in PeopleSoft Application Designer, is False.

This method publishes a message asynchronously, that is, a reply message is not automatically generated. To publish a message synchronously, use the SyncRequest method.

Note. This method supports nonrowset-based messages only if the data is populated using the SetXmlDoc method.

If the Publish method is called and the message isn't populated (either using SetXmlDoc or one of the rowset methods,) an empty message is published.

The Publish method can be called from any PeopleCode event, but is generally called from an Application Engine PeopleCode step or from a component.

When publishing from a component, you should publish messages only from the SavePostChange event, either from record field or component PeopleCode. This way, if there’s an error in your publish code, the data isn’t committed to the database. Also, since SavePostChange is the last Save event fired, you avoid locking the database while the other save processing is happening.

However, until the message is published, the tables involved with the component are locked and are not saved. To avoid problems with this, specify the Deferred_Mode property as true, so the message is published after the table data has been committed to the database.

Generally, if the message is successfully published, the PubID, and PubNodeName properties are set to the publication ID and publishing system node name, respectively. The only exception is when the Publish is performed as part of your subscription PeopleCode. The subscription process is always executed in deferred mode, due to performance considerations, and so the PubID is not populated.

Note. If you’re publishing a message from within an Application Engine program, the message won’t actually be published until the calling program performs a Commit.

Parameters

Returns

None.

Example

The following copies all the data from a page into a message and publishes it.

Local Message &MSG;
Local Rowset &ROWSET;

&MSG = CreateMessage(MESSAGE.MESSAGE_PO):
&ROWSET = GetLevel0();
&MSG.CopyRowset(&ROWSET);
&MSG.Publish;

The following is an example of putting the Incremental Publish PeopleCode on a Record at Level 1 (or 2, 3). If you just do the normal publishing PeopleCode, you get as many messages as there are records at that level (because the code fires for each record).

To make sure the code fires only once, use the following code.

/*NAMES.EMPLID.WORKFLOW */
Local Message &MSG;
Local Rowset &RS;

&LEVEL = CurrentLevelNumber();
&CURRENT_ROW = CurrentRowNumber(&LEVEL);
&TOT_ROW = ActiveRowCount(EMPLID);
/* Only Publish the message once for all records on */
/* this level */
If &CURRENT_ROW = &TOT_ROW Then
  &MSG = CreateMessage(MESSAGE.NAMES);
  &RS = GetRowset();
  &MSG.CopyRowsetDelta(&RS);
  &MSG.Publish();
End-If;

See Also

IsActive, InBoundPublish.

Defining Message Definitions

InboundPublishXmlDoc

SegmentRestart

Syntax

SegmentRestart(PUBID, Segment_Index, Segments_By_Database)

Description

Use the SegmentRestart method only in a PeopleSoft Application Engine program, and only if check point logic is used.

Parameters

Returns

None.

See Also

DeleteOrphanedSegments

Understanding Message Segments

SetEditTable

Syntax

SetEditTable(%PromptField, RECORD.recordname)

Description

The SetEditTable method works with the ExecuteEdits method. It is used to set the value of a field on a record that has its prompt table defined as %PromptField value. %PromptField values are used to dynamically change the prompt record for a field.

There are several steps to setting up a field so that you can dynamically change its prompt table.

To set up a field with a dynamic prompt table:

1. Define a field in the DERIVED record called fieldname.

2. In the record definition for the field that you want to have a dynamic prompt table, define the prompt table for the field as %PromptField, where PromptField is the name of the field that you created in the DERIVED record.

3. Use SetEditTable to dynamically set the prompt table.

%PromptField is the name of the field on the DERIVED work record. RECORD.recordname is the name of the record to be used as the prompt table.

&MSG.SetEditTable("%EDITTABLE1", Record.DEPARTMENT);
&MSG.SetEditTable("%EDITTABLE2", Record.JOB_ID);
&MSG.SetEditTable("%EDITTABLE3", Record.EMPL_DATA);
&MSG.ExecuteEdits();

Every field on a record that has the prompt table field %EDITTABLE1 will have the same prompt table, such as, DEPARTMENT.

Parameters

Returns

None.

See Also

ExecuteEdits

EditError

MessageNumber

MessageSetNumber

IsEditError

SetEditTable

Creating a New Record

SetQueryString

Syntax

SetQueryString(Parameter_Name, Value)

Description

Use the SetQueryString method to add a parameter value to the query string.

Parameters

Returns

None.

Example

Local Message &request;
&request = CreateMessage(Message.QE_SALES_ORDER);
. . .

. . .

&request.SetQueryString("BUYER", "12345");

See Also

AddQueryStringArg, GetQueryString.

SetStatus

Syntax

SetStatus(Status)

Description

Use the SetStatus method to set the status of a publication or subscription contract, much the same way you do in the message monitor.

You may want to use this method after an end-user has finished fixing any errors in the message data.

You can set the status of a contract to one of the following statuses:

• Cancel

• Done

• Error

• New

The method is available only when the message instance has one of the following statuses:

• Cancel

• Done

• Error

• New

Parameters

Returns

None.

See Also

Defining Message Definitions.

SetXmlDoc

Syntax

SetXmlDoc(&XmlDoc)

Description

Use the SetXmlDoc method to load a nonrowset-based message with data from an XmlDoc object.

Note. This method can only be used for a nonrowset-based message. If you use this method with a rowset-based message an error message is returned.

Parameters

Returns

None.

See Also

GetXmlDoc

XmlDoc Class

SyncRequest

Syntax

SyncRequest([NodeName])

Description

Use the SyncRequest method to send a synchronous message for the default message version.

Use the IsActive property to determine if a message is active or not before using this method. A message is specified as Active in PeopleSoft Application Designer.

This method sends a single message synchronously, that is a reply message is returned as a result of this method.

If you want to publish a message asynchronously, use the Publish method.

If you want to publish more than one message at a time synchronously, use the IntBroker SyncRequest method.

Note. This method supports nonrowset-based messages only if the SetXmlDoc method is used to populate the message prior to using the SyncRequest method.

The SyncRequest method can be called from any PeopleCode event, but is generally called from an Application Engine PeopleCode step or from a component.

When sending a synchronous request from a component, you should send messages only from the SavePostChange event, either from record field or component PeopleCode. This way, if there’s an error in your SyncRequest code, the data isn’t committed to the database. Also, since SavePostChange is the last Save event fired, you avoid locking the database while the other save processing is happening.

If the message is successfully sent, a response message is returned. In addition, the GUID property is updated with a unique identifier.

Parameters

Returns

A response message.

Example

Local Message &request, &response;
Local Rowset &sales_order;

&sales_order = GetLevel0();
&request = CreateMessage(Message.QE_SALES_ORDER);
&request.CopyRowsetDelta(&sales_order);
&response = &request.SyncRequest();
If (&response.ResponseStatus = 0) Then
   /* do processing */
End-If;

See Also

Message class: Publish method.

SyncRequest

Update

Syntax

Update([versionlist])

where versionlist is an arbitrary list of message versions in the following format:

version1 [, version2] . . .

Description

The Update method updates a message in the message queue with the specified message versions. If versionlist isn’t specified, the default message version is used. This method is commonly used in the OnRouteSend and OnRouteReceive PeopleCode events.

Note. This method does not support nonrowset-based messages. The Update method can't be called from subscription PeopleCode.

Parameters

Returns

None.

See Also

GetRowset

Defining Message Definitions

UpdateSegment

Syntax

UpdateSegment()

Description

Use the UpdateSegment method to update the current segment with data from the message. This method is used only when creating a message for publication, not after a message has been published.

Note. You should use DeleteSegment and UpdateSegment only when writing to memory, or when SegmentsByDatabase is set to False. These methods do not work when writing to the database, or when SegmentsByDatabase is set to True.

Parameters

None.

Returns

None.

See Also

CreateNextSegment, DeleteSegment, CurrentSegment, SegmentCount.

Message Class Properties

In this section, we discuss the Message class properties. The properties are discussed in alphabetical order.

ChannelName

Description

This property references the name of the channel associated with the message definition. This property is set in PeopleSoft Application Designer, when the message is created. The message instance keys are a subset of the publication and subscription contract keys. This property is one of the message instance keys: the others are PubID and PubNodeName for asynchronous messages, GUID and PubNodeName for synchronous messages.

This property is valid for both synchronous and asynchronous messages.

This property is read-only.

Example

&CHANNEL = &MSG.ChannelName

See Also

Defining Message Definitions.

Cookies

Description

This property returns or sets the cookies associated with a message. You can accept a synchronous response message containing cookies, save those cookies in a global variable, and later return them to the target node in an outbound synchronous or asynchronous request message.

You can access this property only in an inbound synchronous response message or an outbound request message.

This property is read-write.

Example

The following is an example of receiving cookies:

Local Message &SalesRequest, &SalesResponse;
Local Rowset &SALES_ORDER;
Global string &SalesCookies;

&SALES_ORDER = GetLevel0();
&SalesRequest = CreateMessage(Message.SALES_ORDER_SYNC);
&SalesRequest.CopyRowsetDelta(&SALES_ORDER);

/* send the synchronous request; the return value is */
/* the response message object */
&SalesResponse = &SalesRequest.SyncRequest();

/* Retrieve cookies from the response message */
&SalesCookies = &SalesResponse.Cookies;

The following is an example of returning cookies:

Local Message &SalesRequest, &SalesResponse;
Local Rowset &SALES_ORDER;
Global string &SalesCookies;

&SALES_ORDER = GetLevel0();
&SalesRequest = CreateMessage(Message.SALES_ORDER_SYNC);
&SalesRequest.CopyRowsetDelta(&SALES_ORDER);

/* Insert the cookies in the request message */
&SalesRequest.Cookies = &SalesCookies;

/* Send the asynchronous request */
&SalesRequest.Publish();

CurrentSegment

Description

This property returns a number, indicating which segment is the current segment.

This property is read-only.

DefaultMessageVersion

Description

This property returns the default version of the message as a string. This is the message version from the pub/sub contract, not the default message version of the message defined in the current system.

This property is valid for both synchronous and asynchronous messages.

This property is read-only.

Example

Local Message &MSG;
Local String &VER;

&MSG = GetMessage();
&VER = &MSG.DefaultMessageVersion;

DoNotPubToNodeName

Description

Use this property to set the node name of a node that you do not want to publish this message to. For example, a single node may publish and subscribe to the same message. You can use this property to prevent the system from subscribing to the same message it publishes. This can help prevent circular processing where the original publisher eventually receives the same message.

This property is only valid for asynchronous messages.

This property is read-write.

Example

&MSG.DoNotPubToNodeName = &MSG.PubNodeName;
&MSG.Publish();

GUID

Description

This property returns a string representing a global unique identifier generated when the message was sent.

This property returns the unique identifier used with the message.

This property is valid only for synchronous messages.

This property is read-only.

Example

Local Message &request;
Local String &guid;

&request = GetMessage();

&guid = &request.GUID;

IBInfo

Description

Use this property to return a reference to an IBInfo object.

This property is read-only.

IsActive

Description

Indicates whether the message definition has been set to inactive in PeopleSoft Application Designer. This property is True if the message definition is active, False if it’s been inactivated from PeopleSoft Application Designer. If you have a lot of PeopleCode associated with publishing a message, you might use this property to check if the message is active before you publish it.

This property is valid only for rowset-based messages. If you want to find out whether a nonrowset-based message is active or not, use the IsMessageActive function.

This property is valid for both asynchronous and synchronous messages.

This property is read-only.

Example

&MSG = CreateMessage(MESSAGE.MY_MESSAGE)
If &MSG.IsActive Then
  /* do PeopleCode processing */
  &MSG.Publish();
Else
  /* do other processing */
End-if;

See Also

Defining Message Definitions

IsMessageActive

IsDelta

Description

This property indicates if any fields in a message populated from page data have been changed since they were first loaded into the component buffer.

This is generally used in the following scenario:

You want to publish a message only if the end-user has changed a value on a page. The problem is that if the end-user makes a change to a field in the level three rowset, the IsChanged property for the top level row remains False. If the rowset is large, and you don't want to iterate through it to find a single IsChanged, you can use this property to quickly determine if something has changed at a lower level and the message should be published.

Note. This property should be used only when the message and the component do not have the same structure (that is, the same records at the same levels). If the message and the component have the same structure use the CopyRowsetDelta method instead.

This property takes a Boolean value: True if there are changed fields in the message, False otherwise.

This property is valid for both asynchronous and synchronous messages.

This property is read-only.

Example

&Msg = CreateMessage(Message.MY_MESSAGE);
&Msg_Rowset = &Msg.GetRowset(); /* get first level in Msg RS */
&Msg_Detail = &Msg_Rowset(1).GetRowset(); /* get detail in Msg */
&Page_Rowset = GetRowset(); /* get page */
For &I = &Page_Rowset.Rowcount
  &Page_Detail = &Page_Rowset.GetRow(&I).GetRowset();
  &Msg_Detail.CopyRowset(&Page_Detail);
End-For;
/* Find if any data changed and should publish message */
If &Msg.IsDelta Then
   &Msg.Publish();
Else
   /* don't publish message and do other processing */
End-If;

See Also

Message class: CopyRowsetDelta method.

IsEditError

Description

This property is True if an error has been found on any field in any record of the current message after executing the ExecuteEdits() method on either a message object or a record object. This property can be used with the Field Class properties MessageSetNumber and MessageNumber to find the error message set number and error message number.

You can use this property in Subscription PeopleCode with the Exit function with a value of 1. This automatically rolls back any changes that were made to the database, saves the message errors to the message queue, and marks the message status as ERROR.

This property is valid for both asynchronous and synchronous messages.

This property is read-only.

Example

&MSG = GetMessage();
&Rowset = &MSG.GetRowset();
&MSG.ExecuteEdits();
If &MSG.IsEditError Then
  Exit(1);
End-If;

See Also

ExecuteEdits

MessageNumber

MessageSetNumber

Exit

Processing Inbound Errors

IsEmpty

Description

This property indicates whether the transaction occurred without error, but returned an empty XML document. An empty response object contains only the data tags:

<data></data>

This property returns a Boolean value: True, the response message is empty, False, the response message is not empty.

This property is valid only for the returned response message from a synchronous request message.

This property is read-only.

IsLocal

Description

This property is True if the message object that was just instantiated was published locally. This property takes a Boolean value.

This property is valid for both asynchronous and synchronous messages.

This property is read-only.

Example

&MSG = GetMessage();
If &MSG.IsLocal Then /*  LOCAL NODE */
  /* do processing specific to local node */
Else
  /* do processing specific to remote nodes */
End-If;

IsStructure

Description

This property indicates whether the message is structured, that is, based on a rowset, or unstructured, that is, based on an XmlDoc. This property takes a boolean value, true if the message is structured, false otherwise.

This property is read-only.

MessageDetail

Description

This property specifies the message detail, as a string. The message detail can be used to further identify a message.

The only way to set the message detail is using PeopleCode. You cannot set the message detail using PeopleSoft Application Designer.

For synchronous messages, the message detail can be seen in the message monitor.

This property is valid with both asynchronous and synchronous messages.

This property is read-write.

Name

Description

This property returns the name of the message as a string.

This property is valid with both asynchronous and synchronous messages.

This property is read-only.

NRId

Description

This property returns the non-repudiation ID as a string. This property is populated with a unique string when the message is published.

This property is only valid with messages that use non-repudiation.

This property is read-only.

See Also

Implementing Authentication and Nonrepudiation.

PubID

Description

This property refers to the publication identifier, which is a number. It’s generated for asynchronous messages when the message is published, and is sequential, based on the number of messages published for that channel. The message instance keys are a subset of the publication and subscription contract keys. This property is one of the message instance keys: the others are ChannelName and PubNodeName.

Note. The PubID property is not populated when the message is published from a subscription.

This property is valid only with asynchronous messages.

This property is read-only.

Example

&MSG.Publish();
&PUBID = &MSG.PubID;

PubNodeName

Description

This property refers to a string that contains the name of the publishing node. It is generated by the system when the message is published. The message instance keys are a subset of the publication and subscription contract keys. This property is one of the message instance keys: the others are PubID and ChannelName.

This property is valid for both asynchronous and synchronous messages.

For a synchronous message, this property returns the name of the requesting node.

This property is read-only.

Example

&MSG = GetMessage();
&PUBNODE = &MSG.PubNodeName;

ResponseStatus

Description

This property is valid only for the returned response message from a synchronous request message.

This property indicates whether a response was successful or not.

Note. This is not the same as SetStatus, which is used only with the message monitor.

This property returns a numeric value: 0, the response was successful, any other number indicates an error.

This property is read-only.

SegmentCount

Description

This property returns the total number of segments for the message.

This property is read-only.

SegmentsByDatabase

Description

Use this property to specify whether segments are stored in memory while being processed.

If you specify SegmentsByDatabase as false, you can only have the number of segments as specified in PSADMIN (Message Segment From DB). If you specify this property as true, you can have as many segments as you need.

The SegmentsByDatabase property also specifies whether the segments are kept in memory or written to the database when they are received. If you specify true, the segments are automatically written to the database. If you specify false, the segments are held in memory. If you specify true, then cancel out of the program processing the segments, the changes are not committed to the database.

This property is automatically set to true for message segments being processed using a PeopleSoft Application Engine program.

This property is read-write.

See Also

Message Segments

SegmentsUnOrder

Size

Description

This is the approximate size of the uncompressed XML data generated when the message is published. The size is approximate for the following reasons:

• The maximum size of fields is used except for the case of long text and image fields.

• The active row count is used, without regard to whether the rows have been changed. In a CopyRowsetDelta, rows that are not changed, are not published.

• It doesn't include the size of the XML tags.

This property can be used with the system property %MaxMessageSize in a batch Application Engine program to prevent the application from publishing a message that is too large.

This property is valid for both asynchronous and synchronous messages.

This property is read-only.

Example

If &MSG.Size > %MaxMessageSize Then
  &MSG.Publish();
Else
  /*Move more data into the message object */
End-If;

See Also

%MaxMessageSize

Sending and Receiving Messages

SubName

Description

This property refers to a string that contains the name of the subscription process currently processing the message. It is available only when GetMessage is used in a subscription PeopleCode program.

This property is only valid for asynchronous messages.

This property is read-only.

Example

&MSG = GetMessage();
&SUBNAME = &MSG.SubName

SubscriptionProcessId

Description

This property returns a string containing the subscription process identifier. This is a unique sequential number.

This property is populated only if the “Generate Subscription Process Instance” option is turned on in the Subscription Process definition.

The subscription process identifier corresponds to the subscription process instance, not the message instance. If there are multiple subscription processes for the same message each subscription process will have a different, unique ID.

If the subscription process terminated abnormally, its process instance is lost, and a new one is generated on the next retry (that is, there will be a gap in the sequence.)

This property is valid only for asynchronous messages.

This property is read-only.

Considerations for Using SubscriptionProcessId

Consider the following when using SubscriptionProcessId:

• Using the Run PeopleCode option from Message Subscription does not generate the number. It is generated only if the Application Server is running the PeopleCode.

• If for some reason you have to rerun the subscription, a new number is assigned.

• Because generating the number is optional, your program must contain code to support the option being turned off. Here is a code example from ITEM_SYNC:

  If All(&MSG.SubscriptionProcessId) Then
    &EIP_CTL_ID = Generate_EIP_CTL_ID(4, &MSG.SubscriptionProcessId);
  Else
    &EIP_CTL_ID = Generate_EIP_CTL_ID(1, "Random");
  End-If;

• If the flag is off, this property is blank. In this case, you may want to adopt a standard for generating a random number, as shown in the previous example.

See Also

Sending and Receiving Messages.

IntBroker Class

An IntBroker object is returned from the system variable %IntBroker.

IntBroker Class Methods

In the following section, we discuss the IntBroker class methods. The methods are described in alphabetical order.

DeleteOrphanedSegments

Syntax

DeleteOrphanedSegments(PUBID, Channel_Name, Node_Name)

Description

Use the DeleteOrphanedSegments method to delete segments that might have been orphaned if you were processing message segments using a PeopleSoft Application Engine program that had to be restarted. Since each segment is committed to the database, if the application engine program is aborted, these segments need to be deleted from the database.

Parameters

Returns

None.

See Also

SegmentRestart

Understanding Message Segments

GetMessageErrors

Syntax

GetMessageErrors(Type, PubID, PubNodeName, ChannelName [,{SubNode, SegmentNumber | MsgName, SubscriptionName, SegmentNumber}]

Description

Use the GetMessageErrors method to return an array that contains the errors that an application has set for the message, and have been written to the error queue. This method is generally only used with asynchronous messages.

Parameters

Returns

An array of string. If there are no error messages, the Len property of the array is 0.

Example

The following is an example of using the method for returning web services gateway error messages:

&MyErrors = %IntBroker.GetMessageErrors(%IntBroker_BRK, &PubId, &PubNode, &Channel);

The following is an example of using this method for returning publication contract error messages:

&MyErrors = %IntBroker.GetMessageErrors(%IntBroker_PUB, &PubId, &PubNode, &Channel, &Subnode, &Segment);

The following is an example of using this method for returning subscription contract error messages:

&MyErrors = %IntBroker.GetMessageErrors(%IntBroker_SUB, &PubId, &PubNode, &Channel, Message.QE_FLIGHT_INFO, &Subscription,
&Segment);

See Also

SetErrorMessage

Processing Inbound Errors

GetMsgSchema

Syntax

GetMsgScheme(MsgName, MsgVersion)

Description

Use the GetMsgSchema method to access the saved schema for the specified message.

If you specify a message that does not have a saved schema, you receive a null value.

Parameters

Returns

A string containing the message schema. If you try to get a schema for a message that does not have a saved schema, returns null.

See Also

MsgSchemaExists

Using the Message Schema Builder

MsgSchemaExists

Syntax

MsgSchemaExists(MsgName, MsgVersion)

Description

Use the MsgSchemaExists method to determine if a schema has been created and saved for the specified message.

Parameters

Returns

A boolean value: true if the message schema exists, false otherwise.

See Also

GetMsgSchema

Using the Message Schema Builder

SetErrorMessage

Syntax

SetErrorMessage(Type, PubID, PubNodeName, ChannelName, SubNode, MsgName, SubscriptionName, Segment, MsgSet, MsgNumber, Error_Location, ParmList)

Description

Use the SetErrorMessage method to write messages to the error queue. This method is used with asynchronous messages only.

Parameters

Returns

A boolean value, true if the error message was associated correctly, false otherwise.

Example

The following is an example of setting an error message for the web services gateway:

&Rslt = %IntBroker.SetMessageError(%IntBroker_BRK, &pubid, &pubnode, &channelname, "", "", "", &segment, &msgset, &msgnum,
"error location", &parm1, &parm2. &parm3, &parm4 );

The following is an example of setting an error message for the publication contract:

&Rslt = %IntBroker.SetMessageError(%IntBroker_PUB, &pubid, &pubnode, &channelname, &Subnode, "", "", &segment, &msgset, &msgnum,
"error location", &parm1, &parm2. &parm3, &parm4 );

The following is an example of setting an error message for the subscription contract:

&Rslt = %IntBroker.SetMessageError(%IntBroker_SUB, &pubid, &pubnode, &channelname, "", Message.QE_FLIGHT_INFO, &Subscription,
&segment, &msgset, &msgnum, "error location", &parm1, &parm2. &parm3, &parm4 );

See Also

Processing Inbound Errors

GetMessageErrors

SyncRequest

Syntax

SyncRequest([&MsgArray, &NodeNames])

Description

Use the SyncRequest method to send multiple messages at the same time. You should only use this message with synchronous messages. You can also use this method to send a single synchronous message at a time, or you can use the SyncRequest Message class method.

If you want to publish messages asynchronously, use the Publish method.

Note. This method supports nonrowset-based messages only if the SetXmlDoc method is used to populate the message prior to using the SyncRequest method.

You must set the thread pool size of the application server on the receiving system to a value greater than 1 (the default) in order to process more than one message at a time.

How many threads you specify determines how many messages are worked on simultaneously. For example, if you have 10 messages in &MsgArray, and your thread pool size is 5, then only 5 messages are processed at a time.

The maximum number you can specify for your thread pool size is 10.

Parameters

Returns

An array of messages. These are the corresponding messages returned for the published messages. The first message in the returned array corresponds to the first message in the published array, the second message with the second, and so on.

Example

The following is an example of how creating and receiving a series of messages:

Local Rowset &FLIGHTPLAN, &FLIGHTPLAN_RETURN;
Local Message &MSG;
Local File &BI_FILE;
Declare Function out_BI_results PeopleCode QE_FLIGHTDATA.QE_ACNUMBER FieldFormula;

Local array of Message &messages;
Local array of Message &return_mesages;

&messages = CreateArrayRept(&MSG, 0);
&return_mesages = CreateArrayRept(&MSG, 0);

&FLIGHT_PROFILE = GetLevel0();
&messages [1] = CreateMessage(Message.QE_FLIGHTPLAN_SYNC);
&messages [1].CopyRowset(&FLIGHT_PROFILE);

&messages [2] = CreateMessage(Message.QE_FLIGHTPLAN_SYNC);
&messages [2].CopyRowsetDelta(&FLIGHT_PROFILE);

&return_mesages = %IntBroker.SyncRequest(&messages);

&FLIGHTPLAN_RETURN = &return_mesages [1].GetRowset();
&temp = &return_mesages [1].GenXMLString();

out_BI_results(&temp);

&FLIGHTPLAN_RETURN = &return_mesages [2].GetRowset();
&temp = &return_mesages [2].GenXMLString();

out_BI_results(&temp);

See Also

SyncRequest

IBInfo Class

An IBInfo object is returned from the IBInfo message class property.

See Also

IBInfo

IBInfo Class Methods

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

All methods work with both asynchronous as well as synchronous messages unless specified

LoadConnectorProp

Syntax

LoadConnectorProp(ConnectorName)

Description

Use the LoadConnectorProp method to load connector properties to the specified connector. The properties are contained in the message executing the method.

Note. Use this method in the message OnSend event.

Parameters

Returns

A Boolean value: true if properties are loaded successfully, false otherwise.

Example

LOCAL MESSAGE &MSG; 
&MSG = GetMessage(); 
&Rowset = &MSG.GetRowset();
&MSG.IBInfo.LoadConnectorProp("HTTP TargetConnector"); 
/* add connector properties */
&MSG.IBInfo.ConnectorOverride= true; 
ReturnToServer(&MSG);

See Also

ConnectorOverride

ReturnToServer

LoadConnectorPropFromNode

Syntax

LoadConnectorPropFromNode(NodeName)

Description

Use the LoadConnectorPropFromNode method to load connector properties into the message executing the method. Then you can use the LoadConnectorProp method to load the specified connector with the properties.

Note. Use this method in the message OnSend event.

Parameters

Returns

A Boolean value: true if the properties are loaded successfully, false otherwise.

See Also

ConnectorOverride

ReturnToServer

LoadConnectorPropFromTrx

Syntax

LoadConnectorPropFromTrx(NodeName, TransactionType, MsgName, MsgVersion)

Description

Use the LoadConnectorPropFromTrx method to load the message executing the method with the connector properties associated with the specified transaction. Then you can use the LoadConnectorProp method to load the specified connector with the properties.

Note. Use this method in the message OnSend event.

Parameters

Returns

A Boolean value: true if the properties are loaded successfully, false otherwise.

See Also

ConnectorOverride

ReturnToServer

IBInfo Class Properties

In this section, we discuss the IBInfo class properties. The properties are discussed in alphabetical order.

AppServerDomain

Description

This property can be used to set the application server domain for the connector, as a string.

This property is read-write.

IBConnectorInfo

Description

This property returns a reference to a ConnectorInfo object.

This property is read-only.

ConnectorOverride

Description

This property specifies whether the connector override is specified for the transaction. This property takes a Boolean value: true, override the connection properties, false otherwise.

This property is read-write.

DestinationNode

Description

This property returns the name of the destination node that the request was sent to, as a string.

This property is read-only.

ExternalMessageID

Description

This property returns the external ID of the message. This property is used in testing, and to resolve duplicate message issues from non PeopleSoft systems.

This property is read-only.

Example

&str = &MSG.IBInfo.ExternalMessageID;

FinalDestinationNode

Description

When the message is passed across several nodes, this property specifies the ultimate target of the message, as a string.

This property is read-only.

MessageChannel

Description

This property references the name of the channel associated with the message definition, as a string. This property is set in PeopleSoft Application Designer, when the message is created.

This property is read-only.

See Also

Message class: ChannelName property.

MessageName

Description

This property returns the name of the message, as a string.

This property is read-only.

See Also

Message class: Name property.

MessageType

Description

This property returns the type of the message, as a string. Valid types are:

This property is read-only.

MessageVersion

Description

This property returns the message version as a number.

This property is read-only.

NodeDN

Description

For incoming requests, this property gives the distinguished name (DN) extracted from the certificate authentication process, as a string.

This property is read-only.

NonRepudiationID

Description

This property returns the non-repudiation ID as a string. This property is populated with a unique string when the message is published.

This property is only valid with messages that use non-repudiation.

This property is read-only.

See Also

Implementing Authentication and Nonrepudiation.

OrigNode

Description

For requests that cross multiple nodes, this property identifies the node that initiated the request as a string.

The OrigNode property returns the originating node of the message. If the message is not going across nodes, the OrigNode and SoureNode properties return the same value. However, if the message is going across nodes, the source node is the node that most recently published the message.

For example, if A publishes to B, then B publishes the message to C, from C's perspective, A is the original node and B is the source node.

This property is read-only.

See Also

IBInfo class: SourceNode property.

OrigProcess

Description

This property returns the name of the process where the publish originated, as a string. For example, a message published from the Inventory definitions page would have a process name of INVENTORY DEFIN.

This property is read-only.

OrigTimeStamp

Description

This property returns the time stamp that corresponds to the time that the request was created, as a string. For requests that cross nodes, this is the time that the first request was created.

This property is read-only.

OrigUser

Description

This property returns the user ID login where the message was initially generated, as a string.

This property is read-only.

PublicationID

Description

This property returns the unique identifier for the message, as a string. It is used to track the message through the PeopleSoft Web Services Gateway. The value increments by one each time you send the message through the system

This property is read-only.

RequestingNodeName

Description

This property returns the name of the node making the request, as a string.

This property is read-only.

SegmentsUnOrder

Description

The SegmentUnOrder property is only applicable for asynchronous messages. If you specify the SegmentUnOrder property as true, the receiving node processes the segments in parallel.

This property is read-write.

See Also

SegmentsByDatabase

Message Segments

SourceNode

Description

This property returns the name of the publishing node as a string.

The OrigNode property returns the originating node of the message. If the message is not going across nodes, the OrigNode and SoureNode properties return the same value. However, if the message is going across nodes, the source node is the node that most recently published the message.

For example, if A publishes to B, then B publishes the message to C, from C's perspective, A is the original node and B is the source node.

This property is read-only.

See Also

IBInfo class: OrigNode property.

SyncServiceTimeout

Description

This property takes a time (in seconds). This time overrides the default http timeout that is used for all requests. If you set this property, you can use this to read back the time, that is, set the time before the SyncRequest is executed, then see when it is changed in the OnSend event.

Note. This property is only for syncronous requests.

Generally, you use SyncServiceTimeout to dynamically set the timeout value for a specific transaction. The http header file is modified to take this new parameter. In addition this value is sent to the gateway to be used for the http timeout. Use this so that a long running transaction will not timeout. In addition, you don't have to wait through the default period for a specific transaction to timeout.

The following is a typical example of using this property:

&MSG.SetXmlDoc((&xmlReq);
&MSG.IBInfo.LoadConnectorPropFromNode(Node.EAI)
&MSG.IBInfo.SyncServiceTimeout(360000);
&MSG.IBInfo.ConnectorOverride = true;
&MSG_Resp = SyncRequest(&MSG, Node.EAI);
&xmlResponseDoc = &MSG.GetXmlDoc();

Setting the XML directly is not valid. You need to use the message object to set the value. In order for this to work you must override the connector properties, which means you must set up the connector properties for this transaction, using one of the load methods (such as LoadConnectorPropFromNode, LoadConnectorPropFromTrx, and so on.)

This property is read-write.

TransactionID

Description

This property returns the transaction ID as a string. This is used to uniquely identify a request.

This property is read-only.

VisitedNodes

Description

This property returns an array of string containing the names of all the nodes visited by the message. This is useful when a message is being propagated across multiple nodes.

This property is read-only.

ConnectorInfo Collection

A ConnectorInfo collection object is returned from the IBConnectorInfo IBInfo class property.

See Also

IBConnectorInfo

ConnectorInfo Collection Methods

In this section, we discuss the ConnectorInfo collection methods. The methods are discussed in alphabetical order.

AddConnectorProperties

Syntax

AddConnectorProperties(Name, Value, Type)

Description

Use the AddConnectorProperties method to add a set of connector properties to a connector.

Parameters

Returns

A Boolean value: true if the connector properties are added successfully, false otherwise.

Example

The following are example of typical name/value pairs.

&MSG.IBInfo.IBConnectorInfo.AddConnectorProperties("URL", "http://finance.yahoo.com/d/quotes.txt/?symbols=PSFT&format=l1c1d1t1",
%Property); 

&MSG.IBInfo.IBConnectorInfo.AddConnectorProperties("sendUncompressed", "Y", %Header); 

&MSG.IBInfo.IBConnectorInfo.AddConnectorProperties("FilePath", "C:\Temp", %Property);

See Also

ConnectorInfo collection: DeleteConnectorProperties method, ClearConnectorProperties method.

AddQueryStringArg

Syntax

AddQueryStringArg(Name, Value)

Description

Use the AddQueryStringArg method to add query string arguments to the outbound request. The query string arguments are used by the HTTP connector to step parameters in the URL.

Parameters

Returns

A Boolean value: true if the query string argument is added successfully, false otherwise.

See Also

ClearQueryStringArgs, DeleteQueryStringArg, GetNumberOfQueryStringArgs, GetQueryStringArgName, GetQueryStringArgValue.

ClearConnectorProperties

Syntax

ClearConnectorProperties()

Description

Use the ClearConnectorProperties method to clear all the properties in a connector before setting them.

Parameters

None.

Returns

None.

See Also

ConnectorInfo collection: AddConnectorProperties method, DeleteConnectorProperties method.

ClearQueryStringArgs

Syntax

ClearQueryStringArgs()

Description

Use the ClearQueryStringArgs method to clear all of the existing query string arguments.

Use the DeleteQueryStringArg method if you want to remove a specific query string argument.

Parameters

None.

Returns

None.

See Also

ConnectorInfo collection: DeleteQueryStringArg method.

DeleteConnectorProperties

Syntax

DeleteConectorProperties(Name)

Description

Use the DeleteConnectorProperties to delete a specific connector property.

Use the ClearConnectorProperties method to remove all the properties.

Parameters

Returns

A Boolean value: true if the property is deleted successfully, false otherwise.

See Also

ConnectorInfo collection: ClearConnectorProperties method.

DeleteQueryStringArg

Syntax

DeleteQueryStringArg(Name)

Description

Use the DeleteQueryStringArg method to delete a specific query string argument.

Use the ClearQueryStringArg method to delete all of the query string arguments.

Parameters

Returns

A Boolean value: true if the query string argument is deleted successfully, false otherwise.

See Also

ConnectorInfo collection: ClearQueryStringArgs method.

GetConnectorPropertiesName

Syntax

GetConnectorPropertiesName(Index)

Description

Use the GetConnectorPropertiesName to return the name of the connector property in the numeric position specified by Index.

Parameters

Returns

A string containing the name of a connector property.

Example

For &I = 1 to &Msg.IBInfo.IBConnectorInfo.GetNumberOfConnectorProperties();
  &PropName = &Msg.IBInfo.IBConnectorInfo.GetConnectorPropertiesName(&I)
  /* do processing */
End-For;

GetConnectorPropertiesValue

Syntax

GetConnectorPropertiesValue(Index)

Description

Use the GetConnectorPropertiesValue method to return the value of the connector property specified by its numeric position by Index.

Parameters

Returns

A string containing the value of the specified connector.

GetNumberOfConnectorProperties

Syntax

GetNumberOfConnectorProperties()

Description

Use the GetNumberOfConnectorProperties method to determine the number of connector properties.

Parameters

None.

Returns

A number.

GetNumberOfQueryStringArgs

Syntax

GetNumberOfQueryStringArgs()

Description

Use the GetNumberOfQueryStringArgs method to determine the number of query string arguments.

Parameters

None.

Returns

A number.

GetQueryStringArgName

Syntax

GetQueryStringArgName(Index)

Description

Use the GetQueryStringArgName method to access the name of the query string argument by its numeric position as specified by Index.

Parameters

Returns

A string containing the name of a query string argument.

GetQueryStringArgValue

Syntax

GetQueryStringArgValue(Index)

Description

Use the GetQueryStringArgValue method to access the value of the query string argument by its numeric posistion as specified by Index.

Parameters

Returns

A string containing the value of a query string argument.

ConnectorInfo Collection Properties

In this section, we discuss the ConnectorInfo collection properties. The properties are discussed in alphabetical order.

ConnectorClassName

Description

Use this property to identify the name of the target connector to invoke as a string.

This property is read-write.

ConnectorName

Description

Use this property to identify the target connector to invoke to send to the message, as a string.

This property is read-write.

Cookies

Description

Use this property to either return or set the cookies associated with this connector. The cookies are specified as a comma separated string. This is the cookie string found when the request was received by the HTTPListeningConnector.

This property is read-write.

PathInfo

Description

This property is specific to incoming HTTP requests. This is the path information extracted from the request, represented as a string.

This property is read-write.

RemoteFrameworkURL

Description

Use this property to identify the URL to which to send a message, as a string. This value overrides the server URL specified in the Project Definitions section.

This property is read-write.