Reference manual

FICO Xpress OptimizationR

FAC File Transfer
Reference Manual
Release 8.3

Last update 7 July, 2015

www.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.
©2014–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: 7 July, 2015
Version 8.3

Contents
1 Introduction

1

2 Usage examples
2.1 File Download example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 File Upload example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3 File Listing example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2
2
2
3

3 Types

44 Subroutines
facftdelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
facftdownload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
facftexists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
facftgetattributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
facftlist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
facftlogin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
facftlogout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
facftmakedir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
facftremovedir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
facftupload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5
6
7
8
9
10
11
12
13
14
15

Appendix

16

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

16
16
16
16
17
17
17

Index

18

Fair Isaac Corporation Confidential and Proprietary InformationiC HAPTER 1

Introduction
The package and module facfiletransfer provides functionality allowing files to be uploaded toand downloaded from the FICO File Transfer Service on the FICO Analytic Cloud. Thisfunctionality is available from local models as well as models running in permitted applications
on the FICO Analytic Cloud.
Access to the FICO File Transfer Service is authorised by username and password. You must have ausername and password in order to use the FICO File Transfer service. The only exception to this iswhen using a DMP component pre-configured with an FTS username and password.

Fair Isaac Corporation Confidential and Proprietary Information

1

C HAPTER 2

Usage examples
2.1

File Download example
This example demonstrates download a remote file called MyFile.txt from a folder called
MyRemoteFolder into a local file MyFile.txt.
The remote files will be located in a directory that has been provisioned for you on the remote
FTS server. This remote directory can be referred to as your root directory "/", with any
subdirectories or files you have created located within this. For example, if you have a file
"MyFile.txt" in a folder called "MyFolder" then you’d refer to this using the remote path"/MyFolder/MyFile.txt".
model FacFileTransferExample
uses "facfiletransfer"parameters
USER="MyFTSUsername"
PASS="MyFTSPassword"
end-parameters
declarations
LOCAL_FILE="MyFile.txt"
REMOTE_FILE="/MyRemoteFolder/MyFile.txt"
end-declarations! Login to file transfer service
facftlogin(USER,PASS)! Download remote filefacftdownload(REMOTE_FILE,LOCAL_FILE)
end-model

2.2

File Upload example
This example demonstrates upload from a text object in the model to the remote path
/MyRemoteFolder/MyFile.txt.
model FacFileTransferExample
uses "facfiletransfer","mmsystem"
parameters
USER="MyFTSUsername"
PASS="MyFTSPassword"
end-parameters
public declarations

Fair Isaac Corporation Confidential and Proprietary Information

2

Usage examples

localData: text
end-declarations
declarations
REMOTE_FILE="/MyRemoteFolder/MyFile.txt"
end-declarations! Populate data to upload
localData := "Hello World"! Login to file transfer service
facftlogin(USER,PASS)! Download remote filefacftupload(REMOTE_FILE,"mmsystem.text:localData")
end-model

2.3

File Listing example
This example demonstrates listing all the files in the remote folder /MyRemoteFolder.
model FacFileTransferExample
uses "facfiletransfer","mmsystem"
parameters
USER="MyFTSUsername"
PASS="MyFTSPassword"
end-parameters
declarations
remoteFiles: list of facftfile
REMOTE_FOLDER="/MyRemoteFolder"
end-declarations! Login to file transfer service
facftlogin(USER,PASS)! Request remote directory listing
remoteFiles := facftlist(REMOTE_FOLDER)! Output remote filenames
forall( f in remoteFiles) dowriteln(REMOTE_FOLDER,"/",f.filename)end-doend-model

Fair Isaac Corporation Confidential and Proprietary Information

3

C HAPTER 3

Types
facftfile : record
a record containing information about a remote folder or file.
filename :stringFilename of the remote file or folder (leafname, not full path)isdir : boolean
true for folders, false for files
size : integer
Size of the file, in bytes, or -1 if too large to represent as a Mosel integer
owner : string
File owner, given as your numeric user ID in the remote FTS service
permissions : string
File permissions, represented as a Unix-style permissions string. This is athree-digit number in which the first digit is the permission for the file’s owner,
the second digit permissions for the file’s group, and the third digit permissions
for all other FTS users. For each digit, a value of 0 means no permission, 2means read-only permission, and 6 means read-write permission.
Note
Modifying the fields within the record will not modify the information on theserver.

Fair Isaac Corporation Confidential and Proprietary Information

4

C HAPTER 4

Subroutines
facftdelete

Delete a remote filep. 6

facftdownload

Download a file from the remote path to a local filep. 7

facftexists

Check whether a remote folder or file exists.

p. 8

facftgetattributes

Query meta-data about a remote file or folder.

p. 9

facftlist

List the files and subfolders within a remote folder.

p. 10

