Import/export templates: Technical appendix 

Import processing and associated actions

The object import and export is performed using a process created from the compilation of the template. This temporary process is named WWINNNNNN or WWENNNNNN (NNNNNN being an incremental number).

For exports, the process only extracts data (filtered according to the user authorizations). For imports, the process contains instructions to decode the data flow and calls the functions linked to the object to be imported by "emulating" the entry. Thus, the standard labels for the SUBXXX and SPEXXX processes, which are used to manage the objects, have standard names.

Additional specific/custom labels are called on import, defined in the IMPXXX process (if it exists) and in the specific/custom process defined in the template. The chronologies that follow describe how the import takes place when different object types are used (see the documentation in the Object management for more information). In the table below, the actions of the standard object are indicated in italic, those linked to the import are in bold.

The Actions column shows the actions performed right after the operation defined in the context. For example, for a simple object, looking at section 8.2:

  • the actions VERIF_MOD and IMP_VERIF_MOD are carried out.
  • the record is locked, then the actions AVANT_MODFIC and IMP_AVANT_MODFIC are carried out.
  • the variables of class [F] are assigned, then the actions INIMOD and IMP_INIMOD are performed.
  • they are re-written, then the MODIF and IMP_MODIF actions are performed.
  • the transaction operation is carried out (Commit), then the actions APRES_MOD and IMP_APRES_MOD.
  • unlock, then the actions DEVERROU and IMP_DEVERROU are performed.

It should be noted that the actions located in the specific/custom import process are performed before the standard import process; if the specific/custom import process sets the GPE variable to 1, the standard import process action is inhibited.

Single object

Sequence

Context

Actions

1.1

Before creation of the import program:

The Openo, which is used to write the temporary import program (for the name given by the IMPTRT variable) that has not yet been created.

It is possible to change the name of the masks used (NOMMSK table, the number of masks given by NBMASK)

IMP_COMPILE

1.2

After creation of the import program:

The temporary import process (the name given by the IMPTRT variable) is always opened by Openo: it is therefore possible to add other instructions (by Wrseq).

The process will be compiled after this action, then the import process can start.

IMP_TRTSUP

2

Program start

OUVRE IMP_OUVRE

3

Reading the header record

Transfer to the class [F]

The AP_IMPORT action is called after the loading of the variables decoded in each section (the level of overlapping is identified by the variable SEPNUM from 1 to 8), the abbreviation for the principal table for the current process is identified in the variable IMPABR

 

 

AP_IMPORT

4

Verification of the authorization to create or

to modify:

SETBOUT IMP_SETBOUT (*)

5

Object existence test:

 

5.1

If the OBJect does not exist:

SETBOUT IMP_SETBOUT
RAZCREIMP_RAZCRE

5.2

If the OBJect exists:

Then, loading the record

Re-verification of the authorizations

VERROU IMP_VERROU

LIENSIMP_LIENS

SETBOUT IMP_SETBOUT

AVANT_MOD IMP_AVANT_MOD

6.1

Entry simulation in the associated screens

in the principal table

IMPORT

IMP_DEFTRT (*)

6.2

For each field in the screen:

Execution of the before_field actions

before_entry

init

If the field is entered:

To understand if the field is in a grid:

(this action assigns nolign if necessary)

If OK=1, transfer from class [F]

To a field of the same name

Execution of the after_field actions

And as necessary after_modif

 

 

 

 

 

 

IMP_ZONE

7.1

Reading the record in the secondary file (this is carried out for all the secondary level records)

 

IMPORT

IMP_TAB

 

AP_IMPORT

 

7.2

Simulation of associated screens.

In the case of a grid, the variable

nolign is used.

By default, a line is added

(nolign = 0)

 

*8

Recording of the OBJect

 

8.1

In the case of creation:

Transaction start

Write

Transaction end

 

 

In the case of Rollback:

VERIF_CRE IMP_VERIF_CRE

INICREIMP_INICRE

CREATION IMP_CREATION

