Browse Prior Art Database

Generalized API Design to Allow Customization by Calling Application

IP.com Disclosure Number: IPCOM000109582D
Original Publication Date: 1992-Sep-01
Included in the Prior Art Database: 2005-Mar-24
Document File: 3 page(s) / 134K

Publishing Venue

IBM

Related People

Jefferson, KJ: AUTHOR [+3]

Abstract

The following is a description of an Application Programming Interface (API) design that provides the ability for an application program to customize the API's processing and output. This customization is done separately from the actual API code, thus affecting only the API for the specific calling application. Finally, this design suggests a format to help eliminate API style inconsistencies and enhance code reuse.

This text was extracted from an ASCII text file.
This is the abbreviated version, containing approximately 53% of the total text.

Generalized API Design to Allow Customization by Calling Application

       The following is a description of an Application
Programming Interface (API) design that provides the ability for an
application program to customize the API's processing and output.
This customization is done separately from the actual API code, thus
affecting only the API for the specific calling application. Finally,
this design suggests a format to help eliminate API style
inconsistencies and enhance code reuse.

      Many of the APIs that are provided as part of the "programmers
toolkit" are designed to perform a very generalized function.  Many
times the data that is returned from such an API is not exactly what
the application programmer wanted.  This requires the programmer to
then manipulate the data returned from an API so that it matches the
needs of the program.  In the case of such instances, it is the API
that controls the program instead of the program controlling the API.

      Another problem that application programmers face is the
inconsistency of API styles and return codes.  When using APIs from
many different sources, it can become very confusing whether the API
call was successful, what was returned, was there an error, and what
was the error.

      The API design that is presented here consists of two parts:
API customization and API style.  Because a code example of an API
will be shown, API style will be the first topic presented.
API STYLE:
BOOL Api(INPUT, OUTPUT)
where:
  BOOL   - Defines a boolean return code.  FALSE (0) indicates a good
return and TRUE (1) indicates an error.
  API    - Application Programming Interface.
  INPUT  - Defines ALL of the inputs into the API.
  OUTPUT - Defines ALL of the outputs from the API including detail
error information in the case of an API call failure.
API Customization:

      In order to provide customization of an API, some adjustments
to the internals of an API are necessary.  These adjustments consist
of the definition of 2 API exit calling points, and 3 exit calling
point returns.  The Exit points are pre-processing and
post-processing exits.  These exit point receive both the INPUT and
OUTPUT structures and have control on the continued processing of the
API.  This control over API continued processing is done by 3 exit
calling point return codes; Processing complete (-1), continue
processing (0), and error condition (1).

      An example of this type of API would be as follows:
BOOL Api(INPUT, OUTPUT)
{
   SHORT rc;
switch (ApiPreProcess(INPUT, OUT...