Standards for COBOL Service Interface Definitions

A service interface is the combination of:

• The set of service operations supported by a service-enabled COBOL program
• The set of data structures describing the input and output messages exchanged between a service-enabled COBOL program and its clients for each supported service operation
• The interaction mechanisms by which these messages are exchanged
• The set of guarantees that the service-enabled COBOL program asserts for each operation

The service interface describes the interface contract between the service-enabled COBOL program and all of its possible clients including data-terminal based user interfaces, batch process monitors, report programs, and web services. As long as this interface contract is unchanged, developers may change the implementation of the client without having to change the server or vice versa.
Example Service Interface Declaration
For example, the service interface of a simple service-enabled COBOL program might declare that:

• The service program will support a single operation - to retrieve the closing price of a given CUSIP as of a given date.
• The input message structure for this operation will consist of a COBOL record structure declaring a three-digit operation code field, a 10-character alphanumeric CUSIP field, and a 10-character date field in "YYYY-MM-DD" format.
• The output message structure for this operation will consist of COBOL record structure declaring a three-digit reply code field, the 10-character alphanumeric CUSIP field, and a decimal closing price field with a four-digit integer portion and a five-digit decimal portion.
• If the operation code field of the input message contains a value of 1, the service program will process the message as a request to the closing price operation. If the operation code field contains any other value, the service program will return a value of 1 in the reply code field.
• For the closing price operation, if the CUSIP is found and has a recorded closing price for the specified date, the service program will return a value of 0 in the reply code field along with the CUSIP and closing price values.
• For the closing price operation, if the CUSIP is not found, the service program will return a value of *2* in the reply code field, a value of *0.0* in the closing price field, and the CUSIP in the CUSIP field.
• For the closing price operation, if the CUSIP is found but no closing price can be found for the specified date, the service program will return a value of *2* in the reply code field, a value of *0.0* in the closing price field, and the CUSIP in the CUSIP field.
• The service program will expect to receive the input message in its linkage area on invocation. It will place its output message in the same linkage area on return.
• The service program will guarantee that it will process one request as specified by the input message for each invocation and will return either success or failure for the request as indicated by the output message (a synchronous message exchange pattern).

Service Interface Standards

The service interface of a service-enabled program should have the following characteristics which would tend to distinguish it from an interface that is tightly coupled to a data-terminal user interface:

• Fields of the data structures describing the input and output messages should be carried as specific data types, rather than as character display fields.* For example, the data-terminal user interface of an online program in the bond trading system may well allow the user to input a quantity field in the form "10M", meaning 10,000 bonds. However, the quantity field in the data structure of the input message to an operation of a service-enabled program would be declared as a decimal field (in this case, carrying the value 10,000). It is the job of the user interface program or other clients of the service to convert between character input or display output formats and the specific data types required by the service.
• Fields of the data structures describing the input and output messages should convey only standard data formats, rather than accept multiple user-oriented formats.* For example, the data-terminal user interface of an online program may well allow the user to input date fields in a number of formats ("01/02/07", "1/2/07", "1/2/2007") with the allowed variants perhaps even depending on user locale. However, date fields in data structures of input messages to operations of service-enabled program would only accept a single, standard format -- "YYYY-MM-DD" (for example, "2007-01-02"). It is the job of the user interface program or other clients of the service to convert between character input or display output formats (especially locale-specific formats) and the specific data types required by the service.
• Fields of the data structures describing the input and output messages should never be overloaded with respect to their content.* For example, the data-terminal user interface of an online program in the bond trading system might display either the maturity date or average life of a bond in a single display field, but the service interface would carry these as discrete fields in its input and output messages.
• Only fields related to the business function of the service operations should be carried in the data structures of the service interface.* Fields related to display attributes of the user interface should never be carried in the service interface.
• Each service operation should be stateless.* All of the information required to process a request to a given operation should be carried in the input message to that operation.
• Each service operation should carry out a complete, self-contained message exchange.* For example, a query operation should return all selected rows in a single output message. It is the job of the user interface or other clients of the service to implement data paging and similar interaction constructs.
• A service operation should not require stateful user interactions to complete an operation.* For example, the data terminal user interface of an online program in the bond trading system might display a prompt to allow the user to override a condition where the ordered quantity is greater than the inventory quantity remaining. A service-enabled COBOL program might define two operations to support this use case -- a verification operation with input fields indicating that certain warning conditions are to be ignored and a posting operation that performs the requested transaction without regard to warning conditions.
• Each service operation should be self-contained with respect to its transactional semantics.* For example, an online program might begin a transaction, lock a selected record, and present it to the user for update. Once the user has finished all updates, the online program would either commit the transaction or roll it back in the case of an error. A service-enabled program might define two service operations for this use case -- a non-transactional query operation that retrieves the information for display and a transactional update operation that uses a timestamp or other mechanism to detect or avoid update collisions.