Mark P Wilson
Published on 29/05/2019 / Updated on 06/06/2019
In my last blog Integrated IBM MQ support in IBM z/OS Connect Enterprise Edition I described the changes that have been made to improve the experience when using IBM MQ in IBM z/OS Connect Enterprise Edition. In this blog I am going to show you how to put this into practice.
I am going to create a simple two-way service that adds two numbers and gives the answer. The application that is doing the calculation is a COBOL program that uses two structures:
AddNumbersInput.cobolcpy
01 INPUTSTRUC. 05 NUMBER1 PIC 9(9). 05 NUMBER2 PIC 9(9).
AddNumbersOutput.cobolcpy
01 OUTPUTSTRUC. 05 RESULT PIC 9(9).
Now we have those files we can create the properties file:
# Generic propertiesprovider=mqname=addNumbersServiceversion=1.0description=A service that adds two numbers # Properties about the queue manager and queuesconnectionFactory=jms/connectionFactory1destination=jms/calcRequestreplyDestination=jms/calcReply # Properties about the input/output structureslanguage=COBOLlanguageStructureCodePage=IBM037requestStructure=AddNumbersInput.cobolcpyresponseStructure=AddNumbersOutput.cobolcpy # Misc properties for the MQ service providerwaitInterval=100operationName=test
As you can see I have split the properties into 4 sections.
- The top part is the generic properties of the service. The important one for us is the provider as this tells the build toolkit to create a MQ type of SAR.
- The next section is the JNDI properties that I explained in my previous blog
- The third section is properties relating to the input and output structures. The languageStructureCodePage controls what code page in which the message is put to the queue.
- The last section contains a few other properties. The waitInterval is how long the MQ service provider will wait ib milliseconds for a message to turn up on the reply queue. As MQ is asynchronous the reply may not be on the reply queue immediately so waiting for a period of time is a good idea.
Please see Creating an IBM MQ service for more information on the MQ service provider properties.
I have decided to run the build toolkit on my Linux workstation but it can as easily be run on Microsoft Windows or in USS. In the z/OS Connect EE output tree there is a file called zconbt.zi. Transfer this to the location/workstation that you want and unzip this file.
To build a SAR from the properties, the following command is issued:
./zconbt/bin/zconbt -p AddNumbers.properties -f AddNumbers.sar
If all the properties are valid the build toolkit will issue:
BAQB0000I: z/OS Connect Enterprise Edition Build Toolkit Version 1.1.BAQB0001I: Creating service archive from configuration file AddNumbers.properties.BAQB1022I: IBM MQ for z/OS plugin for IBM z/OS Connect EE V3.0 build toolkit, code level is 3.0.21.0(20190514-1637).BAQB0002I: Successfully created service archive file AddNumbers.sar.
Otherwise an error message will be issued for each issue found.
Now we have AddNumbers.sar we need to transfer it to the place which z/OS Connect EE knows to look for SARs. This is governed by the value of location attribute of the zosconnect_services tag in server.xml. If this does not exist then the default is ${server.config.dir}/resources/zosconnect/services
I have the zosconnect_services element in my server.xml (shown below). In my test environment I have updateTrigger set so z/OS Connect EE will look for and load new SARs. In a production environment, the MODIFY REFRESH command would be used to load new SAR.
<zosconnect_services location="/var/zosconnect/servers/markw1/resources/zosconnect/services" updateTrigger="polled" pollingRate="5s">
I used sftp to upload the SAR in binary mode into the location above.:
As I have told z/OS Connect EE to look for new SARs it will automatically issue the BAQR7043I message as shown in the console log.
BAQR7043I: z/OS Connect EE service archive addNumbersService installed successfully.
In theory the service is ready to be used but lets use a web browser to display the properties of the service. Load the page https://{ip-address}:{port}/zosConnect/services and you should see a page that is similar to the screen shot below showing services installed in z/OS Connect EE.
To see the properties of our service click the value of serviceURL and you should see a screen that is similar to the screen show below showing all the properties for our service.
As you will be able to spot most of the properties that we had in our property file are now shown. The build toolkit has added some default properties and some to aid problem analyse e.g. creationTime and pluginLevel.
Lets now try and use this service to add the numbers 1 and 2. I am going to use curl to make the REST call. To invoke our service I use the following command:
curl -i -k -X POST https://winmvs41.hursley.ibm.com:9444/zosConnect/services/addNumbersService?action=invoke -H Content-Type:application/json -u "fred:fredpwd" -d '{"testOperation" : { "instruc" : {"number1" : 1, "number2" : 2}}}'
One thing to note is the ‘testOperation’ element, this is the operationName from the properties appended to the word ‘Operation’.
z/OS Connect EE will take that JSON payload and map it to a COBOL data structure (AddNumbersInput.cobolcpy) which is put on a queue that I have an application getting from. This adds the two numbers and puts the answer in another COBOL data structure (AddNumbersOutput.cobolcpy). z/OS Connect EE will then transform this back into JSON and send it back to the client. This is shown in the response below of the curl call.
HTTP/1.1 200 OKX-Powered-By: Servlet/3.1Content-Type: application/jsonContent-Language: en-USContent-Length: 54Set-Cookie: LtpaToken2=1LzmgpH4N4TRLBG6Lrady1swJCOLr5zBxUWueYGoSS80J3GcRagP19z+4fRUEqHn7GjPbB6zTLEW6MP+/rrjSxlY3xJIOgV6crr2TUMa/3dscjJxD1PlDBqfFqITez2Dq/w0XtyYuOPkybfEWJ0XfoTS20qc73ABW63NYzVlzIciUvjR5bNmtazPDVj92YUR8XL9MzzWmKJWcBwgVWMZJQNw7Xn/TD4JwYsXRddbqVw3oyu9oRadA7agrbrl+El6RSI/rCB1beqpb9/3kFpzYzWRt1qqgNOrzxv+RKnYQrFBwn5aNx91tYW3lfEJrQy1pZFiC747k/QsH03A/g21Jw==; Path=/; HttpOnlyDate: Wed, 22 May 2019 11:07:10 GMTExpires: Thu, 01 Dec 1994 16:00:00 GMTCache-Control: no-cache="set-cookie, set-cookie2" {"TESTOperationResponse":{"outputstruc":{"result":3}}}
curl shows you all the HTTP headers but at the bottom you can see the returned JSON and the result is 3 which is correct.
Conclusion
In this blog I have walked through how to create a MQ service in z/OS Connect EE using the support that was added into z/OS Connect EE version 3.0.21.