Optimization PeopleCode

This chapter discusses how to:

• Use optimization PeopleCode on the application server.

• Use optimization PeopleCode in an Application Engine program.

• Perform optimization in PeopleCode.

• Use lights-out mode with optimization.

• Use optimization built-in functions.

• Use OptEngine class methods.

• Use OptEngine class properties.

• Use the OptBase application class.

• Use OptBase class methods.

• Use OptInterface class methods.

Using Optimization PeopleCode on the Application Server

While running optimization PeopleCode on the application server, ensure that changed data is committed to the database before calling the CreateOptEngine optimization function and the following OptEngine class methods:

• RunSynch

• RunAsynch

• CheckOptEngineStatus

• ShutDown

• SetTraceLevel

• GetTraceLevel

• InsertOptProbInst

• DeleteOptProbInst

Note. The PeopleCode functions CommitWork and DoSaveNow can be called within a step to save uncommitted data to the database before calling the listed functions and methods. Keep in mind that forcing a commit on pending database updates is a serious step; it prevents roll-back on error. CreateOptEngine, ShutDown, InsertOptProbInst and DeleteOptProbInst modify the database, so take care when terminating the Application Engine program without committing the changes made by those calls.

Using Optimization PeopleCode in an Application Engine Program

When you write an optimization PeopleCode program in an Application Engine program and you schedule it in PeopleSoft Process Scheduler, you must set the process definition with a process type of Optimization Engine. Other process types do not allow optimization PeopleCode in Application Engine programs.

While using optimization PeopleCode in Application Engine programs, make sure data is committed before calling the CreateOptEngine optimization function and the following OptEngine class methods:

• RunSynch

• RunAsynch

• CheckOptEngineStatus

• ShutDown

• SetTraceLevel

• GetTraceLevel

• InsertOptProbInst

• DeleteOptProbInst

Note. You can call the PeopleCode functions CommitWork and DoSaveNow within a step to save uncommitted data to the database before calling the listed functions and class methods. Keep in mind that forcing a commit on pending database updates is a serious step; it prevents roll-back on error. CreateOptEngine, ShutDown, InsertOptProbInst and DeleteOptProbInst modify the database, so take care when terminating the Application Engine program without committing the changes made by those calls.

Performing Optimization in PeopleCode

This section discusses how to:

• Create new analytic instances.

• Load analytic instances into an analytic server.

• Run optimization transactions.

• Invoke the Optimization PeopleCode plug-in.

• Shut down optimization engines.

• Delete existing analytic instances.

• Program for database updates.

Creating New Analytic Instances

To create a new analytic instance for an analytic type:

1. Call the function InsertOptProbInst with the analytic type and analytic instance as parameters to create an analytic instance ID.

2. Use PeopleSoft Application Engine or a similar mechanism to load the optimization application tables with data.

   Use the analytic instance ID as the key value in scenario-managed optimization application tables.

The analytic instance is now ready to be loaded into an analytic server.

Note. You can load multiple copies of the same analytic instance into multiple instances of an analytic server, provided that each instance of the analytic server resides in a different application server domain. Each analytic instance loaded into a given domain must be unique. Within a given domain, you cannot have the same analytic instance in more than one analytic server. The analytic server maintains data integrity by checking to see if the data has been altered by another user (refer to the steps in the optimization system architecture description). Try to maintain data consistency when the same analytic instance uses the same database in different domains.

See Also

PeopleSoft Optimization Framework System Architecture

InsertOptProbInst

Loading Analytic Instances Into an Analytic Server

Use the CreateOptEngine function to load an analytic server with an analytic instance. It takes analytic instance ID and a mode parameter with %Synch and %Asynch as possible values and returns a PeopleCode object of type OptEngine.

You can run the PeopleCode on the application server or from PeopleSoft Application Engine.

Loading Analytic Instances by Running PeopleCode on the Application Server

To block PeopleCode from running on the application server until the load is done (synchronous mode), use the %Synch value for the mode parameter. An error is generated if the load isn’t successful. The application server imposes a timeout beyond which the PeopleCode and optimization engine load are terminated. Here is a code example:

Local OptEngine &myopt;
&myopt = CreateOptEngine("PATSMITH", %Synch);

To load the analytic server without blocking the PeopleCode from running (asynchronous mode) on the application server, use the %Asynch value for the mode parameter. The analytic server performs a preliminary check of the load request and returns the OptEngine object if it is successful or an error if it is unsuccessful. A successful return does not mean that the load was successful. You must then use repeated CheckOptEngineStatus methods on the returned OptEngine object to determine whether the analytic engine is done with the load and whether it was successful. Here is a code example:

Local OptEngine &myopt;
&myopt = CreateOptEngine("PATSMITH", %Asynch);

Loading Analytic Instances by Running PeopleCode in PeopleSoft Application Engine

Both synchronous (%Synch) and asynchronous (%Asynch) modes block the PeopleCode from running on PeopleSoft Application Engine until the load is done. Use only %Asynch while loading an optimization engine.

The absolute number of optimization engine instances that may be loaded in a given domain is governed by a configuration file loaded by Tuxedo during its domain startup.

See Also

CheckOptEngineStatus

Administering Optimization Server Components

Running Optimization Transactions

You send an optimization transaction to the optimization engine using the RunSynch and RunAsynch methods. Both are methods on an OptEngine object. The OptEngine object can be created either by calling CreateOptEngine (if the optimization engine is not loaded already) or by calling GetOptEngine (if the optimization engine is already loaded). Both RunSynch and RunAsynch have the same signature, except that RunSynch runs the optimization transaction in synchronous mode and RunAsynch runs it in asynchronous mode. Both return an integer status code. You can run transactions either on the application server or with PeopleSoft Application Engine.

To invoke an optimization transaction:

1. Use the GetOptEngine function to get the OptEngine object as a handle for the optimization engine that has loaded an analytic instance ID.

   Use the CreateOptEngine function to create the OptEngine object for a new optimization engine if the analytic instance has not been loaded.

2. Call RunSynch or RunAsynch to send an optimization transaction to the optimization engine to be run in synchronous or asynchronous mode.

3. If the transaction is run in synchronous mode (RunSynch), use the OptEngine methods GetString, GetNumber, and so on, to retrieve the output result from the optimization transaction.

   The transaction names, parameter names, and data types are viewable in the analytic type in PeopleSoft Application Designer.

4. If the transaction is run in asynchronous mode, use the OptEngine method CheckOptEngineStatus to check the status of the optimization transaction in the optimization engine.

   After the transaction is done, result data is available in the database for retrieval using standard PeopleCode mechanisms.

Running Optimization Transactions from the Application Server

To block the PeopleCode from running on the application server until the optimization transaction is done (synchronous mode) and receives the results, use RunSynch to send an optimization transaction. An error status code is returned if the transaction isn’t successful. If successful, you can use other methods to retrieve the results from the transaction call. The application server imposes a timeout beyond which the PeopleCode and optimization engine transaction are terminated.

To run a transaction without blocking PeopleCode from running (asynchronous mode) on the application server, use RunAsynch to send an optimization transaction. In this mode, the optimization engine performs a preliminary check of the transaction request and returns a success or failure status code. A successful return does not mean that the transaction is successful; it means only that the syntax is correct. You must then use repeated calls to the CheckOptEngineStatus method on the OptEngine object to determine whether the optimization engine is done with the transaction and whether it is successful.

RunAsynch does not allow transaction output results to be returned. Use this method for long-running transactions that return results entirely through the database.

Running Optimization Transactions from PeopleSoft Application Engine

Both synchronous (RunSynch) and asynchronous (RunAsynch) methods block the PeopleCode from running on PeopleSoft Application Engine until the optimization transaction is done. RunSynch allows output results to be returned, but it should be used for transactions that are fast (less than 10 seconds). RunAsynch does not have a time limit, but it does not return output results.

See Also

RunAsynch

Invoking the Optimization PeopleCode Plug-In

If you're developing an optimization application that uses the Optimization PeopleCode plug-in, you must do the following to invoke the plug-in:

• Develop a PeopleCode application class that extends the PT_OPT_BASE:OptBase class.

• Define methods in your application class that use the PeopleCode OptInterface class to perform your optimization functions.

• Define an analytic type that specifies the Optimization PeopleCode plug-in, by selecting the PeopleCode Plugin check box in the analytic type properties.

• Also in the analytic type properties, specify the application package and application class that you developed.

• Define transactions in your analytic type definition that correspond to the methods you developed in your application class, with corresponding parameters.

See Also

Creating Analytic Type Definitions

CreateOptInterface

OptBase Application Class

OptInterface Class Methods

Shutting Down Optimization Engines

Use the GetOptEngine function to get the OptEngine object as a handle for the optimization engine that loaded an analytic instance ID.

Use the OptEngine method named ShutDown to shut down the optimization engine. This ends the optimization engine process with the current analytic instance ID. Based on application server settings, the system restarts a new, unloaded optimization engine process that can be loaded with any other analytic instance.

See Also

ShutDown

Deleting Existing Analytic Instances

To delete an existing analytic instance for an analytic type:

1. Shut down any optimization engines that have this analytic instance currently loaded.

2. Using PeopleSoft Application Engine or a similar mechanism, delete the data in the optimization application tables pertaining to that analytic instance.

   Use the analytic instance ID as the key value to find and delete analytic instance rows from scenario-managed optimization application tables.

3. Use the function DeleteOptProbInst with the analytic type and analytic instance as arguments to delete the analytic instance ID from PeopleTools metadata.

   Note. If you try to delete an existing analytic instance that is loaded in a running optimization engine, DeleteOptProbInst returns %OptEng_Fail, and the optional status reference parameter is set to %OptEng_Exists.

See Also

DeleteOptProbInst

Programming for Database Updates

You must plan for uncommitted database changes in your optimization PeopleCode. The Optimization Framework detects pending database updates, and generates a failure status if data is not committed to the database before certain optimization methods are called.

This checking for database updates happens in runtime for the CreateOptEngine function and the following methods: RunSync, RunAsync, Shutdown, GetTraceLevel, and SetTraceLevel. Ensure that your PeopleCode performs proper database updates and commits before you execute these methods. If you use the optional parameter for detailed status that is available for these functions, or the DetailedStatus property that is available for the methods, you can check for the status of %OptEng_DB_Updates_Pending to see if there is a pending database update.

Note. The pending database update may have happened considerably earlier in the code. Forcing a commit within your PeopleCode to avoid this problem prevents roll-back on database error. Forcing a commit should be used with care.

The InsertOptProbInst and DeleteOptProbInst functions can be called only inside FieldChange, PreSaveChange and PostSaveChange PeopleCode events, and in Application Message Subscription PeopleCode and Workflow.

