IBM i and Web Services – FAQ and Howtos (EN)

C’è una versione italiana di questo post qui!

Introduction

Here’s another collection of FAQs on Web Service and IBM i (formerly AS400)… these are questions that are asked by the Italian IBM i Community or taken directly from industry forums. It does not want to be a complete guide for those who enter the world of Web Service for the first time in the IBM i environment to publish and/or consume services, for this we have special courses that we do in the classroom (if we reach a sufficient number) or directly in this case, see the appropriate area of Faq400.com ( https://www.faq400.com/corsi-e-workshop/ ).

iWS-FAQ001: How deploy Web Services by a script instead of IWS Gui

The IWS GUI makes it very easy to publish programs and service programs such as Web Service, but it’s a “long” and repetitive process … if we have to publish a few web services is great but if the number becomes important or we need to automate the publication for the deployment of a sooftware or other, better resort to scripts

Scripts for Web Services are in this IFS folder: /QIBM/ProdData/OS/WebServices/V1/server/bin

To publish a new webservice having already our program or service program RPG/Cobol or, in general, ILE we can do:

STRQSH function
cd /QIBM/ProdData/OS/WebServices/V1/server/bin
installWebService.sh -server-name' -programObject 'program-object'
[-service 'service-name'] [-pcml 'pcml-file'] [-userid 'userid']
[-libraryList 'library-list'] [-libraryListPosition '*FIRST|*LAST']
[-disableNillableWSDLElements] [-disableOptionalWSDLElements]
[-addUnderscoreToWSDLElementNames] [-libraryListPosition '*FIRST|*LAST'] [-printErrorDetails] [-help]  

 Where:
server is the name of the Web services server in which the service will be installed.
programObject is the integrated file system path to the ILE program or
service program. For example, '/QSYS. LIB/MYLIB. LIB/MYPGM[SRVPGM or PGM].'
service is the name of Web service to be installed. This parameter is
Optional. If not specified, the program object name will be used.
pcml is a path to the PCML file. This parameter is optional. If not
specified, the program object must contain the PCML data.
userid is the user profile the Web service will be modified to run under. This parameter is optional. If not specified, the Web service will run
under the Web services server user profile. Note: The Web service server's
user profile needs to have "USE authority to the user profile specified on
this parameter. A value of "SERVER" will ensure the Web service runs under the
same user profile as the Web services server.
list is a list of libraries, which will be added to the library
list prior to invoking the Web service. Each library in the list must
be delimited by a colon. This parameter is optional.
libraryListPosition is the position in the user portion of the job
library list where the list of libraries specified in -libraryList will be
"I'm not A value of "FIRST inserts the libraries at the beginning of
the user portion of the library list. A value of "LAST inserts the libraries
at the end of the user portion of the library list. This parameter is
Optional. If not specified the default value of "LAST is used.
disableNillableWSDLElements will define elements in generated WSDL as
not nillable. If not specified, elements are defined as nillable.
This parameter is ignored for version 1.3 of Web services engine.
disableOptionalWSDLElements will define elements in generated WSDL as
not optional. If not specified, elements are defined as optional.
This parameter is ignored for version 1.3 of Web services engine.
addUnderscoreToWSDLElementNames will generate WSDL element names
that start with the underscore (_) character, as was always done in
version 1.3 of the Web services engine. If not specified, element names
in WSDL will not start with the underscore character.
This parameter is ignored for version 1.3 of Web services engine.
printErrorDetails will show additional error information, such as stack
traces and error codes, if the command fails. This parameter is optional.
help displays the command syntax. This parameter is optional. 

iWS-FAQ-002: Backup and restore Web Service from different IBM i partitions

When we need to migrate web services to a new IBM i partition (such as switching machines or switching from Development to Production or between two machines in Clustering) we need to know A little more about IWS:

The services we see published by the page http://myibmi:2001/HTTPAdmin actually reside in the IFS in folders generally /www/servername … For example, /www/wservice. There is also a system table that contains one member for each existing application server

Save the webservice configuration to a file:

-- QSH and script directory
STRQSH function
cd /QIBM/ProdData/OS/WebServices/V1/server/bin 
 
-- Save web service server
saveWebServicesServer.sh -server MyServer -saveFile /qsys.lib/mylib.lib/mysavf.file 
--- Save some webservices
saveWebServices.sh -server MyServer -serviceList WS2:WS1 -saveFile /qsys.lib/mylib.lib/mysavf.file 

--- Your save file to another IBM i partition

-- Restore your web service server
restoreWebServicesServer.sh -fromServerDirectory server-directory -saveFile save-file  [ -printErrorDetails ] [ -help ] 

--- Restore some web services
restoreWebServices.sh -server MyServer2 -serviceList WS2:WS1 -fromServerDirectory /www/MyServer -saveFile /qsys.lib/mylib.lib/mysavf.file 

Pay attention: if you move your web service to a new system I want to advise you to spend some time to stop and redeploy your web service for every UserProfile for your web service to authorize the user to web service server.

Here are some in-depth links on the topic:

• IBM Support: https://www-01.ibm.com/support/docview.wss?uid=isg3T1026868
• IBM Support: https://www-01.ibm.com/support/docview.wss?uid=nas8N1022190
• ItJungle: https://www.itjungle.com/2018/02/19/guru-moving-web-service-another-web-server/

iWS-FAQ-003: Web Service Property

This script extracts the properties of a Web Service to an XML (PCML) format file … may be useful for installing new web services on a second partition starting with the properties:

 getConfigurationFile.sh -wSERVICE server -locationDirectory /tmp -serviceList ConvertTemp 

installwebservice.sh -WSTEST server -propertiesFile /tmp/ConvertTemp.properties 

See DeveloperWorks: https://www.ibm.com/developerworks/community/wikis/home?lang=en#!/wiki/dW%20IBM%20Integrated%20Web%20Services%20for%20i/page/Script%20to%20generate%20property%20file%20for%20a%20service guide

iWS-FAQ-004: REST Web service directly from SQL Statements?

From the last two IBM i OS version 7.3 and 7.4 you can deploy a web service directly through a SQL statement.

Take a look at this post by Tim Rowe, IBM:  IBM SystemMag : Getting started with REST and SQL

iWS-FAQ-005: HTTPS and SSL on IBM i – How to create your *SYSTEM certificate and store it in your Digital Certificate Manager DCM

If you have an user with *SECOFR authority follow those 5 simple steps:

https://www.ibm.com/support/pages/how-create-system-store-dcm

iWS-FAQ-006: HTTPGETCLOB and JSON_TABLE to get Latitude and Longitude

More and more often we need to get more data from our customers and destination addresses, a normalized address, latitude, longitude and so on.

With a simple SQL statement in an RPG-SQL Embedded or directly from SQL Script we can get that information and store them in our tables.

Let’s see an example with Google Geocoding Services (you need to open an account in the Google Cloud Platform, activate your APIs and get a uniqe KEY for your web service call … and change the key in the example XXX_YOUR_KEY_HERE):

Select * from
 json_table(
 systools.httpgetclob('https://maps.googleapis.com/maps/api/geocode/json?address=Piazza+Duomo+1,20121+MIlano&components=country:IT&key=XXX_YOUR_KEY_HERE','')
,'$'
COLUMNS( 
formatted_address VARCHAR(200) PATH '$.results.formatted_address',
lat decimal(10, 7) PATH '$.results.geometry.location.lat',
lng decimal(10, 7) PATH '$.results.geometry.location.lng'


) ) as x;

Here’s the result of the SQL statement

For US and Canada addresses, you can call a US CENSUS Bureau API service too … it’s free!

Select * from
 json_table(
 systools.httpgetclob('https://geocoding.geo.census.gov/geocoder/locations/address?street=265+Peachtree+St+NE&city=Atlanta&state=GA&zip=30303&benchmark=Public_AR_Current&format=json','')
,'$'
COLUMNS( 
formatted_address VARCHAR(200) PATH '$.result.addressMatches.matchedAddress',
lat decimal(10, 7) PATH '$.result.addressMatches.coordinates.x',
lng decimal(10, 7) PATH '$.result.addressMatches.coordinates.y'
) ) as x;

Here the CENSUR result

If you prefer RPG to consume this kind of service take a look at this Bradley Stone post on FieldExit

--- Roberto De Pedrini Faq400.com