APRES_CRE IMP_APRES_CRE

 

AB_CREATION

IMP_AB_CREATION

8.2

In the case of modification:

Transaction start

Locking of the record

Assigning the variables [F]

Re-write

Transaction end

 

 

In the case of Rollback:

Unlocking

VERIF_MOD IMP_VERIF_MOD

AVANT_MODFIC

IMP_AVANT_MODFIC

INIMODIMP_INIMOD

MODIF IMP_MODIF (*)

APRES_MOD IMP_APRES_MOD

 

AB_MODIF IMP_AB_MODIF

DEVERROU IMP_DEVERROU

9

End of program:

FERME IMP_FERME

(*) The MODIF and IMP_MODIF actions are usually used to manage the saving of the lines (MODIF is used as standard by the management of the OBJect, IMP_MODIF making it possible to manage the additional actions). The IMP_DEFTRT action is used, if necessary, to reassign the TRTMSK variable, which defines the name of the automatic process defined in the screen dictionary. 

The IMP_SETBOUT action is used to enter the object management options. For example, setting a VIREBOUT call on import to prevent the object creation, which would affect the CHAINE variable that contains all the options.

Combined object

Sequence

Context

Actions

1.1

Before creation of the import program:

The Openo which is used to write the temporary import program (for the name given by the IMPTRT variable) that has not yet been created.

It is possible to change the name of the masks used (NOMMSK table, the number of masks given by NBMASK)

IMP_COMPILE

1.2

After creation of the import program:

The temporary import process (the name given by the variable IMPTRT) is always opened by Openo: it is therefore possible to add (by Wrseq) other instructions.

The process will be compiled after this action, then the import process can start.

IMP_TRTSUP

1.3

Program start

OUVREIMP_OUVRE

2

Read of the import file and transfer in class [F]

The AP_IMPORT action is called after the loading of the variables decoded in each section (the level of overlapping is identified by the variable SEPNUM from 1 to 8), the abbreviation for the principal table for the current process is identified in the variable IMPABR

AP_IMPORT

3

Test for the existence of the OBJect (number of lines >0)

 

3.1

If the OBJect exists:

VERROUIMP_VERROU

3.2

Verification of the authorization to create or

to modify :

SETBOUTIMP_SETBOUT (*)

3.3

If the OBJect does not exist:

SETBOUTIMP_SETBOUT (*)

RAZCREIMP_RAZCRE

4.1

Loop in the reading of the records

Records linked to each line :

Transfer to the class [F]

End of read loop

Records lined to the end of the loop :

FILTRE

LIENS0IMP_LIENS0

LIENSIMP_LIENS

 

LIENS2IMP_LIENS2

5.1

Entry simulation in the associated screens

in the principal table

IMPORT

IMP_DEFTRT (*)

5.2

For each field in the screen:

Execution of the before_field actions

before_entry

init

If the field is entered:

If OK=1, transfer from class [F] to the field of the same name

Execution of the actions after_fieldand if necessary after_modif

 

 

 

 

IMP_ZONE

6.1

Reading a record from the secondary file

The AP_IMPORT action is called after the loading of the variables decoded in each section (the level of overlapping is identified by the variable SEPNUM from 1 to 8), the abbreviation for the principal table for the current process is identified in the variable IMPABR

IMPORT

 

AP_IMPORT

6.2

Simulation of associated screens.

In the case of a table, the variable nolign is used.

By default, a line is added

( nolign = 0)

 

7

Recording of the OBJect

 

7.1

In the case of creation:

 

Transaction start

For each line :

Write

 

At the end of the line read:

Transaction terminated:

VERIF_CRE IMP_VERIF_CRE

DEBUT_CRE IMP_DEBUT_CRE

INICREIMP_INICRE

CREATIONIMP_CREATION

MODIFIMP_MODIF

APRES_CREIMP_APRES_CRE

7.2

In the case of modification:

  Transaction start

Deletion of the lines

Loop on the lines :

 

