(a) Function format

#include<hds_ucommon.h>
#include<hds_ureflect.h>
 int hds_ubegin(UINTERFACE_BLK *interface-block-name,long *status);

(b) Explanation of the parameters

UINTERFACE_BLK *interface-block-name

To inherit information to the hds_uedit() or hds_uend() function, specify the name of the area used to store the information. The caller allocates UINTERFACE_BLK. The following table shows the contents of the interface block.

Table 8-4 Contents of the interface block (UINTERFACE_BLK)

Member name	Length (bytes)	Attribute	Area name	Defined by	Description
auth_id	8	char	Authorization identifier	Caller	Connection authorization identifier specified in the import system definition
password	30	char	Password	Caller	Password specified in the import system definition
exsysid	2	char	Source Datareplicator identifier	Extractor	Source Datareplicator identifier specified in the source Datareplicator's extraction system definition, expressed as a string of lowercase hexadecimal characters. During data linkage with XDM/DS, 00 is set.
repid1	2	char	Identifier 1	Caller	Data linkage identifier specified in the import system definition
repid2	2	char	Identifier 2	Caller	Target Datareplicator identifier specified in the import system definition
*inherinf1	4	char *	Inherited information 1	Caller	Address of the area to be inherited to the hds_uedit() and hds_uend() functions
inherinf2	4	long	Inherited information 2	Caller	Information to be inherited to the hds_uedit() and hds_uend() functions
stopinf	4	long	Termination mode	Caller	UOC routine termination mode (this area is effective only during the hds_uend() function call): HDS_FLG_NORMAL Normal termination HDS_FLG_FORCE Forced termination

Notes:

1. Use the header file provided for UINTERFACE_BLK by the target Datareplicator. For details about the header files, see Table 8-14 Header files for an import information editing UOC routine.
2. End users are not to modify the area that is defined by the caller.

long *status

Specify a status value to be displayed in the event of an error in the editing start instruction function. This status value will be displayed in the message that is output by the caller Datareplicator.

(c) Return value

Set the return value when control is returned to the caller. The following table shows the permissible return values.

Table 8-5 Return values from hds_ubegin()

Code	Status	Mnemonic	Caller's action
0	Normal termination	HDS_RET_NORM	Resumes processing.
4	Minor error detected (resumable level)	HDS_RET_WARN	Outputs a message and resumes processing.
Other	Major error detected (unresumable level)	HDS_RET_ERR	Outputs a message, cancels processing, and terminates the process.

(d) Notes on using the source Datareplicator

If you have specified a transmission-suppressed original receiver identifier in the ndndidxxx operand (xxx: integer in the range 001 to 256) in the source Datareplicator's transmission environment definition, specify in the $PDCLTAPNAME HiRDB environment variable immediately before HiRDB's CONNECT processing a character string of up to 20 bytes beginning with hdssqle and ending with the source Datareplicator identifier.

The character string specified as the source Datareplicator identifier is the same as the one that is specified in the interface block (2-byte hexadecimal character string).

(a) Function format

#include<hds_ucommon.h>
#include<hds_ureflect.h>
 int hds_uedit(UINTERFACE_BLK *interface-block-name,
      UREFLECT_BLK *import-control-block-name,
      UDATA_BLK *key-information-block-name,
      UDATA_BLK *import-data-block-name,
      long *status);

(b) Explanation of the parameters

UINTERFACE_BLK *interface-block-name

To inherit information from the hds_begin() function, specify the name of the area used to store the information. For details about the interface block names, see Table 8-4 Contents of the interface block (UINTERFACE_BLK).

UREFLECT_BLK *import-control-block-name

Specify the name of the area used to store common import information. The caller allocates the import control block. The following table shows the contents of the import control block.

Table 8-6 Contents of the import control block (UREFLECT_BLK)