This database update checking happens in compile time for the following functions: InsertOptProbInst and DeleteOptProbInst. Make sure that there are no pending database updates before you execute these methods.

Using Lights-Out Mode with Optimization

This section provides an overview of lights-out mode, and discusses how to:

• Create a request message.

• Create a response message.

• Edit the request PeopleCode.

• Edit the response PeopleCode.

Understanding Lights-out Mode

Some optimization applications can take several hours to run. These are typically run as overnight batch jobs every night when the work load is small to regenerate the optimization solution and have it ready for end users to use in the morning — hence the term lights-out mode.

In the current release, application messages communicate between the Application Engine batch job and the online optimization engine. After the Application Engine job completes and the optimization solution has been written to the database, an application message initiates the download of the data from the database batch job to the online optimization engine.

Lights-out mode uses an Application Engine PeopleCode program within PeopleSoft Process Scheduler to send requests to an application server and receive responses from it. Within the application server, the OnRequest PeopleCode runs an optimization engine process.

Lights-out process

This request and response is in the form of a rowset as shown by the example supplied with optimization, the OPT_CALL message. Also supplied as an example is an Application Engine message publish PeopleCode program called PT_OPTCALL.

Important! PeopleSoft Application Engine includes an action of type Log Message, which PeopleSoft Process Scheduler uses to record its activity in the PS_MESSAGE_LOG table. The PeopleCode MessageBox and WinMessage built-in functions also record their activity in the PS_MESSAGE_LOG table.

During lights-out optimization, these processes can conflict with each other or with the optimization engine when one process locks a row of the table, and another process tries to access the same row.

To prevent this conflict, pay close attention to where the MessageBox or WinMessage built-in functions are used in your Application Engine PeopleCode. In general, there can't be any outstanding database updates pending when communicating with the optimization engine using application messages.

The OPT_CALL Message

The OPT_CALL message is an example of what the lights-out process uses as the message for optimization. The OPT_CALL message has a structure using a record, PT_OPTPARMS, having the fields PARMKEY and VALUE which represent a name/value pair. These send requests and responses from the Application Engine PeopleCode in PeopleSoft Process Scheduler to and from the message OnRequest PeopleCode in the application server.

The OPT_CALL message also uses a record, PT_OPTDETMSGS, which contains the information needed for processing a detailed message.

OPT_CALL message structure

Creating a Request Message

This section provides an overview of the request message and describes how to create messages that:

• Create an optimization engine.

• Check optimization engine status.

• Run an optimization engine transaction.

• Set the trace level.

• Get the trace level.

• Shutdown an optimization engine.

Understanding the Request Message

For optimization, the Application Engine PeopleCode in PeopleSoft Process Scheduler sends a request OPT_CALL message. The message uses rowsets built from PT_OPTPARMS records as the request. You can use the following rowset structures as an example of how to perform certain optimization actions, by sending them as requests from the application engine program in the process scheduler to the message subscription PeopleCode in the application server.

Creating an Optimization Engine

To create an optimization engine, structure the rowset as follows, using the PT_OPTPARMS record. You set key values using the PARMKEY field, and then set a value for that key field in the VALUE field.

Checking Optimization Engine Status

To check optimization engine status (for example, to see when it finishes loading), structure the rowset as follows, using the PT_OPTPARMS record.

Running a Transaction

To run a transaction, structure the rowset as follows, using the PT_OPTPARMS record.

Setting the Trace Level

To set a trace level, structure the rowset as follows, using the PT_OPTPARMS record.

Getting the Trace Level

To get a trace level, structure the rowset as follows, using the PT_OPTPARMS record.

Shutting Down an Optimization Engine

To shut down an optimization engine, structure the rowset as follows, using the PT_OPTPARMS record.

Creating a Response Message

This section provides an overview of the response message and describes how to create messages that:

• Send optimization status.

• Send a detailed message.

Understanding the Response Message

For optimization, the message PeopleCode in application server receives the request messages, performs an optimization actions, and sends response OPT_CALL messages. One message uses rowsets built from PT_OPTPARMS records, the other uses rowsets from PT_DETMSGS records. You can use the following rowset structures as an example of how to send responses from the message subscription PeopleCode in the application server to the application engine program in the process scheduler.

Sending Optimization Status

To send the status of the optimization functions and methods called within the message OnRequest PeopleCode, structure the rowset as follows using the PT_OPTPARMS record. The optimization functions and messages are called in response to the request input message. You set key values using the PARMKEY field, and then set a value for that key field in the VALUE field.

Sending a Detailed Message

To send a detailed message, structure the rowset as follows, using the PT_DETMSGS record. You set key values using the PARMKEY field, and then set a value for that key field in the VALUE field.

Editing the Request PeopleCode

The PT_OPTCALL Application Engine program serves as a template. It is delivered with all the sections marked as inactive. You can edit the program to suit your needs, then mark the appropriate sections active before running it. You can also use the program as a guide to creating your own Application Engine program.

The program uses these steps to send request messages to perform the following tasks:

1. Load the optimization engine.

2. Wait for the optimization engine load to finish.

3. Run an optimization transaction against the loaded optimization engine.

4. Wait for the optimization transaction to finish running.

5. Set the trace level.

6. Get the trace level.

7. Shut down the optimization engine.

You can edit steps 1 and 3 to run an optimization transaction. You can also use the entire program as a template to create your own Application Engine program.

Loading an Optimization Engine

In step 1, enter the name of your analytic instance. In this example, the name of the analytic instance is FEMALE1.

If you have multiple domains, enter the local node name and the machine name and port number for your application server. In this case, the local node name is %LocalNode and the machine name and port number are foo111111:9000.

Local Message &MSG;
Local Message &response;

Component string &probid;
Component string &isSync;
Component string &procinst;
Local integer &nInst;
Local string &url;

Local Rowset &rs;
Local Row &row;
Local Record &rec;

Local string &stName;
Local integer &stVal;

&MSG = CreateMessage(Message.OPT_CALL);
&rs = &MSG.GetRowset();

&row = &rs.GetRow(1);
&rec = &row.GetRecord(Record.PT_OPTPARMS);
&rec.PARMKEY.Value = "OPTCMD";
&rec.VALUE.Value = "CREATE";

&rs.InsertRow(1);
&rec = &rs.GetRow(2).PT_OPTPARMS;
&rec.PARMKEY.Value = "PROBINST";
&rec.VALUE.Value = "FEMALE1";
&probid = "FEMALE1";

&rs.InsertRow(2);
&rec = &rs.GetRow(3).PT_OPTPARMS;
&rec.PARMKEY.Value = "PROCINSTANCE";
&nInst = Record.PT_OPT_AET.PROCESS_INSTANCE.Value;
&rec.VALUE.Value = String(&nInst);
&procinst = String(&nInst); 

&rs.InsertRow(3);
&rec = &rs.GetRow(4).PT_OPTPARMS;
&rec.PARMKEY.Value = "SYNCH";
&rec.VALUE.Value = "N";
&isSync = "N";


/* Specify the Application Server domain URL (foo111111:9000 in this example)
*/
&response = &MSG.SyncRequest(%LocalNode, "//foo111111:9000 e");

If &response.ResponseStatus = 0 Then
   &stName = &response.GetRowset().GetRow(1).GetRecord(Record.PT_OPTPARMS).GetField(Field.PARMKEY).Value;
   &stVal = Value(&response.GetRowset().GetRow(1).GetRecord(Record.PT_OPTPARMS).GetField(Field.VALUE).Value);
   If &stName = "STATUS" And
         &stVal = %OptEng_Fail Then
      /* Check detailed message here */
      throw CreateException(148, 2, "Can not send to OptEngine");
   End-If;
End-If;

Running An Optimization Transaction

In step 3, enter the name of your optimization transaction and its parameter name/value pairs. In this example, the transaction name is TEST_LONG_TRANS, the first parameter name/value pair is Delay_in_Secs and 30, and the second parameter name/value pair is Sleep0_Work1 and 0.

The parameter values are stored as strings. You may need to convert them in the OnRequest PeopleCode.

Local Message &MSG;
Local Message &response;

Local Rowset &rs, &respRS;
Local Row &row;
Local Record &rec, &msgRec;

Component string &probid;
Component string &procinst;
Component string &isSync;
Local string &url = "";
Local integer &parmCount, &msgSet, &msgNum;

&MSG = CreateMessage(Message.OPT_CALL);
&rs = &MSG.GetRowset();

&row = &rs.GetRow(1);
&rec = &row.GetRecord(Record.PT_OPTPARMS);
&rec.PARMKEY.Value = "OPTCMD";
&rec.VALUE.Value = "RUN";

&rs.InsertRow(1);
&rec = &rs.GetRow(2).PT_OPTPARMS;
&rec.PARMKEY.Value = "PROBINST";
&rec.VALUE.Value = &probid;

&rs.InsertRow(2);
&rec = &rs.GetRow(3).PT_OPTPARMS;
&rec.PARMKEY.Value = "PROCINSTANCE";
&rec.VALUE.Value = &procinst;

&rs.InsertRow(3);
&rec = &rs.GetRow(4).PT_OPTPARMS;
&rec.PARMKEY.Value = "SYNCH";
&rec.VALUE.Value = &isSync;

&rs.InsertRow(4);
&rec = &rs.GetRow(5).PT_OPTPARMS;
&rec.PARMKEY.Value = "TRANSACTION";
&rec.VALUE.Value = "TEST_LONG_TRANS";

&rs.InsertRow(5);
&rec = &rs.GetRow(6).PT_OPTPARMS;
&rec.PARMKEY.Value = "Delay_in_Secs";
&rec.VALUE.Value = "30";

&rs.InsertRow(6);
&rec = &rs.GetRow(7).PT_OPTPARMS;
&rec.PARMKEY.Value = "Sleep0_Work1";
&rec.VALUE.Value = "0";

/* SyncRequest will carry a url */
SQLExec("select URL from PSOPTSTATUS where PROBINST=:1 AND URL NOT LIKE '%:0';", &probid, &url);
If &url = "" Then
   throw CreateException(148, 2, "Can not send to OptEngine");
End-If;

/* Specify the Application Server domain URL. 
   (This was specified in Step 1 in this example.)
*/
&response = &MSG.SyncRequest(%LocalNode, &url);

