Service definitions, and related mapping files (DataViews, XSDs) are created, in a semi-automatic to automatic process (also known as Service Discovery), from meta-data describing the characteristics of resources to be exposed as a Service through Portus, for example from an Adabas FDT, SQL Table description, Natural sources or even other Web Services.
Administration Perspective
The Service creation process can be started by selecting the appropriate driver, right-clicking and selecting either Discover Service(s) or Add Service:
Discover Service(s) will start the discovery wizard and request the specific parameters required for the selected driver type.
Add Service will ask you to name the service and you can then manually set the various parameters as per your particular system.
Legacy Perspective
The Service creation process can either be started from the server's context menu by selecting 'Create new Services':
or by clicking the 'Create new Services' action button in the title area of the Configuration View:
The next step is to select the driver to be used as the source.
There will be a list of defined drivers available, plus a number of special entries, for example <SYSOBJH>, which can be used to create Service(s) from a SYSOBJH unload file containing DDMs, or <3GL> to create a DataView and XSD from a C- or COBOL program or copybook.
When a driver is chosen select Use Driver to display the Service creation (discovery) dialog.
It may be required to provide login credentials, for example when accessing a SQL database system, this can be done from the server's context menu as well:
Specify the credentials - User ID and Password - in the SOAP Security section, click Set
Status and error information can be retrieved later on from the Portus Action Log
Specify the Database Id (range 1 - 255 on OpenSystems, 1 - 65535 on Mainframe platforms), plus 'File range from' and 'to' file numbers (1 - 5000) to limit the discovery to the selected range. Click the 'Discover' button:
Note:
Discovering the full range of possible file numbers (1 - 5000) may
take substantial time and adversely affect performance of both the
Portus server as well as the Adabas target database. Break the discovery
process down to smaller range(s) of files.
Select the file(s) to be turned into Services, click the 'Generate >' button:
Optionally, the Service name can be modified.
The Status pane reports on the discovery process:
The requested Services and Service definition files (DataView(s) and XSD(s)) have been added to your server configuration or, if not, a suitable error message will indicate the cause of failure.
Choose Exit to finish or Discover to generate more web services
Sometimes it is required to create a web service using the Discovery Wizard, and then assign a different DataView to this service. For example, an Adabas web service discovered with "short names" in the DataView, and a pre-created DataView with "long names" available.
Assumptions:
The pre-created (Business)DataView has been imported into the local workspace, and is available in the Navigator View.
Notes:
OR the pre-created (Business)DataView is available on the server already
The web service you wish to modify has already been created.
If the above assumptions are OK, follow these steps:
Drag the XRD and XSD (if available) files from the Navigator View.
In either perspective, drop the files onto the service you wish to modify
OR
In the Portus Perspective a new (Business)DataView can be assigned by dragging it from the respective Views section and drop it onto the service.
Right-click the serverice and select the Refresh function
The WSDL should now reflect the DataView.
Select a defined driver pointing to the SQL database system of your choice from the list. This step-by-step guide will use MySQL to demonstrate the process.
For this example the 'world database' demo has been loaded as per the guide published at the MySQL Community website, and a ODBC Data Source been set up as 'WorldDS', pointing to the 'world' database.
Click the 'Use Driver' button to start the process.
Specify the ODBC Dsn to be browsed. Optionally enter a 'Pattern' limiting the operation, for example 'c%' will return a list of tables starting with an lowercase 'c'. Another option is to specify 'Max.entries to list' to further limit the number of tables to be listed. If appropriate for your database configuration enter a UserId and Password. Click the 'Discover' button:
zOS and DB2
In the ODBC Dsn field above - enter the Location name returned from the DB2 command Display DDF
- in the example below the location name is S1D831
COMMAND INPUT ===> /-D831 DIS DDF
RESPONSE=POC1 DSNL080I -D831 DSNLTDDF DISPLAY DDF REPORT FOLLOWS: DSNL081I
STATUS=STARTD DSNL082I LOCATION LUNAME GENERICLU DSNL083I S1D831
DEIBMIPA.IPAA77D8 -NONE ....... Also ensure that the member CLIINI in the JCL dataset has been modified as necessary. Refer to your DBA on this.
Select the table(s) to be turned into Services. If appropriate the Service name(s) can be modified by selecting the 'Options for generated Service name' tick box and modifying the entries. Finally click the 'Generate' button:
The Status pane indicates what has been generated.
The requested Services and Service definition files (DataView(s) and XSD(s)) have been added to your server configuration
The Wizard is still active and ready for further discovery, click 'Discover' to start the process again, or 'Exit' to dismiss the wizard.
Details on how to create/modify/delete a stored procedure driver can be found here.
Select the stored procedure driver from the list This step-by-step guide will use MS SQL Server database AdventureWorks to demonstrate the discovery process.
Click the 'Use Driver'.
Specify the ODBC Dsn to be browsed. Optionally enter a 'Pattern' limiting the operation, for example 'uspGet%' will return a list of stored procedures starting with 'uspGet'. Optionally specify 'Max. entries to list' to further limit the number of stored procedures to be listed. Click the 'Discover' button.
Note that the generated web service name can also be changed from the default of prefixing with 'storedProcDriver_'
Select the stored procedure(s) to be turned into Services, click the 'Generate' button:
The Status pane will indicate what has been generated.
The requested Services and Service definition files (DataView(s) and XSD(s)) have been added to your server configuration
The Wizard is still active and ready for further discovery, click 'Discover' to start the process again, or 'Exit' to dismiss the wizard.
Start Discovery by right-clicking the Services element on the server you want the DataView(s) to be created
Select <SYSOBJH> from the 'Select the Source' list and then select the ' Use Driver' button.
A step-by-step guide on how to create a SYSOBJH extract file can be found here.
Click the 'Generate' button to start the process
Select the SYSOBJH file to be used as the input to the creation process, specify if XSD(s) are to be created for the generated Service(s) as well, in addition to the DataView(s).
A number of options can be specified here
defaults to be used when generating Service(s) and DataView(s) based on Adabas files
Database Id used when the DDM is defined with a DbId of 0 (zero)
Default number of occurrences for MU(ltiple value) fields and PE(riodic) groups
Default size of large object (LOB) fields
if you wish dashes ('-') in file and element names to be translated to underscores ('_'). This may be desirable where the target programming language used to access Portus Resources do not accept dashes in field names, an example being PHP.
When PDAs include redefinitions you will need to choose the layout that suits you for the DataView to be generated. If you are unsure at the moment, leave the "remove redefinitions" box unchecked, in which case ALL redefinitions will be included in the generated DataView, with a generated fgroup name of "*redefinition_of_<PDA_group_name>". Before the DataView is uploaded to the server, remove all definitions/redefinitions not required. Multiple DataViews (and thus resources) are required when requiring different layouts/set of parameters for the same subprogram.
"Flatten structures" when the PDA includes nested groups but you want all fields to be generated at the "top level" without any group/field structure.
You may need to translate special characters, like the # (hash) sign if they are used as part of field name(s), because they are not valid in a SOAP context.
Click the Discover button
Select the DDM(s) to be turned into Services, click the 'Generate >' button:
For each DDM selected, which contains MU and or PE fields, a dialog will request you to specify the maximum number of occurrences expected.
Important:
The "MaxOcc" accepted by this dialog is 32767, depending on the
ADABAS version the actual limit accepted by the database system may be lower
(191).
The status pane indicates what has been generated, you can now start the process again or exit the wizard.
In case of a Natural Parameter Data Area (PDA), the type will be shown as "PDA"
The requested Services and Service definition files (DataView(s) and XSD(s)) have been added to your server configuration
The Wizard is still active and ready for further discovery, click 'Discover' to start the process again, or 'Exit' to dismiss the wizard.
Select a defined driver of type 'Natural' from the list
Click the 'Use Driver' button
Specify the name of the Library to be scanned, select if it is a Natural "User" or a "System" library.
Alternatively, if the library name is unknown, specify a generic library name, or a from-to range and click the button. For example, the above input
will result in this additional selection dialog to pop up
Select a library with a double-click, or select a library name and click , or stop the wizard by clicking the button.
Select the name(s) of the object(s) to be turned into Services, click the button. Again, this can be a specific object name, a generic object name, or a range of objects. When a specific object name is entered in the Object "from" field, but the "to" Object name field is left empty, this will result in all objects starting from the specified name being listed
You may return to Library selection mode by clicking the button.
A list of objects matching the selection criteria is displayed
Either select all, or only the one(s) you are specifically interested in, click the button.
The Status pane will report on the progress of each item chosen.
The requested Services and Service definition files (DataView(s) and XSD(s)) have been added to your server configuration
The Wizard is still active and ready for further discovery, click 'Select...' to start the process again, or 'Exit' to dismiss the wizard.
Under Services select the Web Services Driver previously added. Right-click and select Discover Service(s).
Specify the Web Service URI and click the 'Discover' button:
The Status section will display the progress of each stage of the web service discovery and the Service discovery section will display the following information retrieved from the service description:
Use Select all to choose all operations or select on an individual basis. When chosen click the button.
The Status section will be updated with the progress of the generation process, listing the operations selected and the results for each one. For clarity we have chosen the TopGoalScorers operation.
The Wizard is still active and ready for further discovery, click to start the process again, or to dismiss the wizard.
The generated web service(s) will be listed under WS Driver.