Creation of the line

At the end of the loop

Transaction end

VERIF_MOD IMP_VERIF_MOD

DEBUT_MOD

IMP_DEBUT_MOD

FILTRE

INICREIMP_INICRE

CREATIONIMP_CREATION

MODIFIMP_MODIF

APRES_MODIMP_APRES_MOD DEVERROUIMP_DEVERROU

*8

End of program:

FERME IMP_FERME

 

Grid object

Sequence

Context

Actions

1.1

Before creation of the import program:

The Openo which is used to write the temporary import program (for the name given by the IMPTRT variable) that has not yet been created.

It is possible to change the name of the masks used (NOMMSK table, the number of masks given by NBMASK)

IMP_COMPILE

1.2

After creation of the import program:

The temporary import process (the name given by the variable IMPTRT) is always opened by Openo: it is therefore possible to add (by Wrseq) other instructions.

The process will be compiled after this action, then the import process can start.

IMP_TRTSUP

1.3

Program start

OUVREIMP_OUVRE

2

Read the data in the file and loading of class [F]

The AP_IMPORT action is called after loading the variables decoded in each section (the degree of overlapping is identified by the SEPNUM variable from 1 to 8), the abbreviation of the main table for the current process is identified in the IMPABR variable.

 

AP_IMPORT

3

If the object exists:

VERROUIMP_VERROU

4

Locking the table

Reading start:

Loop in the reading of the records

When the reading ends

FILTRE

LIENS0IMP_LIENS0

LIENSIMP_LIENS

LIENS2IMP_LIENS2

5

Checking the authorization to modify:

SETBOUTIMP_SETBOUT (*)

6.1

Entry simulation in the associated screens

in the main table

IMPORT

IMP_DEFTRT (*)

6.2

For each field in the screen:

Executing the before_field actions

before_entry

init

If the field is entered:

If OK=1, transfer from class [F] to the corresponding field

Executing the actions after_fieldand if necessary after_modif

 

 

 

 

IMP_ZONE

7.1

Reading a record from the secondary file

IMPORT

7.2

Simulating the associated screens.

a line is added to the grid (nolign is managed by the object management)

 

*8

Recording of the object

 

8.1

Still in creation

Transaction start

locking the table

if OK<>0 following MOD_IMPORT,

the transaction is running:

Deleting all the existing records

For each line:

Write

Once the lines have been written:

End of transaction

VERIF_MOD IMP_VERIF_MOD

MOD_IMPORT

 

FILTRE

INICREIMP_INICRE

CREATIONIMP_CREATION

MODIFIMP_MODIF

9

When the transaction is successful

APRES_MODIMP_APRES_MOD

10

End of program:

FERMEIMP_FERME

 

The actions of the IMPxxx process

All the IMPxxx actions have the same context as those of the SUBxxx and are named after them.

The following actions are specific.

IMPORT action

The IMPORT action is called after each record read.

The IMPFIC variable contains the abbreviation of the imported file. The corresponding class is on line (for the information actually imported).

For grids, the nolign variable is set to 0 and is used to identify which line is entered upon exit. If nolign is remains to zero, a new line is created.

IMP_TAB action

The IMPORT action is used to manage the fields in a secondary table arranged in a grid (page 3 of the object defines the secondary tables, the screens and the variables at the bottom of the corresponding grid). This is used to identify non indexed fields (that will be be sorted in a grid) from the other fields. This action is only used for standard object imports.

IMP_ZONE action

The IMP_ZONE action is called instead of a field entry. It is used to recover a value in a screen, whose name may be different in the file (e.g.: sized fields in a table can correspond to several columns in a grid):

  • The IMPFIC variable contains the abbreviation of the file that triggered the entry.
  • The IMPMSK variable contains the name of the screen being entered.
  • The IMPZON variable contains the name of the field being entered.
  • The IMPMOD variable, preset to 0, is used to trigger the action after_modif.
  • The OK variable, initialized to 1, is used to/not to trigger the standard action.