facftlogin

Login to the FAC File Transfer service.

p. 11

facftlogout

Log out of the FAC File Transfer service.

p. 12

facftmakedir

Create a new remote folder.

p. 13

facftremovedir

Delete an empty, remote folder.

p. 14

facftupload

Upload a file to a remote path from a local filep. 15

Fair Isaac Corporation Confidential and Proprietary Information5

Subroutines

facftdelete
PurposeDelete a remote file
Synopsisprocedure facftdelete(remote_path:string)Argument
remote_path

The path of the remote file to delete, e.g. "/MyFolder/MyFile.txt"

Examplefacftdelete("/MyFolder/MyFile.txt")
Further information
1. If the remote file does not exist, the package will raise an IO error.
2. When used from a DMP component with preconfigured FAC File Transfer Service credentials, thisfunction will automatically try to login to the FAC File Transfer Service if you are not alreadylogged in.

Fair Isaac Corporation Confidential and Proprietary Information

6

Subroutines

facftdownload
PurposeDownload a file from the remote path to a local file
Synopsisprocedure facftdownload(remote_path:string, local_file:string)Arguments
remote_path
local_file

The path of the remote file to download, e.g. "/MyFolder/MyFile.txt"
The filename of the local file to which to write the downloaded data.

Examplefacftdownload("/MyFolder/MyFile.txt","MyFile.txt")
Further information
1. The local filename can reference an IO driver in the usual Mosel fashion, e.g.
"mmsystem.text:MyFileContent"
2. If the remote file does not exist, the package will raise an IO error.
3. If a network error occurs during file download, the package will raise an IO error. Note that inthis case, an incomplete file data may have been written to local_file.
4. When used from a DMP component with preconfigured FAC File Transfer Service credentials, thisfunction will automatically try to login to the FAC File Transfer Service if you are not alreadylogged in.

Fair Isaac Corporation Confidential and Proprietary Information

7

Subroutines

facftexists
PurposeCheck whether a remote folder or file exists.
Synopsisfunction facftexists(remote_path:string):boolean
Argument
remote_path

The path of the remote folder or file, e.g. "/MyFolder/MyFile.txt"

Return value
true if the file or folder exists on the remote server, false otherwise.
Exampleif facftexists("/MyFolder/MySubFolder") thenwriteln("Already exists")
else
writeln("Does not exist")
end-ifFurther information
When used from a DMP component with preconfigured FAC File Transfer Service credentials, thisfunction will automatically try to login to the FAC File Transfer Service if you are not alreadylogged in.

Fair Isaac Corporation Confidential and Proprietary Information

8

Subroutines

facftgetattributes
PurposeQuery meta-data about a remote file or folder.
Synopsisfunction facftgetattributes(remote_path:string):facftfile
Argument
remote_path

The path of the remote file or folder, e.g. "/MyFolder/MyFile.txt"

Examplef := facftgetattributes("/MyFolder/MyFile.txt")
writeln(f.file_name," has size ",f.file_size)

Further information
1. The returned size of the file may have been rounded.
2. The file permissions are given in standard Unix format, e.g. 0644 for owner-writable,group-readable, world-readable.
3. If the remote file or folder does not exist, the package will raise an IO error.
4. When used from a DMP component with preconfigured FAC File Transfer Service credentials, thisfunction will automatically try to login to the FAC File Transfer Service if you are not alreadylogged in.

Fair Isaac Corporation Confidential and Proprietary Information

9

Subroutines

facftlist
PurposeList the files and subfolders within a remote folder.
Synopsisfunction facftlist(remote_path:string):list of facftfile
Argument
remote_path

The path of the remote folder, e.g. "/MyFolder/MySubFolder"

Return value
List containing meta-data for folders and files in the given folder, ordered alphabetically.
Exampledeclarations
files: list of facftfile
end-declarations
files := facftlist("/MyFolder/MySubFolder")forall (f in files) dowriteln(f.file_name)done

Further information
1. The returned size of the file may have been rounded.
2. The file permissions are given in standard Unix format, e.g. 0644 for owner-writable,group-readable, world-readable
3. The relative subfolder paths "." and ".." are not included in the returned list.
4. This function returns the direct children of remote_path only; it is not recursive.
5. If the remote folder does not exist, this function will generate an IO error.
6. When used from a DMP component with preconfigured FAC File Transfer Service credentials, thisfunction will automatically try to login to the FAC File Transfer Service if you are not alreadylogged in.

Fair Isaac Corporation Confidential and Proprietary Information

10

Subroutines

facftlogin
PurposeLogin to the FAC File Transfer service.
Synopsisprocedure facftlogin
procedure facftlogin(username:string, password:string)procedure facftlogin(baseurl:string, username:string, password:string)Arguments
usernamepasswordbaseurl

