Create Web Services

Create Web Services. 1

Type. 1

URL. 1

@Swagger 1

Choosing Max Value. 1

Table 2. 1

Determining the Join Relationship. 1

EXIST-Related Fields. 1

Template. 1

Errors. 1

When menu item Web Service is clicked, the New Web Service form appears, making it easy for you to create a web service provider program: -

Click here to see a 6 minute video about creating web services. While this video doesn’t show recent development, it is still worth seeing to give you a quick overview of the process.

This help page describes how to use the New Web Service form.

Type

Web services may communicate with WSDL or JSON. WSDL (Web Service Description Language) is the XML-based standard used by SOAP (Simple Object Access Protocol) messages. JSON (JavaScript Object Notation) is a lightweight data-interchange format used for REST (Representational State Transfer) messages. JSON is more efficient but sometimes requires more programming effort to ensure that both ends of a service understand the message rules. Whichever option you choose will remain your default until you change it. WSDL or JSON: which to choose? This is a good place to start: Understanding SOAP and REST Basics And Differences

If Type = WSDL then the default names for Program, Commarea, Container, and Template will start with “WS”. If Type = JSON “JS” will be used instead, as shown above. You will be able to change the names of any of these objects, but we recommend that you keep to this naming convention.

URL

This section describes how to access the web service: you will be able to create SOAPUI tests by forming a URL from the values given here together with the program name: for example, you’ll test program JSPG1 with URL

http://localhost:9003/cics/services/JSPG1

NB: this example is with MANASYS Jazz configured to work with Micro Focus. With Micro Focus the basePath will probably be the same for WSDL and JSON. If you have configured MANASYS to work with z/OS then the basePath is probably the pipeline name for JSON or WSDL services, e.g. /JSONPIPE or /WSDLPIPE (or whatever you’ve called them), and the value will change as you toggle between WSDL and JSON.

For a WSDL service @Swagger does not appear, and the port number and basePath may change. Apart from port number and basePath the values for WSDL and JSON will be the same. We assume that your testing environment will be the same except for these two fields. For example, in my case I’m testing JSON services at URL’s such as that above, whereas I’ll test the WSDL equivalent at

http://localhost:5482/cics/services/WSPG1

As you create your services Jazz will create entries in the Jazz Copy Code folder with type .jzw that can be used with INVOKE. ?; For example, writing this into a Jazz program and clicking [Check] invokes the web service discovery dialog: -

Click [Get Service] and the services at this URL are displayed: -

Click the one that is wanted, and INVOKE ?; is replaced with (for example) INVOKE MyJSv-JSPG1(IJSPG1.*) REPLY(OJSPG1.*);

@Swagger

To prepare a web service for execution, a process following the COBOL compile creates a “Binding File”, which converts the COBOL-format message definition to/from the format that will actually be transmitted. For a WSDL service an XML definition of the service is produced conforming to the SOAP standard that includes the URL where the service is to be found, and descriptions of the input and output record. JSON services go through a similar process but the process produces separate input and output definitions, without the URL, so to facilitate testing with ReadyAPI, MANASYS creates an object describing the service in a format that is compliant with the Swagger standard. The main thing to understand for now is that if you click @Swagger, Notepad will open a template, @Swagger.jzt, that you can view (and edit). When you generate your web service program this template will be used to create a .json object such as JSPG1.json. The values that you give here will be used in creating JSPG1.json. Click here for a more detailed understanding of what these parameters mean.

Program Name

The program name follows the usual rules for program names, with maximum length 7. If it is already in use, check [ ] Replace to overwrite it, or else use another program name.

Service

A service name is required. Defaults are MyWSv for WSDL services, and MyJSv for JSON. This name will probably be the same for all web service programs within a project, for example all my JSON testing was done with “MyJSv”. Maximum length: 5 characters.

Container

The container name, which defaults to DFHWS-DATA (and must have this value with Micro Focus) is a name required by COBOL web services that appears in various EXEC CICS statements generated by MANASYS into the COBOL. I haven’t found any reason for ever changing this from the default value.

When a web service provider program is created a copy book named Service-program.jzc, e.g. MyJSv-JSPG1.jzc for program JSPG1, is created to describe the container. This contains at least three DEFINE statements, and in particular contains definitions of the input and output message formats. As with the program, if this already exists then you must check Replace to over-write and replace it, or check Reuse to use the existing definition. You will normally replace the definition as this is usually the easiest way to ensure that the message formats are correct for the program, but if you have edited the message formats as part of your previous development process you may prefer not to replace them but to make whatever edits are necessary for your new logic.

