How to Create a Deployable Web Service Using a Multiple-instance Array

How to Create a Deployable Web Service Using a Multiple-instance Array

This process explains how an experienced CA 2E Application Developer can use CA 2E web service support with enhanced array support to make an invocation and retrieve an order. This process includes the order header and multiple order detail lines.

Important! The coding examples are designed to illustrate enhanced array support and are not production-ready. For example, the examples do not contain any user-added error handling.

As an experienced CA 2E Application Developer, you want your result to be a deployable 2E Web Service that uses Enhanced Array Support to return multiple-instances of data in a single invocation. In this scenario, we use an Order Header and Order Detail file, and the order has a single order header and multiple detail lines.

The following illustration shows how you complete the process:

Follow these steps:

1. Define the Files
2. Define the Order Details Array
3. Create an Execute External Function
4. Retrieve the Order Header and Order Details
5. Set the EXCEXTFUN function to a module
6. Generate and compile the module
7. Create a Service Program
8. Add the module to the Service Program
9. Generate and compile the Service Program
10. Create a web service function
11. Deploy the Web Service instance

Note: This procedure uses individual *MOVE ARRAY statements. As you become familiar with the process, the *MOVE ARRAY, *ALL function helps make your work more efficient.

Back to Top

Define the Files

We assume the following basic file definitions for the process:

Note: The field types are not critical to this scenario, so you can define field type as you see fit.

Order Header Files

If your screen shows the Order Header File as:

Order header			Known by			Order Number

Order header			Has			Customer Name

Order header			Has			Order Date

Then the Order Header Records look like this example:

Order Detail File

If your screen shows the Order Detail File as:

Order detail			Owned by			FIL Order Header

Order detail			Known By			FLD Line Number

Order detail			Refers to			FIL Product

Order detail			Has			FLD Quantity

Then the Order Detail Records look like this example:

Note: Product code refers to the product file. For example, LH refers to Little Hammer and BH refers to Big Hammer.

Product File

FIL Product                   Known by         FLD Product code       

FIL Product                   Has              FLD Product description

FIL Product                   Has              FLD Product price date 

FIL Product                   Has              FLD Product price      

Back to Top

Define the Order Details Array

We assume the following array definition for the process.

Note: The Element number field should be of type NBR.

Follow these steps:

1. Create an array named Order Details over the *Arrays file.
2. Take option Z to open the EDIT ARRAY DETAILS screen.
3. Define the Order details array with the retrieval index structure of the order detail file and additionally an Element number field (Type NBR), as follows:

   

4. Press F7 to access the EDIT ARRAY KEY ENTRIES panel and define Element number as the key to the array.

   

Back to Top

Create an EXCEXTFUN to Retrieve the Order Header and Order Details

The function EEF RTV ORDER, EXCEXTFUN type, based over the Order Detail file takes an input parameter of an order number and returns order information as output parameters as follows:

• The order header is represented by a single-instance output parameter.
• The order detail lines are represented by a multiple-instance output parameter.

This section describes how to define the EXCEXTFUN to include parameter interface and action diagram business logic, including calls to other functions. After you complete the steps in this section, your Action Diagram should match these example screens:

Important! As a CA 2E developer, you need to understand the architectural distinction between the two mechanisms to manipulate array data, despite the ability to use a common structural definition:

• Data can exist and be modified in an array by using database functions (Create Object – CRTOBJ, Delete Object –DLTOBJ, Change Object – CHGOBJ, and Retrieve Object – RTVOBJ) based over the *Arrays file. However, this array data cannot be accessed by the *MOVE ARRAY function.
• Back to TopData can also exist and be modified in a multiple-instance array parameter (in the PAR context) and in the ARR context by using the *MOVE ARRAY function. However, that array data cannot be accessed by database functions (Create Object – CRTOBJ, Delete Object –DLTOBJ, Change Object – CHGOBJ, and Retrieve Object – RTVOBJ) based over the *Arrays file.

Note: The function EEF RTV ORDER (Order Detail) relies on four other internal functions, as listed in the following table.

You need to build the required internal functions and the external function EEF RTV ORDER (Order detail):

