Reference manual

FICO Xpress Optimization
R

S3 Library for Mosel
Reference Manual
Release 8.4

Last update 20 October, 2017www.fico.com

Make every decision countTM

This material is the confidential, proprietary, and unpublished property of Fair Isaac Corporation.
Receipt or possession of this material does not convey rights to divulge, reproduce, use, or allow
others to use it without the specific written authorization of Fair Isaac Corporation and use must
conform strictly to the license agreement.
The information in this document is subject to change without notice. If you find any problems inthis documentation, please report them to us in writing. Neither Fair Isaac Corporation nor its
affiliates warrant that this documentation is error-free, nor are there any other warranties withrespect to the documentation except as may be provided in the license agreement.
©2017 Fair Isaac Corporation. All rights reserved. Permission to use this software and its
documentation is governed by the software license agreement between the licensee and Fair Isaac
Corporation (or its affiliate). Portions of the program may contain copyright of various authors andmay be licensed under certain third-party licenses identified in the software, documentation, orboth.
In no event shall Fair Isaac Corporation or its affiliates be liable to any person for direct, indirect,
special, incidental, or consequential damages, including lost profits, arising out of the use of thissoftware and its documentation, even if Fair Isaac Corporation or its affiliates have been advised ofthe possibility of such damage. The rights and allocation of risk between the licensee and Fair Isaac
Corporation (or its affiliates) are governed by the respective identified licenses in the software,
documentation, or both.
Fair Isaac Corporation and its affiliates specifically disclaim any warranties, including, but not limited
to, the implied warranties of merchantability and fitness for a particular purpose. The software andaccompanying documentation, if any, provided hereunder is provided solely to users licensed under
the Fair Isaac Software License Agreement. Fair Isaac Corporation and its affiliates have no
obligation to provide maintenance, support, updates, enhancements, or modifications except as
required to licensed users under the Fair Isaac Software License Agreement.
FICO and Fair Isaac are trademarks or registered trademarks of Fair Isaac Corporation in the UnitedStates and may be trademarks or registered trademarks 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: 20 October, 2017
Version 8.4

Contents
1 Introduction

1

2 Basic Principles

2

3 Authenticating
3.1 Using s3bucket Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2 Using a JSON Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3 Using the DMP Solution Bucket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3
3
3
5

4 Usage examples
4.1 Downloading from an S3 object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2 Uploading to an S3 object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3 Listing S3 object keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6
6
6
7

5 Types9

6 Variables

12

7 Subroutiness3delobject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
s3getlasterror . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
s3getobject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
s3getobjectmetadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
s3getobjecttagging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
s3listobjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
s3newtag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
s3objectexists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
s3putobject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
s3setobjecttagging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
s3status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

13
14
15
16
17
18
19
20
21
22
23
24

8 Parameters
s3_verbose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
s3_trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
s3_maxkeys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
s3_buckets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

25
25
25
26
26

Appendix

27

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

27
27
27
27
28
28
28

Fair Isaac Corporation Confidential and Proprietary Informationi

Contents

Index

Fair Isaac Corporation Confidential and Proprietary Information

29ii

C HAPTER 1

Introduction
The package and module s3 allow objects to be uploaded to and downloaded from an Amazon
AWS S3 service, or a compatible third-party service that supports the AWS Signature Version 4authentication method. This functionality is available from local models as well as models
running in supported components on the FICO Decision Management Platform (DMP).
When not using DMP, you will need to provide your own credentials (in the form of an access key
id, secret key and optional session token) to allow access to an Amazon S3 service.
This document assumes that the reader is familiar with the basic concepts of the Amazon S3
service. If not, please consult the documentation available online, for example:
https://aws.amazon.com/s3
Getting Started with Amazon Simple Storage Service

Fair Isaac Corporation Confidential and Proprietary Information

1

C HAPTER 2

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

When you want to use S3, you should declare a variable of the ’s3bucket’ type to represent the
Amazon S3 bucket you want to access.
declarations
mybucket: s3bucket
end-declarations

Once the ’s3bucket’ variable has been initialized with your bucket’s location and credentials (see3), it can be used with S3 functions such as s3getobject, s3putobject and s3listobjects. If you
need to access more than one bucket, you can declare multiple s3bucket variables.
One property of the ’s3bucket’ is the ’keyprefix’, which will be automatically prepended to all
keys you pass to functions. This allows you to simulate having a ’working directory’ within the S3
bucket, e.g.:s3putobject(mybucket,’objectkey’,’mydata.dat’)
mybucket.keyprefix := ’myprefix/’
s3putobject(mybucket,’objectkey’,’mydata.dat’)! Upload to key ’objectkey’! Upload to key ’myprefix/objectkey’The examples in this document use a ’/’ in keys and the keprefix to simulate a structure of folders;
this is the convention used in S3 buckets provisioned by DMP, but is not required by the s3
module.
After calling each function on the s3 library, you should check the value of s3status for any
errors - if this is any value other than S3_OK then an error has occurred. In an error case, s3statuswill return an error code and s3getlasterror will return a description of the error.