You can edit the container description at any time by right-clicking the PROGRAM statement’s WEBSERVICE keyword.

Use Database

Check this if any of the tables named later are from a SQL database. The name, “sample”, comes from the SQL tab of Configure.

Table 1

Optional. If present, names the first file read. The file must have a type such as VSAM or SQL that allows direct access. As soon as a name is entered some more fields appear: -

Check Update if this file is to be updated. When Update is checked Add and Delete checkboxes appear: -

A standard update program includes functions Update, Add, and Delete. Uncheck Add if you don’t want an Add function. Uncheck Del if you don’t want a delete function.

If Table2 is defined then Max is set to 1, and the Max textbox disabled.

Select the data that you want returned in the output message: -

Keys: returns the record’s key fields only

All fields: returns all fields defined in the record

Select: causes a selection dialog to be initiated, and you can choose which fields are returned. You must include key fields

Choosing Max Value

A single-table service might return several records because of a DKEY path. For example, Employee is defined with primary key EMPLOYEE.EMPNO, but also a secondary (DKEY) on EMPLOYEE.WORKDEPT:-

DEFINE EMPLOYEE SQL DATA(

EMPNO CHAR(6) PIC '999999' REQUIRED KEY,

FIRSTNME VARCHAR(12) REQUIRED,

MIDINIT CHAR (1),

LASTNAME VARCHAR(15) REQUIRED,

WORKDEPT CHAR(3) CAPS DKEY 'XEMP2' EXISTS DEPARTMENT.DEPTNO,

…

DEPTMGR BOOLEAN);

MANASYS therefore generates a program that will look up (Enquiry) EMPLOYEE following rule: -

· If the enquiry’s input message has a value for EMPLOYEE.EMPNO the program will use this value. Thus EMPLOYEE.EMPNO = 60 a record is returned, with EMPLOYEE.EMPNO = 61 no record is found and an empty record is returned. For lookup by primary key the program always returns 1 record, either a real one or an empty one.

· If there is no EMPLOYEE.EMPNO value in the input message then the program attempts to look up EMPLOYEE using EMPLOYEE.WORKDEPT. Again, if no records are found a single empty record is returned, but depending on the value of EMPLOYEE.WORKDEPT there might be several records returned. With EMPLOYEE.WORKDEPT = 'D11' and my test data up to 16 records can be returned.

You can set Max > 1 to have Jazz generate a program that will return a number of records at once. What Max value should you choose?

Whatever value you choose, Jazz will generate code that allows the client record to request more, in effect provide an equivalent of the paging of a classical CICS program. If Max is too small then every time you want to go forward or backward through the list of records your client (requester) program will have to send a message to the web service asking it to read the next record(s). This is much slower than if the client program already has the records and can page forward or back with local data. On the other hand, if Max is too large then messages will be larger than necessary, possibly slowing network performance.

Max should probably be a value that will usually be sufficient: the overheads of returning larger-than-necessary messages are not easily measurable, while the time for each request/response may be a second or more, so it provides a better user experience if you choose a larger Max value. Client (requester) programs should be written to test whether more records than Max exist and provide dialog options to retrieve them when necessary. This is automatically built into the interface programs that MANASYS creates (see Creating a Client Interface for a MANASYS Jazz Web Service)

For a record hierarchy, for example CustF/Orders, while you can only return one top-level (CustF) record at a time, you can return a number of orders with each customer. The same trade-offs apply when you decide how many orders to return with a hierarchical set, such as Customer/Orders.

Table 2

This functions like Table1, defining a second file that is also read and may be updated if the Update checkbox is checked. The two files (or tables) form a Parent/Child hierarchy, like customers and their orders (Custf/Orders), or work departments and their employees (Department/Employee). MANASYS can usually determine the relationship between Table 1 and Table 2 from their definitions.

There is a new data selection option, Xcpt Join.

Xcpt Join returns all fields except the joining field: since the message will be returning the parent record (Custf in this example), there is no point in repeating the Customer ID with each of the returned Orders records.

Determining the Join Relationship

If there is a second file then if possible MANASYS will determine the join relationship from EXISTS or LIKE properties in the child record definitions. Thus if Table1 is Department, and table 2 is Employee, Employee is the child record, and the relationship can be inferred from

WORKDEPT CHAR(3) CAPS DKEY 'XEMP2' EXISTS DEPARTMENT.DEPTNO,

Here MANASYS will generate

PROCESS Employee WHERE(EMPLOYEE.WORKDEPT = DEPARTMENT.DEPTNO);