Note: The file the functions is based over is shown in parentheses.

Follow these steps:

1. RTV Order Header (Order Header)
2. RTV Order Detail (*Arrays)
3. CRT Order Detail (*Arrays)
4. Load Order Detail Array (Order detail)
5. EEF RTV Order (Order detail)

Back to Top

Retrieve the Order Header

This section explains how you retrieve information about an order header record, given an order number.

Follow these steps:

1. Define the RTV ORDER HEADER: Parameter interface as follows:

   

2. Define the function parameter details as follows:

   

3. Configure an action diagram: RTV ORDER HEADER as follows:

   This example shows User Points that are not empty.

   

4. Save and exit the function.

Back to Top

RTV Order Detail (*Arrays)

This section describes how you retrieve the data for a single element in the Order Details array. You need to configure the RTV ORDER DETAIL to retrieve the data for a single element in the Order Details array.

Follow these steps:

1. Configure the RTV ORDER DETAIL: Parameter interface as follows:

   

2. Define the parameter details as follows:

   

3. Configure the RTV ORDER DETAIL: Action Diagram as follows:

   

4. Save and exit the function.

Back to Top

CRT Order Detail (*Arrays)

This section describes how you configure the CRT ORDER DETAIL to populate the data for a single element in the Order Details array.

Follow these steps:

1. Configure the CRT ORDER DETAIL: Parameter interface as follows:

   

2. Define the parameter details as follows:

   

   Note: The CRT ORDER DETAIL contains no user-added processing in the action diagram.

3. Save and exit the function.

Back to Top

Load Order Detail Array (Order detail)

This section explains how to define a function to populate the Order Detail array. The processing runs through the database to find all order detail lines for a given order number. Each detail line is added as a single element in the Order Details array.

Follow these steps:

1. Create a function called LOAD ORDER DETAIL ARRAY, and configure the parameter interface as follows:

   Note: Define the field Total elements as type NBR.

   

2. Define the parameter details as follows:

   

   

3. Configure a LOAD ORDER DETAIL ARRAY: Action Diagram as follows:

   

   

4. Call to the CRT ORDER DETAIL as follows:

   

   

5. Save and exit the function.

Back to Top

EEF RTV Order (Order detail)

This section describes how you define the external function EEF RTV Order (Order detail) including the parameter interface and action diagram business logic. The EEF RTV Order (Order detail) retrieves information about an order. Given an input of an order number, the function retrieves information about the order header, and all of the order detail lines. The order detail lines are represented using a multiple-instance array parameter.

The key concept is to populate the multiple-instance array parameter (PR3) with order detail lines from the database. Typically, you can obtain database information using a function of type RTVOBJ. However, the RTVOBJ cannot directly access the (PR3) parameters of the EEF. A multiple-instance array parameter can only be defined on functions of Execute External Function and Execute User Program.

A RTVOBJ call might be placed in a loop to retrieve one order detail line at a time into the, LCL context for example, and then the information could be moved from the LCL context to an element of the multiple-instance array (PR3) on the EEF. However, multiple calls to a RTVOBJ based over a database access path is undesirable from a performance point of view. Moreover, if the order detail lines do not exist with some contiguous key or positioned, additional code will have to ensure that each order detail line is retrieved.

We address this issue as follows:

From the AD of the EEF call a RTVOBJ, named LOAD ORDER DETAIL ARRAY, based over a database access path (Order detail) one time, and for each order detail record, create an element in an array.

Note: The array has the same structure as the order detail record, but has an additional key field of Element number.

Once the Array is created, a loop in the EEF can step through the array and call a RTVOBJ, named RTV ORDER DETAIL, based over the Order Detailsarray to recall one element at a time to the LCL context.

The data in the LCL context that represents a single order detail record can then be populated into multiple-instance array parameter (PR3) of the EEF that represents the order detail lines. This move from the single-instance LCL context to a multiple-instance context can be achieved with the *MOVE ARRAY function.

This approach has the benefit that the processing is faster than multiple RTVOBJ (database) calls and the looping through the array in memory overcomes any gaps between order detail line numbers.