Fair Isaac Corporation Confidential and Proprietary Information

2

C HAPTER 3

Authenticating
3.1

Using s3bucket Properties
The simplest way to initialize the s3bucket with your S3 bucket’s URL and access credentials is bydirectly setting properties of the s3bucket object within the model. For example:
model DirectInitExample
uses "s3"declarations
mybucket: s3bucket
end-declarations
mybucket.url := "https://s3-us-west-2.amazonaws.com/nameofmybucket/"mybucket.region := "us-west-2"
mybucket.keyprefix := "myprefix/"
mybucket.accesskeyid := "JKHGDMNAYGWEnbbsJGDI"
mybucket.secretkey := "jhdfusJasfui;SVFYSIAVS++siufgsuUISNISOWJ"
mybucket.sessiontoken := "kHUFGBSUjbfusbuioUHDFSIngudblincxubhxop0szofbv"! mybucket now initialized and can be used
end-model! Optional! Optional

The Bucket URL, Region, Access Key ID and Secret Key must always be specified. If the credentials
you are given include a Session Token (sometimes referred to as a Security Token), then you mustalso specify this. Giving a Key Prefix is optional.
Note that the S3 credentials will not be verified until you make a request to the S3 service. The
values you give for the url, region and keyprefix can be read back out of the s3bucket, but for
security reasons the accesskeyid, secretkey and sessiontoken properties may not be read.
If you are using server-side encryption with AWS-managed keys, you can configure this by setting
additional fields on the s3bucket object, as follows:
mybucket.sse := "aws:kms"
mybucket.ssekmskeyid := "keyid"
mybucket.ssecontext := "x=1"

3.2! Replace ’keyid’ with ID of yourkey in the AWS key m! Encryption context; optional

Using a JSON Configuration FileAs an alternative to setting credentials in the model, you can specify them in a JSON document,
the contents of which which you assign to the s3_buckets parameter. The document should be in
the following format:{"<bucket-id>": {"url": "<URL of bucket>",Fair Isaac Corporation Confidential and Proprietary Information3

Authenticating"region": "<AWS Region>","keyPrefix": "<Key Prefix, optional>","accessKeyId": "<AWS Access Key ID>","secretKey": "<AWS Secret Key>","sessionToken": "<AWS Session Token, optional>"}}

The "<bucket-id>" string is a key that you use to refer to the bucket definition in the JSON andhas no other meaning. You can specify multiple buckets in the same JSON file so long as they
have different "<bucket-id>" strings, e.g.:{"firstbucket": {"url": "https://s3-us-west-2.amazonaws.com/nameofmybucket/","region": "us-west-2","keyPrefix": "myprefix/","accessKeyId": "JKHGDMNAYGWEnbbsJGDI","secretKey": "jhdfusJasfui;SVFYSIAVS++siufgsuUISNISOWJ","sessionToken": "kHUFGBSUjbfusbuioUHDFSIngudblincxubhxop0szofbv"},"secondbucket": {"url": "https://s3-us-east-2.amazonaws.com/nameofmyotherbucket/","region": "us-east-2","accessKeyId": "IHFSUGFOSFUHFJSYIFSG","secretKey": "nusduoUHf;sufbuOFUGSFHRHAFFAbvubddsa=jfb","sessionToken": "UHFSUOFIhfushfglhoFGSiguosnoahusfppgjoUFSUFINM"}}

Then you can initialize an s3bucket in the model with the credentials from the JSON by calling thes3init procedure. For example, if you save the above sample JSON in a file called "buckets.json":model InitExample
uses "s3","mmsystem"
declarations
public bucketcfg: text
mybucket: s3bucket
end-declarations! Load buckets.json into a variable so it can be passed to a parameter
fcopy("buckets.json","text:bucketcfg")
setparam("s3_buckets",string(bucketcfg))! Initialize mybucket using the ’firstbucket’ set of credentials
s3init(mybucket, "firstbucket")if s3status(mybucket)<>S3_OK thenwriteln("Bucket initialization error: ", s3getlasterror(mybucket))exit(1)
end-if! mybucket now initialized and can be used
end-model

