ILE CEE API Calling and Naming Conventions
You access ILE CEE APIs using the same call mechanisms currently used by HLLs to support calls in general.
If you use ILE C, you can use an ILE CEE API with the syntax shown in the following example.
#include <leawi.h> main () { CEExxxx(&parm1, &parm2, ... &parmn, &fc); }
If you use ILE COBOL, you can call most of the ILE CEE APIs using the following syntax.
CALL PROCEDURE 'CEExxxx' USING parm1, parm2, ... parmn, fc.
The following APIs require a different calling convention in ILE COBOL than that shown above.
-
Get String Information (CEEGSI)
-
Register a User Written Condition Handler (CEEHDLR)
-
Retrieve Operational Descriptor Information (CEEDOD)
-
Test for Omitted Argument (CEETSTA)
-
Register Call Stack Entry Termination User Exit Procedure (CEERTX)
-
Unregister a User Written Condition Handler (CEEHDLU)
-
Unregister Call Stack Entry Termination User Exit Procedure (CEEUTX)
In the SPECIAL-NAMES paragraph specify:
LINKAGE TYPE SYS FOR 'CEExxxx' 'CEEyyyy' ...for the APIs that are to be called. In the PROCEDURE DIVISION, the APIs are called using the following syntax.
CALL 'CEExxxx' USING parm1, parm2, ... parmn, fc. . . . CALL 'CEEyyyy' USING parm1, parm2, ... parmn, fc.
If you use ILE RPG, you call an ILE CEE API using the following syntax.
C CALLB 'CEExxxx' C PARM parm1 C PARM parm2 ... C PARM parmn C PARM fc
Note: Operational descriptors are used for some of the ILE CEE APIs, for example, CEEDATE. See the section on #pragma descriptors in the WebSphere® Development Studio: ILE C/C++ Compiler Reference manual for information about how to properly pass arguments to these ILE CEE APIs from inside a C program.
If you use ILE COBOL, you can call functions that require operational descriptors using the following syntax.
SPECIAL NAMES. LINKAGE PROCEDURE FOR 'CEExxxx' USING ALL DESCRIBED. PROCEDURE DIVISION. CALL PROCEDURE 'CEExxxx' USING parm1, parm2, ... parmn, fc.
If you use ILE RPG, you can call functions that require operational descriptors using either of the following approaches.
C CALLB(D) 'CEExxxx' C PARM parm1 C PARM parm2 ... C PARM parmn C PARM fc
or
D CEExxxx PR OPDESC D parm1 D parm2 D ... D parmn D fc C CALLP CEExxxx(parm1 : parm2 : C ... : parmn : fc)
Note: If you use ILE RPG to call ILE CEE APIs, the following restriction applies:
- APIs cannot be used if DFTACTGRP(*YES) is specified on the CRTBNDRPG CL command. ILE static binding is not available when a program is created with DFTACTGRP(*YES). This means that your program cannot contain a CALLB operation. (Also, you cannot use the BNDDIR or ACTGRP parameters when creating this program.) Specifying DFTACTGRP(*YES) during the creation of an ILE RPG program means that the program will always run in the default activation group. See the WebSphere Development Studio: ILE RPG Programmer's Guide manual for more information about the CRTBNDRPG CL command and the DFTACTGRP parameter.
The following descriptions apply to the call syntax shown in the ILE language examples above:
- leawi.h
- The name of the header file for C prototypes
Note: Header files used with ILE CEE APIs are in library QSYSINC. To ensure that these header files are found during compilation, specify *YES on the SYSINC parameter of the CRTCMOD or CRTBNDC CL commands. Also ensure that the Openness Includes can be selected as an option under GO LICPGM during the installation of the IBM® i operating system.
- CEExxxx
- The name of the ILE CEE API
- parm1, parm2, ... parmn
- Omissible or required parameters passed to or returned from the called ILE
CEE API. The & character in the syntax for ILE C indicates that the
parameters are explicitly passed by reference.
- fc
- An omissible feedback code that indicates the result of the ILE CEE API. The & character in the syntax for ILE C indicates that the parameter is explicitly passed by reference.
The order in which the parameters are listed in the parameter table for each ILE CEE API, is the order in which the parameters must be specified. For example, the following table shows the parameters for the CEEHDLR API:
Required Parameter Group:
1 | procedure | Input | HDLR_ENTRY |
2 | token | Input | POINTER |
Omissible Parameter:
3 | fc | Output | FEEDBACK |
When you call the CEEHDLR API, the first parameter you specify must be procedure (number 1 in the table), followed by token (number 2 in the table), and then fc (number 3 in the table).
Naming Conventions of the ILE CEE APIs
Most ILE CEE APIs are available to any HLL that ILE supports. Naming conventions of the ILE CEE APIs are as follows:
- Bindable API names starting with CEE are intended to be consistent across the IBM® systems.
- Bindable API names starting with CEE4 are specific to the System i® product.
For more information about using ILE CEE APIs, see the following sections:
- Data Type Definitions of ILE CEE
- Omitting Parameters in ILE CEE
- IBM i Messages and the ILE CEE API Feedback Code
[ Back to top | ILE CEE APIs | APIs by category ]