Can IDMS access web services? Does this involve SOAP? How is this done?
search cancel

Can IDMS access web services? Does this involve SOAP? How is this done?

book

Article ID: 49402

calendar_today

Updated On:

Products

IDMS IDMS - Database IDMS - ADS

Issue/Introduction

It is possible to write an IDMS program that accesses web services. This is done by issuing socket calls that are sent over a TCP/IP connection.

 

Environment

Release:
Component: IDMS

Resolution

Solution:

Calling a web service from within IDMS/DC is absolutely achievable, and several IDMS clients have successfully implemented TCP/IP-enabled caller programs to do this. Please note, however, that writing a Web Service program is not a trivial task. This article will walk you through the major steps in writing a Service Invocation program, describe various challenges that can occur, and will show you where you can use the TCP/IP services within IDMS to overcome many of these hurdles.

The first step in your efforts will be to understand the protocol employed by the specific service you intend to access, as well as its specific messaging needs. Web Services typically use SOAP (Simple Object Access Protocol), which is a lightweight protocol for the exchange of information in a decentralized, distributed environment. It is an XML (Extensible Markup Language) based protocol that consists of three parts:

  1. an envelope that defines a framework for describing what is in a message and how to process it;

  2. a set of encoding rules for expressing instances of application-defined data types; and

  3. a convention for representing remote procedure calls and responses.

SOAP-enabled services use HTTP (Hyper Text Transfer Protocol) to package XML requests into packets that the Service can process. You'll send / receive these HTTP packets using the services of the CA-IDMS TCP/IP driver, so we'll limit the focus of this document to the facilities it contains. More information on the HTTP protocol specification can be found on the World Wide Web consortium site, at http://www.w3.org/Protocols/rfc2616/rfc2616.html.

All Web Services are identified by a URL (Uniform Resource Locator). A URL consists (in part) of a Doman (or Host) name as well as a Port number. In order to connect to a Web Service you need to convert the Host name to an IP address. Given a Host name(e.g. www.ca.com), you can determine the IP address of your Service by invoking the GETHOSTBYNAME socket function call. The GetHostByName function is part of the IDMS TCP/IP support. Please reference the IDMS Callable Services Guide, Chapter 4.10.13 GETHOSTBYNAME, for complete documentation on this function.*

Once the IP address has been determined, assuming we know the port number on which our service is listening, the next step is to establish a socket connection to your Service. This is accomplished using the CONNECT socket function within the IDMS TCP/IP driver; for full documentation on this function, see the IDMS Callable Services Guide, Chapter 4.10.4 CONNECT. *

The use of secured connections present an additional level of complexity, but this too can be accomplished. You will need to use AT-TLS (Application Transparent Transport Layer Security) to communicate with a service on a secured socket. AT-TLS is a facility within the IBM TCP/IP stack that enables the use of TLS (or SSL - Secure Socket Layer) without the need to modify your application. IDMS uses it to facilitate secure (inbound) communication for both our ODBC & JDBC drivers; it can also be used for outbound communication. In this situation, you enable it by naming the outgoing IP address and Port to which you'll be connecting. AT-TLS will then establish a secure connection to that address and port when the application (in this case your IDMS CV) attempts to connect to that destination. The use of AT-TLS require the use of the IBM TCP/IP stack, so you would need to have that component available. Details about AT-TLS can be found in the "Z/OS Communications Server IP Configuration Guide", one version of which can be found as indicated below. For more information on invoking AT-TLS you may find the following helpful:

Once your program has established a connection to the Web Service, it will need to send a packet across to it identifying more specifically what it is requesting from the service. Most Web Services use ASCII rather than EBCDIB, so a necessary part of your program would be to translate your data packets from EBCDIC and ASCII (and vice-versa). The module IDMS includes an IDMSIN01 entry point which provides various functions to user programs; the parameters passed on a call to IDMSIN01 determine which function is performed. The STRCONV parameter indicates that IDMSIN01 should convert strings to and from EBCDIC and ASCII. Including on the STRCONV call a parameter of CONVFUN='ATOE' will convert a string from ASCII to EBCDIC; specifying CONVFUN='ETOA' will direct IDMSIN01 to convert a string from EBCDIC to ASCII. Details on this can be found in the IDMS Callable Services Guide, chapter 3; the specific section will depend on the language in which the program is written.

Depending on what function you are requesting from the Web service, other socket function calls may also be required. All of the other available function calls are documented in chapter 4 of the IDMS Callable Services Guide, each one in its own section. Each section shows the complete assembler language syntax, as well as a list of parameters that can be passed when invoking the function in COBOL, PL/I, and ADS. The first of these parameters is the function name as defined in the SOCKET-CALL-INTERFACE record, which can be used in the COBOL TCP/IP calls. These various functions can be specified in a call to IDMSOCKI, which allows you to utilize the TCP/IP API functionality to access the web service. The basic format for the calls to do this is covered in section 4.5 of the IDMS Callable Services Guide.

Additional articles authored by various users who have written programs to invoke Web Services can be found in the "IUA Connections" newsletter, published by the IDMS International User Association. Included in the archives are these articles:

  • SOAP HTTP Headers (September 2008)

  • The COBOL XML parser (March 2009)

  • The COBOL XML generator (September 2009)

  • The F/OS Web Services (March 2011)

Copies of these articles can be found within the Communities pages, at https://communities.ca.com/web/ca-idms-iua-eiua-global-user-community/document-library/-/document_library/view/2232085;jsessionid=4354D08D21E06B14CE2D2B5D87347708.prodlr5?&&goback=%2Egde_3803629_member_63604293#p_20.

An alternative to writing your own programs would be to purchase a product that would assist you in invoking the Web Service directly from IDMS. There are a couple of vendors that provide this (ObjEx, Data Direct), but the one solution that is certified by Broadcom is GT Software's 'Ivory' product. More information on this offering can be found at the links below:

* NOTE: Sample TCP/IP Client and Listener programs can be found in Appendix B of the IDMS Callable Services Guide. The sample programs demonstrate the calls mentioned in this article in various languages: ADS, COBOL, PL/I, and Assembler. These programs can be used as a starting point for your Web Service invocation programs.

Additional Information

More information on this offering can be found at the links below:

Powered by Wolken Software