As before, the S3 credentials will not be verified until you make a request to the S3 service.
The s3_buckets 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 the samevalue will be used for all submodels that you start in the same Mosel process.
After calling s3init, the only property on the s3bucket that may be modified is keyprefix, whichmust always start with the value it was given by s3init.
If you are using server-side encryption with AWS-managed keys, you can configure this by setting
3 additional properties on the JSON object: sse should be the string "aws:kms", sseKmsKeyId theidentifier of your key stored in the AWS key-management service, and sseContext is the

Fair Isaac Corporation Confidential and Proprietary Information4

Authenticating(optional) encryption context string.

3.3

Using the DMP Solution Bucket
When using a DMP component such as Xpress Insight, Xpress Workbench or Xpress Executor, in a
DMP 2.0+ environment, the Mosel instance will automatically be configured to access an S3
bucket that is shared by all components in the solution. To use this, simply call s3init with thestring "solutionData", or the constant S3_DMP_SOLUTIONDATA which evaluates to "solutionData":
model DmpInitExample
uses "s3"declarations
mybucket: s3bucket
end-declarations! Initialize mybucket using the ’solutionData’ set of credentials
s3init(mybucket, S3_DMP_SOLUTIONDATA)
if s3status(mybucket)<>S3_OK thenwriteln("Bucket initialization error: ", s3getlasterror(mybucket))exit(1)
end-if! mybucket now initialized and can be used
end-model

By default you will access the solutionData folder matching your component’s current DMP
lifecycle stage (design, staging or production). In Xpress Insight only, you can also initialize yours3bucket with the folder of a different lifecycle stage by passing one of the constants
S3_DMP_DESIGN, S3_DMP_STAGING and S3_DMP_PRODUCTION, as follows:model DmpInitExample
uses "s3"declarations
mybucket: s3bucket
end-declarations! Initialize mybucket using the ’solutionData’ credentials for the ’staging’ lifecycle
s3init(mybucket, S3_DMP_SOLUTIONDATA, S3_DMP_STAGING)
if s3status(mybucket)<>S3_OK thenwriteln("Bucket initialization error: ", s3getlasterror(mybucket))exit(1)
end-if! mybucket now initialized and can be used
end-model

Fair Isaac Corporation Confidential and Proprietary Information

5

C HAPTER 4

Usage examples
4.1

Downloading from an S3 object
This example demonstrates downloading the content of an S3 object with the key MyFile.txt
into a local file MyDownloadedFile.txt.
You will need to fill in the model parameters with your own Amazon S3 access credentials.
model S3DownloadExample
uses "s3"parameters
S3_BUCKET_URL = ""S3_REGION = ""S3_ACCESS_KEY_ID = ""S3_SECRET_KEY = ""end-parameters
declarations
LOCAL_FILE="MyDownloadedFile.txt"
OBJECT_KEY="MyFile.txt"
mybucket: s3bucket
end-declarations! Configure ’mybucket’ with our S3 access credentials
mybucket.url := S3_BUCKET_URL
mybucket.region := S3_REGION
mybucket.accesskeyid := S3_ACCESS_KEY_ID
mybucket.secretkey := S3_SECRET_KEY! Download remote object to local files3getobject( mybucket, OBJECT_KEY, LOCAL_FILE )! Check for errors
if s3status(mybucket)<>S3_OK thenwriteln("Error returned by S3 service: ", s3getlasterror(mybucket))exit(1)
end-ifend-model

4.2

Uploading to an S3 object
This example demonstrates uploading the content of the file "MyLocalFile.txt" to the S3 bucketwith the object key "MyFile.txt".
You will need to fill in the model parameters with your own Amazon S3 access credentials.

Fair Isaac Corporation Confidential and Proprietary Information

6

Usage examples

model S3UploadExample
uses "s3"parameters
S3_BUCKET_URL = ""S3_REGION = ""S3_ACCESS_KEY_ID = ""S3_SECRET_KEY = ""end-parameters
declarations
LOCAL_FILE="MyLocalFile.txt"
OBJECT_KEY="MyFile.txt"
mybucket: s3bucket
end-declarations! Configure ’mybucket’ with our S3 access credentials
mybucket.url := S3_BUCKET_URL
mybucket.region := S3_REGION
mybucket.accesskeyid := S3_ACCESS_KEY_ID
mybucket.secretkey := S3_SECRET_KEY! Upload local file to remote object
s3putobject( mybucket, OBJECT_KEY, LOCAL_FILE )! Check for errors
if s3status(mybucket)<>S3_OK thenwriteln("Error returned by S3 service: ", s3getlasterror(mybucket))exit(1)
end-ifend-model