Member name	Length (bytes)	Attribute	Area name	Defined by	Description
updkind	8	char	Update type	Caller	Type of update processing on the source database (as an 8-byte character string, as shown below; if the type is shorter than 8 bytes, spaces are added): INSERT Indicates INSERT. UPDATE Indicates UPDATE. DELETE Indicates DELETE. PURGE Indicates PURGE. COMMIT Indicates COMMIT#. #: When this value is stored, the values following the authorization identifier serve no purpose.
auth_id	30	char	Authorization identifier	Caller	Authorization identifier used to update the source database
tbl_id	30	char	Table identifier	Caller	Table identifier used to update the source database
upd_date	4	char	Update date	Caller	Date the source database was updated (date the update information was output to the journal). The date is displayed in unsigned packed decimal format (YYYYMMDD).
upd_time	4	char	Update time	Caller	Time the source database was updated (time the update information was output to the journal). The time is displayed in unsigned packed decimal format (HHMMSSTT, where TT is 1/100 sec.).
uapname	8	char	Source UAP name	Caller	Name of the user application program used to update the source database
extsysid	4	char	Source database's system ID	Caller	When the source database is a HiRDB: Source database's HiRDB identifier When the source database is a mainframe (XDM/DS, PDM2 E2, or RDB1 E2): Source database's subsystem ID
infflag1	1	unsigned char	Reserved area1	N/A	Reserved
infflag2	1	unsigned char	Reserved area2	N/A	Reserved
infflag3	1	unsigned char	Reserved area3	N/A	Reserved
reserve1	1	char	Reserved area4	N/A	Reserved
infflag4	4	long	Reserved area5	N/A	Reserved

Notes:

1. Use the header file provided for UREFLECT_BLK by the target Datareplicator. For details about the header files, see Table 8-14 Header files for an import information editing UOC routine.
2. End users are not to modify the area that is defined by the caller.

UDATA_BLK *key-information-block-name

UDATA_BLK *import-data-block-name

Specify the name of the area used to store the import information. This structure is used with the key information block in the third parameter and the import data block in the fourth parameter of the hds_uedit() function. In the key information block, the mapping key information is stored in UDATA_BLK; in the import data block, the import data information is stored in UDATA_BLK.

For the key information block, 0 is set as the number of columns in the case of INSERT, PURGE, or COMMIT. If the key value is changed, the key value before the update processing is set in the key information block. The key value after update processing or during INSERT processing is set in the import data block.

In the case of DELETE, PURGE, or COMMIT, 0 is set as the number of columns in the import data block. The key information and import data information consist of the structure pointed to by UDATA_BLKs (this is referred to as UCOLUMN_BLK) and scalar data. If the number of columns is 0 in UDATA_BLK, do not reference UCOLUMN_BLK. The following figure shows UDATA_BLK and related structures.

Figure 8-4 UDATA_BLK and related structures

#1

For the contents of UDATA_BLK, see Table 8-7 Contents of UDATA_BLK.

#2

For the contents of UCOLUMN_BLK, see Table 8-8 Contents of UCOLUMN_BLK.

#3

This data structure applies to the BLOB or BINARY type with backward deletion updating. For the contents of USUBSTR_BLK, see Table 8-9 Contents of USUBSTR_BLK.

Table 8-7 Contents of UDATA_BLK

Member name	Length (bytes)	Attribute	Area name	Defined by	Description
colnum	4	long	Number of columns	Caller	Number of columns for the mapping key or import data
*colinfptr	4	UCOLUMN_BLK *	UCOLUMN_BLK * address	Caller	Address of UCOLUMN_BLK

Note:

Use the header file provided for UDATA_BLK by Datareplicator. For details about the header files, see Table 8-14 Header files for an import information editing UOC routine.

Table 8-8 Contents of UCOLUMN_BLK

Member name	Length (bytes)	Attribute	Area name	Defined by	Description
colname	30	char	Column name	Caller	Column name
coltype	1	unsigned char	Column data type	Caller	Column's data type. For details about the settings, see Table 8-10 Column data type mnemonics.
coloption	1	unsigned char	Column option	Caller	Column options, as shown below: HDS_COL_NOOPT (0x00): No options HDS_COL_NULL (0x01) Null data HDS_COL_MAPK (0x02): Mapping key: HDS_COL_MAPK is set only in the import data block. It is not set in the key information block. HDS_COL_ARRAY (0x04): Array column HDS_COL_REPET (0x08): Repetition column HDS_COL_ELMNL (0x10): Repetition column's element value is null. HDS_COL_REPTCOL (0x20): Specification of repetition structure HDS_COL_BLOBSUB (0x40): Concatenation operation data HDS_COL_SUBSTR (0x80): SUBSTR operation backward deletion update log
elementnum	4	union	Repetition column's valid element number or number of abstract data types	Caller	For a repetition column: The valid element number is set in the first two bytes (short). If an asterisk (*) is specified, -2 is set. The number of element data items in the corresponding column is set in the last two bytes (short). For an abstract data type column: The number of data types is set, including the inheritance relationship. If there is no inheritance, 1 is set. For an array column: The element number of the source array column is set in the 2 leading bytes. 0 is set in the 2 trailing bytes.
mltcolkind	1	unsigned char	Repetition column update type	Caller	Update type for a repetition column, as shown below (this information is applicable only when the update type is UPDATE): HDS_COL_ADDV (0x01): ADD HDS_COL_DELV (0x02): DELETE HDS_COL_SETV (0x04): SET
adtfunc	1	char	Abstract data type import method	Caller	Always 0x01.
charset	1	char	Character set type	Caller	Character set type of the column data that is to be passed to the UOC routine When no character set is specified: X'00' (HDS_CSET_DEFAULT) When a character set (EBCDIK) is specified: X'01' (HDS_CSET_EBCDIK)
reserve1	2	char	Reserved area	N/A	Reserved
collen	4	long	Column data length	Caller	Column's data length. If the column option is null data, 0 is set.
dataptr	4	union	Data address	Caller	Address of the column data. If the column option is null data, the null pointer is set. For details about the settings, see Table 8-11 Data address mnemonics.

