FICO Xpress OptimizationR

Last update 21 November, 2019

8.9.0
REFERENCE MANUAL

Executor Library for Mosel

©2017–2020 Fair Isaac Corporation. All rights reserved. This documentation is the property of Fair Isaac
Corporation ("FICO"). Receipt or possession of this documentation does not convey rights to disclose,
reproduce, make derivative works, use, or allow others to use it except solely for internal evaluation
purposes to determine whether to purchase a license to the software described in this documentation, oras otherwise set forth in a written software license agreement between you and FICO (or a FICO afﬁliate).
Use of this documentation and the software described in it must conform strictly to the foregoing
permitted uses, and no other use is permitted.
The information in this documentation is subject to change without notice. If you ﬁnd any problems in thisdocumentation, please report them to us in writing. Neither FICO nor its afﬁliates warrant that thisdocumentation is error-free, nor are there any other warranties with respect to the documentation except
as may be provided in the license agreement. FICO and its afﬁliates speciﬁcally disclaim any warranties,
express or implied, including, but not limited to, non-infringement, merchantability and ﬁtness for aparticular purpose. Portions of this documentation and the software described in it may contain copyrightof various authors and may be licensed under certain third-party licenses identiﬁed in the software,
documentation, or both.
In no event shall FICO or its afﬁliates be liable to any person for direct, indirect, special, incidental, or
consequential damages, including lost proﬁts, arising out of the use of this documentation or the software
described in it, even if FICO or its afﬁliates have been advised of the possibility of such damage. FICO and
its afﬁliates have no obligation to provide maintenance, support, updates, enhancements, or modiﬁcations
except as required to licensed users under a license agreement.
FICO is a registered trademark of Fair Isaac Corporation in the United States and may be a registeredtrademark of Fair Isaac Corporation in other countries. Other product and company names herein may be
trademarks of their respective owners.
FICO R Xpress Optimization
Deliverable Version: A
Last Revised: 21 November, 2019
Version 8.9.0

Contents
1

Introduction
1.1 Xpress Executor in FICO Decision Management Platform . . . . . . . . . . . . . . . . . . .
1.2 Executor package for Mosel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1
1
1

2 Basic Principles

2

3 Authenticating
3.1 Using Executor Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2 Using a JSON Conﬁguration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3 Using from Xpress Insight in DMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4 Using local development mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3
3
4
5
6

4 Usage example

7

5 Types9

6 Variables

12

7 Subroutines
executordelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executordeleteall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executorexecute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executorfetchinput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executorfetchresult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executorfetchrunlog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executorfetchrunlogfragment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executorgetconcurrencylevel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executorgetexpiryhours . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executorgetinstanceconﬁg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executorgetmodelparams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executorinit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executorinitlocal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executorlist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executorpoll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executorrepositorystatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executorsetconcurrencylevel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executorsetexecmode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executorsetexpiryhours . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executorsetinputxsd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executorsetinstanceconﬁg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executorsetmodelﬁle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executorsetmodelparams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executorsetresultxsd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executorwaitfor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
getlasterror . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
getstatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

13
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

Fair Isaac Corporation Conﬁdential and Proprietary Informationi

Contents

8 Parameters
executor_verbose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executor_bearer_refresh_interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executor_poll_interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executor_local_workdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executor_components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executor_max_retries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
executor_retry_error_codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

42
42
42
43
43
43
43
44

9 Deprecated Functionality
9.1 dmpmanagerurl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

45
45

Appendix

46

A Contacting FICO
Product support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Product education . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Product documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sales and maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Related services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FICO Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
About FICO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

46
46
46
46
47
47
47
47

Index

48

Fair Isaac Corporation Conﬁdential and Proprietary Informationii

CHAPTER 1

Introduction
1.1

Xpress Executor in FICO Decision Management Platform
FICO Xpress Executor is a component that allows users to deploy optimization as a service within the
FICO Decision Management Platform (DMP). The component owner can conﬁgure the Xpress Executor
component either with a ﬁxed Mosel model, or to accept optimization problems in standard LP or
XMPS formats, and the optimizations will be executed asynchronously in response to SOAP or REST
webservice requests. For more information about Xpress Executor and the FICO Decision Management
Platform, see
www.ﬁcoanalyticcloud.com
This document assumes that the reader is a registered user of the FICO Analytic Cloud and has accessto at least one Xpress Executor component. For general information about DMP solutions,components, lifecycle stages and more, please consult the Decision Management Platform help byclicking the "Help" link on the DMP website. Below are summary deﬁnitions of some DMP terminology
used in this document, but please consult the DMP help for full information.







1.2

Solution - a named collection of Components and Services.
Component - a component provides capabilities that can be added to solutions. Components
typically expose a UI that can be interacted with directly, or webservices that can be called froman external application.
Component Lifecycle - a component has three lifecycle stages - design, staging and production.
You will edit your conﬁguration in the design stage, submit the conﬁguration to staging for testing,and deploy to production once you are satisﬁed. There is a different webservice URL forinteracting with each lifecycle stage of a component.
DMP Manager - the web site that allows you to manage your solutions and components.

Executor package for Mosel
The package executor allows the user to send commands to an Xpress Executor component running in
DMP, from either a local Mosel process or from an Xpress Insight component in the same DMP
solution. The package can be used to run model executions in the Xpress Executor component, as well
as modify the Xpress Executor design instance conﬁguration to a limited extent.
The package does not support direct promotion of conﬁguration to staging or production instances;
this must be done by submitting, approving and then deploying the conﬁguration throught the DMP UI.

Fair Isaac Corporation Conﬁdential and Proprietary Information

1

CHAPTER 2

Basic Principles
The executor library should be loaded into your model or package as follows:
uses "executor"

When you want to interact with an Xpress Executor component instance (design, staging or production),
you should declare a variable of the ’Executor’ type to represent the Executor component instance.
declarations
myexecutor: Executor
end-declarations

Once the ’Executor’ variable has been initialized with your component’s location and credentials (seechapter 3), it can be used with Executor functions such as executorexecute, executorwaitforand executorfetchresult. If you need to access more than one Executor component instance, you
can declare multiple Executor variables.
After calling each function on the executor library, you should check the value of Executor.status
for any errors - if this is any value other than EXECUTOR_OK then an error has occurred. In an errorcase, Executor.status will contain an error code and Executor.lasterror will return adescription of the error.

Fair Isaac Corporation Conﬁdential and Proprietary Information

2

CHAPTER 3

Authenticating
3.1

Using Executor Properties
The simplest way to deﬁne the corresponding properties of your Executor entity, for example:
model DirectInitExample
uses "executor"
declarations
myexecutor: Executor
end-declarations

myexecutor.componenturl := "https://vm65j75lqh-vm65j75lqh.dms.usw2.ficoanalyticcloud.com/"myexecutor.bearertokenurl := "https://iam-svc.dms.usw2.ficoanalyticcloud.com/registration/rest/cli
myexecutor.clientid := "vm5qh0y37c"
myexecutor.secret := "wdS97u648BVoI#d3e4g2Z4mP780Y1DLdSDKm"! myexecutor now initialized and can be used
end-model