4.3

Listing S3 object keys
This example demonstrates listing the key names and last-modified dates of all object keys in our
bucket that start with "MyPrefix/".
Note that the s3listobjects procedure fetches object keys in batches of up to 1000 - you willneed to keep calling this procedure until the istruncated field is false to ensure you process all
the keys.
You will need to fill in the model parameters with your own Amazon S3 access credentials.
model S3ListExample
uses "s3"parameters
S3_BUCKET_URL = ""S3_REGION = ""S3_ACCESS_KEY_ID = ""S3_SECRET_KEY = ""end-parameters
declarations
PREFIX="MyPrefix/"
mybucket: s3bucket
objslistresult: s3objectlist
end-declarations! Configure ’mybucket’ with our S3 access credentials
mybucket.url := S3_BUCKET_URL
mybucket.region := S3_REGION
mybucket.accesskeyid := S3_ACCESS_KEY_ID
mybucket.secretkey := S3_SECRET_KEY

Fair Isaac Corporation Confidential and Proprietary Information

7

Usage examples

repeat! Request objects list
s3listobjects( mybucket, PREFIX, "", objslistresult )! Check for errors
if s3status(mybucket)<>S3_OK thenwriteln("Error returned by S3 service: ", s3getlasterror(mybucket))exit(1)
end-if! Process objects returned
forall (o in objslistresult.objects) dowriteln(’Object key:’,o.key,’, last-modified:’,o.lastmodified)
end-do! Repeat until we’ve fetched the last batch of object keys
until not objslistresult.istruncatedend-model

Fair Isaac Corporation Confidential and Proprietary Information

8

C HAPTER 5

Typess3objectinfo : record
Record type representing basic information about an S3 object
key :

text
The object key. If the s3bucket is configured with a keyprefix, the prefix will
not be included in this value.

etag :

text

The ’entity tag’ - a hash reflecting the content of the object.
lastmodified : datetime
The Last-Modified date for the object
owner : s3owner
The owner of the S3 object
size : real
The size of the S3 object, in bytes.
storageclass : text
The class of storage being used. Currently known values are STANDARD,STANDARD_IA, GLACIER and RRS.

s3objectlist : record
Record type representing a list of S3 objects.
objects :list of s3objectinfo
List of basic information records for a collection of S3 objects, as returned bys3listobjects
commonprefixes : list of text
List of the ’common prefixes’ returned by s3listobjects, if any
istruncated : boolean
Flag indicating whether the list of objects has been truncated. If true, you
should call ’s3listobjects’ again, passing the same arguments and s3objectlist
record structure, after processing the data in the ’objects’ and’commonprefixes’ fields.

s3objectmetadata : record
Record type representing object meta-data for an S3 object
cachecontrol :text

Fair Isaac Corporation Confidential and Proprietary Information

9

TypesThe Cache-Control header used in requests for the object
contentdisposition : text
The Content-Disposition header used in requests for the object
contentencoding : text
The Content-Encoding header used in requests for the object
contentlength : real
The Content-Length header used in requests for the object. This value isignored by the ’s3putobject’ subroutine.
contenttype : text
The Content-Type header used in requests for the object
lastmodified : text
The Last-Modified date for the object, in text format as returned by the server,
e.g. "Wed, 12 Oct 2009 17:50:00 GMT". This value is ignored by the’s3putobject’ subroutine.
expiration : boolean
Boolean value set to ’true’ if the object has a configured expiration action. Thisvalue is ignored by the ’s3putobject’ subroutine
expirationdetails : text
If the expiration field is ’true’, the text content of the ’expiration’ header. This
includes an ’expiry-date’ component and a URL-encoded ’rule-id’ component.
This value is ignored by the ’s3putobject’ subroutinedeletemarker : boolean
Flag indicating whether the object was a delete-marker. This value is ignoredby the ’s3putobject’ subroutine
usermetadata : array(s3usermetadatakeys) of text
Array of user-defined meta-data fields
replicationstatus : string
Replication status, if the object is in a bucket which is the source or destinationof a cross-region replication. When the object is in the source bucket, this will
be PENDING, COMPLETED or FAILED. When the object is in the destination
bucket, this will be REPLICA if the object is a replica created by Amazon S3.
When the object is not in a replication bucket, this will be an empty string. Thisvalue is ignored by the ’s3putobject’ subroutine.
serversideencryption : text
Where server-side encryption is enabled, the name of the encryption algorithm
used, otherwise an empty string.
ssekmskeyid : text
Where server-side encryption type ’aws:kms’ is used, the ID of the encryption
key in the Amazon Key Management Service
storageclass : string
The class of storage being used. Currently known values are STANDARD,STANDARD_IA, GLACIER and RRS.
taggingcount : integer
The count of tags associated with the object. This value is ignored by the’s3putobject’ subroutine.
versionid : text
If the object has a unique version ID, that version ID, otherwise empty string.
This value is ignored by the ’s3putobject’ subroutine.

