Did you ever get strange errors after you called an API?

Did you ever get strange errors after you called an API?

Here are the three most common mistakes I see people make that can cause storage corruption. Storage corruption can then cause strange and sometimes intermittent errors to occur.

Mistake: Not passing the feedback parameter for CEE APIs

When the API documentation says a parameter is "omissible", it means you can pass *OMIT as the parameter. It doesn't mean you can completely leave it out. On your RPG prototype, code OPTIONS(*OMIT).

When you pass *OMIT, the compiler actually passes a null pointer.

When the API is called, it checks whether the feedback parameter is a null pointer. If it doesn't find a null pointer, it assumes that you passed the feedback parameter.

Here's where the problem occurs: Even if you don't pass the feedback parameter, there is still SOMETHING at the place where the API looks for the feedback parameter. There is NO GUARANTEE that it is a null pointer. If it is a valid pointer, the API updates the 12 bytes at the location the pointer is pointing to. This can be ANY STORAGE, not just storage in your program. The effects of making this error are unpredictable, and might not cause an exception until much later. They might not cause an exception at all. Instead, your program might continue to operate with incorrect data.

Here's the API documentation that talks about omitting parameters for CEE APIs: https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_74/apis/ile1a5.htm

Mistake: Not initializing the error-code parameter for non-CEE APIs

The first subfield, "Bytes_Available", of the error-code parameter is a 4-byte integer that gives the length of the error-code parameter. Valid values are zero, meaning "no error-code parameter", or a value 8 or greater.

If you don't initialize your data structure in RPG, that subfield has blanks, x'40404040', which means that the integer subfield has the value 1077952576. At some point, the API might clear the error code parameter starting at the second subfield. If you tell the API that the length is 1077952576, it is almost certain to clear some of the storage following your data structure.

Here's the API documentation about the error code parameter: https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_74/apiref/error.htm

Mistake: Not passing a large enough buffer to QRCVDTAQ (Receive Data Queue)

Many people pass a buffer that is only large enough for the specific message they are interested in. They assume that the "length" parameter is used to tell the API how large the buffer is. But actually, the length parameter is used by the API to return how large the message is. The API assumes that the buffer is at least as large as the maximum size of a message for that data queue.

There are two solutions to this:

1. Pass the optional parameter that indicates how large the buffer is.
2. Code your buffer at least as large as the maximum size of the data queue.

Here's the documentation for the QRCVDTAQ API: https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_74/apis/qrcvdtaq.htm