Cloud Data Access callable services

The z/OS Cloud Data Access callable services are:
All APIs accept a pointer to an optional parameter structure that describe a group of key:value pairs that can be used to modify the processing done by the particular API. The specific keys that are recognized varies per API and are described with each API. The APIs accept a pointer to the GDK_OPTIONAL_PARMS_TYPE structure, or NULL if none are desired. GDK_OPTION_KEY_TYPE is a pointer to character array (char *). GDK_OPTION_VALUE_TYPE is also a pointer to a character array unless the value is expected to be different.

   typedef struct {
     uint32_t GDK_NumberOfOptions;
     GDK_OPTION_TYPE GDK_OptionArray[];
   }   GDK_OPTIONAL_PARMS_TYPE;

   typedef struct { 
     GDK_OPTION_KEY_TYPE GDK_optionKey;
     GDK_OPTION_VALUE_TYPE GDK_optionValue;
   }   GDK_OPTION_TYPE;
Table 1. GDK_OPTIONAL_PARMS_TYPE
GDK_OPTIONAL_PARMS_TYPE
Offset Len Type Name Description
0   STRUCTURE GDK_OPTIONAL_PARMS_TYPE Structure of one optional parameter.
0 4 NUMBER GDK_OptionArray Array of GDK_OPTION_TYPE entries
4 * ARRAY GDK_OptionArray Array of GDK_OPTION_TYPE entries.
Table 2. GDK_OPTION_TYPE
GDK_OPTION_TYPE
Offset Len Type Name Description
0   STRUCTURE GDK_OPTION_TYPE Structure of one optional parameter.
0 4 POINTER GDK_OptionKey Pointer to Null-terminated character string for the key of the optional parameter.
4 4 POINTER GDK_optionValue Pointer to Null-terminated character string or value for the value related to the optional parameter.
Start of change
Table 3. Return and reason codes  for the Cloud Data Access callable services
Return Code  Constant Name Explanation
0 GDK_OK Processing was successful.
100 GDK_UNABLE_TO_READ_KEYFILE The gdkkeyf.json document was not found in the CDA user’s directory.
101 GDK_UNABLE_TO_WRITE_KEYFILE An error occurred while writing to the gdkkeyf.json file
102 GDK_UNABLE_TO_PARSE_KEYFILE When parsing the gdkkeyf.json document, it is not a valid JSON document.
103 GDK_MALFORMED_KEYFILE The object in the keyfile for a particular cloud provider is not a JSON array.
104 GDK_CLOUD_PROVIDER_NOT_FOUND When reading the gdkkeyf.json document, for the requested user, the specified cloud provider entry was not found.
105 GDK_NO_RESOURCE_FOUND_IN_KEYFILE For the specified userid, and cloud provider, no credentials entry for the requested resource was found.
106 GDK_UNABLE_TO_UPDATE_KEYFILE The gdkkeyf.json document cannot be updated.
107 GDK_UNABLE_TO_DELETE_FROM_KEYFILE The gdkkeyf.json cannot be updated to delete keys.
108 GDK_UNABLE_TO_ADD_TO_KEYFILE The gdkkeyf.json document cannot be updated to add keys.
109 GDK_ERROR_READING_SECURITY_CREDENTIALS An error occurred while looking for credentials for a given cloud resource.
110 GDK_PROVIDER_OPEN_FAILURE The JSON document for the requested cloud provider does not exist, or was found, but cannot be opened for READ.
111 GDK_PROVIDER_SPECIFICATION_INVALID When parsing the JSON document, it was found to be invalid.
112 GDK_FEATURE_UNSUPPORTED

An unknown contentType was found in the parameterSet.

113 GDK_BUFFER_TOO_SMALL

When decrypting the security credentials, the specified buffer was too small to hold the decrypted credential.

114 GDK_AUTH_INIT_FAILURE

When using the AWS4 authentication model, the

appropriate entry in the gdkkeyf.json document for the MVSUserID, cloud provider, and name (resource) is missing either the key, or the secretkey key-value pairs.

115 GDK_COULD_NOT_OPEN_OUTPUT_FILE Unable to open the requested local file for output.
116 GDK_AUTH_APPLY_FAILURE An error occurred while applying the authorization parameters.
117 GDK_KEY_GEN_FAILURE DFSMSdfp CDA was unable to create an AES256 encryption key to encrypt the credentials.
118 GDK_USER_INFO_NOT_FOUND

When reading the gdkkeyf.json document, the requested user entry was not found.

119 GDK_DECRYPTION_ERROR An error occurred when decrypting the cloud credentials in the keyfile.
120 GDK_INVALID_RC_VALUE Either a negative number, or greater than RC 1000, was passed.
121 GDK_UNKNOWN_RC A return code value was passed that is currently unused.
122 GDK_ICSF_ERROR An error occurred in the ICSF API. With LOG(ERROR) in effect, more information is provided as to the specific ICSF error.
123 GDK_CONN_NOT_HTTPS