Fair Isaac Corporation Confidential and Proprietary Information

10

Typesetag :

text

The ’entity tag’ - a hash reflecting the content of the object. This value isignored by the ’s3putobject’ subroutine.
websiteredirect : text
When bucket is configured as a website, this metadata will evaluate therequest as a 301 redirect to another object in the same bucket, or an externalURL.

s3owner : record
Record type representing information about the owner of an S3 object
id : text
displayname :text

s3tag : record
Record type representing a single S3 object tag.
key : stringvalue : text

Fair Isaac Corporation Confidential and Proprietary Information

11

C HAPTER 6

Variabless3usermetadatakeys : set of string
Set of all keys used in user-defined object metadata

Fair Isaac Corporation Confidential and Proprietary Information

12

C HAPTER 7

Subroutiness3delobject

Deletes an object from the S3 bucket

p. 14

s3getlasterror

Returns a string describing the error that occurred during the mostrecent operation on the s3bucket.
p. 15

s3getobject

Copies an object from the S3 bucket to a local Mosel file.
p. 16

s3getobjectmetadata

Requests the meta-data for the given object

p. 17

s3getobjecttagging

Requests the tagset for an object

p. 18

s3listobjects

Lists the objects in the bucket
p. 19

s3newtag

Creates an s3tag record with the given key and value

p. 20

s3objectexists

Checks if an S3 object exists

p. 21

s3putobject

Copies an object from a local Mosel file to an object in the S3 bucket
p. 22

s3setobjecttagging

Updates the tagging of the given object.

s3status

Indicates the status of the most recent request this model has madeusing the s3bucket
p. 24

Fair Isaac Corporation Confidential and Proprietary Information

p. 23

13

Subroutiness3delobject
PurposeDeletes an object from the S3 bucket
Synopsisprocedure s3delobject(bucket:s3bucket, objectkey:text)
Arguments
bucketobjectkey

The s3bucket object describing the bucket to access
The key of the object to delete

Exampledeclarations
s3delobject(mybucket,"my/file.dat")
if s3status(mybucket)<>S3_OK thenwriteln("Error returned by S3: ",s3getlasterror(mybucket))exit(1)
end-ifFurther information
1. After calling, check the value of s3status for any errors.
2. The procedure will not return until the object has been deleted or an error detected.
3. If the s3bucket has a configured keyprefix, it will be prepended to the objectkey passed in.
Related topics
s3status

Fair Isaac Corporation Confidential and Proprietary Information

14

Subroutines

s3getlasterror
PurposeReturns a string describing the error that occurred during the most recent operation on thes3bucket.
Synopsisfunction s3getlasterror(bucket:s3bucket):text
Return value
A text value containing the error message, which will be empty if the most recent operation on
the s3bucket succeeded.
Further information
1. After every call to an S3-related function or procedure, you should check the value of s3status tosee if your request succeeded. If it’s unclear why an error is being returned, moretroubleshooting output can be generated by setting the parameter s3_verbose to true, orinspecting the return value of s3geterrormsg.
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
distinguish between different types of error, use s3status instead.
Related topics
s3status s3_verbose

Fair Isaac Corporation Confidential and Proprietary Information

15

Subroutines

s3getobject
PurposeCopies an object from the S3 bucket to a local Mosel file.
Synopsisprocedure s3getobject(bucket:s3bucket, objectkey:text, dstfname:text,
dstobjectmetadata:s3objectmetadata)procedure s3getobject(bucket:s3bucket, objectkey:text, dstfname:text)
Arguments
bucketobjectkey
dstfname
dstobjectmetadata

The s3bucket object describing the bucket to access
The key of the object to retrieve
Filename into which to download the object, e.g. "myfile.dat" or"mmsystem.text:filedata"
Record into which the object meta-data is copied

Exampledeclarations
myfilecontent: text
end-declarations
s3getobject(mybucket,"my/file.dat","mmsystem.text:myfilecontent")
if s3status(mybucket)<>S3_OK thenwriteln("Error returned by S3: ",s3getlasterror(mybucket))exit(1)
end-ifwriteln("Fetched data: ",myfilecontent)
Further information
1. After calling, check the value of s3status for any errors.
2. The procedure will not return until the object has been downloaded or an error detected.
3. If the s3bucket has a configured keyprefix, it will be prepended to the objectkey passed in.
Related topics
s3status s3putobject s3objectmetadata