MOD_IMPORT action

The MOD_IMPORT action is only used in the import of an object grid (in order to prohibit this import if necessary).

The specific/custom import process

This import process skips the standard management of the object (for better performances), and only includes a restricted number of labels called by Gosub from the import function. These labels are defined below:

Label

Context

$OUVRE

When the import starts, this label is used to declare the required masks, tables and variables.

$RAZCRE

When the reading starts (reading a new record). This is used to reset the variables to zero, before they get populated again by the import.

$SAIMSK

When a group of data has been read. The IMPFIC variable is used to identify the abbreviation of the table whose contents have been read. The [F] class corresponding to this table is then entered and it is possible to perform the transfer of data to the masks. When working with objects of the header / line type, the data is usually temporarily stored in a mask.

$VALID

The reading of the data is complete : This label is used to carryout the controls and to create or modify the data in the database.

It is only advisable to use this import method if specific performance problems exist. In fact, even if it takes more time to perform, the "standard" object import makes it possible to have an automatic control that includes what is described in the object logic, whilst the specific/custom import program requires all this to be done by hand.

Transcoding files

Transcoding principle:

In the import or export template, ADONIX X3 receives a data flow in a set of characters which is not necessarily the internal set of characters (set of characters being WE8ISO8951P1 in oracle). It is necessary to be able to transcode it. Please note that this document only addresses the transcoding of characters stored over one byte, which usually correspond to accented characters or characters specific to some Western languages. These characters are usually encoded on one byte with values between 160 and 250. You will find here the equivalence between these characters and the standard ASCII codes used by ADONIX X3 (displayed in Arial):

Byte

0

1

2

3

4

5

6

7

*8

9

16…

¡

¢

£

¤

¥

¦

§

¨

©

17…

ª

«

¬

®

¯

°

±

²

³

18…

´

µ

·

¸

¹

º

"

¼

½

19…

¾

¿

À

Á

Â

Ã

Ä

Å

Æ

Ç

20…

È

É

Ê

Ë

Ì

Í

Î

Ï

Ð

Ñ

21…

Ò

Ó

Ô

Õ

Ö

×

Ø

Ù

Ú

Û

22…

Ü

Ý

Þ

ß

to

á

â

ã

ä

å

23…

æ

ç

è

é

ê

ë

ì

í

î

ï

24…

ð

ñ

ò

ó

ô

õ

ö

÷

ø

ù

25…

ú

û

ü

ý

þ

ÿ

This is performed via field Character sets in the transcoding section. The field is populated with the values specified in Local menu 9. This local menu cannot be set up by default, but it is possible to add values in development in order to manage new external characters sets.

To each value of this local menu corresponds an external file, which is installed on the server and defines the required transcoding operations. This file can be found in the SYS directory of the X3 folder. Its name is TRANS#.cnv, where # corresponds to the local menu number (1, 2, 3…). The TRANS#.cnv file must be encoded with a UNIX format and UTF8 character set. Otherwise, the transcoding operation will not work during the import/export process.

The SYS directory does not exist by default. You need to create the folder for the entry point.

Example of access path to the SYS directory: SAGE\SAGEX3V6\X3V6SQL\Folders\DEMO\SYS

The TRANS0.cnv file contains comments explaining how you should proceed:

  • First define two lines where you need to enter:
    • adonix="string1"
    • output="string2"

string 1 and string2 are 3-character long prefixes corresponding to the set code to be defined. For instance, you can use the ado predix for string1, and set for the second set of characters.

  • First define the lines to define each character by allocating them a mnemonic identifier (with string1 or string2 as prefix) followed by an equal sign and the character code. For instance, when identifying the acute accent with eacute, consider that the character is transcoded in the set target character set with decimal code 238 (the code is 233 in the ado set). In this case, the two following lines would be written:
    • adoeacute="238"
    • seteacute="233"