Note:

Use the header file provided for UCOLUMN_BLK by the target Datareplicator. For details about the header files, see Table 8-14 Header files for an import information editing UOC routine.

Table 8-9 Contents of USUBSTR_BLK

Member name	Length (bytes)	Attribute	Area name	Defined by	Description
reserve1	4	int	Internal information 1	Caller	Internal information
data_len	4	int	Internal information 2	Caller	Internal information
reserve2	4	int	Reserved area 1	Caller	Reserved
substr_spos	4	unsigned int	SUBSTR start position	Caller	Start position of the data column to be obtained when the SUBSTR scalar function is used
reserve3	4	int	Reserved area 2	Caller	Reserved
substr_len	4	unsigned int	SUBSTR data length	Caller	Length of the data column to be obtained when the SUBSTR scalar function is used
reserve4	16	char	Reserved area 3	Caller	Reserved

Table 8-10 Column data type mnemonics shows the column data type mnemonics, and Table 8-11 Data address mnemonics shows the data address mnemonics.

Table 8-10 Column data type mnemonics

Column data type	Mnemonic	Data code
INTEGER	HDS_T_INT	(0xF1)
SMALLINT	HDS_T_SINT	(0xF5)
LARGE DECIMAL	HDS_T_DEC	(0xE5)
FLOAT	HDS_T_FLT	(0xE1)
DOUBLE PRECISION	HDS_T_DBL	(0xE1)
SMALL FLOAT	HDS_T_SFLT	(0xE3)
REAL	HDS_T_REAL	(0xE3)
CHARACTER	HDS_T_CHAR	(0xC5)
VARCHAR	HDS_T_VCHAR	(0xC1)
NCHAR	HDS_T_NCHAR	(0xB5)
NVARCHAR	HDS_T_NVCHAR	(0xB1)
MCHAR	HDS_T_MCHAR	(0xA5)
MVCHAR	HDS_T_MVCHAR	(0xA1)
DATE	HDS_T_DATE	(0x71)
TIME	HDS_T_TIME	(0x79)
TIMESTAMP	HDS_T_TIMESTAMP	(0x7D)
INTERVAL YEAR TO DAY	HDS_T_YTD	(0x65)
INTERVAL HOUR TO SECOND	HDS_T_HTS	(0x6F)
BLOB	HDS_T_BLOB	(0x93)
BINARY	HDS_T_BINARY	(0x91)
UNPACK	HDS_T_UNPACK	(0xFF)

Table 8-11 Data address mnemonics

Data type	Mnemonic	Address type
INTEGER	HDS_A_INT	long *
SMALLINT	HDS_A_SINT	short *
LARGE DECIMAL	HDS_A_DEC	char *
FLOAT	HDS_A_FLT	double *
DOUBLE PRECISION	HDS_A_DBL	double *
SMALL FLOAT	HDS_A_SFLT	float *
REAL	HDS_A_REAL	float *
CHARACTER	HDS_A_CHAR	char *
VARCHAR	HDS_A_VCHAR	char *
NCHAR	HDS_A_NCHAR	char*
NVARCHAR	HDS_A_NVCHAR	char *
MCHAR	HDS_A_MCHAR	char *
MVCHAR	HDS_A_MVCHAR	char *
DATE	HDS_A_DATE	char *
TIME	HDS_A_TIME	char *
INTERVAL YEAR TO DAY	HDS_A_YTD	char *
INTERVAL HOUR TO SECOND	HDS_A_HTS	char *
BLOB	HDS_A_BLOB	char *
UNPACK	HDS_A_UNPACK	char *
TIMESTAMP	HDS_A_TIMESTAMP	char *
BINARY	HDS_A_BINARY	char *
SUBSTR operation backward deletion update log	HDS_A_SUBSTR	USUBSTR_BLK *

