Getting Started With IBM i And .Net XMLSERVICE Connectivity
March 15, 2016 Richard Schoen
|
In my last article I introduced you to XMLSERVICE for accessing IBM i data and discussed why you might want to consider using the XMLSERVICE .Net wrapper API to connect to and utilize live IBM i data from your .Net applications. In this article, I will cover an overview of XMLSERVICE and the .Net wrapper API I created for .Net developers to use IBM i data without needing to install IBM i access. You will also get a chance to do your first connectivity test to the IBM i using the XMLSERVICE for .Net API. Getting Started For this session I assume you have already set up an XMLSERVICE Apache HTTP instance running on TCP/IP port 30000. You have also configured the web server instance to work with XMLSERVICE and have started the web instance. I also assume you have installed Visual Studio Community 2015 or an equivalent on your PC and have unzipped the XmlServiceiApi project directory from the zip file to your PC. Opening the XmlServiceiApi Visual Studio Solution A solution in Visual Studio is a mechanism for structuring or organizing projects. A solution can encompass one or more projects. For the XMLSERVICE .Net API, I have created a solution that contains two projects. One is for the XMLSERVICE API wrapper and one for the tester project. Keeping them together makes it more efficient to edit and test our code. Start up Visual Studio and select File/Open Project. Find the solution file XmlServiceiApi.sln and select the Open button to open the solution and associated projects. If you extracted the project to C:XmlServiceiApi, then you can instead type the entire solution name file path if you like and then click Open. Example Full path to .Net solution: C:XmlServiceiApiXmlServiceiApi.sln After the Visual Studio solution opens you will notice within the XmlServiceiApi solution there are two actual projects: XmlServiceiApi and XmlServiceiApiTester. XmlServiceiApi is the project that contains the XMLSERVICE IBM i data access API functionality. This project type is called a class library because the XMLSERVICE call functionality will get compiled into a DLL file (which is similar to an IBM i service program) for re-usability in all of your .Net applications. The XmlServiceiApi.dll file is the only file that you have to reference or include in your .Net projects for IBM i data access when you using the XMLSERVICE API. You will also distribute a copy of XmlServiceiApi.dll with your .Net applications. By default the XmlServiceiApi project is set to compile using the .Net 2.0 framework so the DLL can work from .Net 2.0 all the way through the current version of .Net. You can change the .Net compile options to any version of .Net that you decide is prudent but .Net 2.0 should work for starters. Also the API code is written in VB.Net but the XmlServiceiApi DLL can be used with any .Net language, including VB.Net and C#, to provide IBM i data access. It would be fun to see someone contribute some C# code samples to the project at some point or convert it to C# using one of the available online converters, but it will work just fine as is with any .Net language. XMLServiceiApiTester is the tester project that can be used and modified to test the IBM i data access functionality of XmlServiceiApi. The tester application project has a reference to the XmlServiceiApi project in Visual Studio, not the actual compiled version of XmlServiceiApi.dll. The reason for this is that you can run the tester program and step through its code interactively and actually debug and see XmlServiceiApi doing its work. Visual studio debugging is amazingly productive for interactive coding, compiling, and debugging. Normally when you create a project that uses XmlServiceiApi you will simply include a copy of the XmlServiceApi.dll and add a reference to the DLL file in your project and you can start using the IBM i XMLSERVICE functionality right away.
Configuring the API Tester Program to Run In the Visual Studio Solution Explorer, right-click on the XmlServiceiApiTester project and select Properties. Then click on the Settings tab. You will notice the test project has four settings that you can set for testing.
After configuring the application settings, you are ready to run the XmlServiceApiTester for the first time.
Running The Tester Application For The First Time To ensure the XmlServiceApiTester program starts when you run the solution, right-click the XmlServiceiApiTester project in Solution Explorer and select the Set as StartUp Project option on the menu. This will make certain that when we run the solution the XmlServiceApiTester project starts instead of trying to start the API itself, which is a class library not an application. Otherwise you may see the following message when you start your project if XmlServiceiApi is the default: A project with an Output Type of Class Library cannot be started directly. Once the startup project is configured, from the Visual Studio development environment, you can run the test application by pressing the Start/Play button, F5 key or select Debug/Start Debugging from the menu. When the main tester application window appears, simply click the Run CL Command button to send a test message to the QSYSOPR user on your IBM i. If the command runs successfully, you will see a message starting with: Command Was Successful in the XML Response Message field. This means your connectivity was successful with the XMLSERVICE for .Net API and XMLSERVICE is working as expected on your IBM i system. You can also check the QSYSOPR messages for this message from a 5250 screen using the following command: DSPMSG MSGQ(QSYSOPR).
Troubleshooting Errors Or Connectivity Issues If you see an XML formatted message in the XML Response Message field starting with “Command Failed,” something went wrong when trying to run the CL command. It’s possible that you specified the wrong IBM i IP address, host name, port or user ID and password in the .Net test application settings. Double-check them. You can also check your IBM i to make sure the Apache server instance is running on port 30000. A quick way to check TCP/IP connections from the IBM i command line is to run the following command: NETSTAT OPTION(*CNN).
Once connections are displayed, page down until you see an entry with a Local Port value of: 30000. If there is no entry with 30000, then your Apache web instance may not be running. You can also attempt to hit the address from a web browser. Example: http://1.1.1.1:30000 and see if the default HTML page displays for the Apache instance. If you see the default page or a 403 or 404 error, the web server instance is running but may not have a home HTML page defined. A home page is not needed, but we now know the web server is working and the problem may be somewhere else. If you run into any odd issues you can send me an email and I will attempt to give you some suggestions for getting things working. Onward If all of the above is working, your homework is done until our next article when we will do a deeper dive into the XMLSERVICE for .Net functionality. Of course, as any good student would, you may have already jumped ahead and started playing with the other functions. Richard Schoen is Director of Document Management for HelpSystems where he spends his time helping customers learn about automating document based processes and implementing automated business processes and system integrations using all of the HelpSystems products. You can contact Richard via email with questions, comments or article ideas. You can also find Richard on Twitter (@richardschoen) or LinkedIn. RELATED STORY IBM i and .Net Connectivity With XMLSERVICE
|