Fair Isaac Corporation Confidential and Proprietary Information

16

Subroutines

s3getobjectmetadata
PurposeRequests the meta-data for the given object
Synopsisfunction s3getobjectmetadata(bucket:s3bucket, objectkey:text):s3objectmetadata
Arguments
bucketobjectkey

The s3bucket object describing the bucket to access
The key of the object to retrieve

Exampledeclarations
mymetadata: s3objectmetadata
end-declarations
mymetadata := s3getobjectmetadata(mybucket,"my/file.dat")
if s3status(mybucket)<>S3_OK thenwriteln("Error returned by S3: ",s3getlasterror(mybucket))exit(1)
end-ifwriteln("my/file.dat last modified: ",mymetadata.lastmodified)
Further information
1. After calling, check the value of s3status for any errors.
2. The procedure will not return until the object metadata has been downloaded or an error
detected.
3. If the s3bucket has a configured keyprefix, it will be prepended to the objectkey passed in.
Related topics
s3status s3putobject s3objectmetadata

Fair Isaac Corporation Confidential and Proprietary Information17

Subroutines

s3getobjecttagging
PurposeRequests the tagset for an object
Synopsisfunction s3getobjecttagging(bucket:s3bucket, objectkey:text):list of s3tag
Arguments
bucketobjectkey

The s3bucket object describing the bucket to access
The key of the object to query

Exampledeclararations
tags: list of s3tag
end-declarations
tags := s3getobjecttagging(mybucket,"my/file.dat")
if s3status(mybucket)<>S3_OK thenwriteln("Error returned by S3: ",s3getlasterror(mybucket))exit(1)
end-ifFurther information
1. After calling, check the value of s3status for any errors.
2. The procedure will not return until the tags have been fetched or an error detected.
3. If the s3bucket has a configured keyprefix, it will be prepended to the objectkey passed in.
Related topics
s3status s3setobjecttagging

Fair Isaac Corporation Confidential and Proprietary Information18

Subroutines

s3listobjects
PurposeLists the objects in the bucket
Synopsisprocedure s3listobjects(bucket:s3bucket, prefix:text, delimiter:text,
result:s3objectlist)
procedure s3listobjects(bucket:s3bucket, prefix:text, result:s3objectlist)
Arguments
bucketprefixdelimiter

resultThe s3bucket object describing the bucket to access
The object prefix to search for
The object delimiter, or "" for no delimiter. If a delimiter is specified, then any
objects containing this string after the prefix will not be returned in result.objects,
but each unique string between the prefix and the next occurrence of this delimiter
will be returned in result.commonprefixes
Record structure to retrieve

Exampledeclarations
myresult: s3objectlist
end-declarations
repeats3listobjects( mybucket, "myprefix/", myresult )if s3status(mybucket)<>S3_OK thenwriteln("Error returned by S3: ",s3getlasterror(mybucket))exit(1)
end-ifforall (o in myresult.objects) dowriteln(’Found object with key ’,o.key)
end-dountil not myresult.istruncatedFurther information
1. After calling, check the value of s3status for any errors.
2. As the number of objects in an S3 bucket can be very large, this function may return a truncatedlist of the keys. If this is the case, the istruncated flag of the s3objectlist will be set to ’true’
and you should call s3listobjects again, passing the same record, to retrieve the next batch ofobject keys.
3. If the s3bucket has a configured keyprefix, it will be prepended to the prefix specified by thes3listobjects request
4. If the s3bucket has a configured keyprefix, it will be stripped from the keys and prefixes returnedin the s3objectlist
Related topics
s3status s3_maxkeys s3objectlist

Fair Isaac Corporation Confidential and Proprietary Information

19

Subroutines

s3newtagPurposeCreates an s3tag record with the given key and value
Synopsisfunction s3newtag(key:string, value:text):s3tagfunction s3newtag(key:text, value:text):s3tag
Examples3setobjecttagging(mybucket,"my/file.dat",[s3newtag("firstname","John"),s3newtag("lastname","Smith")])if s3status(mybucket)<>S3_OK thenwriteln("Error returned by S3: ",s3getlasterror(mybucket))exit(1)
end-ifFurther information
This would most often be used when constructing a tag list to pass to s3setobjecttagging
Related topics
s3setobjecttagging

