Using GDKUTIL
IBM Z mainframes are flexible and run z/OS®, Linux®, z/TPF and z/VM®. GDKUTIL is used to store and retrieve MVS data sets and UNIX files between a z/OS system and cloud object storage.
This blog describes how to use GDKUTIL to store, retrieve, list, and delete cloud objects. The examples shown use the Amazon S3 cloud.
Setting up to use GDKUTIL
Using GDKUTIL requires several components to be set up. These are documented in MVS Programming: Callable Services for High-Level Languages (SA23-1377). The following chapters contain the information on setting up to use GDKUTIL:
· Cloud Data Access configuration
· Cloud Data Access files
· Cloud Data Access cloud credential storage
To encrypt the data before storing it on the cloud, see Cryptographic Services Integrated Cryptographic Service Facility Administrator’s Guide (SC14-7506) for the required configuration steps.
Using GDKUTIL
See DFSMSdfp Utilities (SC23-6864), chapter GDKUTIL (Cloud Object Utility) Program.
GDKUTIL examples
The following examples show the JCL to invoke GDKUTIL and the output produced by the utility. Items in italicized red text are supplied by the user.
The provider name is the name of the json file in /u/userid/gdk/providers/provider.json.
Storing objects
//UPLOAD EXEC PGM=GDKUTIL,REGION=0M
//SYSIN DD *
UPLOAD PROVIDER(provider)
//OBJNAME DD *
/bucketname/foldername/filename.zip
//LOCNAME DD *
/unixdir/filename.zip
//SYSOUT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
5695-DF124 DFSMSdfp CDA 3.1 CLOUD OBJECT UTILITY 2025031 03:00:35
GDKU0013I OBJNAME: /bucketname/foldername/filename.zip
UPLOAD PROVIDER(provider)
GDKU0013I LOCNAME: /unixdir/filename.zip
GDKU0100I UPLOAD PROCESSING SUCCESSFUL
Storing a UNIX file
//UPLOAD EXEC PGM=GDKUTIL,REGION=0M
//SYSIN DD *
UPLOAD PROVIDER(provider)
//OBJNAME DD *
/bucketname/foldername/DATA.SET.NAME
//LOCAL DD DSN=DATA.SET.NAME,DISP=SHR
//SYSOUT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
5695-DF124 DFSMSdfp CDA 3.1 CLOUD OBJECT UTILITY 2025031 03:00:35
GDKU0013I OBJNAME: /bucketname/foldername/DATA.SET.NAME
UPLOAD PROVIDER(provider)
GDKU0013I LOCNAME: DATA.SET.NAME
GDKU0100I UPLOAD PROCESSING SUCCESSFUL
Storing an MVS data set
Retrieving objects
//DOWNLOAD EXEC PGM=GDKUTIL,REGION=0M
//SYSIN DD *
DOWNLOAD PROVIDER(provider)
//OBJNAME DD *
/bucketname/foldername/filename.zip
//LOCNAME DD *
/unixdir/filename.zip
//SYSOUT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
5695-DF124 DFSMSdfp CDA 3.1 CLOUD OBJECT UTILITY 2025031 11:42:12
GDKU0013I OBJNAME: /bucketname/foldername/filename.zip
DOWNLOAD PROVIDER(DSSCLOUD)
GDKU0013I LOCNAME: /unixdir/filename.zip
GDKU0100I DOWNLOAD PROCESSING SUCCESSFUL
Retrieving a UNIX file
//DOWNLOAD EXEC PGM=GDKUTIL,REGION=0M
//SYSIN DD *
DOWNLOAD PROVIDER(provider)
//OBJNAME DD *
/bucketname/foldername/DATA.SET.NAME
//LOCAL DD DSN=DATA.SET.NAME,DISP=(,CATLG),
// SPACE=(CYL,(2000,1000),RLSE),DSNTYPE=LARGE,
// LRECL=80,BLKSIZE=0,RECFM=FB
//SYSOUT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
5695-DF124 DFSMSdfp CDA 3.1 CLOUD OBJECT UTILITY 2025031 17:02:00
GDKU0013I OBJNAME: /bucketname/foldername/DATA.SET.NAME
DOWNLOAD PROVIDER(DSSCLOUD)
GDKU0013I LOCNAME: DATA.SET.NAME
GDKU0100I DOWNLOAD PROCESSING SUCCESSFUL
Retrieving an MVS data set
Listing objects
//LIST EXEC PGM=GDKUTIL,REGION=0M
//SYSIN DD *
LIST PROVIDER(provider)
PREFIX(foldername)
//OBJNAME DD *
/bucketname/
//SYSOUT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
5695-DF124 DFSMSdfp CDA 3.1 CLOUD OBJECT UTILITY 2025031 16:17:35
GDKU0013I OBJNAME: /bucketname/
LIST PROVIDER(provider)
PREFIX(foldername)
GDKU0103I LIST OF BUCKET /bucketname/ IN CLOUD provider
SIZE, DATE, NAME
1699840, Fri Jan 31 07:59:51 2025, foldername/DSN1.XMIT,
2108720, Fri Jan 31 08:00:02 2025, foldername/DSN2.XMIT,
1630000, Fri Jan 31 08:00:13 2025, foldername/DSN3.XMIT,
1024320, Fri Jan 31 08:00:23 2025, foldername/DSN4.XMIT,
970045360, Fri Jan 31 08:06:39 2025, foldername/DSN5.XMIT,
1031642400, Fri Jan 31 08:06:58 2025, foldername/DSN6.XMIT,
657406880, Fri Jan 31 08:04:58 2025, foldername/DSN7.XMIT,
2071532080, Fri Jan 31 08:11:51 2025, foldername/DSN8.XMIT,
2191051760, Fri Jan 31 08:13:15 2025, foldername/DSN9.XMIT,
740523360, Fri Jan 31 08:05:09 2025, foldername/DSN10.XMIT,
11515647600, Fri Jan 31 08:23:20 2025, foldername/DSN11.XMIT,
28802240, Fri Jan 31 08:01:38 2025, foldername/DSN12.XMIT
GDKU0110I PROCESSED 12 OBJECTS
GDKU0100I LIST PROCESSING SUCCESSFUL
List objects in a bucket by prefix
Deleting objects
//DELETE EXEC PGM=GDKUTIL,REGION=0M
//SYSIN DD *
DELETE PROVIDER(provider)
PREFIX(foldername)
//OBJNAME DD *
/bucketname/
//SYSPRINT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
Delete objects in a folder
Full volume dump
This section describes how to create a full volume dump to Amazon S3 Cloud using GDKUTIL.
The sample JCL does the following:
· Step 1 – DUMPENC – full volume dump of a volume, compressing and encrypting the output data set
· Step 2 – XMIT – converts the ADRDSSU dump from RECFM=U to RECFM=FB using the TSO XMIT command
· Step 3 – UPLOAD – Upload the XMIT formatted data set to the Amazon S3 cloud using the GDKUTIL program
· Step 4 – DELXMIT – deletes the XMIT format data set if the upload was successful.
//DUMPENC EXEC PGM=ADRDSSU
//DASD DD UNIT=3390,VOL=SER=VOLSER,DISP=SHR
//TAPE DD DSN=&&DFDSS,DISP=(,PASS),DSNTYPE=LARGE,
// SPACE=(CYL,(10000,1000),RLSE)
//SYSIN DD *
DUMP FULL INDD(DASD) OUTDD(TAPE) -
OPTIMIZE(4) ALLEXCP ALLDATA(*) -
HWCOMPRESS ZCOMPRESS(PREF) - /* REMOVE THIS LINE FOR NO COMPRESSION */
ENCRYPT(CLRTDES) RSA(ENCRYPT.KEY) /* REMOVE THIS LINE FOR NO ENCRYPTION */
//SYSPRINT DD SYSOUT=*
PAGE 0001 5695-DF175 DFSMSDSS 3.1 DATA SET SERVICES 2025.031 03:00
DUMP FULL INDD(DASD) OUTDD(TAPE) -
OPTIMIZE(4) ALLEXCP ALLDATA(*) -
HWCOMPRESS ZCOMPRESS(PREF) -
ENCRYPT(CLRTDES) RSA(ENCRYPT.KEY)
ADR101I (R/I)-RI01 (01), TASKID 001 HAS BEEN ASSIGNED TO COMMAND 'DUMP '
ADR109I (R/I)-RI01 (01), 2025.031 03:00:06 INITIAL SCAN OF USER CONTROL STATEMENTS COMPLETED
ADR016I (001)-PRIME(01), RACF LOGGING OPTION IN EFFECT FOR THIS TASK
ADR533I (001)-ZCOMP(01), 2025.031 03:00:06 ZEDC SERVICES TO BE USED FOR DUMP DATA SET ON DDNAME TAPE
ADR006I (001)-STEND(01), 2025.031 03:00:06 EXECUTION BEGINS
ADR515I (001)-DDTFP(01), 2025.031 03:00:07 ENCRYPTION SERVICES TO BE USED FOR DUMP DATA SET ON VOLSER VOLSER
ADR006I (001)-STEND(02), 2025.031 03:00:19 EXECUTION ENDS
ADR013I (001)-CLTSK(01), 2025.031 03:00:19 TASK COMPLETED WITH RETURN CODE 0000
ADR012I (SCH)-DSSU (01), 2025.031 03:00:19 DFSMSDSS PROCESSING COMPLETE. HIGHEST RETURN CODE IS 0000
// IF (DUMPENC.RC EQ 0) THEN
//XMIT EXEC PGM=IKJEFT01
//INPUT DD DSN=&&DFDSS,DISP=(OLD,DELETE)
//OUTPUT DD DSN=VOLSER.XMIT,DISP=(,CATLG),
// LRECL=80,BLKSIZE=0,RECFM=FB,DSNTYPE=LARGE,
// SPACE=(CYL,(10000,1000),RLSE)
//SYSTSIN DD *
XMIT USERID FILE(INPUT) OUTFILE(OUTPUT) SYSOUT(Z) NOLOG
//SYSTSPRT DD SYSOUT=*
READY
XMIT USERID FILE(INPUT) OUTFILE(OUTPUT) SYSOUT(Z) NOLOG
INMX000I 0 message and 99999 data records sent as 99999 records to XXXXXXX.USERID
INMX001I Transmission occurred on 01/31/2025 at 03:00:20
READY
END
// IF (XMIT.RC EQ 0) THEN
//UPLOAD EXEC PGM=GDKUTIL,REGION=0M
//SYSIN DD *
UPLOAD PROVIDER(provider)
//OBJNAME DD *
/bucketname/foldername/VOLSER.XMIT
//LOCAL DD DSN=VOLSER.XMIT,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
5695-DF124 DFSMSdfp CDA 3.1 CLOUD OBJECT UTILITY 2025031 03:00:22
GDKU0013I OBJNAME: /bucketname/foldername/VOLSER.XMIT
UPLOAD PROVIDER(provider)
GDKU0013I LOCNAME: VOLSER.XMIT
GDKU0100I UPLOAD PROCESSING SUCCESSFUL
// IF (UPLOAD.RC EQ 0) THEN
//DELXMIT EXEC PGM=IEFBR14
//XMITDSN DD DSN=VOLSER.XMIT,DISP=(OLD,DELETE)
// ENDIF
// ENDIF
// ENDIF
Full volume dump JCL
Full volume restore
This section describes how to restore a full volume dump from Amazon S3 Cloud using GDKUTIL.
The sample JCL does the following:
· Step 1 – DOWNLOAD – download the XMIT full volume dump data set
· Step 2 – RECEIVE – convert the XMIT formatted data set to a DFDSS formatted data set
· Step 3 – INITVOL – initialize a volume for the restore
· Step 4 – RESTORE –restore the full volume dump
//DOWNLOAD EXEC PGM=GDKUTIL,REGION=0M
//SYSIN DD *
DOWNLOAD PROVIDER(provider)
//OBJNAME DD *
/bucketname/foldername/VOLSER.XMIT
//LOCAL DD DSN=VOLSER.XMIT,DISP=(,CATLG),
// SPACE=(CYL,(10000,1000),RLSE),DSNTYPE=LARGE,
// LRECL=80,BLKSIZE=0,RECFM=FB
//SYSOUT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
5695-DF124 DFSMSdfp CDA 3.1 CLOUD OBJECT UTILITY 2025031 14:03:52
GDKU0013I OBJNAME: /bucketname/foldername/VOLSER.XMIT
DOWNLOAD PROVIDER(provider)
GDKU0013I LOCNAME: VOLSER.XMIT
GDKU0100I DOWNLOAD PROCESSING SUCCESSFUL
// IF (DOWNLOAD.RC EQ 0) THEN
//RECEIVE EXEC PGM=IKJEFT01
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
RECEIVE INDS(‘VOLSER.XMIT’)
DSNAME(‘VOLSER.DFDSS')
READY
RECEIVE INDS(‘VOLSER.XMIT')
Dataset USERID.DDNAME.INPUT from USERID on XXXXXXX
Enter restore parameters or 'DELETE' or 'END' +
The input file attributes are: DSORG=SEQUENTIAL, RECFM=U, BLKSIZE=27998, LRECL=0, File size=5865M bytes +
You may enter DSNAME, SPACE, UNIT, VOL, OLD/NEW, or RESTORE/COPY/DELETE/END
Restore successful to dataset ‘VOLSER.DFDSS'
READY
END
// IF (RECEIVE.RC EQ 0) THEN
//INITVOL EXEC PGM=ICKDSF,PARM='NOREPLYU,FORCE'
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
INIT UNIT(####) NOVERIFY VOLID(VOLSER) -
VTOC(#,#,##) INDEX(#,#,##)
// IF (INITVOL.RC EQ 0) THEN
//RESTORE EXEC PGM=ADRDSSU
//TAPE DD DSN=VOLSER.DFDSS,DISP=SHR
//SYSIN DD *
RESTORE FULL INDD(TAPE) ODY(VOLSER)
//SYSPRINT DD SYSOUT=*
// ENDIF
// ENDIF
// ENDIF
PAGE 0001 5695-DF175 DFSMSDSS 3.1 DATA SET SERVICES 2025.031 15:33
RESTORE FULL INDD(TAPE) ODY(VOLSER)
ADR101I (R/I)-RI01 (01), TASKID 001 HAS BEEN ASSIGNED TO COMMAND 'RESTORE '
ADR109I (R/I)-RI01 (01), 2025.044 15:33:52 INITIAL SCAN OF USER CONTROL STATEMENTS COMPLETED
ADR016I (001)-PRIME(01), RACF LOGGING OPTION IN EFFECT FOR THIS TASK
ADR006I (001)-STEND(01), 2025.044 15:33:52 EXECUTION BEGINS
ADR780I (001)-TDFP (01), THE INPUT DUMP DATA SET BEING PROCESSED IS IN FULL VOLUME FORMAT AND WAS CREATED BY Z/OS DFSMSDSS VERSION
3 RELEASE 1 MODIFICATION LEVEL 0 ON 2024.127 16:58:20
ADR006I (001)-STEND(02), 2025.044 15:35:21 EXECUTION ENDS
ADR013I (001)-CLTSK(01), 2025.044 15:35:21 TASK COMPLETED WITH RETURN CODE 0000
ADR012I (SCH)-DSSU (01), 2025.044 15:35:21 DFSMSDSS PROCESSING COMPLETE. HIGHEST RETURN CODE IS 0000
Full volume restore JCL