If you haven’t seen the rest of the Game Changing Series Blog posts you can check them out here to get a high-level explanation of CDA and the other enhancements!

Now, we want to dive into the newest enhancement a little deeper from a technical perspective.

The APIs

There is a short description for each of the FIVE! new APIs from this enhancement in A Game Changing Series – Part 2, here we will explain each new API in more detail.

GDKINIT & GDKTERM

The GDKINIT and GDKTERM APIs are a pair that allow the application to start and end/terminate a CDA session. A CDA session allows for multiple CDA API calls for cloud objects without having to perform much of the overhead; During CDA session, the provider file, key file, and config file are only read one time.

More importantly, the SSL connection is kept open across the life of the CDA session, and the SSL handshake is only done for the first request. Later, if the connection has been idle, and closed by the remote server, it’ll be reopened on the next API call. To ensure continued security of the cloud credentials, during a session, the cloud credentials remain encrypted and only decrypted when needed for a particular request.

Since the SSL handshake is only performed once, there is a decrease in crypto usage and processing time per call!

GDKGEN

The GDKGEN API allows the application to request any operation named in the CDA provider file. As part of this support, new operations, CREATEBUCKET and DELETEBUCKET, are added to the sample provider files. If an application wants to create a bucket, it can simply call the GDKGEN API with a parameter indicating that CREATEBUCKET is the operation to be performed. This API allows for application developers to create their own operations conforming to the REST API of the cloud server and request CDA to perform that operation programmatically.

GDKVALD

The GDKVALD API allows an application to validate that a provider file has any operations and key/value pairs the application requires. With the GDKVALD API, the application can pass a list of the operation names, as well as key names within that operation to CDA. CDA will check the provider file and return an indicator of whether the named operation or key exists for each item in the list. Additionally, the application can provide a buffer for CDA to return the value for the requested key. With this functionality, an application can include its own key/value expectations in a provider file and make decisions based on the CDA provider file by requesting the value for the application key name. The application can use the GDKVALD API to ensure that a specific operation exists in the provider file so it can successfully use that name in a later GDKGEN API call.

GDKQUERY

Lastly, the GDKQUERY API allows an application to see if a particular functionality exists on the current system’s CDA code. As CDA continues to be enhanced, indicators of the new function will be added to the return buffer mapping. The return buffer mapping includes API names, as well as newly supported optional parameters that are introduced.

Summary of new or updated Operations/Commands, Keywords, and Statements for GDKUTIL:

 The GDKUTIL utility has also been enhanced to use some of the new APIs.

OPERATION(<oper>)

With the sample provider file updates of the CREATEBUCKET and DELETEBUCKET operations, you can issue OPERATION(CREATEBUCKET) to create new buckets in the cloud object store from z/OS. You will no longer have to log into the object store web interface to create a bucket.

Similarly, the OPERATION(DELETEBUCKET) command can be used to delete any empty buckets from your object store.

Additionally, if there is a cloud object store operation that you wish to perform from z/OS, you can create your own operation in the provider file and invoke it with the OPERATION command!

LIST

The LIST command has been enhanced to support new keywords, PREFIX and DELIM.

Specifying PREFIX(<prefix>) will tell the cloud object store to return a list of objects that start with that prefix. We enhanced GDKUTIL to support the PREFIX keyword for a LIST of all buckets so that it returns only the bucket names that start with the <prefix> when you specify the forward slash (/) as the OBJNAME.

The DELIM keyword allows you to request only the object names up to a particular delimiter such as the forward slash character (/).

DELETE

The DELETE command is enhanced to be able to delete multiple objects with one command. Using the bucket name in the BUCKET DD statement, GDKUTIL will first get a LIST of all objects in the named bucket, and issue DELETE requests for each object name in the list.

The PREFIX keyword can be used to narrow the list returned to just the objects that begin with the specified characters.

The new REGEX(<regular_expression>) keyword was added so that you can further tailor which objects are deleted.

Additionally, a new keyword, TEST, is added so that you can see which objects would be deleted.

Example:

If you wanted to delete all objects in the bucket that end with .log, you would specify REGEX(.*\.log$)

UPLOAD

A z/OS UNIX directory tree can be uploaded to the cloud object store. The UPLOAD command is enhanced to upload files it finds in that directory tree if the BUCKET DD statement is found.

When the LOCNAME DD specifies a z/OS UNIX directory (the name ends with a forward slash (/) ), GDKUTIL will upload each regular file found in the directory tree to the named bucket.

The PREFIX keyword can be used to indicate a prefix that is added to each name before uploading to the object store. The object name will consist of the path name for the file relative to the starting directory.

The REGEX keyword can be used to tailor which files are chosen to upload.

The TEST keyword can be specified to report what files would be sent and what their object names would be.

DOWNLOAD

Multiple cloud objects can be downloaded to a z/OS UNIX directory. The DOWNLOAD command is enhanced to process multiple objects if the BUCKET DD statement exists.

The LOCNAME DD should specify a z/OS UNIX directory as the target for the downloads. GDKUTIL will first get a LIST of all objects in the named bucket, and issue DOWNLOAD requests for each object name in the list.

The PREFIX keyword can be used to narrow the list returned, and the REGEX keyword can be used to select which objects to download.

Note: If an object name has the forward slash character (/) in it, GDKUTIL interprets that as a directory level. A new directory is created with the name up to that point, and the file is created with the non-directory portion of the name.

BUCKET DD

GDKUTIL has also been enhanced to support performing an operation on multiple objects in one command. A new DD name, BUCKET, is recognized on the GDKUTIL job. This is an indicator that you want to perform the operation on multiple objects. For example, multiple objects can be deleted with one command.

These enhancements were delivered in APAR OA65224 and are available on z/OS 2.5 and above.

Our official publications are being updated, but until then, you can visit the following link to get even more details here.

Check out our Cloud Data Access content solution page to learn more and get started!

We would love to hear your thoughts on CDA and these new enhancements! Leave a comment on this blog post, start a discussion on the DFSMS Community Page, or join Mainframe Data Management LinkedIn group to discuss there!

Stay tuned for ‘A Game Changing Series Part 4’!

Author: Andrew Wilt - Cloud Data Access Product Owner

Editors: Alexis Ricci - z/OS DFSMS Product Manager, Barbara McDonald - z/OS DFSMS Product Manager