Fair Isaac Corporation Confidential and Proprietary Information

20

Subroutines

s3objectexists
PurposeChecks if an S3 object exists
Synopsisfunction s3objectexists(bucket:s3bucket, objectkey:text):boolean
Arguments
bucketobjectkey

The s3bucket object describing the bucket to access
The key of the object to check

Return value
true if an object with the given key exists in the bucket, false if it does not.
Exampledeclarations
ifexists: boolean
end-declarations
ifexists := s3objectexists(mybucket,"my/file.dat")
if s3status(mybucket)<>S3_OK thenwriteln("Error returned by S3: ",s3getlasterror(mybucket))exit(1)
end-ifif ifexists thenwriteln("Object exists")
else
writeln("Object does not exist")
end-ifFurther information
1. After calling, check the value of s3status for any errors.
2. If the s3bucket has a configured keyprefix, it will be prepended to the objectkey passed in.
Related topics
s3status

Fair Isaac Corporation Confidential and Proprietary Information21

Subroutines

s3putobject
PurposeCopies an object from a local Mosel file to an object in the S3 bucket
Synopsisprocedure s3putobject(bucket:s3bucket, objectkey:text, srcfname:text,
metadata:s3objectmetadata)procedure s3putobject(bucket:s3bucket, objectkey:text, srcfname:text)
Arguments
bucketobjectkey
srcfname
metadata

The s3bucket object describing the bucket to access
The key of the object to write toFilename containing the object content, e.g. "myfile.dat" or"mmsystem.text:filedata"
Record describing the object meta-data.

Examples3putobject(mybucket,"my/file.dat","mmsystem.text:myfilecontent")
if s3status(mybucket)<>S3_OK thenwriteln("Error returned by S3: ",s3getlasterror(mybucket))exit(1)
end-ifFurther information
1. After calling, check the value of s3status for any errors.
2. The procedure will not return until the object has been uploaded or an error detected.
3. If the s3bucket has a configured keyprefix, it will be prepended to the objectkey passed in.
4. The local file may be opened & read multiple times; this procedure cannot be used with an I/Odriver that does not return the same content each time the filename is opened.
5. When you pass an object meta-data record, only some of the fields are sent to the server - see thes3objectmetadata documentation for full details. In addition, any fields that are empty will not
be sent to the server, with the exception of entries in the usermetadata array
Related topics
s3status s3getobject s3getobjectmetadata s3objectmetadata

Fair Isaac Corporation Confidential and Proprietary Information

22

Subroutines

s3setobjecttagging
PurposeUpdates the tagging of the given object.
Synopsisprocedure s3setobjecttagging(bucket:s3bucket, objectkey:text, tags:list of s3tag)
Arguments
bucketobjectkey
tagging

The s3bucket object describing the bucket to access
The key of the object to write to
The collection of tags to assign to the object. Any pre-existing tags not in this list
will be removed.

Exampledeclarations
lst: list of s3tag
end-declarations
s3setobjecttagging(mybucket,"my/file.dat",lst)
if s3status(mybucket)<>S3_OK thenwriteln("Error returned by S3: ",s3getlasterror(mybucket))exit(1)
end-ifFurther information
1. After calling, check the value of s3status for any errors.
2. The procedure will not return until the tags have been updated or an error detected.
3. If the s3bucket has a configured keyprefix, it will be prepended to the objectkey passed in.
Related topics
s3status s3getobjecttagging

Fair Isaac Corporation Confidential and Proprietary Information23

Subroutiness3status
Purpose
Indicates the status of the most recent request this model has made using the s3bucket
Synopsisfunction s3status(bucket:s3bucket):integer
Return value
One of the following constants:
S3_OK

The operation completed successfully.
The requested object was not found in the S3 bucket.

S3_NOT_FOUND

S3_ACCESS_DENIED

User is not authorized to access the S3 bucket.

S3_CONNECTION_ERROR
S3_SERVICE_ERROR
S3_IO_ERROR

Unable to connect to the S3 service.

The S3 service returned an unexpected error code.

The S3 module encountered an error reading or writing local files.

S3_PARSE_ERRORThe S3 module did not understand the response from the S3 service

Further information
After every call to an S3-related function or procedure, you should check the value of s3status tosee if your request succeeded. If it’s unclear why an error is being returned, moretroubleshooting output can be generated by setting the parameter ’s3_verbose’ to true, orinspecting the return value of s3getlasterror.
Related topics
s3getlasterror

Fair Isaac Corporation Confidential and Proprietary Information

24

C HAPTER 8Parameters
Via the getparam function and the setparam procedure it is possible to access the following
control parameters of module s3 :s3_buckets