If &response.ResponseStatus = 0 Then
   &stName = &response.GetRowset().GetRow(1).GetRecord(Record.PT_OPTPARMS).GetField(Field.PARMKEY).Value;
   &stVal = Value(&response.GetRowset().GetRow(1).GetRecord(Record.PT_OPTPARMS).GetField(Field.VALUE).Value);
   
   If &stName = "STATUS" And
         &stVal = %OptEng_Fail Then
      throw CreateException(148, 2, "Can not send to OptEngine");
   End-If;
   
   /* Check Detailed msg here */
   If &isSync = "Y" And
         &stVal = %OptEng_Success Then
      
      &respRS = &response.GetRowset();
      &rowNum = &respRS.ActiveRowCount;
      For &iloop = 1 To &rowNum
         &msgRec = &respRS.GetRow(&iloop).GetRecord(Record.PT_OPTDETMSGS);
         If (&msgRec.GetField(Field.MSGSET).Value <> 0) Then
            &msgSet = Value(&msgRec.GetField(Field.MSGSET).Value);
            &msgNum = Value(&msgRec.GetField(Field.MSGNUM).Value);
            &parm1 = &msgRec.GetField(Field.MSGPARM1).Value;
            &parm2 = &msgRec.GetField(Field.MSGPARM2).Value;
            &parm3 = &msgRec.GetField(Field.MSGPARM3).Value;
            &parm4 = &msgRec.GetField(Field.MSGPARM4).Value;
            &parm5 = &msgRec.GetField(Field.MSGPARM5).Value;
            &string = MsgGetText(&msgSet, &msgNum, "Message Not Found", &parm1, &parm2, &parm3, &parm4, &parm5);
            
         End-If;
      End-For;
      
   End-If;
   
End-If;

Editing the Response PeopleCode

The OPT_CALL message serves as a template. It is delivered to work with the PT_OPTCALL Application Engine program. You can edit the program to suit your needs, or use it as a guide when creating your own response message program.

OPT_CALL Message Program

The OPT_CALL message OnRequest PeopleCode program shows application messages for lights-out mode.

Depending upon the request message, the OnRequest PeopleCode calls appropriate optimization functions and methods to perform these tasks, and sends a response message containing the returned status and detailed messages from the optimization functions and methods.

You can use the OPT_CALL message OnRequest PeopleCode as a template to create your own response message PeopleCode program. For example, you can edit it to run an optimization transaction, which is shown below as an example. This example is edited to match the examples for step 1 and step 3 in the PT_OPTCALL program.

Processing the Transaction Parameters

Edit the OnRequest PeopleCode for application message OPT_CALL to enter the name of your optimization transaction and the name/value pairs for its parameters. In this example, the transaction name is TEST_LONG_TRANS, the first parameter name/value pair is &delayParm and &delay (maps to Delay_in_Secs from the request message), and the second parameter name/value pair is &sleepParm and &isSleep (maps to Sleep0_Work1 from the request message).

The parameter values are stored as strings in step 3 of the Application Engine program. You may need to convert them here to your desired format. Here is a section of the application program showing the places to edit.

If &trans = "TEST_LONG_TRANS" Then
   &REC = &rs.GetRow(6).PT_OPTPARMS;
   &delayParm = &REC.PARMKEY.Value;
   &delay = Value(&REC.VALUE.Value);
   
   &REC = &rs.GetRow(7).PT_OPTPARMS;
   &sleepParm = &REC.PARMKEY.Value;
   &isSleep = Value(&REC.VALUE.Value);
   
   &myopt = GetOptEngine(&inst, &detStatus);
   If (&myopt = Null) Then
      &optstatus = %OptEng_Fail;
   End-If;
   
   If &myopt <> Null And &isSync = "Y" Then
      &optstatus = &myopt.RunSynch(&trans, &delayParm, &delay, &sleepParm, &isSleep);
      &detStatus = &myopt.DetailedStatus;
      End-If;
      
   If &myopt <> Null And &isSync = "N" Then
      &myopt.ProcessInstance = &procInst;
      &optstatus = &myopt.RunASynch(&trans, &delayParm, &delay, &sleepParm, &isSleep);
      &detStatus = &myopt.DetailedStatus;
   End-If; /* iif myopt=null */
End-If;

Building a Status Response Message

This section shows the a response message to send a status message for the OPT_CALL message in the application server.

/* Insert detailed status and detailed msgs into Response msg rowset */
&respRS = &response.GetRowset();
&respRS.GetRow(1).GetRecord(Record.PT_OPTPARMS).GetField(Field.PARMKEY).Value = "STATUS";
&respRS.GetRow(1).GetRecord(Record.PT_OPTPARMS).GetField(Field.VALUE).Value = String(&optstatus);

&respRS.InsertRow(1);
&respRS.GetRow(2).GetRecord(Record.PT_OPTPARMS).GetField(Field.PARMKEY).Value = "DETAILED_STATUS";
&respRS.GetRow(2).GetRecord(Record.PT_OPTPARMS).GetField(Field.VALUE).Value = String(&detStatus);

Building a Detailed Response Message

This section shows a response message to send a detailed message for the OPT_CALL message on the application server.

/*Either optcmd or inst is not passed in correctly, or optengine is not loaded/created correctly */
If &myopt = Null Then
   &msgRec = &respRS.GetRow(1).GetRecord(Record.PT_OPTDETMSGS);
   If &isParmBad = True Then
      &msgRec.GetField(Field.MSGSET).Value = 148;
      &msgRec.GetField(Field.MSGNUM).Value = 505;
   End-If;
End-If;

/* If it is sync transaction, insert DetailMsg to response msg */
If &myopt <> Null And
      &isSync = "Y" And
      &optcmd = "RUN" And
      &optstatus = %OptEng_Success Then
   &arrArray = &myopt.DetailMsgs;
   For &iloop = 1 To &arrArray.Len
      /* First two rows have been inserted because of PT_OPTPARMS for two status codes */
      If &iloop > 2 Then
         &respRS.InsertRow(&iloop - 1);
      End-If;
      
      &msgRec = &respRS.GetRow(&iloop).GetRecord(Record.PT_OPTDETMSGS);
      &msgRec.GetField(Field.MSGSET).Value = String(&arrArray [&iloop][1]);
      &msgRec.GetField(Field.MSGNUM).Value = String(&arrArray [&iloop][2]);
      &msgRec.GetField(Field.PARMCOUNT).Value = String(&arrArray [&iloop][3]);
      &msgRec.GetField(Field.MSGPARM1).Value = String(&arrArray [&iloop][4]);
      &msgRec.GetField(Field.MSGPARM2).Value = String(&arrArray [&iloop][5]);
      &msgRec.GetField(Field.MSGPARM3).Value = String(&arrArray [&iloop][6]);
      &msgRec.GetField(Field.MSGPARM4).Value = String(&arrArray [&iloop][7]);
      &msgRec.GetField(Field.MSGPARM5).Value = String(&arrArray [&iloop][8]);
   End-For;
   
End-If;

Optimization Built-in Functions

This section discusses the optimization functions. The functions are discussed in alphabetical order.

CreateOptEngine

Syntax

CreateOptEngine(analytic_inst, {%Synch | %ASynch}[, &detailedstatus] [, processinstance])

Description

The CreateOptEngine function instantiates an OptEngine object, loads an optimization engine with an analytic instance and returns a reference to it.

Parameters

Returns

If successful, CreateOptEngine returns an OptEngine PeopleCode object. If the function fails, it returns a null value. Examine the optional status reference parameter in case of a Null return for additional information regarding the failure.

Example

An OptEngine object variable can be scoped as Local, Component, or Global.

You declare OptEngine objects as type OptEngine. For example:

Local OptEngine &MyOptEngine;
Component OptEngine &MyOpt;
Global OptEngine &MyOptEng;

The following example loads an optimization engine with the analytic instance:

Local OptEngine &myopt;
Local string &probinst;
Local string &transaction;
Local integer &detailedstatus;

&probinst = GetRecord(Record.PSOPTPRBINST).GetField(Field.PROBINST).Value; 
&myopt = CreateOptEngine(&probinst, %Synch);

The following example shows the use of the optional status parameter:

&myopt = CreateOptEngine(&probinst, %Synch, &detailedstatus);
if &myopt = Null then
    if &detailedstatus = %OptEng_Invalid_Piid then
        /*perform some action */
    end_if;
end_if;

CreateOptInterface

Syntax

CreateOptInterface()

Description

The CreateOptInterface function instantiates an OptInterface object.

Note. You can use this function — and the OptInterface methods — only within an application class that you extend from the OptBase application class, or within PeopleCode that you call from that application class. This ensures that the OptInterface PeopleCode runs only on the optimization engine.

Parameters

None.

Returns

If successful, CreateOptInterface returns an OptInterface PeopleCode object. If the function fails, it returns a null value.

Example

You declare OptInterface objects as type OptInterface. For example:

Local OptInterface &MyOptInterface;
Component OptInterface &MyOptInt;
Global OptInterface &MyOptInt;

The following example instantiates an OptInterface object:

Local OptInterface &myInterface;
Int &status;

&myInterface = CreateOptInterface(&addtionalStatus);
if (&myInterface != NULL) then
    &status = &myInterface.ActivateModel("RMO_TEST");
        if (&status = %OptInter_Fail) then
            /* examine &myInterface.DetailedStatus for reason */
            ...
        end-if;
else
    /* CreateOptInterface has returned NULL */
    /* take some corrective action here */
        ...
end_if;

DeleteOptProbInst

Syntax

DeleteOptProbInst(probinst[, &detailedstatus])

Description

The DeleteOptProbInst function deletes the analytic instance ID from PeopleTools metadata. This function can be called only inside FieldChange, PreSaveChange and PostSaveChange PeopleCode events, and in Application Message Subscription PeopleCode and Workflow.

Note. Use this function to delete the analytic instance ID after deleting data in optimization application tables for this analytic instance.

Parameters

Returns

Returns %OptEng_Success if successful; otherwise returns %OptEng_Fail.

Example

The following example deletes the instance for an analytic type:

Note. Whenever you add records to an analytic type, you must call DeleteOptProbInst to delete the old analytic type instances and then call InsertOptProbInst to recreate them.

Local string &probinst;
Local string &probtype;
Local integer &ret;
&probinst = "PATSMITH";
&probtype = "QEOPT";
&ret = DeleteOptProbInst(&probinst, &probtype);
If &ret <> %OptEng_Success  Then
   QEOPT_WRK.MESSAGE_TEXT = "Delete of analytic instance " | &probinst | " failed.";
Else
   QEOPT_WRK.MESSAGE_TEXT = "Analytic Instance " | &probinst | " deleted.";
End-If;

The following example shows the use of the optional status parameter:

Local integer &detailedstatus;
&ret = DeleteOptProbInst(&probinst, &probtype, &detailedstatus);
If &ret <> %OptEng_Success  AND &detailedstatus=%OptEng_Invalid_Piid then
   QEOPT_WRK.MESSAGE_TEXT = "Delete of analytic instance " | &probinst | " failed 
for bad piid.";
Else
   QEOPT_WRK.MESSAGE_TEXT = "Analytic Instance " | &probinst | deleted.";
End-If;

GetOptEngine

Syntax

GetOptEngine(probinst[,&detailedstatus])