long *status

Specify a status value to be displayed in the event of an error in the editing and processing instruction function. This status value will be displayed in the message that is output by the caller interface process after control is returned from the function.

(c) Return value

Set the return value when control is returned to the caller. The following table shows the permissible return values.

Table 8-12 Return values from hds_uedit()

Code	Status	Mnemonic	Caller's action
0	Normal termination	HDS_RET_NORM	Resumes processing.
4	Minor error detected (resumable level)	HDS_RET_WARN	Outputs a message and resumes processing.
Other	Major error detected (unresumable level)	HDS_RET_ERR	Outputs a message, cancels processing, and terminates the process.

(a) Function format

#include<hds_ucommon.h>
#include<hds_ureflect.h>
 int hds_uend(UINTERFACE_BLK *interface-block-name,
    long *status);

(b) Explanation of the parameters

UINTERFACE_BLK *interface-block-name

To inherit information from the hds_begin() or hds_edit() function, specify the name of the area used to store the information. For details about the interface block names, see Table 8-4 Contents of the interface block (UINTERFACE_BLK).

If you have allocated the area dynamically with the hds_ubegin() function, you must release it within the hds_uend() function. Close any file that was opened. Once control is returned from the hds_uend() function, release the area for the structure without doing anything to the user-specified item in UINTERFACE_BLK.

If the termination mode of the UOC routine accessing the database is forced termination, execute ROLLBACK on the DBMS, and then execute DISCONNECT.

long *status

Specify a status value to be displayed in the event of an error in the editing termination instruction function. This status value will be displayed in the message that is output by the caller interface process after control is returned from the function.

(c) Return value

Set the return value when control is returned to the caller. The following table shows the permissible return values.

Table 8-13 Return values from hds_uend()

Code	Status	Mnemonic	Caller's action
0	Normal termination	HDS_RET_NORM	Resumes processing.
4	Minor error detected (resumable level)	HDS_RET_WARN	Outputs a message and terminates the process normally.
Other	Major error detected (unresumable level)	HDS_RET_ERR	Outputs a message and terminates the process normally.

A target Datareplicator provides header files for the structures and mnemonics that are used as the interface for the hds_ubegin(), hds_uedit(), and hds_uend() functions.

The header files used with an import information editing UOC routine are stored in the following directory:

UNIX Datareplicator: /opt/hirdbds/include/

Windows Datareplicator: Datareplicator-installation-directory\include\

The following table lists and describes the header files for an import information editing UOC routine.

Table 8-14 Header files for an import information editing UOC routine

Filename	Description	Members associated with the import information editing UOC
hds_ucommon.h	Structures and mnemonic codes common to import information editing UOC routines	UINTERFACE_BLK Mnemonics for the return value
hds_ureflect.h	Structures and mnemonics for an import information editing UOC routine	UREFLECT_BLK Mnemonics for UREFLECT_BLK UDATA_BLK UCOLUMN_BLK Mnemonics for the data type Mnemonics for the data address

(a) Files

You can manipulate only user-specific files (that are open) within the functions of an import information editing UOC routine. The following are the file-related rules:

• Do not use the standard input, standard output, or standard error output.
  If you have specified FALSE in the target Datareplicator's HDS_MST_STDCLOSE environment variable, you can use the standard input, standard output, and standard error output.
  
• Do not write to or read from any file other than those opened by the import information editing UOC routine.
• Do not manipulate any file that belongs to the target Datareplicator.

(b) Relationship with definitions

• A control_trigger instruction is not issued to the UOC routine. Therefore, when the UOC routine is used, the control_trigger parameter in the target environment definition is ignored.
• Because Datareplicator does not issue the disconnect instruction to UOC routines, the discintvl operand specification in the import system definition does not apply to import processing executed by a UOC routine.
• Because Datareplicator does not check the table used within a UOC routine, the tblcheck operand specification in the import environment definition does not apply to import processing executed by a UOC routine.
• To execute import processing with a UOC routine, specify the name of the user-created UOC routine in the import definition. During import processing, the UOC routine whose name is specified is started automatically.
• If you select all UOC routines to execute import processing in the import definition, manipulations on a time-ordered information table will not take place automatically.