Configure bucket credentials using JSON format

p. 26

s3_maxkeys

Limit keys returned by s3listobjects

p. 26

s3_trace

Log HTTP requests and responses

p. 25

s3_verbose

Activate additional logging

p. 25

s3_verbose
Description

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

Type

Boolean, read/write

Default value

false

s3_trace
Description

Set to ’true’ to activate logging of all S3-related HTTP requests, and corresponding
responses, to the model’s error stream.

Type

Boolean, read/write

Default value

false

Note

This can be useful when troubleshooting S3 authentication or other communication
issues.

Note

For security reasons, this feature is disabled when Mosel is used within DMP.

Fair Isaac Corporation Confidential and Proprietary Information25

Parameterss3_maxkeys
Description

Sets the maximum number of keys that can be returned by s3listobjects. If the query
would return more than this number of keys, the istruncated field of the s3objectslist
record will be set to ’true’ and you should call s3listobjects again to retrieve the next
batch of keys.

Type

Integer, read/write

Default value

1000

Note

Values less than 1, or greater than 1000, will be ignored.

s3_buckets
Description

This allows bucket credentials to be configured using a JSON file. 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.

Fair Isaac Corporation Confidential and Proprietary Information

26

A PPENDIX A

Contacting FICO
FICO provides clients with support and services for all our products. Refer to the following
sections for more 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 and have an active support or maintenance contract. You can find support contact
information on the Product Support home page (www.fico.com/support).
On the Product Support home page, you can also register for credentials to log on to FICO Online
Support, our web-based support tool to access Product Support 24x7 from anywhere in the world.
Using FICO Online Support, you can enter cases online, track them through resolution, findarticles in the FICO Knowledge Base, and query known issues.
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, andtraining tools for both new user enablement and ongoing performance support. For additional
information, visit the Product Education homepage at www.fico.com/en/product-training or
email producteducation@fico.com.

Product documentation
FICO continually looks for new ways to improve and enhance the value of the products andservices we provide. If you have comments or suggestions regarding how we can improve thisdocumentation, let us know by sending your suggestions to techpubs@fico.com.

Fair Isaac Corporation Confidential and Proprietary Information

27

Contacting FICO

Sales and maintenanceUSA, CANADA AND ALL AMERICASEmail: XpressSalesUS@fico.com
WORLDWIDE
Email: XpressSalesUK@fico.com
Tel: +44 207 940 8718
Fax: +44 870 420 3601
Xpress Optimization, FICO
FICO HouseInternational Square
Starley Way
Birmingham B37 7GN
UK

Related services
Strategy Consulting: Included in your contract with FICO may be a specified amount ofconsulting 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.fico.com or contact your FICO accountrepresentative.

About FICO
FICO (NYSE:FICO) delivers superior predictive analytics solutions that drive smarter decisions. The
company’s groundbreaking use of mathematics to predict consumer behavior has transformed
entire industries and revolutionized the way risk is managed and products are marketed. FICO’sinnovative solutions include the FICO® Score—the standard measure of consumer credit risk in
the United States—along with industry-leading solutions for managing credit accounts,
identifying and minimizing the impact of fraud, and customizing consumer offers with pinpoint
accuracy. Most of the world’s top banks, as well as leading insurers, retailers, pharmaceuticalcompanies, and government agencies, rely on FICO solutions to accelerate growth, control risk,
boost profits, and meet regulatory and competitive demands. FICO also helps millions ofindividuals manage their personal credit health through www.myfico.com. Learn more atwww.fico.com. FICO: Make every decision countTM .

Fair Isaac Corporation Confidential and Proprietary Information

28

IndexB
bucket content, 19D
delete object, 14
DMP, 5download object, 16
Llist objects, 19Oobject content, 16, 22
object exists, 21
object meta-data, 9, 16, 17, 22
object tagging, 18, 23
S
S3 operation error codes, 24
s3_buckets, 26
s3_maxkeys, 26
s3_trace, 25
s3_verbose, 25
s3bucket, 3s3delobject, 14s3getlasterror, 15
s3getobject, 16
s3getobjectmetadata, 17
s3getobjecttagging, 18
s3init, 3s3listobjects, 19
s3newtag, 20
s3objectexists, 21
s3objectinfo, 9s3objectlist, 9s3objectmetadata, 9s3owner, 11
s3putobject, 22
s3setobjecttagging, 23
s3status, 24
s3tag, 11s3usermetadatakeys, 12Uupdate object, 22

Fair Isaac Corporation Confidential and Proprietary Information

29