Describes the mappings between interface fields, work fields, and screen or COMMAREA fields.

A mapping is a designation of a relationship between a CICS screen, IMS screen, or CICS COMMAREA field, or a work field, and an interface field. Mappings are shown in the Interface Mapper in the Mappings pane. When you create an interface field by dragging and dropping, a mapping is done for you – the interface field maps to the field you dragged and dropped.

An interface field that you define manually requires that you also define its mapping or mappings manually. You can define more than one mapping for each interface field. For an input field, this means that during execution, data received in the field is moved to all the data items the field is mapped to. For an output field it is meaningless (data from several application fields would be sequentially moved to the one interface field, each value replacing the previous), unless the interface field has an Occurs property. In this case you can specify different values of the subscript in different mappings. See Arrays for more information.

Only elementary (non-grouped) interface fields and application fields can be mapped.

You can also make a mapping conditional. See Conditional Statements for more information.

Note: When defining a SOAP Web Service service interface, take care not to map an output interface field defined as a string to an alphanumeric field that can contain a character value that is invalid for a SOAP string. Invalid character values are values less than x"20" except for x"09", x"10" and x"13". If you do create such a mapping, the client program might receive the message: "458 Illegal character in SOAP string".


For screen-based service interfaces, you can use three special fields to map to your output interface fields as follows:

Contains return code information if the application were to end abnormally during the execution of the service.
Contains a status code resulting from an abnormal application termination.
Contains any message returned as a result of an abnormal termination.


For COBOL CICS screen-based service interfaces only, you can use two special fields, USER ID and PASSWORD, to map to input interface fields. The purpose of these two fields is to control access to your application by collecting the user ID and password when you want to verify users before granting authorization to access the application.