This will return from 0 to 16 (with my test data) records, depending on the value of DEPARTMENT.DEPTNO.

The referenced field (DEPARTMENT.DEPTNO) must be the primary key of its table.

EXIST-Related Fields

EMPLOYEE in my test system is defined like this: -

COPY Department;

DEFINE EMPLOYEE SQL DATA(

EMPNO CHAR(6) PIC '999999' REQUIRED KEY,

…

WORKDEPT CHAR(3) CAPS DKEY 'XEMP2' EXISTS DEPARTMENT.DEPTNO,

…

When a web service is generated from EMPLOYEE, as the generation logic creates the web service message formats it recognizes the EXISTS property, and displays a dialog allowing you to select fields from the Department record as well: -

Here we’ve selected DEPTNAME, causing this field definition: -

DEPTNAME LIKE DEPARTMENT.DEPTNAME ASSIGN DEPARTMENT.DEPTNAME FKEY EMPLOYEE.WORKDEPT,

to be added into the EMPLOYEE group in the Web Service Output Message: -

DEFINE OJSPG2E SERVICE OUTPUT DATA(

… header fields

JZ-Employee (6) GROUP,

JZ-Employee-ReturnCode LIKE Types.ReturnCode,

… various fields from EMPLOYEE

Checksum CHAR(40),

DEPTNAME LIKE DEPARTMENT.DEPTNAME ASSIGN DEPARTMENT.DEPTNAME FKEY EMPLOYEE.WORKDEPT,

END GROUP);

This returns a DEPTNAME field with each EMPLOYEE record. It is an output field, FKEY is not valid in the INPUT message. If EMPLOYEE.WORKDEPT is null, or gives a value that does not exist in DEPARTMENT.DEPTNO, then the DEPTNAME value will be blank.

Template

Templates are “Jazz Templates”, they are copied into your Jazz Program folder when Jazz is installed. You may modify them, or you may create your own.

Template names are set depending on the type of web service to be generated. Names all have the form @ttxxxxx.jzt, e.g. @WSBasic.jzt. If this is a WSDL service then “tt” is WS, e.g. @WSBasic.jzt. If a JSON service, tt is JS, e.g. @JSBasic.jzt.

· When a name is given for Table1, xxxxx becomes F1Enq e.g. @JSF1Enq.jzt. A service will be created with logic to get the record key, and return the record.

· If the Update checkbox is checked, then xxxxx becomes F1Upt, e.g. @WSF1Upt.jzt. The message formats will include a function code, and you can read, update, add, or delete the record.

· If a second file is added then xxxxx becomes either F2Enq or F2Upd, depending on whether the records are to be updated.

Errors

As you use this form, various errors may be detected preventing it from working correctly. For example

Possible errors, and how to fix them, are: -

· Service Name absent } The service name in the example above is MyJSv. This name must be present, and

· Service Name > 5 characters } must be no longer than 5 characters. Correct the value.

· Xxxx already exists.
Check Replace or Reuse. Either change the name, or check the appropriate checkbox.

· Xxxx not found, but Replace checked.
Uncheck Replace, or change the name.

· Template Name must start with ‘@’ } The template name, @JSF1Enq in the example above, must be named starting with “@”, and

· Template does not exist } must exist within your project’s Jazz Programs folder (see Configuration)

· No Definition found for xxxxx
A file, “Custf” in the example above, needs to have a Jazz-format definition that can be found in your Jazz Copy Code folder (see Configuration), so that the program’s COPY xxxx; will be valid. If there is no existing definition you may be able to create one from COBOL (use New/Data/Import from COBOL) or from SQL (New/Data/Import from SQL), and then edit this to add extra Jazz properties.

· Max not a number } These messages all relate to values of Max,

· Max not a number from 1 to 1000 } which has value 5 in the example above.

· Table1 is blank: Table2 must also be blank

You can create a web service with no tables (both blank), Table1, or both Table1 and Table2. You can’t create a web service with Table2 only, as Table2 is a table that must be related to Table1 in a Parent/child relationship like Customers and Orders.

· Swagger definition can’t be created: xxxx

This error occurs when Jazz attempts to create a Swagger definition including the new operation. It occurs if the previous Swagger definition has an invalid JSON format. In the example above, it was caused artificially for testing by editing the old Swagger definition to include an extra comma, plus some other text: -

},, <= force error

To correct this error, locate the service’s .json file in your MANASYS project (in my case, C:\tutorials\TstSQL\MyJSv.json ), and edit it so that it has correct JSON format.