Import-/Export-Facility

Userexits

The different kinds of userexits

Menu-userexits

Field-userexits

Tool userexits

Interface to IEF

Integrating own userexits or decision tables

An exemplary IEF userexit

 

The different kinds of userexits

During import and export IEF supports different kinds of userexits.

 

Menu Userexits

edb_ief_ctr_men() / edb_ief_ctr_chr()
Input/Output control

This userexit is a control function for all functions possible in Agile e6 IEF. This functions can be switched on or off with the transfer parameter, e.g. for the trace output, logging etc.

Parameter:

"P[arameter] <Parameter name> <value>"
With this function it is possible to transfer the values defined in the default setting. Here special care must be taken of the integer values as they must not contain any letters or characters in any case.
If this function is called up from a program, it is possible to transfer a value. If no value has been specified the current value is returned. For values of the data type "Char", the userexit "edb_ief_ctr_chr" must be used. It returns a character indicator.

  • "L[ogging] On"
    Switching on logging.
  • "L[ogging] Off"
    Switching off logging
  • "L[ogging] error log"
    Switching on the logging as an error log that means only faulty data records are recorded.
  • "L[ogging] ?"
    Displaying on screen if logging is switched on or off.
  • "T[est] Ein"
    Switching on trace mode.
  • "T[EST] Aus"
    Switching off trace mode.
  • "T[EST] ?"
    Display on screen if the trace mode is switched on or off.
  • "V[ersion]"
    Displaying current internal EDB IEF version on the screen.

edb_ief_put_dat_men()
Output to a file

This userexit writes data from a widget to a file in a predetermined format. It can either be called up in the selection menu or the no-selection menu. In the first case only the selected data records are transferred while in the second case all data records of the mask are transferred.

Parameter:

"<File symbol> <Format name> <Format version> <Resolution> [<Options>]"

  • <File symbol>:
    This value defines the name of an environment variable (icon) which contains the file name ( with path) of the file to be processed.
  • <Format name>:
    This value defines the name of the format with which the file is defined.
  • <Format version>:
    This value defines the version of the data format.
  • <Resolution>:
    For structure widgets (REF, NRF and STR) this value defines the resolution of the structure, that means which data of the structure is to be issued.
    • LAST
      Last data record of the structure.
    • FIRST
      First data record of the structure.
    • STR
      All data record of the structure.
  • <Options>:
    With options the default values of this call-up can be changed. /<Parameter name>=<value>. The following options are available (see also default values):
    • /ACTION
      (Transaction code to be used)
    • /ON-EXP-ERROR
      ("BREAK", "CONTINUE")
    • /ESTART-USX
      (Name of start userexit)
    • /ETST-TOP-USX
      (Name test parent userexit )
    • /ETST-REF-USX
      (Name test relationship userexit)
    • /ETST-BOT-USX
      (Name test component userexit)
    • /EEND-USX
      (Name end userexit )
    • /WHAT
      ("SEL", "SEL_FIRST", "ALL", "ROW")
      Selection of data records to be exported
      • SEL:
        all data records selected.
      • SEL_FIRST
        the first data record selected.
      • ALL:
        all data records in the mask.
      • ROW:
        only those lines transferred with "/ROW"
    • /ROW
      (Lines to be exported when "/WHAT=ROW")
    • /LEN
      (Number of lines to be exported when "/WHAT=ALL")
    • /IGN-VOID-STR=
      • 1
        Do not generate any data records if no position is contained in the structure
      • 0
        Generate a line in the file for the parent data record of a structure
    • /GET-DB-FLD
      • 1
        Exporting multi-lingual fields
      • 0
        Exporting only fields contained in the mask.
    • /TRA-INSERT
      Transaction code for insertion.
    • /TRA-MODIFY
      Transaction code for modification.
    • /GET-USR-ACC
      • 1
        Read User-ID, Group -Id and access rights for each data record from the data base. (This should only be carried out when the corresponding files do really exist. In data base views (e.g. in case of structure derivation) those fields do not exist.).
      • 0
        Do not read access right from the data base. @OWNER, @GROUP and @ACCESS must not be used in the filed definition.
    • /GTM-INS-DUP
      • 1
        Do not read access right from the data base. @OWNER, @GROUP and @ACCESS must not be used in the filed definition.
    • /GET-TOP-ACC
      • 1
        Set access rights of the farther element when exporting.