Username for login
Password for login
URL of the FTS service to use, e.g.
https://fts.chi.ficoanalyticcloud.com/api/v1.0

Examplefacftlogin(’MyUsername’,’MyPassword’)
facftlogin(’https://fts.chi.ficoanalyticcloud.com/api/v1.0’,’MyUsername’,’MyPassword’)
Further information
1. When using the facfiletransfer package from your local machine, you are required to login with ausername and password prior to making any other calls. When using facfiletransfer within a DMP
component, login is not required if the component has been preconfigured with a FAC File
Transfer username and password.
2. If your username or password are rejected by the FAC File Transfer service, or the FAC File Transfer
service is unavailable, the function will return an error and your model will terminate.
3. When used without a username and password, the function will use the credentials
preconfigured in your DMP component. This is not necessary for use in the FAC, as the module
will login on your first facfiletransfer function call, but is provided to allow you to validate
credentials at a predicatable place.
4. Your username and password are transmitted to the remote FTS server using HTTP Basicauthentication across an HTTPS session.
5. When using the facfiletransfer package from your local machine, you are required to login with ausername and password prior to making any other calls. When using facfiletransfer within a DMP
component, login is not required if the component has been preconfigured with a FAC File
Transfer username and password.
6. If your username or password are rejected by the FAC File Transfer service, or the specified FAC
File Transfer service is unavailable, the function will return an error and your model willterminate.
7. When used without a username and password, the function will use the credentials
preconfigured in your DMP component. This is not necessary for use in the FAC, as the module
will login on your first facfiletransfer function call, but is provided to allow you to validate
credentials at a predicatable place.
8. Your username and password are transmitted to the remote FTS server using HTTP Basicauthentication across an HTTPS session.

Fair Isaac Corporation Confidential and Proprietary Information

11

Subroutines

facftlogout
PurposeLog out of the FAC File Transfer service.
Synopsisprocedure facftlogout
Examplefacftlogout
Further information
Logout is not required (you will be logged out automatically when the model ends). This
procedure allows you to end your session earlier for housekeeping reasons.

Fair Isaac Corporation Confidential and Proprietary Information

12

Subroutines

facftmakedir
PurposeCreate a new remote folder.
Synopsisprocedure facftmakedir(remote_path:string)Argument
remote_path

The path of the remote folder to create, relative to your root folder on the FTS
server, e.g. "/MyFolder/MySubFolder"

Examplefacftmakedir("/MyFolder/MySubFolder")Further information
1. If the remote folder already exists, this function will generate an IO error.
2. When used from a DMP component with preconfigured FAC File Transfer Service credentials, thisfunction will automatically try to login to the FAC File Transfer Service if you are not alreadylogged in.

Fair Isaac Corporation Confidential and Proprietary Information

13

Subroutines

facftremovedir
PurposeDelete an empty, remote folder.
Synopsisprocedure facftremovedir(remote_path:string)Argument
remote_path

The path of the remote folder to delete, e.g. "/MyFolder/MySubFolder"

Examplefacftremovedir("/MyFolder/MySubFolder")Further information
1. The remote folder must not contain any files or subfolders.
2. When used from a DMP component with preconfigured FAC File Transfer Service credentials, thisfunction will automatically try to login to the FAC File Transfer Service if you are not alreadylogged in.

Fair Isaac Corporation Confidential and Proprietary Information

14

Subroutines

facftupload
Purpose
Upload a file to a remote path from a local file
Synopsisprocedure facftupload(remote_path:string, local_file:string)Arguments
remote_path
local_file

The path of the remote file to upload to, e.g. "/MyFolder/MyFile.txt"
The filename of the local file to which to read the data to upload.

Examplefacftupload("/MyFolder/MyFile.txt","MyFile.txt")
Further information
1. The local filename can reference an IO driver in the usual Mosel fashion, e.g.
"mmsystem.text:MyFileContent"
2. If the remote file does not exist, it will be created so long as the parent remote folder exists.
3. If the remote file already exists, the previous content will be overwritten.
4. When used from a DMP component with preconfigured FAC File Transfer Service credentials, thisfunction will automatically try to login to the FAC File Transfer Service if you are not alreadylogged in.

Fair Isaac Corporation Confidential and Proprietary Information

15

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

16

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

17

IndexF
facftdelete, 6
facftdownload, 7
facftexists, 8
facftfile, 4facftgetattributes, 9facftlist, 10
facftlogin, 11
facftlogout, 12
facftmakedir, 13
facftremovedir, 14
facftupload, 15Llogin, 11logout, 12
Rremote fileattributes, 9check existence, 8delete, 6
download, 7
upload, 15
remote folder
attributes, 9check existence, 8
create new, 13delete, 14
list contents, 10

Fair Isaac Corporation Confidential and Proprietary Information

18