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 (see Authenticating), 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')  ! Upload to key 'objectkey'
mybucket.keyprefix := 'myprefix/'
s3putobject(mybucket,'objectkey','mydata.dat')  ! 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, s3status will return an error code and s3getlasterror will return a description of the error.