edb_ief_get_dat_men()
Reading in a file

This userexit reads in the data of a file according to a default format. It can be called up from any menu desired.

Parameter:

"<File symbol> <Format name> <Format version> [<Options>]"

  • <File symbol>:
    This value defines the name of an environment variable (icon) which contains the file name (with path) of the file to be processed.
  • <Format name>:
    This value defines the name of the format with which the file is read in.
  • <Format version>:
    This value defines the version of the data format.
  • <Options>:
    With these options the default values for this call-up can be modified. They are as follows /<Parameter name>=<value>. The following options are possible ( see also default values):
    • /REF-DEL
      • 1
        Deleting the positions existing before the import.
    • /TRA-STRICT
      • 1
        Follow transaction code.
    • /ART-UNQ
      • 1
        parent / child element must be unique.
    • /ENT-DEL-REF
      • 1
        Delete all relationships when deleting a data record.
    • /REF-INT-IDX
      • 1
        Integer position number for relationships .
    • /POS-COL-NAM ·
      Column number for position number.
    • /REF-IDX-INC
      Increment for position number.
    • /ISTART-USX
      Start userexit.
    • /IPRE-ACT-USX
      Pre-action userexit.
    • /IPST-ACT-USX
      Post-action userexit.
    • /IEND-USX
      Ende-Userexit
    • /ON-IMP-ERROR
      ("BREAK", "CONTINUE")
    • /PUT-DB-FLD
      • 1
        Importing multi-lingual fields.
      • 0
        Importing fields only contained in the mask.
    • /HEADnumber of lines to be left out at the beginning of the file.
    • /TST-IDX
      • 1
        Checking the position number.
    • /TRA-INSERT
      • 1
        Transaction code for insertion (refresh)
    • /TRA-MODIFY
      • 2
        Transaction code for modifications.
    • /TRA-DELETE
      • 3
        Transaction code for deleting.
    • /ACTION
      • 1
        Action to be sued if the IEF field definition has no @ACTION key word.
    • /CMP-OLD-NEW
      • 1
        Comparison of old and new field contents and no saving of the field if both are identical.

edb_ief_gen_fld_dsc()
Generate field description for a format

The menu userexit generates a default field description of a selected format. It reads out the field description of the mask from the DataView dictionary and enters the field names, Agile e6 start and end positions as well as the sequence number into the format description. Depending on the default setting, it is also possible to generate the file positions. If a format has no mask entry, a form asks for the mask which is saved in the format. If a field description does already exist it will not be changed. If however a new description shall be generated, the old field description must first of all be deleted (also from the trash).

The format description generated must generally be reviewed and if necessary additions must be made (e.g. selection fields set).
The sequence numbers start with 100 and are counted upwards in steps of 10 in order to have space for the extension (e.g. transaction code). Agile e6 start position is always one and the length of the field in the data base determines the end position. The file line identification is always "01". The file position of fields starts with one and is counted upwards continuously.

Parameter:

  • "[<File positions generating flag>]"
    This value defines if the file positions are to be generated"y" or not "n" or "". In the case of "n" the file start and end has the value one.

 

Field-Userexits

edb_ief_cal_pos()
Calculates the end position of a file field

In the format description this post field userexit is added to the field of the start position in the file. It calculates the end position of the file from the Agile e6 field positions as a default in the end position column. It is only executed with Insert or Update if the file end position has the value zero.

 

Tool userexits

edb_ief_left_just()
Field contents left-justified for import and export

This IEF-userexit aligns the field contents left-justified within the start and end position of the current configuration line defined in the configuration.

edb_ief_right_just()
Field contents right-justified for import and export

This IEF userexit aligns the field contents right-justified within the start and end position of the current configuration line defined in the configuration.