To ﬁnd the component URL, bring up the drop-down menu beside the component name in DMP and
select "View Links". Use the value from the ’REST’ ﬁeld but remove everything after the domain name.
For example, if the link displayed is:https://vm65j75lqh-vm65j75lqh.dms.usw2.ficoanalyticcloud.com/rest/
runtime/execution?solutionID=vm5qh0y37c
then use
https://vm65j75lqh-vm65j75lqh.dms.usw2.ficoanalyticcloud.com/
The clientid and secret values for your solution can be found on the "Client Apps" page of the solution
screen in DMP. Finally, the bearertokenurl will be the URL from where we will obtain DMP
authentication tokens - consult the "Requesting a Bearer Token" page of the DMP documentation for
more details.
If you prefer to manage the authentication with DMP yourself, you can alternately initialize the Executor
with the component URL and a DMP bearer token, e.g.:model DirectInitExample
uses "executor"
declarations
myexecutor: Executor
end-declarations
myexecutor.componenturl := "https://vm65j75lqh-vm65j75lqh.dms.usw2.ficoanalyticcloud.com/"myexecutor.bearertoken := "xyfuehdsoguihUGHifsihf7hi"! myexecutor now initialized and can be used
end-model

Fair Isaac Corporation Conﬁdential and Proprietary Information3

Authenticating

However, note you will need to refresh the ’bearertoken’ value periodically as the tokens will expire. If
you initialize with clientid and secret, the ’executor’ module will request new bearer tokens when it
needs to.

3.2

Using a JSON Conﬁguration FileAs an alternative to setting credentials in the model, you can specify them in a JSON document, thecontents of which you assign to the executor_components parameter. The document should be in
the following format:{}"<component-id>": {"componentUrl": "<URL of component>","bearerTokenUrl": "<URL of DMP authentication service, optional>","clientId": "<clientId of DMP solution, optional>","secret": "<secret of DMP solution, optional>","bearerToken": "<DMP bearer token, optional>"}