Description

The GetOptEngine function returns a handle to an optimization engine that is already loaded with the analytic instance.

Parameters

Returns

Returns an OptEngine PeopleCode object if successful, a null value otherwise.

Example

The following example causes an optimization engine to shut down its analytic instance:

Global string &probinst;
Local OptEngine &myopt;
Local integer &status;

&myopt = GetOptEngine(&probinst);
If &myopt <> NULL then
&status = &myopt.ShutDown();
QEOPT_WRK.MESSAGE_TEXT = "Analytic Instance ID " | &probinst 
 | " has been shutdown successfully.";
End-if;

Or, you can use the optional status parameter:

&myopt = GetOptEngine(&probinst, &detailedstatus);
if &myopt=NULL and &detailedstatus=%OptEng_Invalid_Piid then
     /* perform some action */
End-if;

GetOptProbInstList

Syntax

GetOptProbInstList(ProblemType , OutputErrorCode [, Prefix] [, &detailedstatus])

Description

The GetOptProbInstList function gets the list of all analytic instance IDs in an analytic type.

Parameters

Returns

Returns an array of strings containing the optimization analytic instance list.

Example

The following example shows the usage of GetOptProbInstList to fill the display field on a page:

Global string &probinst;
Local integer &detailedstatus;
Local integer &iloop;
Local array of string &instarray;

QEOPT.OPERATOR = %UserId;

&instarray = GetOptProbInstList(QEOPT.PROBTYPE, &ret, &detailedstatus);

If &ret <> %OptEng_Success Then
   QEOPT_WRK.MESSAGE_TEXT = "Could not get analytic instances 
 for analytic type " | QEOPT.PROBTYPE ;
Else
   For &iloop = 1 To &instarray.Len
      QEOPT_WRK.MESSAGE_TEXT = QEOPT_WRK.MESSAGE_TEXT | &instarray[&iloop] | " ";
   End-For;
End-If;

The following example shows the use of the optional status parameter:

&instarray = GetOptProbInstList(QEOPT.PROBTYPE, &ret, &detailedstatus);
If &ret <> %OptEng_Success and &detailedstatus=%OptEng_Invalid_Piid Then
   QEOPT_WRK.MESSAGE_TEXT = "Could not get analytic instances for analytic type " 
| QEOPT.PROBTYPE | "because bad piid" ;
End-If;

InsertOptProbInst

Syntax

InsertOptProbInst(probinst, ProblemType[, &detailedstatus] [,Description])

Description

The InsertOptProbInst function inserts a new analytic instance ID into the PeopleTools metadata.

The InsertOptProbInst function can be called only inside FieldChange, PreSave and PostSave PeopleCode events, and in Application Message Subscription PeopleCode and Workflow.

Note. You must use this function to create the analytic instance ID before inserting data into optimization application tables for this analytic instance.

Parameters

Returns

This method returns a constant. Valid values are:

Example

Local string &probinst;
Local string &probtype;
Local integer &ret;
Local integer &detailedstatus;

&probinst = "PATSMITH";
&probtype = "QEOPT";
&probDescr = "New QEOPT instance"; 
&ret = InsertOptProbInst(&probinst, &probtype, &probDescr);
If &ret <> %OptEng_Success Then
   QEOPT_WRK.MESSAGE_TEXT = "Insert of analytic instance "
 | &probinst | " failed.";
Else
   QEOPT_WRK.MESSAGE_TEXT = "Analytic Instance " | &probinst | " created.";
End-If;

The following example shows the use of the optional status parameter:

&ret = InsertOptProbInst(&probinst, &probtype, &detailedstatus);
If &ret <> %OptEng_Success and &detailedstatus=%OptEng_Invalid_Piid Then
   QEOPT_WRK.MESSAGE_TEXT = "Insert of analytic instance "
 | &probinst | " failed for bad piid.";
End-if;

IsValidOptProbInst

Syntax

IsValidOptProbInst(probinst [, &detailedstatus])

Description

IsValidOptProbInst determines if a given analytic instance exists in the optimization metadata.

Parameters

Returns

This method returns a constant. Valid values are:

Example

Local string &probinst;
Local integer &detailedstatus;
Local integer &ret;

&probinst = "PATSMITH";
&ret = IsValidOptProbInst(&probinst, &detailedstatus);
If &ret <> %OptEng_Success and &detailedstatus=%OptEng_Invalid_Piid Then
   <perform some action>
End-if;

OptEngine Class Methods

This section discusses the optimization methods for the OptEngine PeopleCode class. The methods are listed in alphabetical order.

CheckOptEngineStatus

Syntax

CheckOptEngineStatus()

Description

The CheckOptEngineStatus method returns the status of the optimization engine, using a combination of its return value and the DetailedStatus OptEngine class property. Keep the following in mind:

• The value returned by CheckOptEngineStatus is the operational status of the optimization engine.

• The DetailedStatus property indicates the completion status of the OptEngine method call CheckOptEngineStatus.

For example, CheckOptEngineStatus can return %OptEng_Idle and DetailedStatus is %OptEng_Success. For CheckOptEngineStatus, DetailedStatus can have the value:

• %OptEng_Success.

• %OptEng_Fail.

• %OptEng_Not_Available

Note. Before this method is called, the CreateOptEngine or GetOptEngine must be called.

Returns

Returns an integer for the status of the optimization engine. These numbers are message IDs belonging to message set 148 in the message catalog.

Example

This PeopleCode example shows optimization engine status being checked:

Local OptEngine &myopt;
Local string &probinst;
Local integer &status;
&myopt = GetOptEngine("PATSMITH");
/* Initialize the DESCRLONG field in the QE_FUNCLIB_OPT record to null.  */
GetLevel0().GetRow(1).GetRecord(Record.QE_FUNCLIB_OPT).DESCRLONG.Value = "";
&status = &myopt.CheckOptEngineStatus();
GetLevel0().GetRow(1).GetRecord(Record.QE_FUNCLIB_OPT).DESCRLONG.Value = "OptEngine status = " | MsgGet(148, &status, "Could
not send to the OptEngine.");

You can also retrieve the detailed status:

Local integer &detailedstatus
&status = &myopt.CheckOptEngineStatus();
&detailedstatus = &myopt.DetailedStatus;

FillRowset

Syntax

FillRowset(PARAM_NAME, &Rowset[, &functionstatus])

Description

This method gets the value of a transaction output parameter that is a rowset. This cannot be used with the RunAsynch method; RunSynch is needed to make the transaction output parameter values immediately available.

When using the OptEngine DetailedStatus property, keep the following in mind:

• The value returned by FillRowset is the operational status of the optimization engine.

• The OptEngine DetailedStatus property indicates the completion status of the OptEngine method call FillRowset.

For example, FillRowset returns %OptEng_Fail, and DetailedStatus is %OptEng_Method_Disabled.

For FillRowset, the DetailedStatus property can have the value:

• %OptEng_Success.

• %OptEng_Fail.

• %OptEng_Method_Disabled.

  This indicates that the method is disabled or not valid.

• %OptEng_Wrong_Parm_Type

Parameters

Returns

This method returns a constant. Valid values are:

Example

The following PeopleCode example runs a synchronous optimization transaction named RETURN_MACHINE_UNAVAILABLE. It has these parameters:

• Input: MACHINE_NAME to specify the machine for which we need unavailable times.

• Output: RETURN_TIMES to specify a rowset and MACHINE_WRK record containing the BEGIN_DATE and END_DATE fields.

This PeopleCode example sets input parameter values and gets an output parameter value:

Local OptEngine &myopt;
Local integer &status;
Local string &machname;
Local Rowset &rs;
&myopt = GetOptEngine("PATSMITH");
&machname = QEOPT_WRK.MACHINE_NAME.Value;
/* Run the RETURN_MACHINE_UNAVAILABLE transaction synchronously with input values.  */
&status = &myopt.RunSynch("RETURN_MACHINE_UNAVAILABLE", "MACHINE_NAME", &machname);
If Not &status Then
   QEOPT_WRK.MESSAGE_TEXT = " RETURN_MACHINE_UNAVAILABLE transaction failed.";
   Return;
End-If;
/* Get output value from the RETURN_MACHINE_UNAVAILABLE transaction.  */
&rs = CreateRowset(Record.MACHINE_WRK);
&status = &myopt.FillRowset("RETURN_TIMES", &rs);

You can also use the [new->] DetailedStatus property as follows:

&status = &myopt.FillRowset("RETURN_TIMES", &rs);
if &status=%OptEng_Fail and &myopt.DetailedStatus=%OptEng_Method_Disabled then
    /* perform some action */
End-if;

GetDate

Syntax

GetDate(PARAM_NAME[, &status])

Description

This method gets the value of a transaction output parameter with a data type of Date. This cannot be used with the RunAsynch method; RunSynch is needed to make the transaction output parameter values immediately available.

The OptEngine DetailedStatus property indicates the completion status of the OptEngine method call GetDate. For GetDate, DetailedStatus can have the value:

• %OptEng_Success.

• %OptEng_Fail.

• %OptEng_Method_Disabled: indicates that the method is disabled or not valid.

Parameters

Returns

Returns a Date object; use this method when that is the data type of the transaction output parameter value.

Example

See OptEngine class: GetNumber method.

GetDateArray

Syntax

GetDateArray(PARAM_NAME)

Description

This method gets the value of a transaction output parameter with a data type Array of Date. This cannot be used with the RunAsynch method; RunSynch is needed to make the transaction output parameter values immediately available.

The OptEngine DetailedStatus property indicates the completion status of the OptEngine method call GetDateArray. For GetDateArray, DetailedStatus can have the value:

• %OptEng_Success.

• %OptEng_Fail.

• %OptEng_Method_Disabled: indicates that the method is disabled or not valid.

Parameters

Returns

Returns an Array of Date object; use this method when that is the data type of the transaction output parameter value.

Example

See OptEngine class: GetStringArray method.

GetDateTime

Syntax

GetDateTime(PARAM_NAME)

Description

This method gets the value of a transaction output parameter with a data type of DateTime. This cannot be used with the RunAsynch method; RunSynch is needed to make the transaction output parameter values immediately available.

The DetailedStatus OptEngine property indicates the completion status of the OptEngine method call GetDateTime. For GetDateTime, DetailedStatus can have the value:

• %OptEng_Success.

• %OptEng_Fail.

• %OptEng_Method_Disabled: indicates that the method is disabled or not valid.

Parameters

Returns

Returns a DateTime object; use this method when that is the data type of the transaction output parameter value.

Example

See OptEngine class: GetNumber method.

GetDateTimeArray

Syntax

GetDateTimeArray(PARAM_NAME)

Description

This method gets the value of a transaction output parameter with a data type Array of DateTime. This cannot be used with the RunAsynch method; RunSynch is needed to make the transaction output parameter values immediately available.

The DetailedStatus OptEngine property indicates the completion status of the OptEngine method call GetDateTimeArray. For GetDateTimeArray, DetailedStatus can have the value:

• %OptEng_Success.

• %OptEng_Fail.

• %OptEng_Method_Disabled: indicates that the method is disabled or not valid.

Parameters

Returns

Returns an Array of DateTime object; use this method when that is the data type of the transaction output parameter value.

Example

See OptEngine class: GetStringArray method.

GetNumber

Syntax

GetNumber(PARAM_NAME)

Description

This method gets the value of a transaction output parameter with a data type of Number. This cannot be used with the RunAsynch method; RunSynch is needed to make the transaction output parameter values immediately available.

The DetailedStatus OptEngine property indicates the completion status of the OptEngine method call GetNumber. For GetNumber, DetailedStatus can have the value:

• %OptEng_Success.

• %OptEng_Fail.

• %OptEng_Method_Disabled: indicates that the method is disabled or not valid.

Parameters

Returns

Returns a Number object; use this method when that is the data type of the transaction output parameter value.

Example

The following PeopleCode example runs a synchronous optimization transaction named IS_MACHINE_AVAILABLE. It has these parameters:

• Input MACHINE_NAME to specify the machine.

• Inputs BEGIN_DATE and END_DATE to specify the time slot.

• Output AVAILABLE_FLAG to specify whether the machine is available in that time slot.

This PeopleCode example sets input parameter values and gets an output parameter value:

Local OptEngine &myopt;
Local integer &status;
Local string &machname;
Local datetime &begindate;
Local datetime &enddate;
&myopt = GetOptEngine("PATSMITH");
&machname = QEOPT_WRK.MACHINE_NAME.Value;
&begindate = QEOPT_WRK.BEGIN_DATE.Value;
&enddate = QEOPT_WRK.END_DATE.Value;
/* Run the IS_MACHINE_AVAILABLE transaction synchronously with input values.  */
&status = &myopt.RunSynch("IS_MACHINE_AVAILABLE", "MACHINE_NAME",
 &machname, "BEGIN_DATE", &begindate, "END_DATE", &enddate);
If Not &status Then
   QEOPT_WRK.MESSAGE_TEXT = "IS_MACHINE_AVAILABLE transaction failed.";
   Return;
End-If;
/* Get output value from the IS_MACHINE_AVAILABLE transaction.  */
QEOPT_WRK.AVAILABLE_FLAG = &myopt.GetNumber("AVAILABLE_FLAG");

You can use the DetailedStatus property as follows:

QEOPT_WRK.AVAILABLE_FLAG = &myopt.GetNumber("AVAILABLE_FLAG");
if &myopt.DetailedStatus=%OptEng_Fail then
   /* perform some action */
End-if;

GetNumberArray

Syntax

GetNumberArray(PARAM_NAME)

Description

This method gets the value of a transaction output parameter with a data type Array of Number. This cannot be used with the RunAsynch method; RunSynch is needed to make the transaction output parameter values immediately available.

The DetailedStatus OptEngine property indicates the completion status of the OptEngine method call GetNumberArray. For GetNumberArray, DetailedStatus can have the value:

• %OptEng_Success.

• %OptEng_Fail.

• %OptEng_Method_Disabled

  This indicates that the method is disabled or not valid.

Note. Do not pass an array of type Integer as a transaction parameter. Use an array of type Number instead.

Parameters

Returns

Returns an Array of Number object; use this method when that is the data type of the transaction output parameter value.

Example

See OptEngine class: GetStringArray method.

GetString

Syntax

GetString(PARAM_NAME)

Description

This method gets the value of a transaction output parameter with a data type of String. This cannot be used with the RunAsynch method; RunSynch is needed to make the transaction output parameter values immediately available.

The DetailedStatus OptEngine property indicates the completion status of the OptEngine method call GetString. For GetString, DetailedStatus can have the value:

• %OptEng_Success.

• %OptEng_Fail.

• %OptEng_Method_Disabled: indicates that the method is disabled or not valid.

Parameters

Returns

Returns a String object; use this method when that is the data type of the transaction output parameter value.

Example

See OptEngine class: GetNumber method.

GetStringArray

Syntax

GetStringArray(PARAM_NAME)

Description

This method gets the value of a transaction output parameter with a data type Array of String. This cannot be used with the RunAsynch method; RunSynch is needed to make the transaction output parameter values immediately available.

The DetailedStatus OptEngine property indicates the completion status of the OptEngine method call GetStringArray. For GetStringArray, DetailedStatus can have the value:

• %OptEng_Success.

• %OptEng_Fail.

• %OptEng_Method_Disabled: indicates that the method is disabled or not valid.

Parameters

Returns

Returns an Array of String object; use this method when that is the data type of the transaction output parameter value.

Example

The following PeopleCode example runs a synchronous optimization transaction named ARE_MACHINES_AVAILABLE. It has these parameters:

• Inputs BEGIN_DATE and END_DATE to specify the time slot.

• Output MACHINE_NAMES to specify the machines available in that time slot.

This PeopleCode example sets input parameter values and gets an output parameter value:

Local OptEngine &myopt;
Local integer &status;
Local array of string &machnames;
Local datetime &begindate;
Local datetime &enddate;
&myopt = GetOptEngine("PATSMITH");
&begindate = QEOPT_WRK.BEGIN_DATE.Value;
&enddate = QEOPT_WRK.END_DATE.Value;
/* Run the ARE_MACHINES_AVAILABLE transaction synchronously with input values.  */
&status = &myopt.RunSynch("ARE_MACHINES_AVAILABLE",
 "BEGIN_DATE", &begindate, "END_DATE", &enddate);
If &status=%OptEng_Fail Then
   QEOPT_WRK.MESSAGE_TEXT = "ARE_MACHINES_AVAILABLE transaction failed.";
   Return;
End-If;
/* Get output value from the ARE_MACHINES_AVAILABLE transaction.  */
&machnames = &myopt.GetStringArray("MACHINE_NAMES");

The following example shows the use of the DetailedStatus property:

Local array of string &machnames;
&machnames = &myopt.GetStringArray("MACHINE_NAMES");
if &myopt.DetailedStatus=%OptEng_Fail then
   /* perform some action */
End-if;

GetTime

Syntax

GetTime(PARAM_NAME)

Description

This method gets the value of a transaction output parameter with a data type of Time. This cannot be used with the RunAsynch method; RunSynch is needed to make the transaction output parameter values immediately available.

The DetailedStatus OptEngine property indicates the completion status of the OptEngine method call GetTime. For GetTime, DetailedStatus can have the value:

• %OptEng_Success.

• %OptEng_Fail.

• %OptEng_Method_Disabled: indicates that the method is disabled or not valid.

Parameters

Returns

Returns a Time object; use this method when that is the data type of the transaction output parameter value.

Example

See OptEngine class: GetNumber method.

GetTimeArray

Syntax

GetTimeArray(PARAM_NAME)

Description

This method gets the value of a transaction output parameter with a data type Array of Time. This cannot be used with the RunAsynch method; RunSynch is needed to make the transaction output parameter values immediately available.

The DetailedStatus OptEngine property indicates the completion status of the OptEngine method call GetTimeArray. For GetTimeArray, DetailedStatus can have the value:

• %OptEng_Success.

• %OptEng_Fail.

• %OptEng_Method_Disabled: indicates that the method is disabled or not valid.

Parameters

Returns

Returns an Array of Time object; use this method when that is the data type of the transaction output parameter value.

Example

See OptEngine class: GetStringArray method.

GetTraceLevel

Syntax

GetTraceLevel(component)

Description

GetTraceLevel gets the severity level at which events are logged for a given component.

The DetailedStatus OptEngine property indicates the completion status of the OptEngine method call GetTraceLevel. For GetTraceLevel, DetailedStatus can have the value:

• %OptEng_Success.

  This indicates that the function completed successfully.

• %OptEng_Fail.

  This indicates that the function failed.

• %OptEng_Method_Disabled.

  This indicates that the method is disabled or not valid.

• %OptEng_DB_Updates_Pending.

  This indicates that database updates are pending.

Parameters

Returns

Returns one of the following.

• %Severity_Fatal

• %Severity_Status

• %Severity_Error

• %Severity_Warn

• %Severity_Info

• %Severity_Trace1

• %Severity_Trace2

Example

Local OptEngine &myopt; 
Local integer &tracelevel;

&myopt = GetOptEngine("PATSMITH");  

&tracelevel = &myopt.GetTraceLevel(%Opt_Engine);
if &myopt.DetailedStatus = %OptEng_Success then

   if (&tracelevel = %Severity_Info_ then
      winmessage("Severity level for the OptEngine is 'Info'");
   End-if;
End-if;

RunAsynch

Syntax

RunAsynch(TRANSACTION, PARM_PAIRS)

Description

The RunAsynch method requests the optimization engine to run the transaction in asynchronous mode.

When using the DetailedStatus OptEngine property, keep the following in mind:

• The value returned by RunASynch is the operational status of the optimization engine.

• The DetailedStatus OptEngine property indicates the completion status of the OptEngine method call RunASynch.

For example, RunASynch can return %OptEng_Fail and DetailedStatus is %OptEng_DB_Updates_Pending. For RunASynch, DetailedStatus can have the value:

• %OptEng_Success: indicates that the function completed successfully.

• %OptEng_Fail: indicates that the function failed.

• %OptEng_Method_Disabled: indicates that the method is disabled or not valid.

• %OptEng_DB_Updates_Pending: indicates that database updates are pending.

Parameters

Returns

This method returns a constant. Valid values are:

Example

This PeopleCode example runs an asynchronous optimization transaction named SOLVE. It has no input or output parameters. The SOLVE transaction solves the exercise scheduling problem and puts the results into the QE_RWSM_EXERSCH table.

Local OptEngine &myopt;
Local integer &status;
&myopt = GetOptEngine("PATSMITH");
/* Run the SOLVE transaction asynchronously with input values.  */
&status = &myopt.RunAsynch("SOLVE");
If &status=%OptEng_Fail Then
   QEOPT_WRK.MESSAGE_TEXT = "SOLVE transaction failed.";
   Return;
End-If;

The following example shows the use of the DetailedStatus property.

Local integer &status;
&status = myopt.RunAsynch("SOLVE");
if &status=%OptEng_Fail and &myopt.DetailedStatus=%OptEng_Method_Disabled then
   <perform some action>
End-if;

RunSynch

Syntax

RunSynch(TRANSACTION, PARM_PAIRS)

Description

The RunSynch method requests the optimization engine to run the transaction in synchronous mode.

When using the DetailedStatus OptEngine property, keep the following in mind:

• The value returned by RunSynch is the operational status of the optimization engine.

• The DetailedStatus OptEngine property indicates the completion status of the OptEngine method call RunSynch.

For example, RunSynch can return %OptEng_Fail and DetailedStatus is %OptEng_DB_Updates_Pending. For RunSynch, DetailedStatus can have the value:

• %OptEng_Success: indicates that the function completed successfully.

• %OptEng_Fail: indicates that the function failed.

• %OptEng_Method_Disabled: indicates that the method is disabled or not valid.

• %OptEng_DB_Updates_Pending: indicates that database updates are pending.

Parameters

Returns

This method returns a constant. Valid values are:

Example

The following PeopleCode example runs a synchronous optimization transaction named IS_MACHINE_AVAILABLE. It has these parameters:

• Input MACHINE_NAME to specify the machine.

• Inputs BEGIN_DATE and END_DATE to specify the time slot.

• Output AVAILABLE_FLAG to specify whether the machine is available in that time slot.

This PeopleCode example sets input parameter values and gets an output parameter value:

Local OptEngine &myopt;
Local integer &status;
Local string &machname;
Local datetime &begindate;
Local datetime &enddate;
&myopt = GetOptEngine("PATSMITH");
&machname = QEOPT_WRK.MACHINE_NAME.Value;
&begindate = QEOPT_WRK.BEGIN_DATE.Value;
&enddate = QEOPT_WRK.END_DATE.Value;
/* Run the IS_MACHINE_AVAILABLE transaction synchronously with input values.  */
&status = &myopt.RunSynch("IS_MACHINE_AVAILABLE",
 "MACHINE_NAME", &machname, "BEGIN_DATE", &begindate, "END_DATE", &enddate);
If &status=%OptEng_Fail Then
   QEOPT_WRK.MESSAGE_TEXT = "IS_MACHINE_AVAILABLE transaction failed.";
   Return;
End-If;
/* Get output value from the IS_MACHINE_AVAILABLE transaction.  */
QEOPT_WRK.AVAILABLE_FLAG = &myopt.GetNumber("AVAILABLE_FLAG");

Or, the following example shows the use of the DetailedStatus property.

Local integer &status;
&status = myopt.RunSynch("SOLVE");
if &status=%OptEng_Fail and &myopt.DetailedStatus=%OptEng_Method_Disabled then
   <perform some action>
End-if;

SetTraceLevel

Syntax

SetTraceLevel(component, severity )

Description

SetTraceLevel sets the severity level at which events are logged for a given component.

When using the DetailedStatus OptEngine property, keep the following in mind:

• The value returned by SetTraceLevel is the operational status of the optimization engine.

• The DetailedStatus OptEngine property indicates the completion status of the OptEngine method call SetTraceLevel.

For example, SetTraceLevel can return %OptEng_Fail and DetailedStatus is %OptEng_DB_Updates_Pending. For SetTraceLevel, DetailedStatus can have the value:

• %OptEng_Success: indicates that the function completed successfully.

• %OptEng_Fail: indicates that the function failed.

• %OptEng_Method_Disabled: indicates that the method is disabled or not valid.

• %OptEng_DB_Updates_Pending: indicates that database updates are pending.

Parameters

Returns

This method returns a constant. Valid values are:

Example

Local OptEngine &myopt; 
Local integer &status;  
Local string &machname; 
Local datetime &begindate; 
Local datetime &enddate;
 
&myopt = GetOptEngine("PATSMITH");  

&status = &myopt.SetTraceLevel(%Opt_Engine, %Severity_Warn);  
if &status = %OptEng_Fail then
   <example: notify user that set trace action has failed> 
End-if;

ShutDown

Syntax

ShutDown()

Description

The ShutDown method requests the optimization engine to shut down.

If the optimization engine cannot be contacted for shutdown, the return status is %OptEng_Fail and the DetailedStatus property is OptEng_Not_Available.

When using the DetailedStatus OptEngine property, keep the following in mind:

• The value returned by Shutdown is the operational status of the optimization engine.

• The DetailedStatus OptEngine property indicates the completion status of the OptEngine method call Shutdown.

For example, Shutdown can return %OptEng_Fail and DetailedStatus is %OptEng_DB_Updates_Pending. For Shutdown, DetailedStatus can have the value:

• %OptEng_Success: indicates that the function completed successfully.

• %OptEng_Fail: indicates that the function failed.

• %OptEng_Method_Disabled: indicates that the method is disabled or not valid.

• %OptEng_DB_Updates_Pending: indicates that database updates are pending.

Note. Before this method is called, CreateOptEngine or GetOptEngine must be called. Call ShutDown to shut down optimization engines even when running in PeopleSoft Application Engine.

Parameters

None.

Returns

This method returns a constant. Valid values are:

Example

This PeopleCode example shows an optimization engine being shut down:

Local OptEngine &myopt;
Local integer &status;
&myopt = GetOptEngine("PATSMITH");
/* Shut down the optimization engine */
&status = &myopt.ShutDown();
If &status=%OptEng_Fail Then
   QEOPT_WRK.MESSAGE_TEXT = "PATSMITH optimization engine shutdown failed.";
   Return;
Else
   QEOPT_WRK.MESSAGE_TEXT = "PATSMITH optimization engine shutdown successful.";
   Return;
End-If;

The following example shows the use of the DetailedStatus property:

Local integer &status;
&status = myopt.ShutDown();
if &status=%OptEng_Fail and &myopt.DetailedStatus=%OptEng_Method_Disabled then
   <perform some action>
End-if;

OptEngine Class Properties

This section lists the optimization properties for the OptEngine PeopleCode class. The properties are listed in alphabetical order.

DetailMsgs

Description

The DetailMsgs property returns a list of messages generated by an optimization engine. Use DetailMsgs after you use the RunAsynch and RunSynch methods to check the status messages for an optimization transaction.

If the transaction fails, detailed messages are automatically shown to the user. If the transaction succeeds, warnings and informational messages may be generated by the transaction. Use this property to retrieve those messages and make them available to the user.

DetailMsgs provides a two-dimensional array containing the message set ID, the message number in the message catalog, and any arguments. Each row in the two-dimensional array has the following structure:

1. Message set ID.

2. Message number.

3. Number of message arguments.

4. Argument1.

5. Argument2.

6. Argument3.

7. Argument4.

8. Argument5.

A maximum of five arguments is supported for each message.

Note. To hold the property value returned, you need to declare an array of array of type Any.

Note. Before this method is called, you must call CreateOptEngine or GetOptEngine.

Example

Local OptEngine &myopt;
Local integer &status;
Local string &piid;

Local string &string; 
Local array of array of any &arrArray;
 
&NEWLINE = Char(10);
&string = "";

&piid = GetRecord(Record.PSOPTPRBINST).GetField(Field.PROBINST).Value;
&myopt = GetOptEngine(&piid);

&status = &myopt.RunSynch("TEST_TRANSACTION");

If (&status = %OptEng_Success) then

&arrArray = &myopt.DetailMsgs;
For &iloop = 1 To &arrArray.Len
 
   &string = &string | &NEWLINE | MsgGetText(&arrArray [&iloop][1] /*message set*/, 
   &arrArray [&iloop][2] /*message id*/, "Message Not Found",&arrArray[&iloop][4], 
   &arrArray [&iloop][5],&arrArray [&iloop][6],
&arrArray [&iloop][7],&arrArray[&iloop][8]);

End-For;

GetLevel0().GetRow(1).GetRecord(Record.QE_FUNCLIB_OPT).DESCRLONG.Value = &string;
End-If;

DetailedStatus

Description

The DetailedStatus property contains the detailed execution status of an OptEngine method after the method is executed.

Example

Local integer &status;
&status = myopt.ShutDown();
if &status=%OptEng_Fail and &myopt.DetailedStatus=%OptEng_Method_Disabled then
   <perform some action>
End-if;

OptBase Application Class

This PeopleCode application class is part of the PT_OPT_BASE application package. It establishes the basic framework for developing PeopleCode that invokes the Optimization PeopleCode plug-in. To use the plug-in, you develop a application class that extends the OptBase application class. OptBase contains the following types of methods:

• A set of base methods that you can extend for the purpose of handling input and output parameters.

  You can use them within any method you develop that corresponds by name to a transaction in an analytic type definition. These methods apply to the parameters that are defined for the transaction in the analytic type.

• A set of abstract placeholder methods that you can use to implement callback capability.

  You must extend these if you designate one or more records as callback records in your analytic type definition, even if you don't add any functionality to the methods.

• An abstract placeholder method, Init, that you can extend if you want to do any preprocessing before your first Optimization PeopleCode plug-in transaction runs.

Note. The analytic type definition to which these methods apply is the one that specifies this derived application class.

The CreateOptInterface function is the only optimization built-in function that you can use within an application class that you extend from the OptBase application class, or within PeopleCode that you call from that application class.

Optbase Callback Methods

PeopleSoft Optimization Framework has a built-in callback functionality — when the OptInterface PeopleCode calls an Optimization PeopleCode plug-in transaction, it first determines whether you designated one or more records in your analytic type definition as callback records. For each callback record, the framework determines if any the record's database rows have been inserted, deleted, or updated since the optimization datacache was populated. If any changes have occurred, the framework propagates those changes to the datacache before invoking the transaction.

PeopleSoft provides methods that the framework uses to apply its callback functionality. In combination with the framework's callback changes, you might want to perform additional processing for your own purposes, including updating any derived data structures that are used by your optimization application. You can accomplish this by extending the callback methods and adding your own PeopleCode. Each callback method launches under different circumstances.

Note. Don't call any of these methods in your own PeopleCode. They're called automatically at the appropriate moment by PeopleSoft Optimization Framework, which enables your added functionality to run within each method.

Following is a list of the abstract callback placeholder methods documented as part of the PT_OPT_BASE:OptBase application class:

• OptInsertCallback

  This method launches when the framework propagates to the datacache any database insertions encountered for a callback record.

• OptDeleteCallback

  This method launches when the framework propagates to the datacache any database deletions encountered for a callback record.

• OptPreUpdateCallback

  This method launches before the framework propagates each database update encountered for a callback record.

• OptPostUpdateCallback

  This method launches after the framework propagates each database update encountered for a callback record.

• OptRefreshCallback

  This method launches after the framework propagates all database deletions, insertions, and updates encountered for all callback records.

Important! If any record in your analytic type definition is designated a callback record, you must ensure that you extend all of the callback methods in your extended class, even if each extended method contains only a Return statement. Otherwise your Optimization PeopleCode plug-in will fail.

See Configuring Analytic Type Records.

OptBase Class Methods

This section discusses the abstract base class placeholder methods for the PT_OPT_BASE:OptBase application class. The methods are listed in alphabetical order.

GetParmDate

Syntax

GetParmDate(parmName, &parmVal)

Description

The GetParmDate method retrieves a Date parameter value that's passed as input by any method you develop that corresponds to an Optimization PeopleCode plug-in transaction. You develop the transaction method in an application class that you derive from the OptBase application class.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

GetParmDateArray

Syntax

GetParmDateArray(parmName, &parmVal)

Description

The GetParmDateArray method retrieves a Date array parameter value that's passed as input by any method you develop that corresponds to an Optimization PeopleCode plug-in transaction. You develop the transaction method in an application class that you derive from the OptBase application class.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

GetParmDateTime

Syntax

GetParmDateTime(parmName, &parmVal)

Description

The GetParmDateTime method retrieves a DateTime parameter value that's passed as input by any method you develop that corresponds to an Optimization PeopleCode plug-in transaction. You develop the transaction method in an application class that you derive from the OptBase application class.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

GetParmDateTimeArray

Syntax

GetParmDateTimeArray(parmName, &parmVal)

Description

The GetParmDateTimeArray method retrieves a DateTime array parameter value that's passed as input by any method you develop that corresponds to an Optimization PeopleCode plug-in transaction. You develop the transaction method in an application class that you derive from the OptBase application class.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

GetParmNumber

Syntax

GetParmNumber(parmName, &parmVal)

Description

The GetParmNumber method retrieves a Number parameter value that's passed as input by any method you develop that corresponds to an Optimization PeopleCode plug-in transaction. You develop the transaction method in an application class that you derive from the OptBase application class.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

GetParmNumberArray

Syntax

GetParmNumberArray(parmName, &parmVal)

Description

The GetParmNumberArray method retrieves a Number array parameter value that's passed as input by any method you develop that corresponds to an Optimization PeopleCode plug-in transaction. You develop the transaction method in an application class that you derive from the OptBase application class.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

GetParmInt

Syntax

GetParmInt(parmName, &parmVal)

Description

The GetParmInt method retrieves an Integer parameter value that's passed as input by any method you develop that corresponds to an Optimization PeopleCode plug-in transaction. You develop the transaction method in an application class that you derive from the OptBase application class.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

GetParmIntArray

Syntax

GetParmIntArray(parmName, &parmVal)

Description

The GetParmIntArray method retrieves a Number array parameter value that's passed as input by any method you develop that corresponds to an Optimization PeopleCode plug-in transaction. You develop the transaction method in an application class that you derive from the OptBase application class.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

GetParmString

Syntax

GetParmString(parmName, &parmVal)

Description

The GetParmString method retrieves a String parameter value that's passed as input by any method you develop that corresponds to an Optimization PeopleCode plug-in transaction. You develop the transaction method in an application class that you derive from the OptBase application class.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

GetParmStringArray

Syntax

GetParmStringArray(parmName, &parmVal)

Description

The GetParmStringArray method retrieves a String array parameter value that's passed as input by any method you develop that corresponds to an Optimization PeopleCode plug-in transaction. You develop the transaction method in an application class that you derive from the OptBase application class.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

GetParmTime

Syntax

GetParmTime(parmName, &parmVal)

Description

The GetParmTime method retrieves a Time parameter value that's passed as input by any method you develop that corresponds to an Optimization PeopleCode plug-in transaction. You develop the transaction method in an application class that you derive from the OptBase application class.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

GetParmTimeArray

Syntax

GetParmTimeArray(parmName, &parmVal)

Description

The GetParmTimeArray method retrieves a Time array parameter value that's passed as input by any method you develop that corresponds to an Optimization PeopleCode plug-in transaction. You develop the transaction method in an application class that you derive from the OptBase application class.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

Init

Syntax

Init()

Description

The Init method launches when the CreateOptEngine built-in function loads an analytic instance that uses the Optimization PeopleCode plug-in.

Use this method to perform additional processing for your own purposes, including checking table data, or any functionality you want to apply before any plug-in transactions run. You accomplish this by adding your own PeopleCode to the extended method.

Don't call this method in your own PeopleCode. It's called automatically at the appropriate moment by PeopleSoft Optimization Framework, which enables your added functionality to run before any other code in your extended class.

Note. If you don't extend this method, PeopleSoft Optimization Framework calls its base version from the OptBase application class.

Parameters

None.

Returns

A Boolean value: True if the method is successful, False otherwise.

OptDeleteCallback

Syntax

OptDeleteCallback(&Record)

Description

The OptDeleteCallback method launches when PeopleSoft Optimization Framework propagates to the datacache any database deletions that it encounters for a callback record.

Use this method to perform additional processing for your own purposes, including modifying any derived data structures that might be affected by the deletion. You accomplish this by adding your own PeopleCode to the extended method.

Don't call this method in your own PeopleCode. It's called automatically at the appropriate moment by PeopleSoft Optimization Framework, which enables your added functionality to run.

Important! If you designate any record in the analytic type definition as a callback record, you must ensure that you extend this callback method in your derived class, even if the extended method contains only a Return statement. Otherwise the Optimization PeopleCode plug-in will fail.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

OptInsertCallback

Syntax

OptInsertCallback(&Record)

Description

The OptInsertCallback method launches when PeopleSoft Optimization Framework propagates to the datacache any database insertion that it encounters for a callback record.

Use this method to perform additional processing for your own purposes, including modifying any derived data structures that might be affected by the insertion. You accomplish this by adding your own PeopleCode to the extended method.

Don't call this method in your own PeopleCode. It's called automatically at the appropriate moment by PeopleSoft Optimization Framework, which enables your added functionality to run.

Important! If you designate any record in the analytic type definition as a callback record, you must ensure that you extend this callback method in your derived class, even if the extended method contains only a Return statement. Otherwise the Optimization PeopleCode plug-in will fail.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

OptPostUpdateCallback

Syntax

OptPostUpdateCallback(&OldRecord, &NewRecord)

Description

The OptPostUpdateCallback method launches after PeopleSoft Optimization Framework propagates to the datacache any database update that it encounters for a callback record.

Use this method to perform additional processing for your own purposes, including modifying any derived data structures that might have been affected by the update. You accomplish this by adding your own PeopleCode to the extended method. The parameters provide the previous and current content of the row.

Don't call this method in your own PeopleCode. It's called automatically at the appropriate moment by PeopleSoft Optimization Framework, which enables your added functionality to run.

Important! If you designate any record in the analytic type definition as a callback record, you must ensure that you extend this callback method in your derived class, even if the extended method contains only a Return statement. Otherwise the Optimization PeopleCode plug-in will fail.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

OptPreUpdateCallback

Syntax

OptPreUpdateCallback(&OldRecord, &NewRecord)

Description

The OptPreUpdateCallback method launches before PeopleSoft Optimization Framework propagates to the datacache any database update that it encounters for a callback record.

Use this method to perform additional processing for your own purposes, including modifying any derived data structures that might be affected by the update. You accomplish this by adding your own PeopleCode to the extended method. The parameters provide the current and future content of the row.

Don't call this method in your own PeopleCode. It's called automatically at the appropriate moment by PeopleSoft Optimization Framework, which enables your added functionality to run.

Important! If you designate any record in the analytic type definition as a callback record, you must ensure that you extend this callback method in your derived class, even if the extended method contains only a Return statement. Otherwise the Optimization PeopleCode plug-in will fail.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

OptRefreshCallback

Syntax

OptRefreshCallback()

Description

The OptRefreshCallback method launches after PeopleSoft Optimization Framework propagates to the datacache all database insertions, deletions, and updates that it encounters for all callback records.

Use this method to perform additional processing for your own purposes, including modifying any derived data structures that might be affected by the modifications. You accomplish this by adding your own PeopleCode to the extended method.

Don't call this method in your own PeopleCode. It's called automatically at the appropriate moment by PeopleSoft Optimization Framework, which enables your added functionality to run.

Important! If you designate any record in the analytic type definition as a callback record, you must ensure that you extend this callback method in your derived class, even if the extended method contains only a Return statement. Otherwise the Optimization PeopleCode plug-in will fail.

Parameters

None.

Returns

A Boolean value: True if the method is successful, False otherwise.

SetOutputParmDate

Syntax

SetOutputParmDate(parmName, &parmVal)

Description

Use the SetOutputParmDate method to pass a Date parameter value as output from any method you develop that corresponds to an Optimization PeopleCode plug-in transaction. You develop the transaction method in an application class that you derive from the OptBase application class.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

SetOutputParmDateArray

Syntax

SetOutputParmDateArray(parmName, &parmVal)

Description

Use the SetOutputParmDateArray method to pass a Date array parameter value as output from any method you develop that corresponds to an Optimization PeopleCode plug-in transaction. You develop the transaction method in an application class that you derive from the OptBase application class.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

SetOutputParmDateTime

Syntax

SetOutputParmDateTime(parmName, &parmVal)

Description

Use the SetOutputParmDateTime method to pass a DateTime parameter value as output from any method you develop that corresponds to an Optimization PeopleCode plug-in transaction. You develop the transaction method in an application class that you derive from the OptBase application class.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

SetOutputParmDateTimeArray

Syntax

SetOutputParmDateTimeArray(parmName, &parmVal)

Description

Use the SetOutputParmDateTimeArray method to pass a DateTime array parameter value as output from any method you develop that corresponds to an Optimization PeopleCode plug-in transaction. You develop the transaction method in an application class that you derive from the OptBase application class.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

SetOutputParmNumber

Syntax

SetOutputParmNumber(parmName, &parmVal)

Description

Use the SetOutputParmNumber method to pass a Number parameter value as output from any method you develop that corresponds to an Optimization PeopleCode plug-in transaction. You develop the transaction method in an application class that you derive from the OptBase application class.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

SetOutputParmNumberArray

Syntax

SetOutputParmNumberArray(parmName, &parmVal)

Description

Use the SetOutputParmNumberArray method to pass a Number array parameter value as output from any method you develop that corresponds to an Optimization PeopleCode plug-in transaction. You develop the transaction method in an application class that you derive from the OptBase application class.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

SetOutputParmInt

Syntax

SetOutputParmInt(parmName, &parmVal)

Description

Use the SetOutputParmInt method to pass an Integer parameter value as output from any method you develop that corresponds to an Optimization PeopleCode plug-in transaction. You develop the transaction method in an application class that you derive from the OptBase application class.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

SetOutputParmIntArray

Syntax

SetOutputParmIntArray(parmName, &parmVal)

Description

Use the SetOutputParmIntArray method to pass a Number array parameter value as output from any method you develop that corresponds to an Optimization PeopleCode plug-in transaction. You develop the transaction method in an application class that you derive from the OptBase application class.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

SetOutputParmString

Syntax

SetOutputParmString(parmName, &parmVal)

Description

Use the SetOutputParmString method to pass a String parameter value as output from any method you develop that corresponds to an Optimization PeopleCode plug-in transaction. You develop the transaction method in an application class that you derive from the OptBase application class.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

SetOutputParmStringArray

Syntax

SetOutputParmStringArray(parmName, &parmVal)

Description

Use the SetOutputParmStringArray method to pass a String array parameter value as output from any method you develop that corresponds to an Optimization PeopleCode plug-in transaction. You develop the transaction method in an application class that you derive from the OptBase application class.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

SetOutputParmTime

Syntax

SetOutputParmTime(parmName, &parmVal)

Description

Use the SetOutputParmTime method to pass a Time parameter value as output from any method you develop that corresponds to an Optimization PeopleCode plug-in transaction. You develop the transaction method in an application class that you derive from the OptBase application class.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

SetOutputParmTimeArray

Syntax

SetOutputParmTimeArray(parmName, &parmVal)

Description

Use the SetOutputParmTimeArray method to pass a Time array parameter value as output from any method you develop that corresponds to an Optimization PeopleCode plug-in transaction. You develop the transaction method in an application class that you derive from the OptBase application class.

Parameters

Returns

A Boolean value: True if the method is successful, False otherwise.

OptInterface Class Methods

This section discusses the optimization methods for the OptInterface PeopleCode class. The methods are listed in alphabetical order.

Note. You can use the OptInterface class methods only within an application class that you extend from the OptBase application class, or within PeopleCode that you call from that application class. This ensures that the OptInterface PeopleCode runs only on the optimization engine.

ActivateModel

Syntax

ActivateModel(ModelID, SolverSettingID)

Description

The ActivateModel method designates the specified model and solver setting as active. The model and the solver are initialized and populated with data from the current analytic instance.

Note. This method fails if the specified model (and by extension, one of its solver settings) is already active. If you want to activate a different solver setting for the same model, you must first deactivate the model.

See OptInterface class: DeactivateModel method.

Parameters

Returns

This method returns a constant value. Valid values are:

Example

Local integer &result;
Local OptInterface &oi = CreateOptInterface();

&result = &oi.ActivateModel("QE_PSA_MODEL", "abc");

ActivateObjective

Syntax

ActivateObjective(Model_Name, Objective_Name)

Description

Use the ActivateObjective method to activate the specified objective for an optimization model.

Parameters

Returns

This method returns a constant value. Valid values are:

DeactivateModel

Syntax

DeactivateModel(ModelID)

Description

The DeactivateModel method detaches the solver from the specified model.

Parameters

Returns

This method returns a constant value. Valid values are:

Example

Local integer &result;
Local OptInterface &oi = CreateOptInterface();

&result = &oi.DeactivateModel("QE_PSA_MODEL");

DumpMsgToLog

Syntax

DumpMsgToLog(LogSeverity, Message)

Description

The DumpMsgToLog method writes the specified status message to the optimization engine log file, with the specified severity.

Parameters

Returns

None.

FindRowNum

Syntax

FindRowNum(&Record [, startrow [, endrow [, field_list]]])

Where field_list is a list of field names in the form:

[fieldname1 [, fieldname2]]...

Description

The FindRowNum method determines the row number of a row in the datacache rowset. You provide a record with key values, and this method finds the row with the same key values and returns its row number.

Parameters

Returns

The row number of the row containing the specified key values, or 0 if no row is found.

Example

The following example searches the whole scroll to find the partial key OPT_SITE:

Local Record &rec = CreateRecord(Scroll.OPT_TRANSCOST);
Local Optineterface &oi;

&rec.OPT_SITE.value = "New York";
int nRowNum = &oi.FindRowNum(&rec, 0, 0, "OPT_SITE");

The following example searches from row 5 to row 15 with the full key values New York and San Jose:

Local Record &rec = CreateRecord(Scroll.OPT_TRANSCOST);
Local Optineterface &oi;

&rec.OPT_SITE.value = "New York";
&rec.OPT_STORE.value = "San Jose";
int nRowNum = &oi.FindRowNum(&rec, 5, 15);	

GetSolution

Syntax

GetSolution(ModelID, varArrayID, skipZero [, KeyFieldNames, KeyFieldValues [, &Solution]])

Description

The GetSolution method retrieves the model solution values generated by the Solve method.

Parameters

Returns

This method returns a constant value. Valid values are:

Example

Local array of string &strArray;
Local array of any &valArray;
Local integer &index;
Local Rowset &rowSet;
Local integer &result;
Local string &modelId = "QE_PSA_MODEL";
Local string &varArrayName = "X";
Local boolean &bSkipZero = True;

Local OptInterface &oi = CreateOptInterface();

&strArray = CreateArrayRept("", 0);
&valArray = CreateArrayAny();
&rowSet = CreateRowset(Record.QEOPT_VAL_X_WRK);

&strArray [1] = "EMPLID";
&valArray [1] = 1;
&strArray [2] = "ORDER_ID";
&valArray [2] = 23;

/* fetch only the part of the solution where  EMPLID = 1 and ORDER_ID = 23 */
&result = &oi.GetSolution(&modelId, &varArrayName,
 &bSkipZero, &strArray, &valArray, &rowSet);

GetSolutionDetail

Syntax

GetSolutionDetail(ModelID, SolutionType, Name, &Solution)

Description

The GetSolutionDetail method retrieves the model solution detail of the specified type generated by the Solve method. You can retrieve dual value, slack value, or reduced cost information.

Parameters

Returns

This method returns a constant value. Valid values are:

Example

Local Rowset &dual_rowset;
Local integer &result;
Local OptInterface &oi = CreateOptInterface();
Local string &modelId = "QE_PSA_MODEL";
Local string &varArrayName = "X";
Local string &constrName = "Constraint_1";

/* fetch dual values for Contraint "Constraint_1"
 in a rowset based on the QEOPT_C1_WRK record */

&dual_rowset = CreateRowset(Record.QEOPT_C1_WRK);
&result = &oi.GetSolutionDetail(&modelId, %Opt_Dual, &constrName, &dual_rowset);

IsModelActive

Syntax

IsModelActive(ModelID)

Description

Use the IsModelActive method to determine if the model specified by ModelId is active before it is used.

Parameters

Returns

A boolean value: true if the model is active, false otherwise.

RestoreBounds

Syntax

RestoreBounds(modelID [,varArrayID])

Description

The RestoreBounds method returns the bounding values of the specified variable array or arrays to the current settings in the specified model.

If you previously called the SetVariableBounds method with the changeModelBounds parameter set to true for any variable or variable array, those bounding values still apply.

Parameters

Returns

%OptInter_Success if the method succeeds, %OptInter_Fail otherwise.

SetVariableBounds

Syntax

SetVariableBounds(modelID, varArrayID, boundType, lowerBound, upperBound, &keyRecord [, changeModelBounds])

Description

The SetVariableBounds method overrides the bounding values specified for a model variable array, or for a variable within the array.

Parameters

Returns

%OptInter_Success if the method succeeds, %OptInter_Fail otherwise.

Example

Local Record &rec;
Local integer &result;
Local OptInterface &oi = CreateOptInterface();
Local float &objval = 0.0;
Local string &modelId = "QE_PSA_MODEL";
Local string &varArrayName = "X";
Local float &lb = 0.0;
Local float &ub = 0.0;

&rec = CreateRecord(Record.QEOPT_VAL_X_WRK);
&rec.QEOPT_RESINDEX.Value = 1;
&rec.QEOPT_SOLINDEX.Value = 2;
&rec.QEOPT_TIMEINDEX.Value = 3;

&result = &oi.SetVariableBounds(&modelId, &varArrayName,
 %Opt_Upper_Bound, &lb, &ub, &rec, False);

SetVariableType

Syntax

SetVariableType(modelID, varArrayID, varType)

Description

Use the SetVariableType method to change the data type of a model variable array.

Parameters

Returns

%OptInter_Success if the method succeeds, %OptInter_Fail otherwise.

Example

Local OptInterface &oi = CreateOptInterface();
Local string &varArrayName = "X";
Local integer &result;

&result = &oi.SetVariableType("QE_PSA_MODEL",  &varArrayName, %Opt_Var_Bin);

If (&result <> %OptInter_Success) Then
   &oi.DumpMsgToLog(%Severity_Status, "Failed to change variable type ");
End-If;

Solve

Syntax

Solve(modelID, SolutionType [, &objValue [, name-value_pairs]])

Where name-value_pairs is a list of solver setting parameter values in the form:

[parmname1, parmvalue1 [, parmname2, parmvalue2]]...

Description

The Solve method solves the specified model using the currently active solver settings, and provides an objective value as the solution output. You can override the solver setting parameters. The returned solution status is a predefined system constant.

Parameters

Returns

One of the following system constants:

%OptInter_Fail: The solver fails to solve the problem.

%Opt_Optimal: The solution is optimal.

%Opt_Infeasible: The solution is infeasible.

%Opt_Unbounded: The solution is unbounded.

%Opt_Timeup: The solver reached the time limit specified in the solver setting.

%Opt_Iterlimit: The solver reached the limit on the number of iterations specified in the solver setting.

%Opt_LP_Max_Sols: The solver generated maximum number of solutions without improvement.

%Opt_Idle: The solution shows no improvement in a specified time limit.

%Opt_Unknown: The solver status is unknown.

%Opt_MIP_NumSolutions: The specified number of solutions corresponding to an MIP solver reached.

%Opt_MIP_NumNodes: The specified number of nodes corresponding to an MIP solver reached.

%Opt_Aborted: The solver aborted.

%Opt_User_Exit: A user exit was encountered.

%Opt_First_LP_NoOpt: While solving an MIP, the first LP solution obtained was not optimal.

Example

Following is an example of the basic use of the Solve method:

Local OptInterface &oi = CreateOptInterface();

Local float &objval = 0.0;
Local integer &result;
Local string &modelId = "QE_PSA_MODEL";
Local string &varArrayName = "X";   
Local integer &solType;

&solType = %Opt_RCost + %Opt_Dual + %Opt_Slack;

/* Solve the problem */
&result = &oi.Solve("QE_PSA_MODEL", &solType, &objval);

If & result = %Opt_Optimal Then
   &oi.DumpMsgToLog(%Severity_Warn, " Solution Status =  " Optimal !!!");
Else
   &oi.DumpMsgToLog(%Severity_Warn, " Solution Status =  " | &result );
End-If;

Following is an example of a solver setting parameter override:

Local OptInterface &oi = CreateOptInterface();
Local float &objval = 0.0;
Local integer &result;

/* This overrides the solver setting for MPS_Filename and generates
 an MPS file called myfile.mps instead of the name specified
 in the current solver setting parameter. */

&result = &oi.Solve("QE_PSA_MODEL", %Opt_Primal, &objval, "MPS_FileName", "myfile");