Data naming convention for input/output parameters and methods

BIS uses a set of naming conventions to define a data area A Data Area defines an RPC pattern web services interface. It is important to follow the naming conventions. The benefit is the ability to create a WSDL, process web service requests, and provide web service responses with a level of simplicity.

Here is the data area definition for the simple look up:

       78 Service-URI          VALUE "{{Value(""tutorial.srf"",HTMLDECODE,MAKEABS)}}".
       78 Service-Name         VALUE "tutorial".
       78 SOAP-Action-URI      VALUE "http://tempuri.org/bis/samples/action/tutorial".
       78 Method-Namespace-URI VALUE "http://tempuri.org/bis/samples/tutorial/".
       78 HTTP-Method-POST     VALUE "POST".
       78 HTTP-Method-GET      VALUE "GET".
       01 SOAP-Request-Response.
          10 HTTP-Method                   VALUE HTTP-Method-POST.
             88 HTTP-Method-Is-POST        VALUE HTTP-Method-POST.
             88 HTTP-Method-Is-GET         VALUE HTTP-Method-GET.
          10 Method-Name PIC X(100)        VALUE SPACES.
             88 Method-Is-Find	           VALUE "find".
          10 Fault-Area.
             20 FaultCode                  PIC X(10) VALUE SPACES.
             20 FaultString                PIC X(30) VALUE SPACES.
             20 FaultDetail                PIC X(80) VALUE SPACES.
          10 Find--Method-Parameters.
             20 Input-Parameters.
                30 desired-company-name    PIC X(50).
             20 Output-Parameters.
                30 Result                  PIC X(80).
                copy  "offcode.rec" replacing ==05== by ==30==.

First a series of constants (level 78) is defined to collect many of the service-specific values into a single block.

The Service-URI is a string that encodes a BIS VALUE tag. This tag specifies the SRF file that is the service endpoint. The value tag attributes HTMLDECODE and MAKEABS tell the BIS request handler that the SRF filename (tutorial1.srf in this case) should be made into a URI by adding the additional parts of the URI to the filename. When this value tag is returned in the WSDL, the actual URI of the service endpoint repoaces it before the WSDL is sent to the client. See the Xcentrisity Business Information Server user's Guide for reference information.
The Service-Name is a string that identifies the service to clients. It becomes the value of the name attribute in the <wsdl:service> tag. The actual use of the Service-name depends on the programming language of the client. It appears in the client's API, so a meaningful name is recommended.
The SOAP-Action-URI is a string that is used to uniquely identify a <soap:operation>. This string should take the form of a URI. As shown in this example, you may use the tempuri.org domain for testing purposes. However, you are encouraged to use a unique, permanent URI for published web services. You can use your company's domain as part of the URI value. Note that this URI does not point to an actual resource on the web.
The Method-Namespace-URI is a string that is used in the targetNamespace attribute of the <wsdl:definitions> tag. Like the SOAP-Action-URI, this URI should be unique, and otherwise follow the same guidelines.

In the definition of the 01-level SOAP-Request-Response, the first items (through 10 Fault-Area) should be defined as they are here. These definitions convey values to the XSLT stylesheets that create the WSDL, import the SOAP request, and form the SOAP response, and the names of these items must remain the same. However, condition-names (level 88) may be added, as these do not affect the values. Condition-names may be convenient for enumerating the possible method name values. By default, method name values are all folded to lowercase by the XSLT style sheets.

Method parameter definitions follow 10 Fault-Area, with a separate level 10 group data item defined for each method (function) in the service. The naming convention for these group items is: methodname--method-parameters, where methodname is the desired name of the method, followed by two hyphens. In this first example, there is only one method, named find. (Note that the method name is folded to lower case, so Find, FIND and fInD all result in a method named find.)

Within each method parameter group item, zero, one, two or three group items may exist. The names of these group items are: INPUT-PARAMETERS, OUTPUT-PARAMETERS, and INPUT-OUTPUT-PARAMETERS. Input and output parameters are defined within each of these groups as appropriate.

Note: Complex structures and arrays of structures can sometimes cause difficult programming issues on clients.