Optimization Built-in Functions
This section discusses the optimization functions. The functions are discussed in alphabetical order.
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
Field or Control |
Definition |
---|---|
Analytic_inst |
Specify the analytic instance ID, which is a unique ID for this analytic instance in this optimization engine. This is supplied by users when they request that an optimization be run. |
%Synch | %Asynch |
Specify whether the optimization engine is synchronous or asynchronous. The values are:
|
&detailedstatus |
Specify a variable that the engine uses to give further information about the evaluation of this function. The value returned is one of the following:
|
processinstance |
Enter the process instance ID. You use this parameter only with lights-out processing, most likely with the subscription PeopleCode for application message. Note: This optional parameter is positional. If you use it, you must also use the &detailedstatus parameter. The state record that you use with Application Engine contains the process instance ID. See Using Lights-Out Mode with Optimization. See Using State Records. |
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;
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;
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 Workflow.
Note: Use this function to delete the analytic instance ID after deleting data in optimization application tables for this analytic instance.
Parameters
Field or Control |
Definition |
---|---|
probinst |
Enter the analytic instance ID to delete. |
&detailedstatus |
(Optional) This status reference parameter returns an integer value giving further information about the evaluation of this function. The value returned is one of the following:
|
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;
Syntax
GetOptEngine(probinst[,&detailedstatus])
Description
The GetOptEngine function returns a handle to an optimization engine that is already loaded with the analytic instance.
Note: You cannot call GetOptEngine from a domain other than the application server.
Parameters
Field or Control |
Definition |
---|---|
probinst |
Enter the analytic instance ID, which is unique ID for this analytic instance in this optimization engine. |
&detailedstatus |
(Optional) This status reference parameter returns an integer value giving further information about the evaluation of this function. The value returned is one of the following:
|
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;
Syntax
GetOptProbInstList(ProblemType , OutputErrorCode [, Prefix] [, &detailedstatus])
Description
The GetOptProbInstList function gets the list of all analytic instance IDs in an analytic type.
Parameters
Field or Control |
Definition |
---|---|
ProblemType |
Enter the name of the analytic type that you created in Application Designer. |
OutputErrorCode |
Future use. Always returns zero. |
Prefix |
(Optional) Enter a string. If used, this prefix causes the returned list to include only the analytic instance IDs that start with this prefix. If not used, all the analytic instance IDs in the analytic type are returned. |
&detailedstatus |
(Optional) This status reference parameter returns an integer value giving further information about the evaluation of this function. The value returned is one of the following:
|
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;
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 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
Field or Control |
Definition |
---|---|
probinst |
Enter the analytic instance ID to be inserted into the analytic type. |
ProblemType |
Enter the name of the analytic type that you created in Application Designer. |
&detailedstatus |
(Optional) This status reference parameter returns an integer value giving further information about the evaluation of this function. The value returned is one of the following:
|
Description |
(Optional) Specify a description for the analytic instance. This parameter takes a string value. |
Returns
This method returns a constant. Valid values are:
Value |
Description |
---|---|
%OptEng_Success |
Returned if method succeeds. |
%OptEng_Fail |
Returned if the method fails. |
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;
Syntax
IsValidOptProbInst(probinst [, &detailedstatus])
Description
IsValidOptProbInst determines if a given analytic instance exists in the optimization metadata.
Parameters
Field or Control |
Definition |
---|---|
probinst |
Enter the analytic instance ID to be validated. |
&detailedstatus |
(Optional) This status reference parameter returns an integer value giving further information about the evaluation of this function. The value returned is one of the following:
|
Returns
This method returns a constant. Valid values are:
Value |
Description |
---|---|
%OptEng_Success |
Returned if method succeeds. |
%OptEng_Fail |
Returned if the method fails. |
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;