Ingres CL OL
From Ingres Community Wiki
|
Ingres Compatability Library |
Contents |
Compatibility Library Specification - OL
Abstract
This is the specification of the OL facility provided by the compatibility library.
Revision: 1.2, 14-Nov-1997
Document History
- Revision 1.2, 14-Nov-1997
- Converted to HTML.
- Revision 1.1, 29-Jul-94
- OLang_info approved (11-dec-92).
- OL_STRUCT_PTR added (22-jan-92, 29-jan-92).
- OL_value member OLPV is now a PTr, not a char *. (12-feb-92)
- OL_DEC type member added (12-feb-92)
- Other changes in OLpcall caller requirements (12-feb-92).
- Revision 1.0, last modified 29-Aug-91.
- Noted that OLpcall returns STATUS.
- Typos.
Specification
Introduction
OL provides a way to call other languages from C. It is mainly used by the 4GL tools to provide a way to call user code.
These routines are highly system dependent.
Library
CL
Header File
The header file "ol.h" must be included before using any of the functions provided. It defines the following:
Constants
Data type tags
For use in the OL_type field of an OL_PV structure.
| # define OL_NOTYPE 0 |
| # define OL_I4 1 |
| # define OL_F8 2 |
| # define OL_DEC 3 |
| # define OL_STR 6 |
| # define OL_PTR 7 |
Language type tags
For passing to OLlang_info and OLanguage.
| # define OLC 0 |
| # define OLFORTRAN 1 |
| # define OLPASCAL 2 |
| # define OLBASIC 3 |
| # define OLCOBOL 4 |
| # define OLPL1 5 |
| # define OLADA 6 |
| # define OLOSL 7 |
| # define OLSQL 8 |
OL_PV - OL parameter vector element
typedef struct
{
i4 OL_type;
PTR OL_value;
i4 OL_size;
} OL_PV;
OL_RET - OLpcall return union
/* never defined */
typedef struct ol_struct *OL_STRUCT_PTR;
typedef union
{
i4 OL_int;
f8 OL_float;
char *OL_string;
OL_STRUCT_PTR OL_ptr;
} OL_RET;
Executable Interface
The following functions are provided.
OLlang_info - get language name and support status
Given a language type, return a character string of it's name and set a flag describing whether it is supported on the platform.
Inputs:
| ol_type | From the set OLC, |
| flags | A pointer to a flags word, or NULL if support information isn't desired. |
Outputs:
| flags | If not null, set to a mask of the values OL_I_DEFINED, indicating the language is supported, and OL_I_HAS_DECIMAL, indicating the language supports native packed decimal. |
| Returns Character string of the language name. |
Definition:
char *OLang_info( i4 ol_type, i4 *flags);
OLpcall - call a user procedure
Call the user procedure func written in the language given by lang. Lang must be one of the constants OLFORTRAN, OLC, OLBASIC, OLCOBOL, OLBASIC, OLPASCAL, OLADA, OLPL1, OLPASCAL, OLOSL, or OLSQL.
OLpcall takes the argcnt arguments given in the structure args, converts them as needed by the particular language, and passes those arguments. The structure args has the type of the argument in the field OL_type (the absolute value of which is one of OL_I4, OL_F8, OL_STR, OL_DEC, or OL_PTR) and a pointer to the argument value in OL_value.
The OL_value should be cast to an (i4 *) when abs(OL_type) is OL_I4; it should be cast to a (f8 *) when abs(OL_type) is OL_F8; it should be cast to a (OL_VSTR *) when abs(OL_type) is OL_STR; it should be cast to a (OL_STRUCT_PTR) when abs(OL_type) is OL_PTR.
If OL_type is positive, then the OL_value field for this argument contains a pointer to a copy of the value to pass. this is to be passed by value. If OL_type is negative then the OL_value contains a pointer to an address to pass by reference to the procedure. Arguments should be converted to a value that is reasonible for the language being called (e.g. on VMS strings are passed to descriptor to most languages).
The arguments proc_rettype, and ret_value are used to handle return values from the procedure. If ret_value is not NULL, then the procedure is expected to return a value of type proc_rettype. This value should be placed in the proper variant of ret_value.
When the return type is OL_STR, the caller must set the OL_RET member OL_string on input to contain a pointer to an allocated char buffer of at least OL_MAX_RETLEN bytes. Depending upon the 3GL language, OLpcall() will either fill the buffer pointed to by OL_string, or set a new value of OL_string (currently only C does this).
WARNING: The structures used by OLpcall are generated by OSL. They can not be changed without coordinating the change with OSL development. The argument formats that OLpcall passes arguments to must be documented in the ABF User's Guide for each implementation. IMPLEMENTATION NOTE: the argument formats chosen should be natural for the language being called. Also, different languages will return values of a given type in different ways.
Inputs:
| func | pointer to the function to call. |
| args | Array of arguments and types to pass. |
| argcnt | Number of elements in the args[] array. |
| lang | The language of the function. |
| proc_rettype | The return type of the function. |
Outputs:
| ret_value | Filled in with the value returned from the called function. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS OLpcall(func, args, argcnt, lang, proc_rettype, ret_value); VOID (*func)(); OL_PV args[]; i4 argcnt; i4 lang; i4 proc_rettype; OL_RET *ret_value
OLanguage - return Name for Host Language type
This function maps between OL language types and the official names of the languages. Although not system-dependent, this function is grouped with OL because it defines the OL language types. Note that all defined OL language types are mapped, whether they are supported or not on a system.
NOTE: The CL module should also define IIolLang[] and _OLMAX appropriately. The typical implementation of this function is as a macro which references this table of language names. The talbe is of size _OLMAX+1.
Inputs:
| ol_type | the language type (one of OLC, etc.) |
Outputs:
| None |
Returns:
| A reference to the language name, or NULL on error |
Definition:
char * OLanguage( ol_type ) i4 ol_type;
|
Ingres Compatability Library |