(c) Specifications in the SQL descriptor area

To use the SQL descriptor area to update the target database, you must create the UOC routine by setting the necessary information from the UOC interface table into the SQL descriptor area. For the UOC routine to directly reference column data in the UOC interface table, it might be necessary to code in C language, depending on the data type. The following figure shows the relationships among the format of data indicated by the column data address in the UOC interface table, the length of real data, and the representation in C language.

Table 8-15 Relationships among the UOC routine's column data type, data length, and representation in C language

UOC interface table		Size of data area (bytes)	Representation in C language
Mnemonic	Length of column data
HDS_T_INT	4	4	long
HDS_T_SINT	2	2	short
HDS_T_DEC	Leading 2 bytes: precision Trailing 2 bytes: scaling	Precision 2 + 1	char data-area[real-data-length]
HDS_T_FLT	8	8	double
HDS_T_DBL
HDS_T_SFLT	4	4	float
HDS_T_REAL
HDS_T_CHAR	Length of character string (bytes)	UOC routine's column data length	char data-area[real-data-length]
HDS_T_MCHAR
HDS_T_VCHAR	Length of character string in the data section (bytes)	UOC routine's column data length + 2	struct{ unsigned short real-data-length char data-area[real-data-length] }
HDS_T_NCHAR	Length of character string (characters)	UOC routine's column data length x 2	char data-area[real-data-length]
HDS_T_NVCHAR	Length of character string in the data section (characters)	UOC routine's column data length x 2 + 2	struct{ unsigned short real-data-length char data-area[real-data-length] }
HDS_T_DATE	4	4	char data-area[real-data-length]
HDS_T_TIME	3	3	char data-area[real-data-length]
HDS_T_YTD	Leading 2 bytes: precision (8) Trailing 2 bytes: scaling (0)	5	char data-area[real-data-length]
HDS_T_HTS	Leading 2 bytes: precision (6) Trailing 2 bytes: scaling (0)	4	char data-area[real-data-length]
HDS_T_BLOB (when the column option is not 0x80)	Length of data in the data section (bytes)	UOC routine's column data length + 8	struct{ long reserved-area unsigned long real-data-length char data-area[real-data-length] }
HDS_T_BLOB (when the column option is 0x80)	32	UOC routine's column data length + 8	Table 8-9 Contents of USUBSTR_BLK
HDS_T_UNPACK	Length of UNPACK data (bytes)	Length of integer part + length of fraction part	char data-area[real-data-length]
HDS_T_TIMESTAMP	7 + p/2 (bytes) p: Number of decimal places	UOC routine's data column data length	char data-area[real-data-length]
HDS_T_BINARY (when the column option is not 0x80)	Length of data in the data section (bytes)	UOC routine's data column data length + 4	struct{ long real-data-length char data-area[real-data-length] }#
HDS_T_BINARY (when the column option is 0x80)	32	UOC routine's column data length + 8	Table 8-9 Contents of USUBSTR_BLK

Notes:

In the case of data in a repetition column, the data for one element is stored in one UCOLUMN_BLK.

#

The transfer method is the same for concatenation operations.

(d) Data types

• If the source database is a mainframe database and data conversion is required, the data obtained after data conversion is passed to the UOC routine. For details about data conversion, see 4.3.4 Designing for the supported data types.
• DATE-type and TIME-type data are stored in unsigned packed format. When you create a UAP that uses the SQL descriptor area, you can specify the address of the data storage area directly in the SQL descriptor area. When you create a UAP that does not use the SQL descriptor area, you must convert DATE-type and TIME-type data to the corresponding date and time character string data, and then specify them in embedded variables.
• SMALLFLOAT-type data is passed as FLOAT-type data to avoid overflow that might occur due to a difference in representation ranges.
• If an extracted column's type is UNPACK, Datareplicator converts it to DECIMAL-type data, and then passes it to the UOC routine in DECIMAL data format. If Datareplicator cannot convert the UNPACK data to DECIMAL, it passes the UNPACK data to the UOC routine. For details about the mnemonic for the UNPACK-type that is passed to the UOC routine, see Table 8-10 Column data type mnemonics or Table 8-11 Data address mnemonics.