edb_ief_blank_to_0()
Replace all blanks with the number zero

This IEF userexit replaces all blanks in the current field with the number "0".

edb_ief_no_log()
Do not record current data

This IEF pre-action userexit sets the error status to "No protocol output" for the current data record.

edb_ief_ign_dat_usx()
Ignore current data record

If this IEF userexit is called up as a field userexit in a conversion line of the field description, it is ignored in the current conversion line. If it is called up as a pre-action userexit, the complete data record is ignored. In such a case a report message is issued.

Output of all parameters for testing

This userexit issues all parameters transferred to it. It should always be used in order to determine the parameter transferred by IEF to the userexit in the current version.

edb_ief_uppercase()
Field contents in uppercase when importing or exporting

This IEF userexit converts the field contents within the start and end position defined in the configuration to uppercase letters in the configuration line.

edb_ief_lowercase()
Field contents in lowercase when importing and exporting

This IEF userexit converts the field contents within the start and end position defined in the configuration to lowercase letters in the configuration line.

edb_ief_run()
Calling up an operating system command

This IEF userexit executes an operating system command (e.g. start of a command procedure or a program). All call-up parameters are determined by the userexit transferred. It can be called up as a pre-action or post-action userexit.
The first value in the user parameter is an operating system variable in which the real operating system call-up is defined. All other values in the user parameters determine the contents of the action parameter to be transferred to the command as a parameter.

Example:
Userexit entry:
edb_ief_run(CPY_FIL_SYM,FILE,FUNCTION)

Contents of variables:
Contents of CPY_FIL_SYM="$EDB_COM/cpy_file.com"
Contents of FILE=EDB_ART_EXP_DAT
Contents of EDB_ART_EXP_DAT= "$EDB_TMP/export.dat"
Contents of FUNCTION="EXPORT"

The call-up of the operating system command will then be as follows:
$EDB_COM/cpy_file.com "EDB_ART_EXP_DAT" "EXPORT"


UNIX:
filesym=\$$1
eva filename=$filesym

VMS:
filename='P1'

edb_ief_usrname_2_id()
Converts user name to User-ID

This IEF-field userexit converts a user name possibly transferred to the internal DataView user code so that the owner of the data record can be set by the external system when reading in.

edb_ief_usrid_2_name()
Converts User-ID to user name

This IEF field userexit converts a DATAVIEW User-ID determined to the corresponding user name, so that the user name can be transferred to the external system when exporting.

edb_ief_grpid_2_name()
Converts Group-ID to group name

This IEF field userexit converts a DATAVIEW Group-ID determined during export to the corresponding group name, so that the group name can be transferred to the external system when exporting.

edb_ief_set_usr_acc()
Setting user and access rights

This IEF post-action userexit determines the owner, the group and the access rights for the read-in data record when reading in. If the user parameter has the value (TOP), the rights and users of the parent elements are used for relationships.

It is necessary that always all three values are set. If the userexit is used "@USER", "@GROUP" and "@RIGHTS" must be entered in the field definition. This data records might otherwise belong to the user "SYSTEM and the group "DATAVIEW".

edb_ief_write_buf()
Writing a line in the file

This IEF field export userexit enables to write data records in several lines of the output file. It must be called up as an export field userexit in its own individual line in which the EDB field is occupied with @XITand the column file line with @XIT. The buffer contents collected up to now is written to the file. All following configuration lines then describe the structure of further lines in the file for a data record. The last line of a data record must not be written to the file with this function. The buffer area must if necessary be deleted after calling up this function. (@BLANK).

edb_ief_read_buf()
Reading a new line from the file

This IEF field userexit enables to read data records from the file which are placed in several lines. The line number in the file for a data record must be constant in this case. The userexit must be called up as an import field userexit in an individual line in which the column EDB field is occupied with @XIT and the col-umn file line with @XIT. The last line of a data record must not be written to the file with this function.

edb_ief_set_val()
Setting a return value

