Server Program Considerations for REST Services

Enterprise Server for .NET CICS REST web services invoke CICS transaction programs. There are some considerations when writing these programs.

Since a REST server program is a CICS transaction program, the top-level program specified in the PCT definition for the transaction should be a procedural managed-code COBOL program compiled with the CICSECM directive, just as with a program associated with a transaction you would initiate from a terminal session. (While the top-level program must be procedural, it can instantiate classes and invoke methods defined in managed-code OO COBOL assemblies, of course.)

REST server programs do not have a CICS primary facility (terminal session), and so they are not allowed to use certain CICS APIs, including any API dealing with terminal I/O or BMS such as EXEC CICS SEND MAP. REST server programs are limited to the DPL subset of the CICS API as defined by IBM, though this restriction may not be enforced in all cases.

For the same reason, REST server programs do not receive any terminal input. Application data supplied by the client is passed to the server program as a CICS commarea, and the server program uses the commarea for its response. The maximum size of the commarea is determined before the server program is executed, based on the size of the request data and the REST service configuration, so if the server needs to send a response that is larger than the client's request, the service configuration must specify the minimum commarea size. See Configuring REST Web Services. See the REST server sample program included with the product for an example of using the commarea.

REST services are non-conversational. No program state is maintained by the server between requests. Usually, if the application needs to maintain state, it is kept by the client and passed in each request (this is the REST design philosophy). Server programs can also use CICS facilities such as temporary storage to retain state between invocations, but be aware of potential complications such as performance costs.