Hello, this is Joe Malinowski from z/OSMF Restfiles and Datasets API Support with IBM. I have been with the company since 2005 and have supported the z/OSMF Restfiles code since it first came out a few years ago. Over these years, I’ve helped clients with various configuration issues as well as identifying the root cause of a few reported bugs here and there. The information below describes the three most common configuration issues we have seen in support. If you know about these ahead of time, it may just save you hours of debugging!
1) Over-customization of your z/OSMF System
Setting your System up so that it works best for you and your environment is a great idea. The biggest problem we see is that many people attempt to do this from the start. When they run into problems, it makes it almost impossible to figure out where things went wrong. Instead, it is recommended that your first attempt at setting up z/OSMF is not customized. Once you have things working, then you can attempt to make the changes that your environment needs.One example of this involves changing the SYS1.PROCLIB(IZUFPROC) member to be named something else. This is a very simple change, however it can cause issues later on when trying to debug a problem with a failed Restfiles request. Since the default IZUFPROC member still exists, you may spend time looking at this instead of the customized member you have created. If you are going to make this change, it is highly recommended that you also update the IZUFPROC with a comment notifying anyone who is using it what the new SYS1.PROCLIB member is called.
2) Securing yourself from Cross-Site Request Forgery Attacks
Let me be clear when I say this: It is ALWAYS recommended to be as secure as possible when setting up any system that enables user’s to access data from a remote location. With that being said, a lot of system administrators will enable checking for Cross-Site Request Forgery during setup, but then they forget to tell their users about this (or their users forget about it). If this is the case, any user that attempts to issue a GET or POST request will be blocked if they are trying to access the system off site. With the right certificate, proper authentication can be done ahead of time in order to avoid any delays. If you suspect your user is not getting authenticated with this certificate, you can set CSRF_SWITCH=OFF temporarily in your IZUPRMxx member to see if the requests go through successfully. Just don’t forget to turn it back ON!
3) Sending too much data at once
Some people rely on the default settings in the IZUPRMxx parmlib member. Others will make necessary changes required by their system administrator. The RESTAPI_FILE ACCT parameter will allow you to specify certain restrictions for the Restfiles and Datasets API code. The most common parameter that people change is the REGION size. In order for the Restfiles code to work, this has to fall inside the range of 65536 – 2096128 kilobytes (KB). The higher the size will allow more data to be successfully sent at once from the host system to the remote system. You should avoid setting this below 65,536 KB.
A second consideration is the size of the dataset being READ. If you are trying to read a large dataset, you may want to consider reading it in chunks with the <X-IBM-Record-Range> header instead. This will allow you to read a subset of records at one time.
Although these three things are not the only things that can go wrong, they are the most popular. By reducing the chance of these configuration issues coming up, this should help lead to a seamless integration of the z/OSMF Restfiles and Datasets API for your users.
References:
https://www.ibm.com/docs/en/zos/2.3.0?topic=v2r3-establish-security-cross-site-zosmf-rest-requests
https://www.ibm.com/docs/en/zos/2.3.0?topic=time-izuprmxx-reference-information#izuhpinputcorescripts
https://www.ibm.com/docs/en/zos/2.3.0?topic=configuration-step-3-prepare-zosmf-server-initialization#PreparingToStartTheServer__izuLogonProcedures
#IBMZ