This IEF-int function enables the transfer of a value modified in the userexit to the IEF functions. From IEF revision 1.9 on the values must be set with this function and must not be transferred as a CHAR-RETURN value.

Call-up:
i_ret = edb_ief_set_val (0, cp_return);

whereas cp_return can be the return value or ZERO.

edb_ief_get_sep_fld()
Reading a divided field from a file

This IEF field import userexit enables to read out fields from a file which are determined by a field separator. It is therefor possible to read in variable file formats.

Call-up as IEF Import userexit in the IEF field definition:
edb_ief_get_sep_fld(<data delimiter>,<Field number>)

whereas

  • <data delimiter> can exactly be one character long and must be the same for all fields.
  • <Field number> specifies the number of the field to be read out in the file line (starting with one).

Example:
edb_ief_get_sep_fld(;,1)
edb_ief_get_sep_fld(;,2)
edb_ief_get_sep_fld(;,11)

 

edb_ief_del_lead_0
The userexit deleted leading zeros.

With the parameter (LEFT) the field contents is aligned left-justified. With the parameter (RIGHT) the field contents is aligned right-justified.

edb_ief_def_val (<par>)
The IEF field userexit inserts a default value if the field is empty.

The value to be inserted must be transferred as a parameter. If the value starts with "@", a default value with this name is searched for in the EDB system defaults and its contents is inserted. It is therefore possible to insert user-specific default values. If the first character is "\", the following "@" is not interpreted as an EDB system default but inserted in the field as specified.

edb_ief_wri_ascii(<ASCII-value>)

This IEF field userexit enable to fill an EDB field or output file with non-printable characters e.g. with this it is possible to write the tab character. Only one value is possible.

Example:
eedb_ief_wri_ascii(9)
This userexit is called up as an export field userexit in the IEF field definition, here the <TAB> character is inserted in the line position specified by the field definition.

 

Interface to IEF

With the interface programs for IEF it, is possible to convert fields from an EDB mask to a string and vice versa with the help of an IEF format definition. These functions can also be called up from LogiView.

edb_ief_mas_2_str
Mask contents to string

This function enables the conversion of the mask contents of the current EDB mask to a character string. With this it is possible to use the IEF format definition from any userexit desired. The function must first be called up with the control character 'I' and then with the control character 'F' (also with different formats).

Call-up
ret = edb_ief_mas_2_str (fmt, fmtver, wdg, row, str, len, act, pos, log, ctr);

ret off int Return value of function (0 = no error)
fmt on char* Format name of the IEF format to be applied
fmtver on char* Format version of the IEF format
wdg on int Widget-Id of the mask or "0" for current widget
row on long Line number of the mask from which the field contents is read
str off char* Character string to which the data is to be written
Len on int Length of the character strings
act on char* Transaction code which is written into the string at the position "@ACTION".
POs on str Position number which is written to the string at the position "@INDEX".
log off char* Report output which is defined in the format with "@LOGINFO"
ctr on char Control character for filling in the string:
  • " I " Implementation of the string
  • " F " Filling the string with the mask contents

edb_ief_mas_2_lgvstr
Mask contents to LOGIVIEW string

This function enables the conversion of the mask contents of the current EDB mask to a character string in LogiView.
The call-up of this function is only allowed in a decision table or LogiView procedure.

Call-up:
ret = #edb_ief_mas_2_lgvstr (fmt, fmtver, wdg, row, str, Len, act, POs, log, ctr);

ret off int Return value of function (0 = no error)
fmt on char* Format name of the IEF format to be applied
fmtver on str Format version of the IEF format
wdg on int Widget-Id of the mask or "0" for current widget
row on int Line number of the mask from which the field contents is read
str off str Character string to which the data is to be written
Len on int Length of the character strings
act on str Transaction code which is written into the string at the position "@ACTION".
POs on str Position number which is written to the string at the position "@INDEX".
log off str Report output which is defined in the format with "@LOGINFO"
ctr on str Control character for filling in the string::
  • " I" Implementation of the string
  • " F " Filling the string with the mask contents

edb_ief_str_2_mas
String contents to EDB mask

