Chapter 4. Services
This chapter describes several functions that are related to using the CDRA identifiers. CDRA-defined services are functions that are needed to consistently and correctly process graphic character data. These are detailed in "Chapter 5. CDRA Interface Definitions". Other related services are also discussed.
Data Flow Models
Figure 14 shows a model containing generic processing modules. This model does not imply any product implementation. Its elements and their individual roles are described below, identifying the CDRA functions that are needed.
Applications
A collection of processing functions that serve to execute a user application. Graphic character data is exchanged between the application and the operating system, or between the application and the providers of various types of services such as presentation services, file management services, database management services, and communication services.
Shared Services
A collection of functions provided in the operating system that is useful to several components or applications in a system.
Presentation Services
A collection of functions that allow data exchanges between devices and applications. The services that handle graphic character data have the following capabilities:
- They support graphic character data interchange at the application interface.
- They have logic to recognize the device capabilities and to manage any difference between the encodings of application data strings and device capabilities
- They provide their own specific interface to applications; and provide the necessary tagging-related functions (such as set and query of tags) for graphic character data entities (such as fields, panels, windows, or sessions) at the application interface.
File Management Services
A collection of functions that allow applications to place data into organized data units called files. The graphic-character handling capabilities of these services are:
- Using their own interfaces to applications, they allow the application to set and query character data entities such as files, records, fields, or strings.
- They may provide automatic difference management functions to applications.
- In support of automatic difference management, they may have capabilities to support a specific set of encodings in the application or data views.
Database Management Services
A collection of functions that allow organizing and managing data as well-defined structures such as tables, columns, and rows. The graphic-character-data related aspects of these services include the following:
- Using their own method and interfaces, they allow applications or database administrators to set and query tags associated with graphic character data.
- They may provide transparent access to data from the database in a specified list of encodings at the application interface.
Communications Services
A collection of functions that allow various modules to communicate with peer modules or other modules in the same system or a different system.
- A minimum of a transparent data path is provided by these services.
- No automatic difference management functions are assumed to be present in the communications services in this model.
Applications have a choice of using the difference management services provided in the various service providers, where available. The list of encodings supported by each of these must be known to the application. The application must restrict its data across the service provider interfaces to one of these supported encodings. The potential interface points where CDRA functions are required are shown in Figure 14. If the service providers do not have support for a specific encoding the application must manage the difference.
CDRA-Defined Services and Other Related Services
An implementation of CDRA will include a collection of CDRA-defined services and other related services. Together they will provide the environment with a method of identifying graphic character data and managing the differences in graphic character data representations.
CDRA-defined services have the following properties:
- Their semantics are definable and are equally applicable in all environments; the function can be defined in a manner independent of the system's or environment's unique methods or organizations.
- The function can be provided once per system, and will be of maximum benefit to many callers from different layers in the system.
- The syntax of the functions can be common across all environments; the common-service implementations will provide at least one function interface using the defined syntax. They may provide other system-specific function interfaces as well.
The CDRA-defined services can be grouped into four categories:
- Functions for querying CCSID information
- Functions for querying CCSID relationships
- Functions related to difference management
- Functions for identifying exception conditions.
A brief description of the functions in each group follows. "Chapter 5. CDRA Interface Definitions" details each of the APIs.
Functions for Querying CCSID Information to assist in migrating from the use of an intermediate form of tagging, the caller of a CDRA service may obtain the various elements of a CCSID. Similarly, a caller may have an intermediate form and need to find the equivalent CCSID. Additionally, the caller may obtain control function assignment information. The following functions provide these services.
CDRGESP Get Encoding Scheme, Character Set, and Code Page Elements
CDRSCSP Get Short Form (CCSID) from Specified ES (CS, CP)
CDRGESE Get Encoding Scheme Element and its Subelements
CDRGCTL Get Control Function Definition
CDRSMXC Get Short Form (CCSID) with Maximal CS for Specified ES, CP
Functions for Querying CCSID Relationships when an environment deals with multiple encoding schemes (such as PC-Data and PC-Display in the OS/2 environment, or the pure single-byte or mixed single-byte and double-byte codes in systems supporting Group 2 character sets), special query functions are needed to find different CCSIDs that have specific relationships. For example, when data is received in a CCSID that is not native to a system environment, such as PC-Data encoded data in an EBCDIC supporting iSeries* (aka AS/400*) system, it is necessary to find a supported CCSID that best relates to the CCSID of the received data. The following functions provide information on the relationships between CCSIDs:
CDRGRDC Get Related Default CCSID
CDRGCCN Get CCSID for Normalization
Functions Related to Difference Management when different data representations, as described by the CCSIDs of two entities is detected (using query functions), a conversion service can be called to convert data in one CCSID to another. The conversion service is a collection of conversion methods and supporting conversion tables. The concepts and criteria associated with difference management, the selection of an appropriate conversion method, and the creation of the contents of conversion tables are described in "Chapter 6. Difference Management" and in Appendix B. "Conversion Methods". The following functions are defined for difference management:
CDRCVRT Convert a Graphic Character String
CDRMSCI Multiple-Step Convert Initialize
CDRMSCP Multiple-Step Convert Perform
CDRMSCC Multiple-Step Convert Clean Up
Function for Identifying Exception Conditions a service is provided for callers of the CDRA services who cannot use the feedback structure. This service will provide the user with a status code and reason code as separate elements. The following function is defined for identifying exception conditions:
CDRXSRF Extract Status and Reason Codes from Feedback Code
Related Services
The related services include those functions that can potentially have a common syntax, but whose semantics cannot be defined in a common manner across all environments; for example, querying system defaults or the current session CCSID.
The resource management functions are contained in the group of related services. These functions are system-specific because they deal with system-specific resource structures, access, and storage; and they provide system-specific administration facilities (utilities and their end-user interfaces).
Functions that are not common within a system are object-manager-specific (for example, querying the CCSID of a relational database table). These functions may have a common object-manager-specific syntax across systems. The functions and their syntaxes cannot be supported as common services in all environments.
Brief descriptions of related services follow.
Setting Tag Values
Setting is the process of entering one or more tag values into the tag fields associated with different graphic character data elements. The set function is provided as part of the various object-manager-specific interfaces, or associated service functions. Setting of tag fields on entities owned by the operating system is provided by the system-specific interfaces. Setting is usually performed at object create time, and may be modified if the data encoding changes.
Querying is the process of reading or obtaining one or more tag values associated with graphic character data elements. The query function is provided as part of various object-manager-specific interfaces, or associated service functions. Querying of tag fields in entities (or objects) owned by the operating system is provided by services in the operating system, as part of the system-specific services.
The query function also resolves any unknown or default tag values such as a CCSID value of X'0000'. Any hierarchy used for organizing the different elements owned by the object managers is object-manager-specific. Different types of queries are applicable to different object managers. For example, a file manager may provide for querying all the CCSIDs that may be present within a file; a presentation manager may provide for querying the CCSID used in a currently active window.
To assist in resolving the defaults in a hierarchy, a function may be provided to create and maintain a resource of default values for an application, a user, or another module. This resource is system-specific.
Resource Management Functions
Different systems have different structures and different methods of storing information resources. The content of the CDRA-supporting resources is defined by the architecture; however, the manner in which the resources are stored is system-specific as are the functions for maintaining (creating, updating, and querying) them. These functions, when provided, are classed as related services.
The related services include those functions that can potentially have a common syntax, but whose semantics cannot be defined in a common manner across all environments; for example, querying system defaults or the current session CCSID.
The resource management functions are contained in the group of related services. These functions are system-specific because they deal with system-specific resource structures, access, and storage; and they provide system-specific administration facilities (utilities and their end-user interfaces).
Functions that are not common within a system are object-manager-specific (for example, querying the CCSID of a relational database table). These functions may have a common object-manager-specific syntax across systems. The functions and their syntaxes cannot be supported as common services in all environments.
Brief descriptions of related services follow.
Setting Tag Values
Setting is the process of entering one or more tag values into the tag fields associated with different graphic character data elements. The set function is provided as part of the various object-manager-specific interfaces, or associated service functions. Setting of tag fields on entities owned by the operating system is provided by the system-specific interfaces. Setting is usually performed at object create time, and may be modified if the data encoding changes.
Querying Tag Values
Querying is the process of reading or obtaining one or more tag values associated with graphic character data elements. The query function is provided as part of various object-manager-specific interfaces, or associated service functions. Querying of tag fields in entities (or objects) owned by the operating system is provided by services in the operating system, as part of the system-specific services.
The query function also resolves any unknown or default tag values such as a CCSID value of X'0000'. Any hierarchy used for organizing the different elements owned by the object managers is object-manager-specific. Different types of queries are applicable to different object managers. For example, a file manager may provide for querying all the CCSIDs that may be present within a file; a presentation manager may provide for querying the CCSID used in a currently active window.
To assist in resolving the defaults in a hierarchy, a function may be provided to create and maintain a resource of default values for an application, a user, or another module. This resource is system-specific.
Resource Management Functions
Different systems have different structures and different methods of storing information resources. The content of the CDRA-supporting resources is defined by the architecture; however, the manner in which the resources are stored is system-specific as are the functions for maintaining (creating, updating, and querying) them. These functions, when provided, are classed as related services.