HTTPS was not specified for httpMethod in the provider file.

124 GDK_OBJ_NAME_INVALID Object name contains characters from errorUrlChars in provider file.
125 GDK_INVALID_BUCKET_NAME Specified bucket name is an invalid.
126 GDK_OBJ_NAME_INCORRECT Object name does not start with /
127 GDK_METAHEADER_MISSING Provider file requestParameters missing METAHEADER object.
130 GDK_INVALID_CRED_FILE Error processing Credentials File JSON document.
131 GDK_SSL_SERV_ERROR SSL System Services returned an error.
132 GDK_INV_DATA_LOC_TYPE Invalid value passed for DATA_LOCATION_TYPE.
Start of change136End of change GDK_GENKEY_NOT_FOUND A requested key name (GDK_genKey) was not found in the CDA variable store after processing was complete.
137 GDK_INVALID_GENTYPE Invalid Type provided for genParms value.
138 GDK_OPERATION_AND_KEY_NOT_DEFINED Neither operation name nor key defined in the Validate parameters structure.
139 GDK_VALPARMS_NOT_DEFINED Validate parameters structure not defined.
140 GDK_VALUE_RETRIEVAL_FAILURE Retrieval of value from provider file failed.
141 GDK_PARAMETER_ERROR

One of the parameters on the API call was incorrect.

Examine the ERROR log message for details on the parameter in error.

142 GDK_EMPTY_PROVIDER_FILE The specified <cloudProvider>.JSON file is empty. <cloudProvider> is the provider name specified on the API parameter list.
143 GDK_PROVIDER_MISMATCH

Requested provider name does not match provider name for CDA session.

144 GDK_REGEX_ERROR The requested regular expression is not valid.
145 GDK_ICONV_ERROR Conversion error, converting from one code page to another code page.
146 GDK_COMPRESSION_INIT_FAILURE

An error occurred while initializing the stream to perform compression.

147 GDK_COMPRESSION_FAILURE An error occurred while compressing the data.
148 GDK_DECOMPRESSION_INIT_FAILURE Inflate initialization for decompression has failed.
149 GDK_DECOMPRESSION_FAILURE Decompression using Inflate has failed.
150 GDK_INVALID_JSON_TYPE An unexpected type was encountered as a JSON value.
151 GDK_NO_MEMORY_AVAILABLE Could not allocate memory for compressing the data.
152 GDK_INVALID_COMP_PARMS Invalid compression or compLevel parameter passed.
155 GDK_FULLY_QUALIFIED_DS_NOT_PASSED The dataLocation name that is a z/OS data set is not a fully qualified data set name.
156 GDK_COULD_NOT_ALLOCATE_DATASET

An error occurred while CDA was trying to create a new data set. An ERROR level message will describe the S99ERROR or S99INFO values that describe the error. Details about the error codes can be found in “Interpreting error reason codes from DYNALLOC”.

If the error was for a VSAM data set, refer to the IDCxxxxx messages that are included in the output. DEBUG level logging may provide additional information.

157 GDK_PDS_OR_PDSE_NOT_FOUND The specified data set name for a PDS or PDSE data set was not found in the Catalog.
158 GDK_IO_ERROR An unexpected error occurred with I/O to a data set.
159 GDK_INVALID_METADATA The metadata string has values which are incorrect or not allowed
160 GDK_INVALID_CF_PARMS “cloudformat”was passed, but the value was invalid.
161 GDK_UNSUPPORTED_DS The requested data set is of a type that DFSMSdfp CDA does not support for processing.
799 GDK_UNEXPECTED_ERROR An unexpected error occurred. Contact IBM Support, and provide the logging output.
800 GDK_CONNECTION_FAILED

Unable to connect to the host set in the cloud provider JSON definition.

801 GDK_TOOLKIT_FAILED Error occurred in the z/OS Client for Web Enablement Toolkit HWTHRQST call.
850 GDK_XML_PARSER_FAILED The XML parser failed with a bad return code
851 GDK_JSON_PARSER_FAILED The JSON parser failed with a bad return code
900 GDK_OBJECT_NOT_FOUND HTTP status 404 was returned indicating the object was not found.
901 GDK_ACCESS_DENIED HTTP status 403 was returned indicating the user is not authorized to access the resource in the desired manner.
902 GDK_OPERATION_NOT_SUPPORTED When parsing the cloud provider JSON document, the WRITEOBJECT description was not found in the supportedOperations array.
903 GDK_RESPONSE_FORMAT_MISMATCH The request was successful, but the data returned was in a format that did not match what is expected according to the contentType specified in the responseResults for the action in the provider file.
904 GDK_REQUEST_FAILED A bad HTTP status (4xx or 5xx) was returned.
End of change