This function enables the conversion of a string contents to the field of an EDB mask. With this it is possible to use the IEF format definition from any userexit desired.

Call-up:
ret = edb_ief_str_2_mas (fmt, fmtver, wdg, row, str, Len, act, POs, log, ctr);

ret off int Return value of function (0 = no error)
fmt on char* Format name of the IEF format to be applied
fmtver on char* Format version of the IEF format
wdg on int Widget-Id of the mask or "0" for current widget
row on long Line number of the mask from which the field contents is read
str on char* Character string to which the data is to be written
Len on int Length of the character strings
act off char* Transaction code which is written into the string at the position "@ACTION".
POs off str Position number which is written to the string at the position "@INDEX".
log off char* Report output which is defined in the format with "@LOGINFO"
ctr on char Control character for filling in the string:
  • " F " Filling the string with the mask contents
  • " M " marks the row (DTV: mas_set_drt_rec)
  • " W " marking the row and saving the widget contents in the database (DTV: mas_set_drt_rec and wdh_wri_lis).
    The mask contents is not changed.

edb_ief_lgvstr_2_mas
LogiView string contents to EDB mask

This function enables the conversion of the string contents to the field of an EDB mask within a decision table or a LogiView procedure.
The call-up of this function is only allowed in a decision table or LogiView procedure.

Call-up
ret = #edb_ief_lgvstr_2_mas (fmt, fmtver, wdg, row, str, Len, act, POs, log, ctr);

ret off int Return value of function (0 = no error)
fmt on str Format name of the IEF format to be applied
fmtver on str Format version of the IEF format
wdg on int Widget-Id of the mask or "0" for current widget
row on int Line number of the mask from which the field contents is read
str on str Character string to which the data is to be written
Len on int Length of the character strings
act off str Transaction code which is written into the string at the position "@ACTION".
POs off str Position number which is written to the string at the position "@INDEX".
log off str Report output which is defined in the format with "@LOGINFO"
ctr on str Control character for filling in the string:
  • " F " Filling the string with the mask contents
  • " M " marking the row (DTV: mas_set_drt_rec)
  • " W " marking the row and saving the widget contents in the database (DTV: mas_set_drt_rec and wdh_wri_lis).
    The mask contents is not changed.

 

Integrating own userexits or decision tables

Userexits

There are two kinds of userexits in IEF:

The field userexits are initiated every time a field definition line is processed. In relationships they are also called up when searching for components or the parent as well as when entering data into the EDB fields or in the file:


Action userexits are executed with the following actions:

All userexits must be contained in the Agile e6 programs. The userexits must be INT-functions . A string is transferred which can be processed with the functions zag_get_buf_elm and zag_set_buf_elm The modified data is returned to IEF with the IEF function "edb_ief_set_val". If the data is not modified, the return value "ZERO" shall be entered. (speed).

Example:
i_ret = edb_ief_set_val (0, cp_buffer);
The contents of the userexit can have a maximum length of 40 characters.

 

Call-up parameter

Parameters can be specified for the name of the userexit ( user parameter) by dividing the individual parameters with comma and including them in parenthesis. The whole string must not contain any "white space". This user parameters are converted by "PARAM".

Example :
usx_wrt_prot(protokoll.dat,datum,zeit)
A character string is transferred to the userexits. This character string can be reduced to its elements with the function zag_get_buf_elm. The parameters can be displayed with the tool userexit "edb_ief_tst_usx".

The userexit must return a character string with exactly the same structure and the possibly occurred error code (ERROR) as well as an action to be executed (ACTION). If no values are to be returned a ZERO pointer is to be transferred as the analysis would be quicker.

The following table gives information on the parameters which can be transferred to the userexits:

Key Import Import Export Export LogiView

Field-
Userexit
Actions-
Userexit
Field-
Userexit
Actions-
Userexit
ET-
Call-up
WIDGET
X
X X
MASK X X X X X
ROW X X X X X
PARAM X X X X
ERROR X X X X X
ACTION X X X X X
IS_ACTION X X
X X
FIELD X
X
X
OLD_FIELD X


