20 User Exits

20.1 What Is a User Exit?

A user exit is a C subroutine written by you and called by Oracle Forms to do special-purpose processing. You can embed SQL statements and PL/SQL blocks in your user exit, then precompile it as you would a host program.

When called by an Oracle Forms V3 trigger, the user exit runs, then returns a status code to Oracle Forms. Your exit can display messages on the Oracle Forms status line, get and set field values, do high-speed computations and table lookups, and manipulate Oracle data.

Figure 20-1 shows how an Oracle Forms application interacts with a user exit.

Figure 20-1 Oracle Forms and a User Exit

Description of the illustration lnpcc018.gif

20.2 Why Write a User Exit?

SQL*Forms Version 3 provides the ability to use PL/SQL blocks in triggers. So, in most cases, instead of calling a user exit, you can use the procedural power of PL/SQL. If the need arises, you can call user exits from a PL/SQL block with the USER_EXIT function. User exits are harder to write and implement than SQL, PL/SQL, or SQL*Forms commands. So, you will probably use them only to do processing that is beyond the scope of SQL, PL/SQL, and SQL*Forms. Some common uses follow:

• Operations more quickly or easily done in a third generation languages like C (numerical integration, for instance)

• Controlling real time devices or processes (issuing a sequence of instructions to a printer or graphics device, for example)

• Data manipulations that need extended procedural capabilities (recursive sorting, for example)

• Special file I/O operations

20.3 Developing a User Exit

This section outlines the way to develop a SQL*Forms 3.0 user exit; later sections go into more detail.

To incorporate a user exit into a form, you take the following steps:

• Write the user exit in Pro*C.

• Precompile the source code.

• Compile the. c file from step 2.

• Use the GENXTB utility to create a database table, IAPXTB.

• Use the GENXTB form in SQL*Forms to insert your user exit information into the table.

• Use the GENXTB utility to read the information from the table and create an IAPXIT source code module. Then compile the source code module.

• Create a new SQL*Forms executable by linking the standard SQL*Forms modules, your user exit object, and the IAPXIT object created in step 6.

• In the form, define a trigger to call the user exit.

• Instruct operators to use the new IAP when running the form. This is unnecessary if the new IAP replaces the standard one. For details, see the Oracle installation or user's guide for your system.

20.4 Writing a User Exit

You can use the following kinds of statements to write your SQL*Forms user exit:

• C code

• EXEC SQL

• EXEC ORACLE

• EXEC TOOLS

This section focuses on the EXEC TOOLS statements, which let you pass values between SQL*Forms and a user exit.

EXEC IAF GET field_name1, field_name2, ... 
    INTO :host_variable1, :host_variable2, ...; 

EXEC IAF GET employee.job INTO :new_job;   

char blkfld[20] = "employee.job"; 
EXEC IAF GET :blkfld INTO :new_job; 

char blk[20] = "employee"; 
strcpy(fld, "job"); 
EXEC IAF GET :blk.:fld INTO :new_job; 

strcpy(fld, "job"); 
EXEC IAF GET employee.:fld INTO :new_job; 

EXEC IAF PUT field_name1, field_name2, ... 
    VALUES (:host_variable1, :host_variable2, ...); 

EXEC IAF PUT employee.number, employee.name, employee.job 
     VALUES (7934, 'MILLER', :new_job); 

char blkfld[20] = "employee.job"; 
...
EXEC IAF PUT :blkfld VALUES (:new_job);  

20.5 Calling a User Exit

You call a user exit from a SQL*Forms trigger using a packaged procedure named USER_EXIT (supplied with SQL*Forms). The syntax you use is

USER_EXIT(user_exit_string [, error_string]);  

where user_exit_string contains the name of the user exit plus optional parameters and error_string contains an error message issued by SQL*Forms if the user exit fails. For example, the following trigger command calls a user exit named LOOKUP:

USER_EXIT('LOOKUP'); 

Notice that the user exit string is enclosed by single (not double) quotes.

20.6 Passing Parameters to a User Exit

When you call a user exit, SQL*Forms passes it the following parameters automatically:

However, the user exit string provides the ability to pass additional parameters to the user exit. For example, the following trigger command passes two parameters and an error message to the user exit LOOKUP:

Notice that the user exit string is enclosed by single (not double) quotes.

USER_EXIT('LOOKUP 2025 A', 'Lookup failed');
 

You can use this feature to pass field names to the user exit, as the following example shows:

USER_EXIT('CONCAT firstname, lastname, address');
 

However, it is up to the user exit, not SQL*Forms, to parse the user exit string.

20.7 Returning Values to a Form

When a user exit returns control to SQL*Forms, it must also return a code indicating whether it succeeded, failed, or suffered a fatal error. The return code is an integer constant defined by SQL*Forms (see the next section). The three results have the following meanings:

sqliem (char *error_message, int message_length); 

20.8 An Example

The following example shows how a user exit that uses the EXEC IAF GET and PUT routines, as well as the sqliem function, is coded.

int
myexit()
{
    char field1[20], field2[20], value1[20], value2[20];
    char result_value[20];
    char errmsg[80];
    int errlen;

    #include sqlca.h
    EXEC SQL WHENEVER SQLERROR GOTO sql_error;
    /* get field values into form */
    EXEC IAF GET :field1, :field2 INTO :value1, :value2;
    /* manipulate the values to obtain result_val */
    ...
    /* put result_val into form field result */
    EXEC IAF PUT result VALUES (:result_val);
    return IAPSUCC;   /* trigger step succeeded */

sql_error:
    strcpy(errmsg, CONCAT("MYEXIT", sqlca.sqlerrm.sqlerrmc);
    errlen = strlen(errmsg);
    sqliem(errmsg, &errlen); /* send error msg to Forms */
    return IAPFAIL;

20.9 Precompiling and Compiling a User Exit

User exits are precompiled like standalone host programs. For instructions on compiling a user exit, see the Oracle installation or user's guide for your system.

20.10 Example Program: A User Exit

The following example shows a user exit.

/**************************************************************
Sample Program 5:  SQL*Forms User Exit

This user exit concatenates form fields.  To call the user 
exit from a SQL*Forms trigger, use the syntax

   user_exit('CONCAT field1, field2, ..., result_field');

where user_exit is a packaged procedure supplied with SQL*Forms
and CONCAT is the name of the user exit.  A sample form named
CONCAT invokes the user exit.
**************************************************************/

#define min(a, b) ((a < b) ? a : b)
#include <stdio.h>
#include <string.h>

/* Include the SQL Communications Area, a structure through which
 * Oracle makes runtime status information such as error
 * codes, warning flags, and diagnostic text available to the
 * program.
 */
#include <sqlca.h>

/* All host variables used in embedded SQL in this example
 * appear in the Declare Section.
 */
EXEC SQL BEGIN DECLARE SECTION;
    VARCHAR   field[81];
    VARCHAR   value[81];
    VARCHAR   result[241];
EXEC SQL END DECLARE SECTION;


/* Define the user exit, called "concat". */
int concat(cmd, cmdlen, msg, msglen, query)
char *cmd;     /* command line in trigger step ("CONCAT...") */
int  *cmdlen;  /* length of command line */
char *msg;     /* trigger step failure message from form */
int  *msglen;  /* length of failure message */
int  *query;   /* TRUE if invoked by post-query trigger,
                  FALSE otherwise */
{
    char *cp = cmd + 7;    /* pointer to field list in
                              cmd string; 7 characters
                              are needed for "CONCAT " */
    char *fp = (char*)&field.arr[0];  /* pointer to a field name in
                                         cmd string */
    char  errmsg[81];      /* message returned to SQL*Forms
                              on error */
    int   errlen;          /* length of message returned
                              to SQL*Forms */

/* Branch to label sqlerror if an ORACLE error occurs. */
    EXEC SQL WHENEVER SQLERROR GOTO sqlerror;

    result.arr[0] = '\0';

/* Parse field names from cmd string. */
    for (; *cp != '\0'; cp++)
    {
       if (*cp != ',' && *cp != ' ')
           /* Copy a field name into field.arr from cmd. */
       {
           *fp = *cp;
           fp++;
       }
       else
           if (*cp == ' ')
           {   /* Have whole field name now. */
               *fp = '\0';
               field.len = strlen((char *) field.arr);
               /* Get field value from form. */
               EXEC IAF GET :field INTO :value;
               value.arr[value.len] = '\0';
               strcat((char *) result.arr, (char *) value.arr);
               fp = (char *)&field.arr[0];  /* Reset field pointer. */
           }
    }

/* Have last field name now. */
    *fp = '\0';
    field.len = strlen((char *) field.arr);
    result.len = strlen((char *) result.arr);

/* Put result into form. */
    EXEC IAF PUT :field VALUES (:result);

/* Trigger step succeeded. */
    return(IAPSUCC);

sqlerror:
    strcpy(errmsg, "CONCAT: ");
    strncat(errmsg, sqlca.sqlerrm.sqlerrmc, min(72,
        sqlca.sqlerrm.sqlerrml));
    errlen = strlen(errmsg);
/* Pass error message to SQL*Forms status line. */
    sqliem(errmsg, &errlen);
    return(IAPFAIL);  /* Trigger step failed. */
}

20.11 Using the GENXTB Utility

The IAP program table IAPXTB in module IAPXIT contains an entry for each user exit linked into IAP. IAPXTB tells IAP the name, location, and host language of each user exit. When you add a new user exit to IAP, you must add a corresponding entry to IAPXTB. IAPXTB is derived from a database table, also named IAPXTB. You can modify the database table by running the GENXTB form on the operating system command line, as follows:

RUNFORM GENXTB username/password 

A form is displayed for you to enter the following information for each user exit you define:

• Exit name

  
  

  See Also: "Guidelines"

  
  

• C-language code

• Date created

• Date last modified

• Comments

After modifying the IAPXTB database table, use the GENXTB utility to read the table and create an Assembler or C source program that defines the module IAPXIT and the IAPXTB program table it contains. The source language used depends on your operating system. The syntax you use to run the GENXTB utility is

GENXTB username/password outfile 

where outfile is the name you give the Assembler or C source program that GENXTB creates.

20.12 Linking a User Exit into SQL*Forms

Before running a form that calls a user exit, you must link the user exit into IAP, the SQL*Forms component that runs a form. The user exit can be linked into your standard version of IAP or into a special version for those forms that call the exit.

To produce a new executable copy of IAP, link your user exit object module, the standard IAP modules, the IAPXIT module, and any modules needed from the Oracle and C link libraries.

The details of linking are system-dependent. Check the Oracle installation or user's guide for your system.

20.13 Guidelines

The guidelines in this section will help you avoid some

common pitfalls.

20.14 EXEC TOOLS Statements

EXEC TOOLS statements support the basic Oracle Toolset (Oracle Forms V4, Oracle Report V2, and Oracle Graphics V2) by providing a generic way to handle get, set, and exception callbacks from user exits. The following discussion focuses on Oracle Forms but the same concepts apply to Oracle Report and Oracle Graphics.

EXEC TOOLS SET form_variable[, ...] 
     VALUES ({:host_variable :indicator | constant}[, ...]); 

char ename[20];
short ename_ind;

...

    strcpy(ename, "MILLER");
    ename_ind = 0;
    EXEC TOOLS SET emp.ename VALUES (:ename :ename_ind);

EXEC TOOLS GET form_variable[, ...] 
    INTO :host_variable:indicator[, ...]; 

...
char     name_buff[20];
VARCHAR  name_fld[20];
 
strcpy(name_fld.arr, "EMP.NAME");
name_fld.len = strlen(name_fld.arr);
EXEC TOOLS GET :name_fld INTO :name_buff;

EXEC TOOLS SET CONTEXT :host_pointer_variable 
    IDENTIFIED BY context_name; 

... 
char  *context_ptr; 
char  context[20]; 
 
strcpy(context, "context1") 
EXEC TOOLS SET CONTEXT :context IDENTIFIED BY application1; 

EXEC TOOLS GET CONTEXT context_name 
    INTO :host_pointer_variable; 

... 
char  *context_ptr; 
 
EXEC TOOLS GET CONTEXT application1 INTO :context_ptr;  

EXEC TOOLS MESSAGE message_text [severity_code]; 

EXEC TOOLS MESSAGE 'Bad field name! Please reenter.';