Please note:
  • Double quotes are not mandatory (you can write adoeacute=238).
  • Codes can also be given in byte format, in the form \nnn, and in hexadecimal format in the form Hxx.
  • The order for line display is not important: you can define all the characters of a set first, then those of the new set, pair the characters together, or use any other order.
  • The characters that are not described (or described in a one set but not the other) are not transcoded.
  • The comment lines can be freely inserted or added at the end of a line, provided that they are prefixed by '#'.

File example: TRANS0.cnv

The content of the TRANSO.cnv, which explains the procedure, can be found below:

#
########################################################################
#
# trans0.cnv
#
# Transcodification file used for ADONIX X3 import/export
#
# Each line (except the comments prefixed by # ) must have the following format
#
# adoxxxxx = value1 or extxxxxx = value2
#
# (ado for adonix internal code, ext for "external" file code
#
# xxxxx is an identifier used to associate external & internal code together
#

# values can be defined in following formats :
#
# nnn or "nnn"         value in decimal
# \nnn or "\nnn"       value in octal
# Hnnn or "Hnnn"       value in hexadecimal
#
# Author: Bertrand YVINEC   
# Translated by Dominique BOPP
#
# Copyright (c) ADONIX 1992-2001
#
########################################################################
#
# Identifier definition (default is ado and ext)
#
adonix = "iso"
output = "ibm"

Exemple de fichier : TRANS2.cnv

This file is used to transcode in the IBM PC set. In this file, most of the comment lines were left out.

#
########################################################################
# trans2.cnv
# Copyright (c) ADONIX 1992-2001
########################################################################
adonix = "iso"
output = "ibm"
#
# ISO code first
isoagr="\340"    # a grave
isoeai="\351"    # e acute
isoegr="\350"    # e grave
isocce="\347"    # c cedilla
isougr="\371"    # u grave
isodeg="\260"    # degree
isoali="\247"    # alinea
isoaci="\342"    # a circumflex
isoeci="\352"    # e circumflex
isoici="\356"    # i circumflex
isooci="\364"    # o circumflex
isouci="\373"    # u circumflex
isoatr="\344"    # a dieresis
isoetr="\353"    # e dieresis
isoitr="\357"    # i dieresis
isootr="\366"    # o dieresis
isoutr="\374"    # u dieresis
isopou="\243"    # pound
#
# Ensuite en code PC
ibmagr="\205"    # a grave
ibmeai="\202"    # e acute
ibmegr="\212"    # e grave
ibmcce="\207"    # c cedilla
ibmugr="\227"    # u grave
ibmdeg="\370"    # degree
ibmali="\365"    # alinea (CP 850)
ibmaci="\203"    # a circumflex
ibmeci="\210"    # e circumflex
ibmici="\214"    # i circumflex
ibmoci="\223"    # o circumflex
ibmuci="\226"    # u circumflex
ibmatr="\204"    # a dieresis
ibmetr="\211"    # e dieresis
ibmitr="\213"    # i dieresis
ibmotr="\224"    # o dieresis
ibmutr="\201"    # u dieresis
ibmpou="\234"    # pound

Silent import

Call principle

If an import is required directly within a process, it can be performed by inserting the following lines:

If !GSERVEUR
    Call OUVRE_TRACE(TIT) From LECFIC
Endif
Call IMPORTSIL([L]COD_MODELE,[L]NOM_FICHIER)from GIMPOBJ
If !GSERVEUR
    Call CLOSE_LOC From LECFIC
Endif

 With

  • [L]COD_MODELE=Variable defining the import template code
  • [L]NOM_FICHIER=Variable defining the full name of the file to import

Involved variables

The variables passed on to the argument are the following: 

  • [L]COD_MODELE=Variable defining the import template code
  • [L]NOM_FICHIER=Variable defining the full name of the file to import

The import end status may be retrieved from the [M:IMP2]STAT field.
The plain text of the error message can be viewed by calling the following sub-program:

Call ERR_IMPORT([M:IMP2]STAT,MESSAGE) From GIMPOBJ