Checking for errors by using C functions and macros

z/TPFDF provides several C functions and macros that can be used to check for common errors and return conditions.

Table 1 lists a set of C functions that you can use to test a particular condition when you have called a C function.

Note:

Do not use any of these functions after a dfcls function.
Any application that uses the DF_EMPTY function or checks SW00RT2 #BIT5 must use the DBDEF macro with the EMPTYCHECK parameter specified or the dfdel function with the DFDEL_EMPTYCHECK option specified to obtain accurate results.

Table 1. C functions for detecting errors
Function	Condition
`DF_BLOCKSRELEASED`	Test after the `dfhold` or `dfuhld` function, whether all existing data was flushed from memory and must be refreshed via the `dfred` functions.
`DF_EF`	End of file (any error indicated in SW00RTN requiring remedial action).
`DF_EMPTY`	Test if a subfile is empty. This function is available only after a delete operation that does not use fullfile processing and before the next z/TPFDF macro call. Any application that uses the `DF_EMPTY` function or checks SW00RT2 #BIT5 must use the DBDEF macro with the EMPTYCHECK parameter specified or the `dfdel` function with the DFDEL_EMPTYCHECK option specified to obtain accurate results.
`DF_ER`	Any serious error indicated in SW00RTN.
`DF_ERBAM`	Error occurred with buffered access mode (BAM). Specific error indicated in SW00RT3.
`DF_ERBAMSZ`	Error occurred with buffered access mode (BAM). Buffer was not large enough.
`DF_ERBTR`	B⁺Tree index error.
`DF_ERCNT`	Numbers of errors detected during fullfile processing.
`DF_ERDSP`	Error with the `dfdsp` function.
`DF_ERLST`	Error in list of logical record numbers.
`DF_ERRTN`	Return-optional system error issued by the z/TPFDF product.
`DF_ERX`	Any serious error indicated in SW00RTN except indexing errors.
`DFFSYS_OK`	The `dffsys_write` function processing completed successfully.
`DFFSYS_ERROR_ON_SUBFILE`	A serious error occurred during subfile processing. SW00RTN is set accordingly.
`DFFSYS_FILE_ALREADY_EXISTS`	Unable to process because the specified z/TPF file system file already exists
`DFFSYS_FILESYS_OPEN_ERROR`	Unable to open the destination file in the file system on a `dffsys_write` operation.
`DFFSYS_FILESYS_WRITE_ERROR`	Unable to write to the destination file in the file system on a `dffsys_write` operation.
`DFFSYS_NOTHING_READ`	No LRECs were found that match the selection criteria on a `dffsys_write` request, so no LRECs were written to the file system.
`DFFSYS_WRITE_LIMIT_REACHED`	Write limit is reached, and not all data is written to the file system. If the limit was reached in the middle of an LREC, that LREC is not written out to the z/TPF file system file.
`DFIDX_ENTRY_NOT_FOUND`	The index entry for the specific subfile does not exist in the top-level or intermediate index file. This check is valid only if SW00RTN #BIT3 is set to 1.
`DFIDX_ENTRY_ALREADY_EXISTS`	The index entry for the specific subfile already exists in the top-level or intermediate index file. This check is valid only if SW00RTN #BIT3 is set to 1.
`DFIDX_ALG_OUT_OF_RANGE`	The algorithm argument specified, which is used to calculate the top-level index ordinal, was out of range. This check is valid only if SW00RTN #BIT3 is set to 1.
`DFIDX_SERIOUS_ERROR`	A serious error (for example, a find error) occurred on the top-level or intermediate index file. This check is valid only if SW00RTN #BIT3 is set to 1.
`DFIDX_VAR_ALG_LENGTH_ERROR`	The length of the variable-length algorithm is not valid. The length must adhere to all of the following conditions: Greater than or equal to 1. Less than or equal to 253. Less than or equal to the value that is specified for the MILK parameter in the DBDEF macro This check is valid only if SW00RTN #BIT3 is set to 1.
`DF_LLR`	LLR found.
`DFMBUF_OK`	dfmbuf processing completed successfully
`DFMBUF_LREC_SIZE_NOT_VALID`	On a `dfmbuf_append` function, an invalid LREC size was provided.
`DFMBUF_NO_SPACE`	On a `dfmbuf_append` function, there was not enough space to add the new LREC.
`DFMBUF_TEST`	Test specified values in DF_MBUFRTN.
`DFMULTI_BUF_ADDR_ZERO`	The buffer address specified is zero.
`DFMULTI_BUF_CORRUPT`	The header of the buffer is corrupt.
`DFMULTI_ERROR_ON_SUBFILE`	On a read or add multiple request, a serious error occurred during subfile processing. SW00RTN is set accordingly.
`DFMULTI_INCOMPLETE`	Not all LRECs could be read into the buffer on a `dfred_multi` function. The length of the next LREC to be added to the buffer is returned in 4-byte field SW00NXT.
`DFMULTI_NOTHING_ADDED`	No LRECs were found in the buffer on a `dfadd_multi` function.
`DFMULTI_NOTHING_READ`	No LRECs were found to read into the buffer on a `dfred_multi` function.
`DFMULTI_OK`	Multiple LREC processing completed successfully.
`DFMULTI_UNIQUE_LREC_EXISTS`	An LREC already exists that matches the unique keys specified.
`DF_NR`	Record not found (any error indicated in SW00RTN requiring remedial action).
`DF_OK`	No errors indicated in SW00RTN.
`DFRSF_INVALID_PARAMETER`	An invalid parameter was specified on the `dfrsf_setLocation` function.
`DFRSF_RDS_NOT_DEPLOYED`	A remote data store descriptor is not deployed for the specified remote data store name.
`DFRSF_REMFIL_NOT_DEPLOYED`	A remote file descriptor is not deployed for the file ID of this subfile.
`DFRSF_REMOTE_NOT_ALLOWED`	A remote data store name was specified, but the REMOTEALLOW parameter was not specified as YES in the DBDEF of the file.
`DFRSF_SUBFILE_NOT_ACCESSED`	The subfile was not accessed after the subfile was opened. Ensure that the subfile is accessed before the `dfrsf_setLocation` or `dfrsf_getLocation` function is called. For example, a `dfred` function can be entered with the DFRED_HEADER value specified to access the subfile.
`DFRSF_SUBFILE_OPENED_WITHOUT_HOLD`	The subfile was not opened with hold.
`DFRSF_SYSTEM_NOT_IN_NORM_STATE`	The system is not in NORM state.
`DFRSF_INTERNAL_ERROR`	An unexpected condition was detected during z/TPFDF remote subfile processing. This condition might be caused by database corruption or an internal error.
`DFRSF_AUTHENTICATION_ERROR`	An authentication error occurred when the tpfrdsClient JAM tried to connect to the remote data store.
`DFRSF_AUTHORIZATION_ERROR`	An authorization error occurred when the tpfrdsClient JAM tried to connect to the remote data store.
`DFRSF_DFDL_EXCEPTION`	An DFDL exception occurred when a z/TPFDF subfile that is in a remote data store was being read, created, or updated.
`DFRSF_DOCUMENT_NOT_FOUND`	When a read request was received to read a document from the remote data store, the document could not be found.
`DFRSF_JAM_ERROR`	The tpfrdsClient JAM encountered an error.
`DFRSF_MALLOC_ERROR`	An error occurred when ECB heap storage was being allocated while a remote subfile was being accessed or updated.
`DFRSF_MAX_READER_ECBS_EXCEEDED`	The maximum number of ECBs that can read concurrently from the remote data store was exceeded.
`DFRSF_MQ_ERROR`	An error occurred when a WebSphere MQ API was being issued.
`DFRSF_RDS_CLIENT_UNAVAILABLE`	The tpfrdsClient JAM is not active.
`DFRSF_RDS_TIMEOUT`	A timeout occurred or the remote data store could not be reached by the tpfrdsClient JAM.
`DFRSF_SUBFILE_CORRUPT`	An error occurred when a subfile on the z/TPF system was being accessed.
`DFRSF_TAPE_NOT_SUPPORTED`	Tape functions are not supported for files that can have subfiles stored in a remote data store.
`DF_SERRC`	System error issued by the z/TPFDF product.
`DF_TEST`	Test specified bits in SW00RTN.

The following topics describe the format, parameters, and normal return for these functions. In addition, there is an example of how you can use these functions.