Data naming convention for input/output parameters and methods

BIS uses a set of naming conventions to define a data area which in turn is used to define 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.

1. The Service-URI is a string that encodes a BIS value tag. (See the Xcentrisity Business Information Server user's Guide for reference information.) This tag specifies the SRF file that will be the service endpoint; the value tag attributes HTMLDECODE and MAKEABS indicate to the BIS request handler (described below) that the SRF filename (tutorial1.srf in this case) should be synthesized into a URI by adding the additional parts of the URI to the filename. When this value tag is returned in the WSDL, it will be replaced by the actual URI of the service endpoint before the WSDL is sent to the client.
2. The Service-Name is a string that is used to identify 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, but it will appear in the client's API, so a meaningful name is recommended.
3. 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 could 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.
4. 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; note that, by default, method name values are all 'folded' to lower case 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 INPUTOUTPUT-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. More about this below.)