The EXCEXTFUN function type can be deployed as a *MODULE, which allows it to be bundled into Service Program and deployed as a web service. Thus a single invocation of the web service can retrieve all the information regarding the order header and all order detail lines.

Follow these steps:

1. Create a function called EEF RTV Order and define the parameter interface as follows:

   Notes:

   • EEF RTV Order has function option Duplicate parameters set to Yes.
   • PR3 is defined as a multiple-instance array parameter.

   PR1

   Indicates the input parameter for the Order number, passed as a field (FLD), from which the Header and Detail are retrieved.

   PR2

   Indicates the output parameter for the Order Header, passed as a record format (RCD), which is populated with the single-instance data for the Order Header.

   PR3

   Indicates the output parameter for the Order details array.

   Note: This parameter is marked as being a multiple-instance parameter, so multiple order detail records can be contained within this one parameter. If the A(Pass as Array) field is marked as Y, before usages have been specified on the EDIT FUNCTION PARAMETER DETAILS panel for the fields of this parameter a warning message will be sent: Y2V0717 A (Pass as Array) cannot be set to 'Y'.However, you may leave the field set to Y and zoom into the parameter to specify usages.

   

2. Define the parameter details as follows:

   

   

   

3. Configure the EEF RTV ORDER : Action Diagram as follows:

   Notes:

   • Function calls that are not self-evident are shown in the following examples.
   • The Count field should be defined as type NBR.

     

     

4. Initiate a call to the RTV ORDER HEADER as follows:

   

5. Initiate a call to LOAD ORDER DETAIL ARRAY as follows:

   

6. Initiate a call to RTV ORDER DETAIL as follows:

   

7. Save and exit the function.

Back to Top

Set the EXCEXTFUN to a Module

CA 2E automatically creates the EXCEXTFUN function type as PGM (Program), so you must change the type to MOD (Module).

Follow these steps:

1. From EDIT DATABASE RELATIONS take option F against the Order detail file to access the EDIT FUNCTIONS screen.
2. Take option Z (Details) against EEF RTV ORDER for the EDIT FUNCTION DETAILS screen.
3. Change the Target HLL to RP4 or CBI. Take option T (T-ILE Compilation Type) to change the object type to MOD.
4. Press enter to save the changes and press F3 to return the EDIT FUNCTIONS screen.

The EXCEXTFUN has all the necessary configuration and details, so you must then generate and compile before you can use it.

Back to Top

Generate and Compile the Module

With the EXCEXTFUN fully configured, you must compile the module.

Note: Before generating the module, your model must be set up to include PCML in the module. For more information, see the section “PCML in Module” in the Building Applications guide for details

Follow these steps:

1. Take option J (Generate) on the new EEF RTV ORDER function.
2. Press F17 for the Services Menu, and take Option 1 (Submit Model Create Request).
3. Locate the EEF RTV ORDER function and press Enter.

   Note: Depending on your processing speed, the compile can complete quickly or take several minutes.

4. Verify that the compile completed correctly.
5. Press F3 until you return the EDIT FUNCTIONS screen.

This procedure completes your work on the EXCEXTFUN module. Next, you create a Service Program for use with the module.

Back to Top

Create a Service Program

In the CA 2E model, you define a Service Program (*SRVPGM) function type, which you will then use with the module. You can customize the source member name, which is then used for the final *SRVPGM object name.

Follow these steps:

1. From EDIT DATABASE RELATIONS take option F against the Order detail file to access the EDIT FUNCTIONS screen.
2. Create a Service Program and complete the fields as follows:

   Function:

   Order srvpgm

   Function Type:

   Service Program

   Access path

   *NONE

A Service Program does not contain parameters or an action diagram, so you must add the module in the following procedure.

Back to Top

Add the Module to the Service Program

You now have your EEF RTV ORDER module and your Order srvpgm Service Program. Combine the two by adding the module to the Service Program.

Follow these steps:

1. Take option F against the Order detail file from EDIT DATABASE RELATIONS to access the EDIT FUNCTIONS screen.
2. Take option Z (Details) on the new service program Order srvpgm.
3. Take option M (Modules).
4. Press F6 (add) to add a module.
5. Take option X (Select) against the EEF RTV ORDER module.
6. Press F3 to access the SERVICE PROGRAM MODULE screen.

   Verify that the module is listed.

7. Press F3 until you return the EDIT FUNCTIONS screen.

The combined Service Program and module are not usable until you generate and compile them in the following procedure.

Back to Top

Generate and Compile the Service Program

The combined module and Service Program are not usable until you generate and compile.

Follow these steps:

1. Take option F against the Order detail file from EDIT DATABASE RELATIONS to access the EDIT FUNCTIONS screen.
2. Take option J (Generate) on the Order srvpgm Service Program.
3. Press F17 for the Services Menu, and take option 1 (Submit model create).
4. Press Enter to submit the job, which generates and compiles the source.

   Note: Depending on your processing speed, the compile can complete quickly or take several minutes.

5. Press F3 until you return to the EDIT FUNCTIONS screen.

This gives you a usable, compiled Service Program that includes the EEF RTV Order module you created. Next, create a Web Service Function that includes the compiled Service Program.

Back to Top

Create a Web Service Function

The CA 2E Web Service uses the Service Program you created in the previous procedures to create a Web Service Function. This function contains one-to-multiple operations, where each operation corresponds to a single procedure in a module in an ILE Service Program.

Follow these steps:

1. Access the EDIT FUNCTIONS screen.
2. Add a new Web Service function type by competing the following fields:

   Function

   Order websrv

   Function type

   Web Service

   Access Path

   *NONE

3. Press Enter to save, and then take option Z (Details) for the EDIT FUNCTION DETAILS screen.
4. Complete the details fields as follows:

   Web service name

   GetOrder

   Service program file

   Order Detail

   Service Program Function

   Order srvpgm

5. Press Enter to save, and then F3 until you return the EDIT FUNCTIONS screen.

The result is a modeled Web Service Function, but it is not available to invoke until you complete the following procedure to deploy Web Service Function on your Web Server.

Back to Top

Deploy the Web Service Instance

From the newly created Web Service Function, you can deploy a Web Service instance. Use the YCRTWS (Create Web Service Instance) command to install the web service to the IBM Web Services Server.

Notes:

• Before you deploy the Web Service Instance, verify that the Runtime Library List contains all of the libraries that are required to support the runtime business logic.
• Here we use the EDIT FUNCTION DETAILS screen, but you can also invoke YCRTWS from the command line and then configure the appropriate parameters.

Follow these steps:

1. Take option F against the Order detail file from EDIT DATABASE RELATIONS to access the EDIT FUNCTIONS screen.
2. Take option Z against the web service Order websrv.
3. Press F10 (Create Web Service Instance) and complete the fields as follows:

   Update Model

   *ADD

   Install to Server

   *YES

   Web Services Server

   YourServerName (the actual name for you Web Server)

4. Press Enter to save and deploy.

The Web Service Function is now available for users to call from your Web Server. Test the Web Service before notifying your users.

For detailed information on web service deployment see the Chapter Web Service Creation.

Note: Use the IBM Web Administration interface to start, stop, and test the deployed Web Service.

Back to Top

*MOVE ARRAY (*ALL)

Four individual *MOVE ARRAY statements are used in the example code for EEF RTV Order (Order detail) to move data from a field in the LCL context to a field in a multiple instance array parameter. This is a good illustration of how you can use *MOVE ARRAY. However, you can use *MOVE ARRAY, *ALL support for a more efficient approach.

You can replace the multiple *MOVE ARRAY statements with a single *MOVE ARRAY statement, specifying *ALL for the *Result and *Factor fields. You do not have to change the action diagram if you then add or remove fields from the array; a simple regeneration and recompilation works.

The following EDIT ACTION DIAGRAM panel shows how you can use *MOVE ARRAY (*ALL:)

The following EDIT ACTION DIAGRAM – FUNCTION DETAILS panel shows more detail on how you can use *MOVE ARRAY (*ALL:):

Back to Top