X
FORMAT X X X X
FUNCTION IMP. IMP. EXP. EXP. X
BUFFER X
X

PART_ID X
X

SHEET X
X

VERSION X
X

REVISION X
X

RIGHTS
X
X
OWNER
X
X
GROUP
X
X
K-ROW

X (internal)

WHAT


X
FILE
X
X

The following return parameters can be set:

Key Import Import Export Export LogiView
Field-
Userexit
Actions-
Userexit
Field-
Userexit
Actions-
Userexit
ET-
Call-up
ERROR X X X X X
FIELD X
X
X
FILE
X
X
ACTION
X

X
OWNER
X


GROUP
X


RIGHTS
X


As in the course of the further development other parameters might be added the userexit edb_ief_tst_usx which issues all currently transferred parameters on stderr output.

 

Include files

The userexits must be announced in the IEF header files.
As for EDB or DTV userexits they must be declared in the file ief_dcl.h.In the file ief_usx.h the name is specified so that the IEF userexit menu can be built.

Example:
ief_dcl.h int my_own_ief_usx()
ief_usx.h USX->fnc = my_own_ief_usx;
USX->nam = "my_own_ief_usx";
USX++;

 

Decision tables and procedures

At any position where a userexit can be placed it is also possible to call up a decision table or a LOGIVIEW procedure.
A decision table or procedure is indicated by the character"@" (e.g. "@LV_VERBUND/ LV_PROZEDUR") placed in front.
The data transfer between LOGIVIEW and IEF is carried out via LOGIVIEW system variables.
The following LOGIVIEW variables can be employed:

 

An exemplary IEF userexit

/********  Informational PART *****************
MODUL : IEF
PROJECT : EDB
DESCRIPTION : Userexitfunktionen fuer die Import-Export-Facility
MODIFICATIONS:
Date Name Description
************ DECLARATIONAL PART **************/
/* INCLUDED FILES: */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#include "epz_zag.h2"
#include <errno.h>

#include "epqpara.h"
#include "epqerror.h"
#include "epqdatendef.h"
#include "glbdef.h"
#include "fncdef.h"
#include "wdgdef.h"
/* Include for the IEF error messages */
#include "ief_error.h"
/* Include for parameterising  */
#include "ief_para.h"
/* MODUL LOCAL CONSTANTS:  */
/* DEFINES     */
#define VIR_MOD_OFF       0
#define VIR_MOD_ON 1
/* EXTERN REFERENCES    */
/* EXTERNAL FUNCTIONS */
/* USED FUNCTIONS */
/* int kun_ief_my_usx (par) #001  Examplary  userexit */
/* MODUL GLOBAL VARIABLES  */
/************ IMPLEMENTATIONAL PART **********/
/***************#001 *************************/
/******** START OF FUNCTION ******************/
/*********************************************/
int kun_ief_my_usx (par)
/* INPUT: */
char *par;
/* OUTPUT */
/*********************************************/
/* */
/* RETURN-CODE: */
/* */
/* REMARKS : */
/* */
/* DESCRIPTION: ´ */
/* This userexit replaces all lowercase letters with uppercase letters */
/* */
{ /*******************************************/
char *cp_buffer;
char ca_field [ MAX_STR_LEN +1];
int ok;
/****************** CODING PART **************/
/* */
/*********************************************/
zag_tst ("KUN-USX", 1, "kun_ief_my_usx","Start of function", NULL, NULL, NULL);
cp_buffer = NULL;
ok = zag_get_buf_elm (par, "FIELD", ca_field);
if (ok == 0)
{
ok = bsf_upp_cas (ca_field);
if (ok == 0)
{
cp_buffer = zag_set_buf_elm (cp_buffer, "FIELD", ca_field);
}
else
{
sprintf (ca_field, "%d", ok);
cp_buffer = zag_set_buf_elm (cp_buffer, "ERROR", ca_field);
}
}
ok = edb_ief_set_val (0, cp_buffer);
return (0);
}/****** END OF FUNCTION *********************/