The challenge was part of an Open Mainframe Project, where I was required to upload files from a GitHub repository to the mainframe USS environment. The line of code in the bash script that I was trying to run was something like this:
zowe zos-files upload dir-to-uss <GitHub_Directory_Path> <USS_Mainframe_Directory_Path> --recursive --binary-files “filename.jar”
There were about three folder/subfolders and a few files within them that were needed to be uploaded. One of the them was a jar file. The other files were COBOL source code files and shell script files. The folders and subfolders were getting uploaded to USS environment thanks to the ‘--recursive’ option, and also the jar file but not the COBOL source code or the shell script files. I was getting the following error in GitHub Actions Run.
‘message: Illegal character sequence detected by iconv()’
Changing CRLF to LF
The COBOL source code and other script files that I was trying to transfer are essentially text files. These were pushed from my local repository (Windows PC) into GitHub repository. Upon research I found that, text files in Windows are encoded with CRLF (Carriage Return Line Feed) format. Whereas text files in USS environment are encoded with LF (Line Feed) format. So, I thought if I could change the files in my local repository to LF, I could probably upload them to mainframe without getting the error. I changed text file encoding to LF in VS Code. I then pushed the changes to my GitHub repository. System warns though before pushing, something like ‘If you do that again, I will delete the file’. I thought, allowing just one time is fine for me! When I ran the shell script in GitHub, it was unsuccessful.
dos2unix
I used dos2unix, which essentially converts CRLF to LF encoding. I installed dos2unix in GitHub Actions workflow and also coded in script file before uploading the file. This appeared not to have any impact. I still got the same error.
Tagging the text file
Another idea that came to my mind was, the upload function was actually transferring all the files to USS mainframe environment even those that the system is not able to resolve the file type, in raw format. So, I thought tagging them in USS environment as text files would probably work. I did try to use ‘chtag -t -c’ in ssh but that did not work. It would probably work if tagging is done in the shell script itself before the file transfer. I did not try that though.
The Solution
By this time, I started realizing that the issue was about ASCII and EBCDIC. The text files such as COBOL source codes and shell scripts that were stored in my PC as well as in GitHub repository were in ASCII encoding format. Whereas mainframe only recognizes, IBM’s EBCDIC encoding format. The shell code was able to neatly upload the jar file since the system was told it has to be uploaded as a binary file (--binary) while there were no instructions on how the system should treat the text files while uploading from GitHub repository to the mainframe.
Upon research I found that ’IBM-1047’ is what I needed to tell to the system to convert the text file encoding from ASCII to EBCDIC so that the mainframe USS environment recognizes it as a text file and stores that way, in EBCDIC format though. So, I added the “IBM-1047” option for encoding to each one of the COBOL source files and shell scripts and could finally upload all the files from GitHub repository to the mainframe USS environment. It is interesting to know that ‘iconv’ shown in the error is essentially the built-in IBM z/OS utility to translate ASCII or UTF-8 encoding to IBM’S EBCDIC.