The "<component-id>" string is a key that you use to refer to the component in the JSON and has noother meaning. You can specify multiple components in the same JSON ﬁle so long as they havedifferent "<component-id>" strings, e.g.:{}"main": {"componentUrl": "https://vm65j75lqh-vm65j75lqh.dms.usw2.ficoanalyticcloud.com/","bearerTokenUrl": "https://iam-svc.dms.usw2.ficoanalyticcloud.com/registration/rest/client/token"clientId": "vm5qh0y37c","secret": "wdS97u648BVoI#d3e4g2Z4mP780Y1DLdSDKm"},"dev": {"componentUrl": "https://6tk0a8qheb-6tk0a8qheb.dms.usw2.ficoanalyticcloud.com/","bearerTokenUrl": "https://iam-svc.dms.usw2.ficoanalyticcloud.com/registration/rest/client/token"clientId": "vm5qh0y37c","secret": "wdS97u648BVoI#d3e4g2Z4mP780Y1DLdSDKm"}

The JSON document must always specify the componentUrl, and either the bearerToken or all of
the bearerTokenUrl, clientId and secret values. If you do specify your own bearer token, beaware that it will eventually expire.
Then you can initialize an Executor in the model with the credentials from the JSON by calling theexecutorinit procedure. For example, if you save the above sample JSON in a ﬁle called"executors.json":model InitExample
uses "executor","mmsystem"
declarations
public jsoncfg: text
myexecutor: Executor
end-declarations! Load executors.json into a variable so it can be passed to a parameter
fcopy("executors.json","text:jsoncfg")
setparam("executor_components",string(jsoncfg))! Initialize myexecutor using the 'main' set of credentials
executorinit(myexecutor, "main")if myexecutor.status<>EXECUTOR_OK then

Fair Isaac Corporation Conﬁdential and Proprietary Information4

Authenticating
writeln("Executor initialization error: ", myexecutor.lasterror)exit(1)
end-if! myexecutor now initialized and can be used
end-model

The executor_components parameter is special in that it has a single value shared by all models
within the Mosel instance - this means that if, for example, you set it for your master model, then thesame value will be used for all submodels that you start in the same Mosel process.

3.3

Using from Xpress Insight in DMPWhen using Xpress Insight within DMP, the Mosel instance will automatically be conﬁgured to accessany Xpress Executor components in the same solution. To use this, simply call executorinit, passing thename of your Xpress Executor component:
model DmpInitExample
uses "executor"
declarations
myexecutor: Executor
end-declarations! Initialize myexecutor for the component called "My Executor"
executorinit(myexecutor, "My Executor")
if myexecutor.status<>EXECUTOR_OK thenwriteln("Executor initialization error: ", myexecutor.lasterror)exit(1)
end-if! myexecutor now initialized and can be used
end-model

Alternatively, if you call executorinit without a name, it will access the an Xpress Executor
component it ﬁnds in your solution:model DmpInitExample
uses "executor"
declarations
myexecutor: Executor
end-declarations! Initialize myexecutor for the an Xpress Executor component we findexecutorinit(myexecutor)
if myexecutor.status<>EXECUTOR_OK thenwriteln("Executor initialization error: ", myexecutor.lasterror)exit(1)
end-if! myexecutor now initialized and can be used
end-model

The Insight component instance will access Executor instances in the same lifecycle stage (forexample, an Insight in the staging environment will access the staging environment of Executor, notproduction or design). You can override this by specifying the environment on the ’executorinit’ line, forexample:model DmpInitExample
uses "executor"
declarations
myexecutor: Executor
end-declarations! Initialize myexecutor for the an Xpress Executor component we findFair Isaac Corporation Conﬁdential and Proprietary Information5

Authenticating
executorinit(myexecutor,"My Executor","STAGING")
if myexecutor.status<>EXECUTOR_OK thenwriteln("Executor initialization error: ", myexecutor.lasterror)exit(1)
end-if! myexecutor now initialized and can be used
end-model

3.4

Using local development mode
An Executor can also be initialized in a ’local’ mode that does not require a DMP component. In thisconﬁguration, Executor will run any submitted executions locally using Mosel submodels. This can be
conﬁgured as follows:model LocalInitExample
uses "executor"
declarations
myexecutor: Executor
end-declarations! Initialize myexecutor to simulate a Xpress Executor component using local submodels
executorinitlocal(myexecutor)
if myexecutor.status<>EXECUTOR_OK thenwriteln("Executor initialization error: ", myexecutor.lasterror)exit(1)
end-if! myexecutor now initialized and can be used
end-model

After being initialized, the ’local’ executor will always have an empty conﬁguration, so you should call
executorsetmodelfile and executorsetexecmode to conﬁgure it.
Once conﬁgured, you can interact with the local execution using the same functions as you would use
for a true Xpress Executor component (e.g. executorexecute, executorwaitfor,
executorfetchresult, ...). Local execution is supplied as an aid in developing your model and there
may be small differences between how your model reacts to errors locally and how it behaves in a real
Xpress Executor.
Note that the local Xpress Executor does not support the MPS or LP ﬁle execution mode, and theprogress ﬁeld of the ModelExecution record will always contain 0 regardless of the progress events
emitted by your models.

Fair Isaac Corporation Conﬁdential and Proprietary Information

6

CHAPTER 4

Usage example
This example demonstrates running an execution in an already-conﬁgured Xpress Executor component.
You will need to ﬁll in the model parameters with your Xpress Executor component details.
model ExecutorExecuteExample
uses "executor"
parameters
COMPONENT_URL = ""BEARER_TOKEN_URL = ""CLIENT_ID = ""SECRET = ""end-parameters
declarations
INPUT_FILE="MyExecutionInputFile.dat"
RESULT_FILE="MyExecutionResultFile.dat"
myexecutor: Executor
myexecution: ModelExecution
EXECUTION_TIMEOUT = 10⁎60 ! Timeout in seconds
end-declarations! Configure 'myexecutor' with our Xpress Executor component details
myexecutor.componenturl := COMPONENT_URL
myexecutor.bearertokenurl := BEARER_TOKEN_URL
myexecutor.clientid := CLIENT_ID
myexecutor.secret := SECRET! Start execution passing local input data
myexecution := executorexecute(myexecutor,INPUT_FILE)
if myexecutor.status<>EXECUTOR_OK thenwriteln("Error from Executor when starting execution: ",myexecutor.lasterror)exit(1)
end-if! Wait for execution to complete
executorwaitfor(myexecutor,myexecution,EXECUTION_TIMEOUT)
if myexecutor.status<>EXECUTOR_OK thenwriteln("Error from Executor when waiting for completion: ",myexecutor.lasterror)! If execution did not complete within time limit, display error
elif not myexecution.iscompleted thenwriteln("Execution failed to complete within ",EXECUTION_TIMEOUT,"s")! If execution completed with error, display error
elif myexecution.status<>EXECUTION_STATUS_OK or myexecution.exitcode<>0 thenwriteln("Execution failed with status ",myexecution.status," and exit code ",myexecution.exitcode)! In error cases, execution run log will contain valuable information
executorfetchrunlog(myexecutor,myexecution,"runlog.txt")
if myexecutor.status<>EXECUTOR_OK thenwriteln("Error from Executor when fetching run log: ",myexecutor.lasterror)
else

Fair Isaac Corporation Conﬁdential and Proprietary Information

7

Usage example
writeln("Run log saved in file runlog.txt")
end-if! If execution completed ok, download result
else! Completed okay, download results
executorfetchresult(myexecutor,myexecution,RESULT_FILE)
if myexecutor.status<>EXECUTOR_OK thenwriteln("Error from Executor when fetching results: ",myexecutor.lasterror)
else
writeln("Result data saved in file ",RESULT_FILE)
end-ifend-if! Delete execution from server
executordelete(myexecutor,myexecution)
if myexecutor.status<>EXECUTOR_OK thenwriteln("Error from Executor when deleting execution: ",myexecutor.lasterror)exit(1)
end-ifend-model

Fair Isaac Corporation Conﬁdential and Proprietary Information

8

CHAPTER 5

Types
ModelExecution : record
Record type representing information about the status of an execution in an Xpress Executor
component
id : text
The unique identifer of the execution
iscompleted : boolean
Whether the execution has completed (successfully or with errors), or not (notstarted or currently executing)hasinput : boolean
Whether the execution has input data.
hasresult : boolean
Whether the execution has result data.
isexecuting : boolean
Whether the execution is currently running (not completed and not waiting to start)
executionnode : text
The name of the gear on which the execution was executed
progress : real
Progress value as set by the model being executed. Always 0 in local mode.
status : string
Status of the execution. One of: EXECUTION_STATUS_OK,EXECUTION_STATUS_MATHERR, EXECUTION_STATUS_ERROR,EXECUTION_STATUS_IOERR, EXECUTION_STATUS_NIFCT,EXECUTION_STATUS_NULL, EXECUTION_STATUS_LICERR,
EXECUTION_STATUS_STOP, EXECUTION_STATUS_LOAD_ERROR,EXECUTION_STATUS_INTERNAL_ERROR,EXECUTION_STATUS_NOT_COMPLETED
exitcode : integer
The exit code of the model - the value passed to the Mosel exit() procedure, or 0
creationtimestamp : real
Timestamp when the execution was created, expressed as milliseconds since
1/1/1970 00:00 UTC
starttimestamp : real
Timestamp when the execution started to execute, expressed as milliseconds since
1/1/1970 00:00 UTC, or 0 if unset
ﬁnishtimestamp : real

Fair Isaac Corporation Conﬁdential and Proprietary Information

9

TypesTimestamp when the execution ﬁnished executing, expressed as milliseconds since
1/1/1970 00:00 UTC, or 0 if unset
modelparams : dynamic array(ExecutorParamNames) of text
Additional model parameters used with this execution

MoselInstanceConﬁg : record
Record type representing the Mosel instance (process) re-use policy conﬁgured in the Xpress Executor
component
reuse : boolean
If false, every execution will run in a separate Mosel process. If true, Xpress
Executor will re-use a Mosel process after the execution completes, in some cases.
In neither case will Xpress Executor run two executions in the same Mosel process
at the same time.
maxexecutions : integer
When reuse is true, the maximum number of executions that can be run using each
Mosel process before it is automatically terminated.
reuseaftererror : boolean
If reuse is true, ﬂag indicating whether to allow a Mosel process to be re-used if theprevious execution terminated with an error code.
reuseafternonzeroexit : boolean
If reuse is true, ﬂag indicating whether to allow a Mosel process to be re-used if theprevious execution terminated with a non-zero exit code.

RepositoryStatus : record
Record type representing a summary of the Xpress Executor component’s repository statuscomponentid : string
The ID string of the Xpress Executor DMP component
componentenv : string
The component environment / lifecycle stage, either "design", "staging" or"production", or "LOCAL" in local mode.
numgears : integer
The number of gears assigned to the DMP component in this environment
numexecutions : integer
The total number of executions currently in the repository
numqueued : integer
The number of executions in the repository that have not yet started to executenuminprogress : integer
The number of executions in the repository that are currently executing
numcompleted : integer
The number of executions in the repository that have completed (either
successfully or with errors)
binarydatasize : integer
The approximate number of megabytes of binary data stored in the databasebinarydataquota : integer
The maximum number of megabytes of binary data that may be stored in the

Fair Isaac Corporation Conﬁdential and Proprietary Information

10

Typesdatabase
dbsize : integer
The current size of the database, in megabytes

RunLogFragment : record
Record type representing part of the run log of a model execution
id : text
The ID of the execution in the Xpress Executor component
logversion : text
A version string for the run log. When Executor restarts an execution from the
beginning, the run log version will change.
ﬁrstlinenum : integer
The index of the ﬁrst line in this fragment of the run log, where the ﬁrst line of the
run log has index 1.
numavailablelines : integer
The total number of lines in the run log.
lines : list of text
Individual lines in this fragment of the run log.

Fair Isaac Corporation Conﬁdential and Proprietary Information

11

CHAPTER 6

Variables
ExecutorParamNames : set of string
Set of all parameter names used in model executions

Fair Isaac Corporation Conﬁdential and Proprietary Information

12

CHAPTER 7

Subroutines
executordelete

Deletes an execution from the Xpress Executor component

p. 15

executordeleteall

Deletes all executions from the Xpress Executor component

p. 16

executorexecute

Submits a new execution to the Xpress Executor component.

p. 17

executorfetchinput

Downloads the input data ﬁle of the given execution

p. 18

executorfetchresult Downloads the result data ﬁle of the given execution

p. 19

executorfetchrunlog Downloads the run log of the given execution

p. 20

executorfetchrunlogfragment
p. 21

Downloads a fragment of the run log of the given execution.

executorgetconcurrencylevel Fetch the currently conﬁgured concurrency level of the Xpress
Executor component.
p. 22
executorgetexpiryhours Fetch the conﬁgured execution expiry time of the Xpress Executor
component.
p. 23
executorgetinstanceconfig Fetch the Mosel instance re-use conﬁguration of the Xpress
Executor component.
p. 24
executorgetmodelparams

Fetch the model parameters of the Xpress Executor component. p. 25

executorinit

Initialize the given Executor with the details of the indicated component
conﬁgured in executor_components, or in the same DMP solution.
p. 26

executorinitlocal

Initialize the given Executor in local mode.

executorlist

Request a list of all the model executions currently present in the Xpress
Executor component
p. 28

executorpoll

Update the status of the given ModelExecution

p. 27

p. 29

executorrepositorystatus Query the current repository status for the Xpress Executor
component

p. 30

executorsetconcurrencylevel Conﬁgure the concurrency level of the Xpress Executor
component.

p. 31

executorsetexecmode Conﬁgure the execution mode of the Xpress Executor component.

p. 32

executorsetexpiryhours Conﬁgure the number of hours after which a completed execution may
be automatically deleted.
p. 33
executorsetinputxsd Conﬁgure the input XSD describing the format of the input data.

Fair Isaac Corporation Conﬁdential and Proprietary Information

p. 34

13

Subroutines

executorsetinstanceconfig Conﬁgure when Xpress Executor is allowed to re-use a Mosel
instance (process) for multiple executions.
p. 35
executorsetmodelfile

Conﬁgure the model ﬁle of the Xpress Executor component.

p. 36

executorsetmodelparams Conﬁgure the model parameters of the Xpress Executor component.
p. 37
executorsetresultxsd

Conﬁgure the result XSD describing the format of the result data.

p. 38

executorwaitfor

Wait until the given execution has completed

p. 39

getlasterror

Returns a string describing the error that occurred during the most recent
operation on the Executor instance.
p. 40

getstatus

Indicates the status of the most recent request this model has made using
the Executor instancep. 41

Fair Isaac Corporation Conﬁdential and Proprietary Information

14

Subroutines

executordelete
Purpose
Synopsis

Deletes an execution from the Xpress Executor component
procedure executordelete(exec:Executor, execution:ModelExecution)

Arguments
exec
execution

The Executor on which the execution resides
The execution to delete

Exampleexecutordelete( myexecutor, myexecution )if myexecutor.status<>EXECUTOR_OK thenwriteln("Error returned by Executor: ",myexecutor.lasterror)exit(1)
end-ifFurther information
1. After calling, check the value of exec.status for any errors.
2. The procedure will not return until the execution has been marked for deletion or an error was detected.
3. Only the id ﬁeld of the ModelExecution record is read by this procedure.
4. If the execution is still running, Xpress Executor will cancel it.
5. Once deleted, the execution result, status and run log will not be available.
Related topics
getstatus

Fair Isaac Corporation Conﬁdential and Proprietary Information

15

Subroutines

executordeleteall
Purpose
Synopsis

Deletes all executions from the Xpress Executor component
procedure executordeleteall(exec:Executor)

Argument
exec

The Executor with which to interact

Exampleexecutordeleteall( myexecutor )if myexecutor.status<>EXECUTOR_OK thenwriteln("Error returned by Executor: ",myexecutor.lasterror)exit(1)
end-ifFurther information
1. After calling, check the value of exec.status for any errors.
2. The procedure will not return until all executions have been marked for deletion or an error was
detected.
3. If any executions are still running, Xpress Executor will cancel them.
4. Once deleted, the execution result, status and run log will not be available.
Related topics
getstatus

Fair Isaac Corporation Conﬁdential and Proprietary Information

16

Subroutines

executorexecute
Purpose
Synopsis

Submits a new execution to the Xpress Executor component.
function executorexecute(exec:Executor, inputfname:text,
modelparams:array(set of string) of text):ModelExecutionfunction executorexecute(exec:Executor, inputfname:text):ModelExecution

Arguments
exec
inputfnamemodelparams

The Executor with which to interact
The ﬁlename containing the input data to submit to the execution. If an empty string,
execution will be submitted with an empty input data ﬁle. May reference a Mosel I/Odriver, e.g. "mmsystem.text:myinputdata"
Values of any additional model parameter to set for this execution. Moduleparameters such as mmxprs.xprs_verbose may not be set using this array.

Return value
A record containing the execution id and the initial status.
Examplemyexecution := executorexecute( myexecutor, "inputdata.dat" )if myexecutor.status<>EXECUTOR_OK thenwriteln("Error returned by Executor: ",myexecutor.lasterror)exit(1)
end-ifFurther information
1. After calling, check the value of exec.status for any errors.
2. The procedure will not return until the execution has been submitted to the component or an error was
detected.
3. Once submitted, the execution will be executed asynchronously. Use executorpoll or
executorwaitfor to check the execution status.
4. Once deleted, the execution result, status and run log will not be available.
Related topics
getstatus, executordelete, executorwaitfor, executorpoll, executorfetchinput,
executorfetchresult, executorfetchrunlog

Fair Isaac Corporation Conﬁdential and Proprietary Information17

Subroutines

executorfetchinput
Purpose
SynopsisDownloads the input data ﬁle of the given execution
procedure executorfetchinput(exec:Executor, execution:ModelExecution,
dstfile:text)

Arguments
exec
execution
dstfileThe Executor on which the execution resides
The execution whose input we should request
The ﬁlename to which to save the input.

Exampleexecutorfetchinput( myexecutor, myexecution, "text:inputdata" )if myexecutor.status<>EXECUTOR_OK thenwriteln("Error returned by Executor: ",myexecutor.lasterror)exit(1)
end-ifFurther information
1. After calling, check the value of exec.status for any errors.
2. The procedure will not return until the execution input data has been downloaded or an error was
detected.
3. Only the id ﬁeld of the ModelExecution record is read by this procedure.
Related topics
getstatus, executorexecute

Fair Isaac Corporation Conﬁdential and Proprietary Information18

Subroutines

executorfetchresult
Purpose
SynopsisDownloads the result data ﬁle of the given execution
procedure executorfetchresult(exec:Executor, execution:ModelExecution,
dstfile:text)

Arguments
exec
execution
dstfileThe Executor on which the execution resides
The execution whose result we should request
The ﬁlename to which to save the result.

Exampleexecutorfetchresult( myexecutor, myexecution, "text:resultdata" )if myexecutor.status<>EXECUTOR_OK thenwriteln("Error returned by Executor: ",myexecutor.lasterror)exit(1)
end-ifFurther information
1. After calling, check the value of exec.status for any errors.
2. The procedure will not return until the execution result data has been downloaded or an error was
detected.
3. Only the id ﬁeld of the ModelExecution record is read by this procedure.
4. The execution results will not be available until the execution completes(ModelExecution.iscompleted is true)
Related topics
getstatus, executorwaitfor

Fair Isaac Corporation Conﬁdential and Proprietary Information

19

Subroutines

executorfetchrunlog
Purpose
SynopsisDownloads the run log of the given execution
procedure executorfetchrunlog(exec:Executor, execution:ModelExecution,
dstfile:text)

Arguments
exec
execution
dstfileThe Executor on which the execution resides
The execution whose run log we should request
The ﬁlename to which to save the run log

Exampleexecutorfetchrunlog( myexecutor, myexecution, "text:runlog" )if myexecutor.status<>EXECUTOR_OK thenwriteln("Error returned by Executor: ",myexecutor.lasterror)exit(1)
end-ifFurther information
1. After calling, check the value of exec.status for any errors.
2. The procedure will not return until the execution run log has been downloaded or an error was detected.
3. Only the id ﬁeld of the ModelExecution record is read by this procedure.
4. If the execution has not completed, this procedure will download whatever run log it has output so far.
Related topics
getstatus executorfetchrunlogfragment

Fair Isaac Corporation Conﬁdential and Proprietary Information

20

Subroutines

executorfetchrunlogfragment
Purpose
SynopsisDownloads a fragment of the run log of the given execution.
function executorfetchrunlogfragment(exec:Executor,
execution:ModelExecution, firstline:integer,
maxlines:integer):RunLogFragment

Arguments
exec
execution
firstline
maxlines

The Executor on which the execution resides
The execution whose run log we should request
The index of the ﬁrst line of the run log to fetch, where the ﬁrst line of the run log has
index 1
The maximum number of lines to return in the fragment

Examplefrag := executorfetchrunlogfragment( myexecutor, myexecution, 10, MAX_INT )if myexecutor.status<>EXECUTOR_OK thenwriteln("Error returned by Executor: ",myexecutor.lasterror)exit(1)
end-ifforall (line in frag.lines) dowriteln(line)
end-doFurther information
1. After calling, check the value of exec.status for any errors.
2. The procedure will not return until the execution run log fragment has been downloaded or an error was
detected.
3. Only the id ﬁeld of the ModelExecution record is read by this function.
4. If the execution has not completed, this procedure will download a fragment based on however muchof the run log is available.
5. When passing a value of firstline greater than 1, always check the logversion of the returned
fragment; if this value is different from the logversion of previously fetched fragments then theexecution has been restarted and you should re-fetch the run log from line 1.
Related topics
getstatus executorfetchrunlog

Fair Isaac Corporation Conﬁdential and Proprietary Information21

Subroutines

executorgetconcurrencylevel
Purpose
Synopsis

Fetch the currently conﬁgured concurrency level of the Xpress Executor component.
function executorgetconcurrencylevel(exec:Executor):integer

Argument
exec

The Executor to query

Return value
The number of executions that can be performed concurrently on a single Xpress Executor gear
Exampledeclarations
concurrencylevel: integer
end-declarations
concurrencylevel := executorgetconcurrencylevel( myexecutor )if myexecutor.status<>EXECUTOR_OK thenwriteln("Error returned by Executor: ",myexecutor.lasterror)exit(1)
end-ifFurther information
1. After calling, check the value of exec.status for any errors.
2. "Concurrency Level" is the number of executions that can be performed concurrently on a single gear; if
the Xpress Executor component is scaled over multiple gears then the total number of concurrent
executions will be concurrencylevel*numgears
3. If you start an execution when the maximum number of executions are concurrently executing, newexecutions are queued and will start when other executions complete.
4. This will always be 1 if the Executor is conﬁgured in local mode.
Related topics
getstatus executorsetconcurrencylevel

Fair Isaac Corporation Conﬁdential and Proprietary Information

22

Subroutines

executorgetexpiryhours
Purpose
Synopsis

Fetch the conﬁgured execution expiry time of the Xpress Executor component.
function executorgetexpiryhours(exec:Executor):integer

Argument
exec

The Executor to query

Return value
The number of hours after which a completed execution may be automatically deleted.
Exampledeclarations
expiryhours: integer
end-declarations
expiryhours := executorgetexpiryhours( myexecutor )if myexecutor.status<>EXECUTOR_OK thenwriteln("Error returned by Executor: ",myexecutor.lasterror)exit(1)
end-ifFurther information
1. After calling, check the value of exec.status for any errors.
2. This will always be MAX_INT if the Executor is conﬁgured in local mode.
Related topics
executordelete executorsetexpiryhours

Fair Isaac Corporation Conﬁdential and Proprietary Information23

Subroutines

executorgetinstanceconﬁgPurpose
Synopsis

Fetch the Mosel instance re-use conﬁguration of the Xpress Executor component.
function executorgetinstanceconfig(exec:Executor):MoselInstanceConfig

Argument
exec

The Executor to query

Return value
A record describing in what circumstances (if any) Xpress Executor will re-use Mosel processes for
multiple executions
Exampledeclarations
cfg: MoselInstanceConfig
end-declarations
executorgetinstanceconfig( myexecutor, cfg)
if myexecutor.status<>EXECUTOR_OK thenwriteln("Error returned by Executor: ",myexecutor.lasterror)exit(1)
end-ifFurther information
After calling, check the value of exec.status for any errors.
Related topics
getstatus executorsetinstanceconfig

Fair Isaac Corporation Conﬁdential and Proprietary Information24

Subroutines

executorgetmodelparams
Purpose
Synopsis

Fetch the model parameters of the Xpress Executor component.
procedure executorgetmodelparams(exec:Executor, modelparameters:array(setof string) of text)

Arguments
exec
The Executor to querymodelparameters Array into which the model parameters should be written
Exampledeclarations
myparams: array(set of string) of text
end-declarations
executorgetmodelparams( myexecutor, myparams)
if myexecutor.status<>EXECUTOR_OK thenwriteln("Error returned by Executor: ",myexecutor.lasterror)exit(1)
end-ifFurther information
1. After calling, check the value of exec.status for any errors.
2. The parameters returned by this procedure will be passed to the model for all subsequent executions
with this Executor.
3. Where named model parameters are set both here and in executorexecute, the values passed to
executorexecute shall have priority.
Related topics
getstatus executorsetmodelparams

Fair Isaac Corporation Conﬁdential and Proprietary Information25

Subroutines

executorinit
Purpose

Synopsis

Initialize the given Executor with the details of the indicated component conﬁgured in
executor_components, or in the same DMP solution.
procedure executorinit(exec:Executor)
procedure executorinit(exec:Executor, name:text)
procedure executorinit(exec:Executor, name:text, env:text)

Arguments
exec
name
env

The Executor to initialize
The component ID in the conﬁguration JSON, or the component name when running within
DMP. Within DMP, empty string to ﬁnd any Xpress Executor component in the solution.
The component lifecycle stage ("DESIGN","STAGING" or "PRODUCTION") when the component
name when running within DMP, empty string to use the lifecycle stage of the current
component.

Exampleexecutorinit( myexecutor )if myexecutor.status<>EXECUTOR_OK thenwriteln("Error returned by Executor: ",myexecutor.lasterror)exit(1)
end-ifFurther information
1. After calling, check the value of exec.status for any errors.
2. When no component name is given, and the solution a single Xpress Executor component, thatcomponent will be used.
3. When no component name is given, and the solution contains multiple Executor components, anarbitrary one will be chosen.
4. When used from Xpress Insight running in DMP, this will initialize the Executor with the indicated Xpress
Executor found within the solution containing the Insight component.
Related topics
getstatus, executor_components

Fair Isaac Corporation Conﬁdential and Proprietary Information

26

Subroutines

executorinitlocal
Purpose
Synopsis

Initialize the given Executor in local mode.
procedure executorinitlocal(exec:Executor)

Argument
exec

The Executor to initialize

Exampleexecutorinitlocal( myexecutor )if myexecutor.status<>EXECUTOR_OK thenwriteln("Error returned by Executor: ",myexecutor.lasterror)exit(1)
end-ifFurther information
1. After calling, check the value of exec.status for any errors.
2. In local mode, submodels are used to simulate an Xpress Executor component.
3. After initializing, the local Executor will have no conﬁguration, so call executorsetexecmode andexecutorsetmodelfile to supply some.
Related topics
getstatus, executorinit, executor_local_workdir

Fair Isaac Corporation Conﬁdential and Proprietary Information27

Subroutines

executorlist
Purpose
Synopsis

Request a list of all the model executions currently present in the Xpress Executor component
function executorlist(exec:Executor):list of ModelExecution

Argument
exec

The Executor to initialize

Return value
a list of the id and status of every execution in the repository.
Exampleexecutions := executorlist( myexecutor )if myexecutor.status<>EXECUTOR_OK thenwriteln("Error returned by Executor: ",myexecutor.lasterror)exit(1)
end-ifFurther information
After calling, check the value of exec.status for any errors.
Related topics
getstatus, executorpoll

Fair Isaac Corporation Conﬁdential and Proprietary Information28

Subroutines

executorpoll
Purpose
Synopsis

Update the status of the given ModelExecution
procedure executorpoll(exec:Executor, execution:ModelExecution)

Arguments
exec
execution

The Executor to on which the execution resides
The ModelExecution record to update

Exampleexecutorpoll( myexecutor, myexecution )if myexecutor.status<>EXECUTOR_OK thenwriteln("Error returned by Executor: ",myexecutor.lasterror)exit(1)
end-ifFurther information
1. After calling, check the value of exec.status for any errors.
2. Only the id ﬁeld of the ModelExecution record is read by this procedure.
3. When the procedure returns without an error, all ﬁelds of the ModelExecution record will have been
refreshed with the latest status from the server.
Related topics
getstatus, executorexecute, executorwaitfor

Fair Isaac Corporation Conﬁdential and Proprietary Information

29

Subroutines

executorrepositorystatus
Purpose
SynopsisQuery the current repository status for the Xpress Executor component
function executorrepositorystatus(exec:Executor):RepositoryStatus

Argument
exec

The Executor to query

Examplerepostatus := executorrepositorystatus( myexecutor )if myexecutor.status<>EXECUTOR_OK thenwriteln("Error returned by Executor: ",myexecutor.lasterror)exit(1)
end-ifif repostatus.binarydataquota - repostatus.binarydatasze < 10 thenwriteln("Warning: Executor is less than 10Mb under binary data quota")
end-ifFurther information
1. After calling, check the value of exec.status for any errors.
2. The repository status will summarise how many executions are stored on the component and how
close it is to the data storage quota.
Related topics
getstatus

Fair Isaac Corporation Conﬁdential and Proprietary Information30

Subroutines

executorsetconcurrencylevel
Purpose
Synopsis

Conﬁgure the concurrency level of the Xpress Executor component.
procedure executorsetconcurrencylevel(exec:Executor, newlevel:integer)

Arguments
exec The Executor to conﬁgurelevel The new concurrency level, must be an integer greater than 1
Exampleexecutorsetconcurrencylevel( myexecutor, 4)
if myexecutor.status<>EXECUTOR_OK thenwriteln("Error returned by Executor: ",myexecutor.lasterror)exit(1)
end-ifFurther information
1. After calling, check the value of exec.status for any errors.
2. "Concurrency Level" is the number of executions that can be performed concurrently on a single gear; if
the Xpress Executor component is scaled over multiple gears then the total number of concurrent
executions will be concurrencylevel*numgears
3. If you start an execution when the maximum number of executions are concurrently executing, newexecutions are queued and will start when other executions complete.
4. In local mode, the concurrency level cannot be modiﬁed and calling this procedure will do nothing.
5. This can only be used with the design instance of the Xpress Executor component, or with an Executor
initialized using executorinitlocal.
Related topics
getstatus executorgetconcurrencylevel

Fair Isaac Corporation Conﬁdential and Proprietary Information

31Subroutines

executorsetexecmode
Purpose
Synopsis

Conﬁgure the execution mode of the Xpress Executor component.
procedure executorsetexecmode(exec:Executor, execmode:string)Arguments
exec
The Executor to conﬁgure
execmode The execution mode; one of EXECUTOR_MODE_MODEL_BIM (if modelﬁle is a single .bim),
EXECUTOR_MODE_MODEL_ZIP (if modelﬁle is a .zip ﬁle containing a model.bim),
EXECUTOR_MODE_LP_XMPS (if the execution input data is a model in LP or XMPS format).
Exampleexecutorsetexecmode( myexecutor, EXECUTOR_MODE_MODEL_ZIP )if myexecutor.status<>EXECUTOR_OK thenwriteln("Error returned by Executor: ",myexecutor.lasterror)exit(1)
end-ifFurther information
1. After calling, check the value of exec.status for any errors.
2. This can only be used with the design instance of the Xpress Executor component, or with an Executor
initialized using executorinitlocal.
3. If the executor has been initialized with executorinitlocal, the execution mode may not be
EXECUTOR_MODE_LP_XMPS.
Related topics
getstatus

Fair Isaac Corporation Conﬁdential and Proprietary Information

32

Subroutines

executorsetexpiryhours
Purpose
Synopsis

Conﬁgure the number of hours after which a completed execution may be automatically deleted.
procedure executorsetexpiryhours(exec:Executor, hours:integer)

Arguments
exec The Executor to conﬁgure
hours The new number of hours after which a completed execution may be automatically deleted,
Exampleexecutorsetexpiryhours( myexecutor, 4)
if myexecutor.status<>EXECUTOR_OK thenwriteln("Error returned by Executor: ",myexecutor.lasterror)exit(1)
end-ifFurther information
1. After calling, check the value of exec.status for any errors.
2. In local mode, executions are never automatically expired so calling this procedure does nothing.
3. This can only be used with the design instance of the Xpress Executor component, or with an Executor
initialized using executorinitlocal.
Related topics
getstatus executorgetexpiryhours

Fair Isaac Corporation Conﬁdential and Proprietary Information

33

Subroutines

executorsetinputxsd
Purpose
Synopsis

Conﬁgure the input XSD describing the format of the input data.
procedure executorsetinputxsd(exec:Executor, srcfile:text)

Arguments
exec
The Executor to conﬁgure
srcfile Filename of the local input XSD ﬁleExampleexecutorsetinputxsd( myexecutor, "input.xsd" )if myexecutor.status<>EXECUTOR_OK thenwriteln("Error returned by Executor: ",myexecutor.lasterror)exit(1)
end-ifFurther information
1. After calling, check the value of exec.status for any errors.
2. This cannot only be used with the design instance of the Xpress Executor component.
3. The input XSD will be incorporated into the SOAP WSDL for the Xpress Executor component.
4. If you aren’t calling the Xpress Executor SOAP interface from FICO Application Studio, you don’t need to
set the Input XSD.
Related topics
getstatus

Fair Isaac Corporation Conﬁdential and Proprietary Information

34

Subroutines

executorsetinstanceconﬁgPurpose

Synopsis

Conﬁgure when Xpress Executor is allowed to re-use a Mosel instance (process) for multiple
executions.
procedure executorsetinstanceconfig(exec:Executor,
newcfg:MoselInstanceConfig)

Arguments
exec
newcfg

The Executor to conﬁgure
A record describing in what circumstances (if any) Xpress Executor will re-use Mosel
processes for multiple executions

Exampleexecutorsetexpiryhours( myexecutor, 4)
if myexecutor.status<>EXECUTOR_OK thenwriteln("Error returned by Executor: ",myexecutor.lasterror)exit(1)
end-ifFurther information
1. After calling, check the value of exec.status for any errors.
2. In local mode, executions are always run in the same Mosel instance so this procedure has no effect.
3. This can only be used with the design instance of the Xpress Executor component, or with an Executor
initialized using executorinitlocal.
Related topics
getstatus executorgetinstanceconfig

Fair Isaac Corporation Conﬁdential and Proprietary Information

35

Subroutines

executorsetmodelﬁlePurpose
Synopsis

Conﬁgure the model ﬁle of the Xpress Executor component.
procedure executorsetmodelfile(exec:Executor, srcfile:text)

Arguments
exec
The Executor to conﬁgure
srcfile Filename of the local model ﬁleExampleexecutorsetmodelfile( myexecutor, "mymodel.bim" )if myexecutor.status<>EXECUTOR_OK thenwriteln("Error returned by Executor: ",myexecutor.lasterror)exit(1)
end-ifFurther information
1. After calling, check the value of exec.status for any errors.
2. The model ﬁle is the Mosel model executed by Xpress Executor executions. It should be a .bim ﬁle if
the execution mode is "FIXED_MODEL", or a .zip containing a ﬁle called model.bim if"FIXED_MODEL_IN_ZIPFILE".
3. This can only be used with the design instance of the Xpress Executor component, or with an Executor
initialized using executorinitlocal.
Related topics
getstatus

Fair Isaac Corporation Conﬁdential and Proprietary Information

36

Subroutines

executorsetmodelparams
Purpose
Synopsis

Conﬁgure the model parameters of the Xpress Executor component.
procedure executorsetmodelparams(exec:Executor, modelparameters:array(setof string) of text)

Arguments
exec
The Executor to conﬁguremodelparameters The model parameters
Exampledeclarations
myparams: array(set of string) of text
end-declarations
myparams("VERBOSE") := "true"
myparams("MAX_COST") := "1.5"executorsetmodelparams( myexecutor, myparams)
if myexecutor.status<>EXECUTOR_OK thenwriteln("Error returned by Executor: ",myexecutor.lasterror)exit(1)
end-ifFurther information
1. After calling, check the value of exec.status for any errors.
2. The parameters set by this procedure will be passed to the model for all subsequent executions withthis Executor.
3. Where named model parameters are set both here and in executorexecute, the values passed to
executorexecute shall have priority.
4. This can only be used with the design instance of the Xpress Executor component, or with an Executor
initialized using executorinitlocal.
Related topics
getstatus executorgetmodelparams

Fair Isaac Corporation Conﬁdential and Proprietary Information

37

Subroutines

executorsetresultxsd
Purpose
Synopsis

Conﬁgure the result XSD describing the format of the result data.
procedure executorsetresultxsd(exec:Executor, srcfile:text)

Arguments
exec
The Executor to conﬁgure
srcfile Filename of the local result XSD ﬁleExampleexecutorsetresultxsd( myexecutor, "result.xsd" )if myexecutor.status<>EXECUTOR_OK thenwriteln("Error returned by Executor: ",myexecutor.lasterror)exit(1)
end-ifFurther information
1. After calling, check the value of exec.status for any errors.
2. This cannot only be used with the design instance of the Xpress Executor component.
3. The result XSD will be incorporated into the SOAP WSDL for the Xpress Executor component.
4. If you aren’t calling the Xpress Executor SOAP interface from FICO Application Studio, you don’t need to
set the Result XSD.
Related topics
getstatus

Fair Isaac Corporation Conﬁdential and Proprietary Information

38

Subroutines

executorwaitforPurpose
Synopsis

Wait until the given execution has completed
procedure executorwaitfor(exec:Executor, execution:ModelExecution,
timeoutseconds:integer)

Arguments
exec
The Executor to on which the execution resides
execution
The ModelExecution to wait for
timeoutseconds The maximum number of seconds to wait before returning
Exampleexecutorwaitfor( myexecutor, myexecution )if myexecutor.status<>EXECUTOR_OK thenwriteln("Error returned by Executor: ",myexecutor.lasterror)exit(1)
end-ifFurther information
1. After calling, check the value of exec.status for any errors.
2. Only the id ﬁeld of the ModelExecution record is read by this procedure.
3. When the procedure returns without an error, all ﬁelds of the ModelExecution record will have been
refreshed with the latest status from the server.
4. Check the ModelExecution.iscompleted ﬁeld to see whether the execution completed within thegiven timeout period.
5. This procedure will make repeated calls to executorpoll will delays in between. You can conﬁgure
how frequently it should call executorpoll by modifying the parameter
executor_poll_interval.
Related topics
getstatus, executorexecute, executorpoll, executor_poll_interval

Fair Isaac Corporation Conﬁdential and Proprietary Information

39

Subroutines

getlasterror
Purpose

Synopsis

Returns a string describing the error that occurred during the most recent operation on the Executor
instance.
function getlasterror(exec:Executor):text

Return value
A text value containing the error message, which will be empty if the most recent operation on the
Executor instance succeeded.
Further information
1. After every call to an Executor-related function or procedure, you should check the value of getstatus
to see if your request succeeded. If it’s unclear why an error is being returned, more troubleshooting
output can be generated by setting the parameter executor_verbose to true, or inspecting the return
value of getlasterror.
2. This function returns human-readable English description of the error that may be useful fortroubleshooting purposes, but you should not assume that it is in any particular format. To distinguishbetween different types of error, use getstatus instead.
Related topics
getstatus executor_verbose

Fair Isaac Corporation Conﬁdential and Proprietary Information40

Subroutines

getstatus
Purpose
Synopsis

Indicates the status of the most recent request this model has made using the Executor instancefunction getstatus(exec:Executor):integer

Return value
One of the following constants:
EXECUTOR_OK

The operation completed successfully.

EXECUTOR_NOT_FOUND

The requested execution was not found in the Xpress Executor service.

EXECUTOR_ACCESS_DENIED

User is not authorized to access the Xpress Executor service

EXECUTOR_CONNECTION_ERROREXECUTOR_SERVICE_ERROREXECUTOR_IO_ERROR

Unable to connect to the Xpress Executor service.

The Xpress Executor service returned an unexpected error code.

The executor module encountered an error reading or writing local ﬁles.

EXECUTOR_PARSE_ERRORThe executor module did not understand the response from the
Executor component.
EXECUTOR_USAGE_ERRORThe executor module did not understand a parameter you passed to it.

Further information
After every call to an Executor-related function or procedure, you should check the value of getstatus
to see if your request succeeded. If it’s unclear why an error is being returned, more troubleshooting
output can be generated by setting the parameter ’executor_verbose’ to true, or inspecting the return
value of getlasterror.
Related topics
getlasterror

Fair Isaac Corporation Conﬁdential and Proprietary Information

41

CHAPTER 8Parameters
Via the getparam function and the setparam procedure it is possible to access the following control
parameters of module executor :executor_bearer_refresh_interval

Maximum age of bearer token to re-use

p. 42

executor_components Conﬁgure component details using JSON format

p. 43

executor_local_workdir

Working directory for local executions

p. 43

How many times to retry Executor requests

p. 43

executor_max_retries

executor_poll_intervalInterval between polls of Execution status

executor_retry_error_codes
executor_verbose

Which types of error to retry

Activate additional logging

p. 43
p. 44
p. 42

executor_verbose
Description

Set to ’true’ to activate additional logging of Executor-related actions and errors, to themodel’s error stream.

Type

Boolean, read/write

Default value

false

executor_bearer_refresh_interval
Description

The interval, in seconds, after which to refresh the bearer token, when a clientid and secrethas been supplied to the Executor.

Type

Integer, read/write

Default value

1800

Note

This parameter has no effect when the Executor was initialized with a bearerToken value, or
when used from Insight within DMP.

Fair Isaac Corporation Conﬁdential and Proprietary Information

42

Parameters

executor_poll_interval
Description

Sets the interval, in milliseconds, between checks of the execution status in theexecutorwaitfor procedure.

Type

Integer, read/write

Default value

500

Note

Values less than 100 will raise an error from executorwaitfor.

executor_local_workdir
Description

Sets the path under which to store conﬁguration ﬁles and model working directories for an
executor conﬁgured using executorinitlocal.

Type

String, read/write

Default value

tmp:executorlocal

executor_components
Description

This allows Executor component details to be conﬁgured using a JSON ﬁle. See the chapter
on authentication, 3.2, for more details.

Type

String, write only

Default value

{}

Note

For security reasons, the value of this parameter cannot be read using getparam.

Note

The value of this parameter will be shared by all Mosel models running in the current process.

executor_max_retries
Description

Set the maximum number of times a ’failed’ Executor request will be retried.

Type

Integer, read/write

Default value

8

Note

Each retry will be after an exponentially larger delay (200ms, 400ms, 800ms, etc) so be awarethat large values can take a long time to report errors.

Note

The default setting will retry for approximately 52 seconds.

Note

The types of operation that are retried can be controlled using theexecutor_retry_error_codes parameter.

Fair Isaac Corporation Conﬁdential and Proprietary Information

43

Parameters

executor_retry_error_codes
Description

Comma-separated list of the HTTP status codes that should be retried.

Type

String, read/write

Default value

999,500,504,403,401

NoteControls which errors to retry when executor_max_retries is non-zero.

Note

Supported error codes are HTTP status codes returned by the Executor HTTP component,with code 999 meaning a communication error.

Fair Isaac Corporation Conﬁdential and Proprietary Information

44

CHAPTER 9

Deprecated Functionality
9.1

dmpmanagerurl
As an alternative to specifying the bearertokenurl attribute of the Executor variable, you can specify
the dmpmanagerurl attribute to request the bearer token from DMP Manager, e.g.:model DirectInitExample
uses "executor"
declarations
myexecutor: Executor
end-declarations
myexecutor.componenturl := "https://vm65j75lqh-vm65j75lqh.dms.usw2.ficoanalyticcloud.com/"myexecutor.dmpmanagerurl := "https://console.dms.usw2.ficoanalyticcloud.com/"myexecutor.clientid := "vm5qh0y37c"
myexecutor.secret := "wdS97u648BVoI#d3e4g2Z4mP780Y1DLdSDKm"! myexecutor now initialized and can be used
end-model

Similarly, you can set the dmpManagerUrl ﬁeld of a JSON conﬁguration document:{}"main": {"componentUrl": "https://vm65j75lqh-vm65j75lqh.dms.usw2.ficoanalyticcloud.com/","dmpManagerUrl": "https://console.dms.usw2.ficoanalyticcloud.com/","clientId": "vm5qh0y37c","secret": "wdS97u648BVoI#d3e4g2Z4mP780Y1DLdSDKm"}

Requesting a bearer token from DMP Manager is deprecated functionality in recent versions of DMP
and this approach should not be used in new solutions.

Fair Isaac Corporation Conﬁdential and Proprietary Information

45

APPENDIX A

Contacting FICO
FICO provides clients with support and services for all our products. Refer to the following sections formore information.

Product support
FICO offers technical support and services ranging from self-help tools to direct assistance with a FICO
technical support engineer. Support is available to all clients who have purchased a FICO product andhave an active support or maintenance contract. You can ﬁnd support contact information and a link to
the Customer Self Service Portal (online support) on the Product Support home page(www.ﬁco.com/en/product-support).
The FICO Customer Self Service Portal is a secure web portal that is available 24 hours a day, 7 days aweek from the Product Support home page. The portal allows you to open, review, update, and close
cases, as well as ﬁnd solutions to common problems in the FICO Knowledge Base.
Please include ’Xpress’ in the subject line of your support queries.

Product education
FICO Product Education is the principal provider of product training for our clients and partners.
Product Education offers instructor-led classroom courses, web-based training, seminars, and training
tools for both new user enablement and ongoing performance support. For additional information, visit
the Product Education homepage at www.ﬁco.com/en/product-training or email
producteducation@ﬁco.com.

Product documentation
FICO continually looks for new ways to improve and enhance the value of the products and services weprovide. If you have comments or suggestions regarding how we can improve this documentation, let
us know by sending your suggestions to techpubs@ﬁco.com.
Please include your contact information (name, company, email address, and optionally, your phone
number) so we may reach you if we have questions.

Fair Isaac Corporation Conﬁdential and Proprietary Information46

Contacting FICO

Sales and maintenanceIf you need information on other Xpress Optimization products, or you need to discuss maintenancecontracts or other sales-related items, contact FICO by:

Phone: +1 (408) 535-1500 or +44 207 940 8718



Web: http://www.ﬁco.com/optimization and use the available contact forms

Related services
Strategy Consulting: Included in your contract with FICO may be a speciﬁed amount of consulting time
to assist you in using FICO Optimization Modeler to meet your business needs. Additional consulting
time can be arranged by contract.
Conferences and Seminars: FICO offers conferences and seminars on our products and services. For
announcements concerning these events, go to www.ﬁco.com or contact your FICO accountrepresentative.

FICO Community
The FICO Community is a great resource to ﬁnd the experts and information you need to collaborate,
support your business, and solve common business challenges. You can get informal technicalsupport, build relationships with local and remote professionals, and improve your business practices.
For additional information, visit the FICO Community (community.ﬁco.com/welcome).

About FICO
FICO (NYSE:FICO) powers decisions that help people and businesses around the world prosper.
Founded in 1956 and based in Silicon Valley, the company is a pioneer in the use of predictive analytics
and data science to improve operational decisions. FICO holds more than 165 US and foreign patents
on technologies that increase proﬁtability, customer satisfaction, and growth for businesses inﬁnancial services, telecommunications, health care, retail, and many other industries. Using FICO
solutions, businesses in more than 100 countries do everything from protecting 2.6 billion payment
cards from fraud, to helping people get credit, to ensuring that millions of airplanes and rental cars arein the right place at the right time. Learn more at www.ﬁco.com.

Fair Isaac Corporation Conﬁdential and Proprietary Information

47

IndexD
delete execution, 15, 16
Development, 6
DMP, 5E
execution input, 18
execution result, 19–21
execution status, 9Executor, 3
Executor operation error codes, 41
executor_bearer_refresh_interval, 42
executor_components, 43
executor_local_workdir, 43
executor_max_retries, 43
executor_poll_interval, 43
executor_retry_error_codes, 44
executor_verbose, 42
executordelete, 15
executordeleteall, 16
executorexecute, 17
executorfetchinput, 18
executorfetchresult, 19
executorfetchrunlog, 20
executorfetchrunlogfragment, 21
executorgetconcurrencylevel, 22
executorgetexpiryhours, 23
executorgetinstanceconﬁg, 10
executorgetinstanceconfig, 24
executorgetmodelparams, 25
executorinit, 4executorinit, 26
executorinitlocal, 6
executorinitlocal, 27
executorlist, 28
ExecutorParamNames, 12
executorpoll, 29
executorrepositorystatus, 10
executorrepositorystatus, 30
executorsetconcurrencylevel, 31
executorsetexecmode, 32
executorsetexpiryhours, 33
executorsetinputxsd, 34
executorsetinstanceconfig, 35
executorsetmodelfile, 36
executorsetmodelparams, 37
executorsetresultxsd, 38
executorwaitfor, 39

L
Local, 6M
ModelExecution, 9MoselInstanceConfig, 10
R
repository status, 10
RepositoryStatus, 10
RunLogFragment, 11
Ssubmit execution, 17Ggetlasterror, 40
getstatus, 41

Fair Isaac Corporation Conﬁdential and Proprietary Information

48