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: %Synch: run the optimization engine synchronously. %Asynch: run the optimization engine asynchronously.
`&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: %OptEng_Success: The function completed successfully. %OptEng_Fail: The function failed. %OptEng_Invalid_Aiid: The analytic instance ID passed to the function is invalid. %OptEng_Exists: An optimization engine instance already exists and is loaded. %OptEng_Method_Disabled: A method is disabled or not valid. %OptEng_DB_Updates_Pending: indicates that database updates are pending.
`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: %OptEng_Success: The function completed successfully. %OptEng_Fail: The function failed. %OptEng_Invalid_Piid: The analytic instance ID passed to the function is invalid. %OptEng_Sql_Exception: A SQLerror is encountered when access database. %OptEng_Exists: An analytic server loaded with this analytic instance still exists.

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:

%OptEng_Success: The function completed successfully.
%OptEng_Fail: The function failed.
%OptEng_Invalid_Piid: The analytic instance ID passed to the function is invalid.
%OptEng_Sql_Exception: A SQLerror is encountered when access database.
%OptEng_Exists: An analytic server loaded with this analytic instance still exists.

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: %OptEng_Success: The function completed successfully. %OptEng_Fail: The function failed. %OptEng_Invalid_Piid: The analytic instance ID passed to the function is invalid.

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:

%OptEng_Success: The function completed successfully.
%OptEng_Fail: The function failed.
%OptEng_Invalid_Piid: The analytic instance ID passed to the function is invalid.

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: %OptEng_Success: The function completed successfully. %OptEng_Fail: The function failed. %OptEng_Invalid_Piid: The analytic type name passed to the function is invalid.

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: %OptEng_Success: The function completed successfully. %OptEng_Fail: The function failed. %OptEng_Invalid_Piid: The analytic instance ID passed to the function is invalid.
`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: %OptEng_Success: The function completed successfully. %OptEng_Invalid_Piid: The analytic type name passed to the function is invalid.

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:

%OptEng_Success: The function completed successfully.
%OptEng_Invalid_Piid: The analytic type name passed to the function is invalid.

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;