head	1.106;
access;
symbols
	REL9_0_0:1.100.2.6
	REL9_1_ALPHA1:1.106
	REL9_0_RC1:1.100.2.4
	REL9_0_BETA4:1.100.2.1
	REL9_0_STABLE:1.100.0.2
	REL9_0_BETA3:1.100
	REL9_0_BETA2:1.100
	REL7_4_29:1.53.2.2
	REL8_0_25:1.62.4.2
	REL8_1_21:1.71
	REL8_2_17:1.77.2.1
	REL8_3_11:1.85.2.1
	REL8_4_4:1.89.2.1
	REL9_0_BETA1:1.98
	REL9_0_ALPHA5_BRANCH:1.98.0.2
	REL9_0_ALPHA5:1.98
	REL7_4_28:1.53.2.2
	REL8_0_24:1.62.4.2
	REL8_1_20:1.71
	REL8_2_16:1.77
	REL8_3_10:1.85
	REL8_4_3:1.89
	REL9_0_ALPHA4:1.97
	REL9_0_ALPHA4_BRANCH:1.97.0.2
	REL8_5_ALPHA3:1.93
	REL8_5_ALPHA3_BRANCH:1.93.0.2
	REL7_4_27:1.53.2.2
	REL8_0_23:1.62.4.2
	REL8_1_19:1.71
	REL8_2_15:1.77
	REL8_3_9:1.85
	REL8_4_2:1.89
	REL8_5_ALPHA2:1.91
	REL8_5_ALPHA2_BRANCH:1.91.0.2
	REL7_4_26:1.53.2.2
	REL8_0_22:1.62.4.2
	REL8_1_18:1.71
	REL8_2_14:1.77
	REL8_3_8:1.85
	REL8_4_1:1.89
	REL8_5_ALPHA1:1.90
	REL8_5_ALPHA1_BRANCH:1.90.0.2
	REL8_4_STABLE:1.89.0.2
	REL8_4_0:1.89
	REL8_4_RC2:1.89
	REL8_4_RC1:1.89
	REL8_4_BETA2:1.88
	REL8_4_BETA1:1.87
	REL7_4_25:1.53.2.2
	REL8_0_21:1.62.4.2
	REL8_1_17:1.71
	REL8_2_13:1.77
	REL8_3_7:1.85
	REL7_4_24:1.53.2.2
	REL8_0_20:1.62.4.2
	REL8_1_16:1.71
	REL8_2_12:1.77
	REL8_3_6:1.85
	REL7_4_23:1.53.2.2
	REL8_0_19:1.62.4.2
	REL8_1_15:1.71
	REL8_2_11:1.77
	REL8_3_5:1.85
	REL7_4_22:1.53.2.2
	REL8_0_18:1.62.4.2
	REL8_1_14:1.71
	REL8_2_10:1.77
	REL8_3_4:1.85
	REL7_4_21:1.53.2.2
	REL8_0_17:1.62.4.2
	REL8_1_13:1.71
	REL8_2_9:1.77
	REL8_3_3:1.85
	REL7_4_20:1.53.2.2
	REL8_0_16:1.62.4.2
	REL8_1_12:1.71
	REL8_2_8:1.77
	REL8_3_2:1.85
	REL8_2_7:1.77
	REL8_3_1:1.85
	REL8_3_STABLE:1.85.0.2
	REL8_3_0:1.85
	REL8_3_RC2:1.85
	REL7_3_21:1.39
	REL7_4_19:1.53.2.2
	REL8_0_15:1.62.4.2
	REL8_1_11:1.71
	REL8_2_6:1.77
	REL8_3_RC1:1.85
	REL8_3_BETA4:1.84
	REL8_3_BETA3:1.84
	REL8_3_BETA2:1.83
	REL8_3_BETA1:1.83
	REL7_3_20:1.39
	REL7_4_18:1.53.2.2
	REL8_0_14:1.62.4.2
	REL8_1_10:1.71
	REL8_2_5:1.77
	REL7_3_19:1.39
	REL7_4_17:1.53.2.2
	REL8_0_13:1.62.4.2
	REL8_1_9:1.71
	REL8_2_4:1.77
	REL8_0_12:1.62.4.2
	REL8_1_8:1.71
	REL8_2_3:1.77
	REL7_3_18:1.39
	REL7_4_16:1.53.2.2
	REL8_0_11:1.62.4.2
	REL8_1_7:1.71
	REL8_2_2:1.77
	REL8_0_10:1.62.4.2
	REL8_1_6:1.71
	REL8_2_1:1.77
	REL7_4_15:1.53.2.2
	REL7_3_17:1.39
	REL8_2_STABLE:1.77.0.2
	REL8_2_0:1.77
	REL8_2_RC1:1.77
	REL8_2_BETA3:1.77
	REL8_2_BETA2:1.77
	REL8_1_5:1.71
	REL8_0_9:1.62.4.2
	REL7_4_14:1.53.2.2
	REL7_3_16:1.39
	REL8_2_BETA1:1.76
	REL7_3_15:1.39
	REL7_4_13:1.53.2.2
	REL8_0_8:1.62.4.2
	REL8_1_4:1.71
	REL7_3_14:1.39
	REL7_4_12:1.53.2.2
	REL8_0_7:1.62.4.2
	REL8_1_3:1.71
	REL7_3_13:1.39
	REL7_4_11:1.53.2.2
	REL8_0_6:1.62.4.2
	REL8_1_2:1.71
	REL7_3_12:1.39
	REL7_4_10:1.53.2.2
	REL8_0_5:1.62.4.2
	REL8_1_1:1.71
	REL8_1_STABLE:1.71.0.2
	REL8_1_0:1.71
	REL8_1_0RC1:1.69
	REL8_1_0BETA4:1.69
	REL8_1_0BETA3:1.67
	REL7_3_11:1.39
	REL7_4_9:1.53.2.2
	REL8_0_4:1.62.4.2
	REL8_1_0BETA2:1.65
	REL8_1_0BETA1:1.65
	REL7_2_8:1.36
	REL7_3_10:1.39
	REL7_4_8:1.53.2.2
	REL8_0_3:1.62.4.1
	REL8_0_2:1.62.4.1
	REL7_2_7:1.36
	REL7_3_9:1.39
	REL7_4_7:1.53.2.2
	REL8_0_1:1.62.4.1
	REL8_0_STABLE:1.62.0.4
	REL8_0_0:1.62.0.2
	REL8_0_0RC5:1.62
	REL8_0_0RC4:1.60
	REL8_0_0RC3:1.60
	REL8_0_0RC2:1.59
	REL8_0_0RC1:1.59
	REL8_0_0BETA5:1.59
	REL8_0_0BETA4:1.59
	REL7_4_6:1.53.2.2
	REL7_3_8:1.39
	REL7_2_6:1.36
	REL8_0_0BETA3:1.59
	REL8_0_0BETA2:1.59
	REL7_2_5:1.36
	REL7_4_5:1.53.2.2
	REL7_3_7:1.39
	REL7_4_4:1.53.2.2
	REL8_0_0BETA1:1.59
	REL7_4_3:1.53.2.2
	REL7_4_2:1.53.2.2
	REL7_3_6:1.39
	REL7_4_1:1.53.2.2
	REL7_3_5:1.39
	REL7_4:1.53.2.1
	REL7_4_RC2:1.53
	REL7_4_STABLE:1.53.0.2
	REL7_4_RC1:1.53
	REL7_4_BETA5:1.53
	REL7_4_BETA4:1.52
	REL7_4_BETA3:1.51
	REL7_4_BETA2:1.48
	WIN32_DEV:1.48.0.2
	REL7_4_BETA1:1.47
	REL7_3_4:1.39
	REL7_3_2:1.39
	REL7_2_4:1.36
	REL7_3_STABLE:1.39.0.2
	REL7_2_3:1.36
	REL7_2_STABLE:1.36.0.2
	REL7_2:1.36
	REL7_2_RC2:1.36
	REL7_2_RC1:1.36
	REL7_2_BETA5:1.33
	REL7_2_BETA4:1.31
	REL7_2_BETA3:1.30
	REL7_2_BETA2:1.28
	REL7_2_BETA1:1.26
	REL7_1_2:1.18
	REL7_1_STABLE:1.18.0.2
	REL7_1_BETA:1.17
	REL7_1_BETA3:1.18
	REL7_1_BETA2:1.18
	REL7_1:1.18
	REL7_0_PATCHES:1.14.0.2
	REL7_0:1.14
	REL6_5_PATCHES:1.9.0.2
	REL6_5:1.9
	REL6_4:1.5.0.2
	release-6-3:1.1;
locks; strict;
comment	@# @;


1.106
date	2010.09.02.14.57.04;	author tgl;	state Exp;
branches;
next	1.105;

1.105
date	2010.09.02.14.46.44;	author tgl;	state Exp;
branches;
next	1.104;

1.104
date	2010.08.17.04.37.20;	author petere;	state Exp;
branches;
next	1.103;

1.103
date	2010.08.11.19.03.16;	author rhaas;	state Exp;
branches;
next	1.102;

1.102
date	2010.08.11.18.52.02;	author rhaas;	state Exp;
branches;
next	1.101;

1.101
date	2010.07.29.19.34.40;	author petere;	state Exp;
branches;
next	1.100;

1.100
date	2010.05.13.14.16.41;	author mha;	state Exp;
branches
	1.100.2.1;
next	1.99;

1.99
date	2010.05.09.16.30.31;	author tgl;	state Exp;
branches;
next	1.98;

1.98
date	2010.02.27.04.29.44;	author tgl;	state Exp;
branches;
next	1.97;

1.97
date	2010.02.19.00.15.25;	author momjian;	state Exp;
branches;
next	1.96;

1.96
date	2010.02.17.04.19.37;	author tgl;	state Exp;
branches;
next	1.95;

1.95
date	2010.01.26.14.21.29;	author momjian;	state Exp;
branches;
next	1.94;

1.94
date	2010.01.26.09.10.11;	author meskes;	state Exp;
branches;
next	1.93;

1.93
date	2009.12.02.14.07.25;	author momjian;	state Exp;
branches;
next	1.92;

1.92
date	2009.11.30.14.47.37;	author momjian;	state Exp;
branches;
next	1.91;

1.91
date	2009.09.18.13.13.32;	author meskes;	state Exp;
branches;
next	1.90;

1.90
date	2009.07.11.21.15.32;	author petere;	state Exp;
branches;
next	1.89;

1.89
date	2009.05.18.11.08.24;	author petere;	state Exp;
branches
	1.89.2.1;
next	1.88;

1.88
date	2009.04.27.16.27.35;	author momjian;	state Exp;
branches;
next	1.87;

1.87
date	2008.12.07.23.46.39;	author alvherre;	state Exp;
branches;
next	1.86;

1.86
date	2008.06.12.19.15.40;	author momjian;	state Exp;
branches;
next	1.85;

1.85
date	2007.12.03.23.49.50;	author tgl;	state Exp;
branches
	1.85.2.1;
next	1.84;

1.84
date	2007.11.07.12.24.23;	author petere;	state Exp;
branches;
next	1.83;

1.83
date	2007.04.17.17.30.35;	author tgl;	state Exp;
branches;
next	1.82;

1.82
date	2007.02.16.03.56.45;	author momjian;	state Exp;
branches;
next	1.81;

1.81
date	2007.02.16.03.50.29;	author momjian;	state Exp;
branches;
next	1.80;

1.80
date	2007.02.01.19.10.24;	author momjian;	state Exp;
branches;
next	1.79;

1.79
date	2007.02.01.00.28.16;	author momjian;	state Exp;
branches;
next	1.78;

1.78
date	2007.01.31.20.56.17;	author momjian;	state Exp;
branches;
next	1.77;

1.77
date	2006.10.23.18.10.31;	author petere;	state Exp;
branches
	1.77.2.1;
next	1.76;

1.76
date	2006.09.22.15.22.04;	author tgl;	state Exp;
branches;
next	1.75;

1.75
date	2006.09.21.09.10.27;	author meskes;	state Exp;
branches;
next	1.74;

1.74
date	2006.09.16.00.30.12;	author momjian;	state Exp;
branches;
next	1.73;

1.73
date	2006.03.10.19.10.47;	author momjian;	state Exp;
branches;
next	1.72;

1.72
date	2006.01.31.13.32.20;	author meskes;	state Exp;
branches;
next	1.71;

1.71
date	2005.11.04.23.13.59;	author petere;	state Exp;
branches
	1.71.2.1;
next	1.70;

1.70
date	2005.11.04.02.56.30;	author tgl;	state Exp;
branches;
next	1.69;

1.69
date	2005.10.13.17.55.18;	author momjian;	state Exp;
branches;
next	1.68;

1.68
date	2005.10.13.17.46.18;	author momjian;	state Exp;
branches;
next	1.67;

1.67
date	2005.09.25.03.12.13;	author momjian;	state Exp;
branches;
next	1.66;

1.66
date	2005.09.25.03.06.41;	author momjian;	state Exp;
branches;
next	1.65;

1.65
date	2005.07.14.06.17.35;	author neilc;	state Exp;
branches;
next	1.64;

1.64
date	2005.05.20.12.36.48;	author neilc;	state Exp;
branches;
next	1.63;

1.63
date	2005.01.22.22.56.35;	author momjian;	state Exp;
branches;
next	1.62;

1.62
date	2005.01.08.22.13.25;	author tgl;	state Exp;
branches
	1.62.4.1;
next	1.61;

1.61
date	2005.01.07.05.43.28;	author momjian;	state Exp;
branches;
next	1.60;

1.60
date	2004.12.28.22.47.15;	author tgl;	state Exp;
branches;
next	1.59;

1.59
date	2003.12.26.20.00.00;	author meskes;	state Exp;
branches;
next	1.58;

1.58
date	2003.12.16.01.06.39;	author momjian;	state Exp;
branches;
next	1.57;

1.57
date	2003.12.01.22.36.40;	author momjian;	state Exp;
branches;
next	1.56;

1.56
date	2003.11.29.19.51.36;	author pgsql;	state Exp;
branches;
next	1.55;

1.55
date	2003.11.24.19.08.02;	author petere;	state Exp;
branches;
next	1.54;

1.54
date	2003.11.12.22.47.47;	author petere;	state Exp;
branches;
next	1.53;

1.53
date	2003.10.17.18.57.00;	author tgl;	state Exp;
branches
	1.53.2.1;
next	1.52;

1.52
date	2003.09.20.20.12.04;	author tgl;	state Exp;
branches;
next	1.51;

1.51
date	2003.09.11.21.42.19;	author momjian;	state Exp;
branches;
next	1.50;

1.50
date	2003.09.09.10.54.44;	author meskes;	state Exp;
branches;
next	1.49;

1.49
date	2003.08.31.17.32.18;	author petere;	state Exp;
branches;
next	1.48;

1.48
date	2003.08.07.04.17.21;	author momjian;	state Exp;
branches
	1.48.2.1;
next	1.47;

1.47
date	2003.08.01.13.53.36;	author petere;	state Exp;
branches;
next	1.46;

1.46
date	2003.08.01.03.10.04;	author momjian;	state Exp;
branches;
next	1.45;

1.45
date	2003.07.23.17.27.28;	author momjian;	state Exp;
branches;
next	1.44;

1.44
date	2003.06.15.04.07.58;	author momjian;	state Exp;
branches;
next	1.43;

1.43
date	2003.03.25.16.15.35;	author petere;	state Exp;
branches;
next	1.42;

1.42
date	2003.03.13.01.30.28;	author petere;	state Exp;
branches;
next	1.41;

1.41
date	2003.01.19.00.13.28;	author momjian;	state Exp;
branches;
next	1.40;

1.40
date	2002.11.15.03.11.16;	author momjian;	state Exp;
branches;
next	1.39;

1.39
date	2002.10.24.17.48.54;	author petere;	state Exp;
branches;
next	1.38;

1.38
date	2002.10.21.18.04.05;	author petere;	state Exp;
branches;
next	1.37;

1.37
date	2002.09.21.18.32.52;	author petere;	state Exp;
branches;
next	1.36;

1.36
date	2002.01.20.22.19.55;	author petere;	state Exp;
branches;
next	1.35;

1.35
date	2002.01.18.21.17.07;	author momjian;	state Exp;
branches;
next	1.34;

1.34
date	2002.01.18.20.32.53;	author momjian;	state Exp;
branches;
next	1.33;

1.33
date	2002.01.07.02.29.11;	author petere;	state Exp;
branches;
next	1.32;

1.32
date	2002.01.06.17.54.14;	author momjian;	state Exp;
branches;
next	1.31;

1.31
date	2001.11.21.05.53.41;	author thomas;	state Exp;
branches;
next	1.30;

1.30
date	2001.11.12.19.19.39;	author petere;	state Exp;
branches;
next	1.29;

1.29
date	2001.11.08.23.37.50;	author petere;	state Exp;
branches;
next	1.28;

1.28
date	2001.11.01.04.48.00;	author tgl;	state Exp;
branches;
next	1.27;

1.27
date	2001.10.31.20.37.39;	author petere;	state Exp;
branches;
next	1.26;

1.26
date	2001.10.18.20.43.05;	author momjian;	state Exp;
branches;
next	1.25;

1.25
date	2001.10.18.20.32.58;	author momjian;	state Exp;
branches;
next	1.24;

1.24
date	2001.10.11.20.25.42;	author momjian;	state Exp;
branches;
next	1.23;

1.23
date	2001.09.13.15.55.22;	author petere;	state Exp;
branches;
next	1.22;

1.22
date	2001.09.10.21.58.46;	author petere;	state Exp;
branches;
next	1.21;

1.21
date	2001.09.06.00.23.42;	author momjian;	state Exp;
branches;
next	1.20;

1.20
date	2001.08.26.17.04.02;	author momjian;	state Exp;
branches;
next	1.19;

1.19
date	2001.08.24.18.08.25;	author momjian;	state Exp;
branches;
next	1.18;

1.18
date	2000.12.22.21.51.57;	author petere;	state Exp;
branches;
next	1.17;

1.17
date	2000.09.29.20.21.33;	author petere;	state Exp;
branches;
next	1.16;

1.16
date	2000.09.18.20.11.36;	author petere;	state Exp;
branches;
next	1.15;

1.15
date	2000.08.23.05.59.01;	author thomas;	state Exp;
branches;
next	1.14;

1.14
date	2000.05.02.20.01.51;	author thomas;	state Exp;
branches;
next	1.13;

1.13
date	2000.03.31.03.27.40;	author thomas;	state Exp;
branches;
next	1.12;

1.12
date	2000.03.30.22.22.40;	author thomas;	state Exp;
branches;
next	1.11;

1.11
date	2000.03.03.09.55.51;	author meskes;	state Exp;
branches;
next	1.10;

1.10
date	99.09.15.14.14.10;	author meskes;	state Exp;
branches;
next	1.9;

1.9
date	99.04.06.15.41.13;	author thomas;	state Exp;
branches;
next	1.8;

1.8
date	99.03.30.15.20.43;	author thomas;	state Exp;
branches;
next	1.7;

1.7
date	99.03.24.14.54.10;	author meskes;	state Exp;
branches;
next	1.6;

1.6
date	98.12.29.02.24.15;	author thomas;	state Exp;
branches;
next	1.5;

1.5
date	98.10.10.17.12.11;	author thomas;	state Exp;
branches;
next	1.4;

1.4
date	98.09.30.05.41.43;	author thomas;	state Exp;
branches;
next	1.3;

1.3
date	98.09.21.05.55.23;	author scrappy;	state Exp;
branches;
next	1.2;

1.2
date	98.07.29.06.49.57;	author thomas;	state Exp;
branches;
next	1.1;

1.1
date	98.03.01.08.15.51;	author thomas;	state Exp;
branches;
next	;

1.48.2.1
date	2003.09.07.04.36.41;	author momjian;	state Exp;
branches;
next	;

1.53.2.1
date	2003.11.12.20.05.14;	author petere;	state Exp;
branches;
next	1.53.2.2;

1.53.2.2
date	2003.12.16.01.06.51;	author momjian;	state Exp;
branches;
next	1.53.2.3;

1.53.2.3
date	2010.08.11.18.53.04;	author rhaas;	state Exp;
branches;
next	1.53.2.4;

1.53.2.4
date	2010.08.11.19.04.16;	author rhaas;	state Exp;
branches;
next	;

1.62.4.1
date	2005.01.22.23.05.47;	author momjian;	state Exp;
branches;
next	1.62.4.2;

1.62.4.2
date	2005.05.20.12.37.51;	author neilc;	state Exp;
branches;
next	1.62.4.3;

1.62.4.3
date	2010.08.11.18.52.58;	author rhaas;	state Exp;
branches;
next	1.62.4.4;

1.62.4.4
date	2010.08.11.19.04.09;	author rhaas;	state Exp;
branches;
next	;

1.71.2.1
date	2010.08.11.18.52.52;	author rhaas;	state Exp;
branches;
next	1.71.2.2;

1.71.2.2
date	2010.08.11.19.04.03;	author rhaas;	state Exp;
branches;
next	;

1.77.2.1
date	2010.05.13.14.16.45;	author mha;	state Exp;
branches;
next	1.77.2.2;

1.77.2.2
date	2010.08.11.18.52.43;	author rhaas;	state Exp;
branches;
next	1.77.2.3;

1.77.2.3
date	2010.08.11.19.03.56;	author rhaas;	state Exp;
branches;
next	;

1.85.2.1
date	2010.05.13.14.16.51;	author mha;	state Exp;
branches;
next	1.85.2.2;

1.85.2.2
date	2010.08.11.18.52.33;	author rhaas;	state Exp;
branches;
next	1.85.2.3;

1.85.2.3
date	2010.08.11.19.03.46;	author rhaas;	state Exp;
branches;
next	;

1.89.2.1
date	2010.05.13.14.16.57;	author mha;	state Exp;
branches;
next	1.89.2.2;

1.89.2.2
date	2010.08.11.18.52.23;	author rhaas;	state Exp;
branches;
next	1.89.2.3;

1.89.2.3
date	2010.08.11.19.03.36;	author rhaas;	state Exp;
branches;
next	;

1.100.2.1
date	2010.07.29.19.34.36;	author petere;	state Exp;
branches;
next	1.100.2.2;

1.100.2.2
date	2010.08.11.18.52.12;	author rhaas;	state Exp;
branches;
next	1.100.2.3;

1.100.2.3
date	2010.08.11.19.03.25;	author rhaas;	state Exp;
branches;
next	1.100.2.4;

1.100.2.4
date	2010.08.17.04.37.16;	author petere;	state Exp;
branches;
next	1.100.2.5;

1.100.2.5
date	2010.09.02.14.46.51;	author tgl;	state Exp;
branches;
next	1.100.2.6;

1.100.2.6
date	2010.09.02.14.57.09;	author tgl;	state Exp;
branches;
next	;


desc
@@


1.106
log
@Clean up description of ecpg's dtcvfmtasc function.
Per KOIZUMI Satoru.
@
text
@<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.105 2010/09/02 14:46:44 tgl Exp $ -->

<chapter id="ecpg">
 <title><application>ECPG</application> - Embedded <acronym>SQL</acronym> in C</title>

 <indexterm zone="ecpg"><primary>embedded SQL</primary><secondary>in C</secondary></indexterm>
 <indexterm zone="ecpg"><primary>C</primary></indexterm>
 <indexterm zone="ecpg"><primary>ECPG</primary></indexterm>

 <para>
  This chapter describes the embedded <acronym>SQL</acronym> package
  for <productname>PostgreSQL</productname>. It was written by
  Linus Tolke (<email>linus@@epact.se</email>) and Michael Meskes
  (<email>meskes@@postgresql.org</email>). Originally it was written to work with
  <acronym>C</acronym>. It also works with <acronym>C++</acronym>, but
  it does not recognize all <acronym>C++</acronym> constructs yet. 
 </para>

 <para>
  This documentation is quite incomplete.  But since this
  interface is standardized, additional information can be found in
  many resources about SQL.
 </para>

 <sect1 id="ecpg-concept">
  <title>The Concept</title>

  <para>
   An embedded SQL program consists of code written in an ordinary
   programming language, in this case C, mixed with SQL commands in
   specially marked sections.  To build the program, the source code
   is first passed through the embedded SQL preprocessor, which converts it
   to an ordinary C program, and afterwards it can be processed by a C
   compiler.
  </para>

  <para>
   Embedded <acronym>SQL</acronym> has advantages over other methods
   for handling <acronym>SQL</acronym> commands from C code. First, it
   takes care of the tedious passing of information to and from
   variables in your <acronym>C</acronym> program.  Second, the SQL
   code in the program is checked at build time for syntactical
   correctness.  Third, embedded <acronym>SQL</acronym> in C is
   specified in the <acronym>SQL</acronym> standard and supported by
   many other <acronym>SQL</acronym> database systems.  The
   <productname>PostgreSQL</> implementation is designed to match this
   standard as much as possible, and it is usually possible to port
   embedded <acronym>SQL</acronym> programs written for other SQL
   databases to <productname>PostgreSQL</productname> with relative
   ease.
  </para>

  <para>
   As already stated, programs written for the embedded
   <acronym>SQL</acronym> interface are normal C programs with special
   code inserted to perform database-related actions.  This special
   code always has the form:
<programlisting>
EXEC SQL ...;
</programlisting>
   These statements syntactically take the place of a C statement.
   Depending on the particular statement, they can appear at the
   global level or within a function.  Embedded
   <acronym>SQL</acronym> statements follow the case-sensitivity rules
   of normal <acronym>SQL</acronym> code, and not those of C.
  </para>

  <para>
   The following sections explain all the embedded SQL statements.
  </para>
 </sect1>

 <sect1 id="ecpg-connect">
  <title>Connecting to the Database Server</title>

  <para>
   One connects to a database using the following statement:
<programlisting>
EXEC SQL CONNECT TO <replaceable>target</replaceable> <optional>AS <replaceable>connection-name</replaceable></optional> <optional>USER <replaceable>user-name</replaceable></optional>;
</programlisting>
   The <replaceable>target</replaceable> can be specified in the
   following ways:

   <itemizedlist>
    <listitem>
     <simpara>
      <literal><replaceable>dbname</><optional>@@<replaceable>hostname</></optional><optional>:<replaceable>port</></optional></literal>
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      <literal>tcp:postgresql://<replaceable>hostname</><optional>:<replaceable>port</></optional><optional>/<replaceable>dbname</></optional><optional>?<replaceable>options</></optional></literal>
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      <literal>unix:postgresql://<replaceable>hostname</><optional>:<replaceable>port</></optional><optional>/<replaceable>dbname</></optional><optional>?<replaceable>options</></optional></literal>
     </simpara>
    </listitem>
 
    <listitem>
     <simpara>
      an SQL string literal containing one of the above forms
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      a reference to a character variable containing one of the above forms (see examples)
     </simpara>
    </listitem>
 
    <listitem>
     <simpara>
      <literal>DEFAULT</literal>
     </simpara>
    </listitem>
   </itemizedlist>

   If you specify the connection target literally (that is, not
   through a variable reference) and you don't quote the value, then
   the case-insensitivity rules of normal SQL are applied.  In that
   case you can also double-quote the individual parameters separately
   as needed.  In practice, it is probably less error-prone to use a
   (single-quoted) string literal or a variable reference.  The
   connection target <literal>DEFAULT</literal> initiates a connection
   to the default database under the default user name.  No separate
   user name or connection name can be specified in that case.
  </para>

  <para>
   There are also different ways to specify the user name:

   <itemizedlist>
    <listitem>
     <simpara>
      <literal><replaceable>username</replaceable></literal>
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      <literal><replaceable>username</replaceable>/<replaceable>password</replaceable></literal>
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      <literal><replaceable>username</replaceable> IDENTIFIED BY <replaceable>password</replaceable></literal>
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      <literal><replaceable>username</replaceable> USING <replaceable>password</replaceable></literal>
     </simpara>
    </listitem>
   </itemizedlist>

   As above, the parameters <replaceable>username</replaceable> and
   <replaceable>password</replaceable> can be an SQL identifier, an
   SQL string literal, or a reference to a character variable.
  </para>

  <para>
   The <replaceable>connection-name</replaceable> is used to handle
   multiple connections in one program.  It can be omitted if a
   program uses only one connection.  The most recently opened
   connection becomes the current connection, which is used by default
   when an SQL statement is to be executed (see later in this
   chapter).
  </para>

  <para>
   Here are some examples of <command>CONNECT</command> statements:
<programlisting>
EXEC SQL CONNECT TO mydb@@sql.mydomain.com;

EXEC SQL CONNECT TO unix:postgresql://sql.mydomain.com/mydb AS myconnection USER john;

EXEC SQL BEGIN DECLARE SECTION;
const char *target = "mydb@@sql.mydomain.com";
const char *user = "john";
EXEC SQL END DECLARE SECTION;
 ...
EXEC SQL CONNECT TO :target USER :user;
</programlisting>
   The last form makes use of the variant referred to above as
   character variable reference.  You will see in later sections how C
   variables can be used in SQL statements when you prefix them with a
   colon.
  </para>

  <para>
   Be advised that the format of the connection target is not
   specified in the SQL standard.  So if you want to develop portable
   applications, you might want to use something based on the last
   example above to encapsulate the connection target string
   somewhere.
  </para>
 </sect1>

 <sect1 id="ecpg-disconnect">
  <title>Closing a Connection</title>

  <para>
   To close a connection, use the following statement:
<programlisting>
EXEC SQL DISCONNECT <optional><replaceable>connection</replaceable></optional>;
</programlisting>
   The <replaceable>connection</replaceable> can be specified
   in the following ways:

   <itemizedlist>
    <listitem>
     <simpara>
      <literal><replaceable>connection-name</replaceable></literal>
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      <literal>DEFAULT</literal>
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      <literal>CURRENT</literal>
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      <literal>ALL</literal>
     </simpara>
    </listitem>
   </itemizedlist>

   If no connection name is specified, the current connection is
   closed.
  </para>

  <para>
   It is good style that an application always explicitly disconnect
   from every connection it opened.
  </para>
 </sect1>

 <sect1 id="ecpg-commands">
  <title>Running SQL Commands</title>

  <para>
   Any SQL command can be run from within an embedded SQL application.
   Below are some examples of how to do that.
  </para>

  <para>
   Creating a table:
<programlisting>
EXEC SQL CREATE TABLE foo (number integer, ascii char(16));
EXEC SQL CREATE UNIQUE INDEX num1 ON foo(number);
EXEC SQL COMMIT;
</programlisting>
  </para>

  <para>
   Inserting rows:
<programlisting>
EXEC SQL INSERT INTO foo (number, ascii) VALUES (9999, 'doodad');
EXEC SQL COMMIT;
</programlisting>
  </para>

  <para>
   Deleting rows:
<programlisting>
EXEC SQL DELETE FROM foo WHERE number = 9999;
EXEC SQL COMMIT;
</programlisting>
  </para>

  <para>
   Single-row select:
<programlisting>
EXEC SQL SELECT foo INTO :FooBar FROM table1 WHERE ascii = 'doodad';
</programlisting>
  </para>

  <para>
   Select using cursors:
<programlisting>
EXEC SQL DECLARE foo_bar CURSOR FOR
    SELECT number, ascii FROM foo
    ORDER BY ascii;
EXEC SQL OPEN foo_bar;
EXEC SQL FETCH foo_bar INTO :FooBar, DooDad;
...
EXEC SQL CLOSE foo_bar;
EXEC SQL COMMIT;
</programlisting>
  </para>

  <para>
   Updates:
<programlisting>
EXEC SQL UPDATE foo
    SET ascii = 'foobar'
    WHERE number = 9999;
EXEC SQL COMMIT;
</programlisting>
  </para>

  <para>
   The tokens of the form
   <literal>:<replaceable>something</replaceable></literal> are
   <firstterm>host variables</firstterm>, that is, they refer to
   variables in the C program.  They are explained in <xref
   linkend="ecpg-variables">.
  </para>

  <para>
   In the default mode, statements are committed only when
   <command>EXEC SQL COMMIT</command> is issued. The embedded SQL
   interface also supports autocommit of transactions (similar to
   <application>libpq</> behavior) via the <option>-t</option> command-line
   option to <command>ecpg</command> (see below) or via the <literal>EXEC SQL
   SET AUTOCOMMIT TO ON</literal> statement. In autocommit mode, each
   command is automatically committed unless it is inside an explicit
   transaction block. This mode can be explicitly turned off using
   <literal>EXEC SQL SET AUTOCOMMIT TO OFF</literal>.
  </para>
 </sect1>

 <sect1 id="ecpg-set-connection">
  <title>Choosing a Connection</title>

  <para>
   The SQL statements shown in the previous section are executed on
   the current connection, that is, the most recently opened one.  If
   an application needs to manage multiple connections, then there are
   two ways to handle this.
  </para>

  <para>
   The first option is to explicitly choose a connection for each SQL
   statement, for example:
<programlisting>
EXEC SQL AT <replaceable>connection-name</replaceable> SELECT ...;
</programlisting>
   This option is particularly suitable if the application needs to
   use several connections in mixed order.
  </para>

  <para>
   If your application uses multiple threads of execution, they cannot share a
   connection concurrently. You must either explicitly control access to the connection
   (using mutexes) or use a connection for each thread. If each thread uses its own connection,
   you will need to use the AT clause to specify which connection the thread will use.
  </para>

  <para>
   The second option is to execute a statement to switch the current
   connection.  That statement is:
<programlisting>
EXEC SQL SET CONNECTION <replaceable>connection-name</replaceable>;
</programlisting>
   This option is particularly convenient if many statements are to be
   executed on the same connection.  It is not thread-aware.
  </para>
 </sect1>

 <sect1 id="ecpg-variables">
  <title>Using Host Variables</title>

  <para>
   In <xref linkend="ecpg-commands"> you saw how you can execute SQL
   statements from an embedded SQL program.  Some of those statements
   only used fixed values and did not provide a way to insert
   user-supplied values into statements or have the program process
   the values returned by the query.  Those kinds of statements are
   not really useful in real applications.  This section explains in
   detail how you can pass data between your C program and the
   embedded SQL statements using a simple mechanism called
   <firstterm>host variables</firstterm>. In an embedded SQL program  we
   consider the SQL statements to be <firstterm>guests</firstterm> in the C
   program code which is the <firstterm>host language</firstterm>. Therefore
   the variables of the C program are called <firstterm>host
   variables</firstterm>.
  </para>

  <sect2>
   <title>Overview</title>

   <para>
    Passing data between the C program and the SQL statements is
    particularly simple in embedded SQL.  Instead of having the
    program paste the data into the statement, which entails various
    complications, such as properly quoting the value, you can simply
    write the name of a C variable into the SQL statement, prefixed by
    a colon.  For example:
<programlisting>
EXEC SQL INSERT INTO sometable VALUES (:v1, 'foo', :v2);
</programlisting>
    This statements refers to two C variables named
    <varname>v1</varname> and <varname>v2</varname> and also uses a
    regular SQL string literal, to illustrate that you are not
    restricted to use one kind of data or the other.
   </para>

   <para>
    This style of inserting C variables in SQL statements works
    anywhere a value expression is expected in an SQL statement.
   </para>
  </sect2>

  <sect2>
   <title>Declare Sections</title>

   <para>
    To pass data from the program to the database, for example as
    parameters in a query, or to pass data from the database back to
    the program, the C variables that are intended to contain this
    data need to be declared in specially marked sections, so the
    embedded SQL preprocessor is made aware of them.
   </para>

   <para>
    This section starts with:
<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
</programlisting>
    and ends with:
<programlisting>
EXEC SQL END DECLARE SECTION;
</programlisting>
    Between those lines, there must be normal C variable declarations,
    such as:
<programlisting>
int   x = 4;
char  foo[16], bar[16];
</programlisting>
    As you can see, you can optionally assign an initial value to the variable.
    The variable's scope is determined by the location of its declaring
    section within the program.
    You can also declare variables with the following syntax which implicitly
    creates a declare section:
<programlisting>
EXEC SQL int i = 4;
</programlisting>
    You can have as many declare sections in a program as you like.
   </para>

   <para>
    The declarations are also echoed to the output file as normal C
    variables, so there's no need to declare them again.  Variables
    that are not intended to be used in SQL commands can be declared
    normally outside these special sections.
   </para>

   <para>
    The definition of a structure or union also must be listed inside
    a <literal>DECLARE</> section. Otherwise the preprocessor cannot
    handle these types since it does not know the definition.
   </para>
  </sect2>

  <sect2>
   <title>Different types of host variables</title>
   <para>
    As a host variable you can also use arrays, typedefs, structs and
    pointers. Moreover there are special types of host variables that exist
    only in ECPG.
   </para>

   <para>
    A few examples on host variables:
    <variablelist>
     <varlistentry>
      <term>Arrays</term>
      <listitem>
      <para>
       One of the most common uses of an array declaration is probably the
       allocation of a char array as in:
<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
    char str[50];
EXEC SQL END DECLARE SECTION;
</programlisting>
       Note that you have to take care of the length for yourself. If you use
       this host variable as the target variable of a query which returns a
       string with more than 49 characters, a buffer overflow occurs.
      </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Typedefs</term>
      <listitem>
      <para>
      Use the <literal>typedef</literal> keyword to map new types to already
      existing types.
<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
    typedef char mychartype[40];
    typedef long serial_t;
EXEC SQL END DECLARE SECTION;
</programlisting>
       Note that you could also use:
<programlisting>
EXEC SQL TYPE serial_t IS long;
</programlisting>
       This declaration does not need to be part of a declare section.
      </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Pointers</term>
      <listitem>
      <para>
       You can declare pointers to the most common types. Note however that
       you cannot use pointers as target variables of queries without
       auto-allocation. See <xref linkend="ecpg-descriptors"> for more
       information on auto-allocation.
      </para>
<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
    int   *intp;
    char **charp;
EXEC SQL END DECLARE SECTION;
</programlisting>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Special types of variables</term>
      <listitem>
       <para>
        ECPG contains some special types that help you to interact easily with
        data from the SQL server. For example it has implemented support for
        the <type>varchar</>, <type>numeric</>, <type>date</>, <type>timestamp</>, and <type>interval</> types.
        <xref linkend="ecpg-pgtypes"> contains basic functions to deal with
        those types, such that you do not need to send a query to the SQL
        server just for adding an interval to a timestamp for example.
       </para>
       <para>
        The special type <type>VARCHAR</type> 
        is converted into a named <type>struct</> for every variable. A
        declaration like:
<programlisting>
VARCHAR var[180];
</programlisting>
         is converted into:
<programlisting>
struct varchar_var { int len; char arr[180]; } var;
</programlisting>
        This structure is suitable for interfacing with SQL datums of type
        <type>varchar</type>.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </sect2>

  <sect2>
   <title><command>SELECT INTO</command> and <command>FETCH INTO</command></title>

   <para>
    Now you should be able to pass data generated by your program into
    an SQL command.  But how do you retrieve the results of a query?
    For that purpose, embedded SQL provides special variants of the
    usual commands <command>SELECT</command> and
    <command>FETCH</command>.  These commands have a special
    <literal>INTO</literal> clause that specifies which host variables
    the retrieved values are to be stored in.
   </para>

   <para>
    Here is an example:
<programlisting>
/*
 * assume this table:
 * CREATE TABLE test1 (a int, b varchar(50));
 */

EXEC SQL BEGIN DECLARE SECTION;
int v1;
VARCHAR v2;
EXEC SQL END DECLARE SECTION;

 ...

EXEC SQL SELECT a, b INTO :v1, :v2 FROM test;
</programlisting>
    So the <literal>INTO</literal> clause appears between the select
    list and the <literal>FROM</literal> clause.  The number of
    elements in the select list and the list after
    <literal>INTO</literal> (also called the target list) must be
    equal.
   </para>

   <para>
    Here is an example using the command <command>FETCH</command>:
<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
int v1;
VARCHAR v2;
EXEC SQL END DECLARE SECTION;

 ...

EXEC SQL DECLARE foo CURSOR FOR SELECT a, b FROM test;

 ...

do {
    ...
    EXEC SQL FETCH NEXT FROM foo INTO :v1, :v2;
    ...
} while (...);
</programlisting>
    Here the <literal>INTO</literal> clause appears after all the
    normal clauses.
   </para>

   <para>
    Both of these methods only allow retrieving one row at a time.  If
    you need to process result sets that potentially contain more than
    one row, you need to use a cursor, as shown in the second example.
   </para>
  </sect2>

  <sect2>
   <title>Indicators</title>

   <para>
    The examples above do not handle null values.  In fact, the
    retrieval examples will raise an error if they fetch a null value
    from the database.  To be able to pass null values to the database
    or retrieve null values from the database, you need to append a
    second host variable specification to each host variable that
    contains data.  This second host variable is called the
    <firstterm>indicator</firstterm> and contains a flag that tells
    whether the datum is null, in which case the value of the real
    host variable is ignored.  Here is an example that handles the
    retrieval of null values correctly:
<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
VARCHAR val;
int val_ind;
EXEC SQL END DECLARE SECTION:

 ...

EXEC SQL SELECT b INTO :val :val_ind FROM test1;
</programlisting>
    The indicator variable <varname>val_ind</varname> will be zero if
    the value was not null, and it will be negative if the value was
    null.
   </para>

   <para>
    The indicator has another function: if the indicator value is
    positive, it means that the value is not null, but it was
    truncated when it was stored in the host variable.
   </para>
  </sect2>
 </sect1>

 <sect1 id="ecpg-dynamic">
  <title>Dynamic SQL</title>

  <para>
   In many cases, the particular SQL statements that an application
   has to execute are known at the time the application is written.
   In some cases, however, the SQL statements are composed at run time
   or provided by an external source.  In these cases you cannot embed
   the SQL statements directly into the C source code, but there is a
   facility that allows you to call arbitrary SQL statements that you
   provide in a string variable.
  </para>

  <para>
   The simplest way to execute an arbitrary SQL statement is to use
   the command <command>EXECUTE IMMEDIATE</command>.  For example:
<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
const char *stmt = "CREATE TABLE test1 (...);";
EXEC SQL END DECLARE SECTION;

EXEC SQL EXECUTE IMMEDIATE :stmt;
</programlisting>
   You cannot execute statements that retrieve data (e.g.,
   <command>SELECT</command>) this way.
  </para>

  <para>
   A more powerful way to execute arbitrary SQL statements is to
   prepare them once and execute the prepared statement as often as
   you like.  It is also possible to prepare a generalized version of
   a statement and then execute specific versions of it by
   substituting parameters.  When preparing the statement, write
   question marks where you want to substitute parameters later.  For
   example:
<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
const char *stmt = "INSERT INTO test1 VALUES(?, ?);";
EXEC SQL END DECLARE SECTION;

EXEC SQL PREPARE mystmt FROM :stmt;
 ...
EXEC SQL EXECUTE mystmt USING 42, 'foobar';
</programlisting>
   If the statement you are executing returns values, then add an
   <literal>INTO</literal> clause:
<programlisting><![CDATA[
EXEC SQL BEGIN DECLARE SECTION;
const char *stmt = "SELECT a, b, c FROM test1 WHERE a > ?";
int v1, v2;
VARCHAR v3;
EXEC SQL END DECLARE SECTION;

EXEC SQL PREPARE mystmt FROM :stmt;
 ...
EXEC SQL EXECUTE mystmt INTO v1, v2, v3 USING 37;
]]>
</programlisting>
   An <command>EXECUTE</command> command can have an
   <literal>INTO</literal> clause, a <literal>USING</literal> clause,
   both, or neither.
  </para>

  <para>
   When you don't need the prepared statement anymore, you should
   deallocate it:
<programlisting>
EXEC SQL DEALLOCATE PREPARE <replaceable>name</replaceable>;
</programlisting>
  </para>
 </sect1>


 <sect1 id="ecpg-pgtypes">
  <title>pgtypes library</title>

  <para>
   The pgtypes library maps <productname>PostgreSQL</productname> database
   types to C equivalents that can be used in C programs. It also offers
   functions to do basic calculations with those types within C, i.e., without
   the help of the <productname>PostgreSQL</productname> server. See the
   following example:
<programlisting><![CDATA[
EXEC SQL BEGIN DECLARE SECTION;
   date date1;
   timestamp ts1, tsout;
   interval iv1;
   char *out;
EXEC SQL END DECLARE SECTION;

PGTYPESdate_today(&date1);
EXEC SQL SELECT started, duration INTO :ts1, :iv1 FROM datetbl WHERE d=:date1;
PGTYPEStimestamp_add_interval(&ts1, &iv1, &tsout);
out = PGTYPEStimestamp_to_asc(&tsout);
printf("Started + duration: %s\n", out);
free(out);
]]>
</programlisting>
  </para>

  <sect2>
   <title>The numeric type</title>
   <para>
    The numeric type offers to do calculations with arbitrary precision. See
    <xref linkend="datatype-numeric"> for the equivalent type in the
    <productname>PostgreSQL</> server. Because of the arbitrary precision this
    variable needs to be able to expand and shrink dynamically. That's why you
    can only create numeric variables on the heap, by means of the
    <function>PGTYPESnumeric_new</> and <function>PGTYPESnumeric_free</>
    functions. The decimal type, which is similar but limited in precision,
    can be created on the stack as well as on the heap.
   </para>
   <para>
   The following functions can be used to work with the numeric type:
   <variablelist>
    <varlistentry>
     <term><function>PGTYPESnumeric_new</function></term>
     <listitem>
      <para>
      Request a pointer to a newly allocated numeric variable.
<synopsis>
numeric *PGTYPESnumeric_new(void);
</synopsis>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_free</function></term>
     <listitem>
      <para>
      Free a numeric type, release all of its memory.
<synopsis>
void PGTYPESnumeric_free(numeric *var);
</synopsis>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_from_asc</function></term>
     <listitem>
      <para>
       Parse a numeric type from its string notation.
<synopsis>
numeric *PGTYPESnumeric_from_asc(char *str, char **endptr);
</synopsis>
       Valid formats are for example:
        <literal>-2</literal>,
        <literal>.794</literal>,
        <literal>+3.44</literal>,
        <literal>592.49E07</literal> or
        <literal>-32.84e-4</literal>.
       If the value could be parsed successfully, a valid pointer is returned,
       else the NULL pointer. At the moment ECPG always parses the complete
       string and so it currently does not support to store the address of the
       first invalid character in <literal>*endptr</literal>. You can safely
       set <literal>endptr</literal> to NULL.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_to_asc</function></term>
     <listitem>
      <para>
       Returns a pointer to a string allocated by <function>malloc</function> that contains the string
       representation of the numeric type <literal>num</literal>.
<synopsis>
char *PGTYPESnumeric_to_asc(numeric *num, int dscale);
</synopsis>
       The numeric value will be printed with <literal>dscale</literal> decimal
       digits, with rounding applied if necessary.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_add</function></term>
     <listitem>
      <para>
       Add two numeric variables into a third one.
<synopsis>
int PGTYPESnumeric_add(numeric *var1, numeric *var2, numeric *result);
</synopsis>
       The function adds the variables <literal>var1</literal> and
       <literal>var2</literal> into the result variable
       <literal>result</literal>.
       The function returns 0 on success and -1 in case of error.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_sub</function></term>
     <listitem>
      <para>
       Subtract two numeric variables and return the result in a third one.
<synopsis>
int PGTYPESnumeric_sub(numeric *var1, numeric *var2, numeric *result);
</synopsis>
       The function subtracts the variable <literal>var2</literal> from
       the variable <literal>var1</literal>. The result of the operation is
       stored in the variable <literal>result</literal>.
       The function returns 0 on success and -1 in case of error.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_mul</function></term>
     <listitem>
      <para>
       Multiply two numeric variables and return the result in a third one.
<synopsis>
int PGTYPESnumeric_mul(numeric *var1, numeric *var2, numeric *result);
</synopsis>
       The function multiplies the variables <literal>var1</literal> and
       <literal>var2</literal>. The result of the operation is stored in the
       variable <literal>result</literal>.
       The function returns 0 on success and -1 in case of error.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_div</function></term>
     <listitem>
      <para>
       Divide two numeric variables and return the result in a third one.
<synopsis>
int PGTYPESnumeric_div(numeric *var1, numeric *var2, numeric *result);
</synopsis>
       The function divides the variables <literal>var1</literal> by
       <literal>var2</literal>. The result of the operation is stored in the
       variable <literal>result</literal>.
       The function returns 0 on success and -1 in case of error.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_cmp</function></term>
     <listitem>
      <para>
       Compare two numeric variables.
<synopsis>
int PGTYPESnumeric_cmp(numeric *var1, numeric *var2)
</synopsis>
       This function compares two numeric variables. In case of error,
       <literal>INT_MAX</literal> is returned. On success, the function
       returns one of three possible results:
       <itemizedlist>
        <listitem>
         <para>
          1, if <literal>var1</> is bigger than <literal>var2</>
         </para>
        </listitem>
        <listitem>
         <para>
          -1, if <literal>var1</> is smaller than <literal>var2</>
         </para>
        </listitem>
        <listitem>
         <para>
          0, if <literal>var1</> and <literal>var2</> are equal
         </para>
        </listitem>
       </itemizedlist>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_from_int</function></term>
     <listitem>
      <para>
       Convert an int variable to a numeric variable.
<synopsis>
int PGTYPESnumeric_from_int(signed int int_val, numeric *var);
</synopsis>
       This function accepts a variable of type signed int and stores it
       in the numeric variable <literal>var</>. Upon success, 0 is returned and
       -1 in case of a failure.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_from_long</function></term>
     <listitem>
      <para>
       Convert a long int variable to a numeric variable.
<synopsis>
int PGTYPESnumeric_from_long(signed long int long_val, numeric *var);
</synopsis>
       This function accepts a variable of type signed long int and stores it
       in the numeric variable <literal>var</>. Upon success, 0 is returned and
       -1 in case of a failure.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_copy</function></term>
     <listitem>
      <para>
       Copy over one numeric variable into another one.
<synopsis>
int PGTYPESnumeric_copy(numeric *src, numeric *dst);
</synopsis>
       This function copies over the value of the variable that
       <literal>src</literal> points to into the variable that <literal>dst</>
       points to. It returns 0 on success and -1 if an error occurs.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_from_double</function></term>
     <listitem>
      <para>
       Convert a variable of type double to a numeric.
<synopsis>
int  PGTYPESnumeric_from_double(double d, numeric *dst);
</synopsis>
       This function accepts a variable of type double and stores the result
       in the variable that <literal>dst</> points to. It returns 0 on success
       and -1 if an error occurs.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_to_double</function></term>
     <listitem>
      <para>
       Convert a variable of type numeric to double.
<synopsis>
int PGTYPESnumeric_to_double(numeric *nv, double *dp)
</synopsis>
       The function converts the numeric value from the variable that
       <literal>nv</> points to into the double variable that <literal>dp</> points
       to. It returns 0 on success and -1 if an error occurs, including
       overflow. On overflow, the global variable <literal>errno</> will be set
       to <literal>PGTYPES_NUM_OVERFLOW</> additionally.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_to_int</function></term>
     <listitem>
      <para>
       Convert a variable of type numeric to int.
<synopsis>
int PGTYPESnumeric_to_int(numeric *nv, int *ip);
</synopsis>
       The function converts the numeric value from the variable that
       <literal>nv</> points to into the integer variable that <literal>ip</>
       points to. It returns 0 on success and -1 if an error occurs, including
       overflow. On overflow, the global variable <literal>errno</> will be set
       to <literal>PGTYPES_NUM_OVERFLOW</> additionally.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_to_long</function></term>
     <listitem>
      <para>
       Convert a variable of type numeric to long.
<synopsis>
int PGTYPESnumeric_to_long(numeric *nv, long *lp);
</synopsis>
       The function converts the numeric value from the variable that
       <literal>nv</> points to into the long integer variable that
       <literal>lp</> points to. It returns 0 on success and -1 if an error
       occurs, including overflow. On overflow, the global variable
       <literal>errno</> will be set to <literal>PGTYPES_NUM_OVERFLOW</>
       additionally.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_to_decimal</function></term>
     <listitem>
      <para>
       Convert a variable of type numeric to decimal.
<synopsis>
int PGTYPESnumeric_to_decimal(numeric *src, decimal *dst);
</synopsis>
       The function converts the numeric value from the variable that
       <literal>src</> points to into the decimal variable that
       <literal>dst</> points to. It returns 0 on success and -1 if an error
       occurs, including overflow. On overflow, the global variable
       <literal>errno</> will be set to <literal>PGTYPES_NUM_OVERFLOW</>
       additionally.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_from_decimal</function></term>
     <listitem>
      <para>
       Convert a variable of type decimal to numeric.
<synopsis>
int PGTYPESnumeric_from_decimal(decimal *src, numeric *dst);
</synopsis>
       The function converts the decimal value from the variable that
       <literal>src</> points to into the numeric variable that
       <literal>dst</> points to. It returns 0 on success and -1 if an error
       occurs. Since the decimal type is implemented as a limited version of
       the numeric type, overflow cannot occur with this conversion.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
   </para>
  </sect2>

  <sect2>
   <title>The date type</title>
   <para>
    The date type in C enables your programs to deal with data of the SQL type
    date. See <xref linkend="datatype-datetime"> for the equivalent type in the
    <productname>PostgreSQL</> server.
   </para>
   <para>
    The following functions can be used to work with the date type:
    <variablelist>
     <varlistentry id="PGTYPESdatefromtimestamp">
      <term><function>PGTYPESdate_from_timestamp</function></term>
      <listitem>
       <para>
        Extract the date part from a timestamp.
<synopsis>
date PGTYPESdate_from_timestamp(timestamp dt);
</synopsis>
        The function receives a timestamp as its only argument and returns the
        extracted date part from this timestamp.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPESdatefromasc">
      <term><function>PGTYPESdate_from_asc</function></term>
      <listitem>
       <para>
       Parse a date from its textual representation.
<synopsis>
date PGTYPESdate_from_asc(char *str, char **endptr);
</synopsis>
        The function receives a C char* string <literal>str</> and a pointer to
        a C char* string <literal>endptr</>. At the moment ECPG always parses
        the complete string and so it currently does not support to store the
        address of the first invalid character in <literal>*endptr</literal>.
        You can safely set <literal>endptr</literal> to NULL.
       </para>
       <para>
        Note that the function always assumes MDY-formatted dates and there is
        currently no variable to change that within ECPG.
       </para>
       <para>
        <xref linkend="ecpg-pgtypesdate-from-asc-table"> shows the allowed input formats.
       </para>
        <table id="ecpg-pgtypesdate-from-asc-table">
         <title>Valid input formats for <function>PGTYPESdate_from_asc</function></title>
         <tgroup cols="2">
          <thead>
           <row>
            <entry>Input</entry>
            <entry>Result</entry>
           </row>
          </thead>
          <tbody>
           <row>
            <entry><literal>January 8, 1999</literal></entry>
            <entry><literal>January 8, 1999</literal></entry>
           </row>
           <row>
            <entry><literal>1999-01-08</literal></entry>
            <entry><literal>January 8, 1999</literal></entry>
           </row>
           <row>
            <entry><literal>1/8/1999</literal></entry>
            <entry><literal>January 8, 1999</literal></entry>
           </row>
           <row>
            <entry><literal>1/18/1999</literal></entry>
            <entry><literal>January 18, 1999</literal></entry>
           </row>
           <row>
            <entry><literal>01/02/03</literal></entry>
            <entry><literal>February 1, 2003</literal></entry>
           </row>
           <row>
            <entry><literal>1999-Jan-08</literal></entry>
            <entry><literal>January 8, 1999</literal></entry>
           </row>
           <row>
            <entry><literal>Jan-08-1999</literal></entry>
            <entry><literal>January 8, 1999</literal></entry>
           </row>
           <row>
            <entry><literal>08-Jan-1999</literal></entry>
            <entry><literal>January 8, 1999</literal></entry>
           </row>
           <row>
            <entry><literal>99-Jan-08</literal></entry>
            <entry><literal>January 8, 1999</literal></entry>
           </row>
           <row>
            <entry><literal>08-Jan-99</literal></entry>
            <entry><literal>January 8, 1999</literal></entry>
           </row>
           <row>
            <entry><literal>08-Jan-06</literal></entry>
            <entry><literal>January 8, 2006</literal></entry>
           </row>
           <row>
            <entry><literal>Jan-08-99</literal></entry>
            <entry><literal>January 8, 1999</literal></entry>
           </row>
           <row>
            <entry><literal>19990108</literal></entry>
            <entry><literal>ISO 8601; January 8, 1999</literal></entry>
           </row>
           <row>
            <entry><literal>990108</literal></entry>
            <entry><literal>ISO 8601; January 8, 1999</literal></entry>
           </row>
           <row>
            <entry><literal>1999.008</literal></entry>
            <entry><literal>year and day of year</literal></entry>
           </row>
           <row>
            <entry><literal>J2451187</literal></entry>
            <entry><literal>Julian day</literal></entry>
           </row>
           <row>
            <entry><literal>January 8, 99 BC</literal></entry>
            <entry><literal>year 99 before the Common Era</literal></entry>
           </row>
          </tbody>
         </tgroup>
        </table>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPESdatetoasc">
      <term><function>PGTYPESdate_to_asc</function></term>
      <listitem>
       <para>
        Return the textual representation of a date variable.
<synopsis>
char *PGTYPESdate_to_asc(date dDate);
</synopsis>
        The function receives the date <literal>dDate</> as its only parameter.
        It will output the date in the form <literal>1999-01-18</>, i.e., in the
        <literal>YYYY-MM-DD</> format.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPESdatejulmdy">
      <term><function>PGTYPESdate_julmdy</function></term>
      <listitem>
       <para>
        Extract the values for the day, the month and the year from a variable
        of type date.
<synopsis>
void PGTYPESdate_julmdy(date d, int *mdy);
</synopsis>
       <!-- almost same description as for rjulmdy() -->
        The function receives the date <literal>d</> and a pointer to an array
        of 3 integer values <literal>mdy</>. The variable name indicates
        the sequential order: <literal>mdy[0]</> will be set to contain the
        number of the month, <literal>mdy[1]</> will be set to the value of the
        day and <literal>mdy[2]</> will contain the year.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPESdatemdyjul">
      <term><function>PGTYPESdate_mdyjul</function></term>
      <listitem>
       <para>
        Create a date value from an array of 3 integers that specify the
        day, the month and the year of the date.
<synopsis>
void PGTYPESdate_mdyjul(int *mdy, date *jdate);
</synopsis>
        The function receives the array of the 3 integers (<literal>mdy</>) as
        its first argument and as its second argument a pointer to a variable
        of type date that should hold the result of the operation.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPESdatedayofweek">
      <term><function>PGTYPESdate_dayofweek</function></term>
      <listitem>
       <para>
        Return a number representing the day of the week for a date value.
<synopsis>
int PGTYPESdate_dayofweek(date d);
</synopsis>
        The function receives the date variable <literal>d</> as its only
        argument and returns an integer that indicates the day of the week for
        this date.
        <itemizedlist>
         <listitem>
          <para>
           0 - Sunday
          </para>
         </listitem>
         <listitem>
          <para>
           1 - Monday
          </para>
         </listitem>
         <listitem>
          <para>
           2 - Tuesday
          </para>
         </listitem>
         <listitem>
          <para>
           3 - Wednesday
          </para>
         </listitem>
         <listitem>
          <para>
           4 - Thursday
          </para>
         </listitem>
         <listitem>
          <para>
           5 - Friday
          </para>
         </listitem>
         <listitem>
          <para>
           6 - Saturday
          </para>
         </listitem>
        </itemizedlist>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPESdatetoday">
      <term><function>PGTYPESdate_today</function></term>
      <listitem>
       <para>
        Get the current date.
<synopsis>
void PGTYPESdate_today(date *d);
</synopsis>
        The function receives a pointer to a date variable (<literal>d</>)
        that it sets to the current date.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPESdatefmtasc">
      <term><function>PGTYPESdate_fmt_asc</function></term>
      <listitem>
       <para>
        Convert a variable of type date to its textual representation using a
        format mask.
<synopsis>
int PGTYPESdate_fmt_asc(date dDate, char *fmtstring, char *outbuf);
</synopsis>
        The function receives the date to convert (<literal>dDate</>), the
        format mask (<literal>fmtstring</>) and the string that will hold the
        textual representation of the date (<literal>outbuf</>).
       </para>
       <para>
        On success, 0 is returned and a negative value if an error occurred.
       </para>
       <para>
        The following literals are the field specifiers you can use:
        <itemizedlist>
         <listitem>
          <para>
           <literal>dd</literal> - The number of the day of the month.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>mm</literal> - The number of the month of the year.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>yy</literal> - The number of the year as a two digit number.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>yyyy</literal> - The number of the year as a four digit number.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>ddd</literal> - The name of the day (abbreviated).
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>mmm</literal> - The name of the month (abbreviated).
          </para>
         </listitem>
        </itemizedlist>
        All other characters are copied 1:1 to the output string.
       </para>
       <para>
        <xref linkend="ecpg-pgtypesdate-fmt-asc-example-table"> indicates a few possible formats. This will give
        you an idea of how to use this function. All output lines are based on
        the same date: November 23, 1959.
       </para>
        <table id="ecpg-pgtypesdate-fmt-asc-example-table">
         <title>Valid input formats for <function>PGTYPESdate_fmt_asc</function></title>
         <tgroup cols="2">
          <thead>
           <row>
            <entry>Format</entry>
            <entry>Result</entry>
           </row>
          </thead>
          <tbody>
           <row>
            <entry><literal>mmddyy</literal></entry>
            <entry><literal>112359</literal></entry>
           </row>
           <row>
            <entry><literal>ddmmyy</literal></entry>
            <entry><literal>231159</literal></entry>
           </row>
           <row>
            <entry><literal>yymmdd</literal></entry>
            <entry><literal>591123</literal></entry>
           </row>
           <row>
            <entry><literal>yy/mm/dd</literal></entry>
            <entry><literal>59/11/23</literal></entry>
           </row>
           <row>
            <entry><literal>yy mm dd</literal></entry>
            <entry><literal>59 11 23</literal></entry>
           </row>
           <row>
            <entry><literal>yy.mm.dd</literal></entry>
            <entry><literal>59.11.23</literal></entry>
           </row>
           <row>
            <entry><literal>.mm.yyyy.dd.</literal></entry>
            <entry><literal>.11.1959.23.</literal></entry>
           </row>
           <row>
            <entry><literal>mmm. dd, yyyy</literal></entry>
            <entry><literal>Nov. 23, 1959</literal></entry>
           </row>
           <row>
            <entry><literal>mmm dd yyyy</literal></entry>
            <entry><literal>Nov 23 1959</literal></entry>
           </row>
           <row>
            <entry><literal>yyyy dd mm</literal></entry>
            <entry><literal>1959 23 11</literal></entry>
           </row>
           <row>
            <entry><literal>ddd, mmm. dd, yyyy</literal></entry>
            <entry><literal>Mon, Nov. 23, 1959</literal></entry>
           </row>
           <row>
            <entry><literal>(ddd) mmm. dd, yyyy</literal></entry>
            <entry><literal>(Mon) Nov. 23, 1959</literal></entry>
           </row>
          </tbody>
         </tgroup>
        </table>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPESdatedefmtasc">
      <term><function>PGTYPESdate_defmt_asc</function></term>
      <listitem>
       <para>
        Use a format mask to convert a C <type>char*</type> string to a value of type
        date.
<synopsis>
int PGTYPESdate_defmt_asc(date *d, char *fmt, char *str);
</synopsis>
        <!-- same description as rdefmtdate -->
        The function receives a pointer to the date value that should hold the
        result of the operation (<literal>d</>), the format mask to use for
        parsing the date (<literal>fmt</>) and the C char* string containing
        the textual representation of the date (<literal>str</>). The textual
        representation is expected to match the format mask. However you do not
        need to have a 1:1 mapping of the string to the format mask. The
        function only analyzes the sequential order and looks for the literals
        <literal>yy</literal> or <literal>yyyy</literal> that indicate the
        position of the year, <literal>mm</literal> to indicate the position of
        the month and <literal>dd</literal> to indicate the position of the
        day.
       </para>
       <para>
        <xref linkend="ecpg-rdefmtdate-example-table"> indicates a few possible formats. This will give
        you an idea of how to use this function.
       </para>
        <table id="ecpg-rdefmtdate-example-table">
         <title>Valid input formats for <function>rdefmtdate</function></title>
         <tgroup cols="3">
          <thead>
           <row>
            <entry>Format</entry>
            <entry>String</entry>
            <entry>Result</entry>
           </row>
          </thead>
          <tbody>
           <row>
            <entry><literal>ddmmyy</literal></entry>
            <entry><literal>21-2-54</literal></entry>
            <entry><literal>1954-02-21</literal></entry>
           </row>
           <row>
            <entry><literal>ddmmyy</literal></entry>
            <entry><literal>2-12-54</literal></entry>
            <entry><literal>1954-12-02</literal></entry>
           </row>
           <row>
            <entry><literal>ddmmyy</literal></entry>
            <entry><literal>20111954</literal></entry>
            <entry><literal>1954-11-20</literal></entry>
           </row>
           <row>
            <entry><literal>ddmmyy</literal></entry>
            <entry><literal>130464</literal></entry>
            <entry><literal>1964-04-13</literal></entry>
           </row>
           <row>
            <entry><literal>mmm.dd.yyyy</literal></entry>
            <entry><literal>MAR-12-1967</literal></entry>
            <entry><literal>1967-03-12</literal></entry>
           </row>
           <row>
            <entry><literal>yy/mm/dd</literal></entry>
            <entry><literal>1954, February 3rd</literal></entry>
            <entry><literal>1954-02-03</literal></entry>
           </row>
           <row>
            <entry><literal>mmm.dd.yyyy</literal></entry>
            <entry><literal>041269</literal></entry>
            <entry><literal>1969-04-12</literal></entry>
           </row>
           <row>
            <entry><literal>yy/mm/dd</literal></entry>
            <entry><literal>In the year 2525, in the month of July, mankind will be alive on the 28th day</literal></entry>
            <entry><literal>2525-07-28</literal></entry>
           </row>
           <row>
            <entry><literal>dd-mm-yy</literal></entry>
            <entry><literal>I said on the 28th of July in the year 2525</literal></entry>
            <entry><literal>2525-07-28</literal></entry>
           </row>
           <row>
            <entry><literal>mmm.dd.yyyy</literal></entry>
            <entry><literal>9/14/58</literal></entry>
            <entry><literal>1958-09-14</literal></entry>
           </row>
           <row>
            <entry><literal>yy/mm/dd</literal></entry>
            <entry><literal>47/03/29</literal></entry>
            <entry><literal>1947-03-29</literal></entry>
           </row>
           <row>
            <entry><literal>mmm.dd.yyyy</literal></entry>
            <entry><literal>oct 28 1975</literal></entry>
            <entry><literal>1975-10-28</literal></entry>
           </row>
           <row>
            <entry><literal>mmddyy</literal></entry>
            <entry><literal>Nov 14th, 1985</literal></entry>
            <entry><literal>1985-11-14</literal></entry>
           </row>
          </tbody>
         </tgroup>
        </table>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </sect2>
 
  <sect2>
   <title>The timestamp type</title>
   <para>
    The timestamp type in C enables your programs to deal with data of the SQL
    type timestamp. See <xref linkend="datatype-datetime"> for the equivalent
    type in the <productname>PostgreSQL</> server.
   </para>
   <para>
    The following functions can be used to work with the timestamp type:
    <variablelist>
     <varlistentry id="PGTYPEStimestampfromasc">
      <term><function>PGTYPEStimestamp_from_asc</function></term>
      <listitem>
       <para>
        Parse a timestamp from its textual representation into a timestamp
        variable.
<synopsis>
timestamp PGTYPEStimestamp_from_asc(char *str, char **endptr);
</synopsis>
        The function receives the string to parse (<literal>str</>) and a
        pointer to a C char* (<literal>endptr</>).
        At the moment ECPG always parses
        the complete string and so it currently does not support to store the
        address of the first invalid character in <literal>*endptr</literal>.
        You can safely set <literal>endptr</literal> to NULL.
       </para>
       <para>
        The function returns the parsed timestamp on success. On error,
        <literal>PGTYPESInvalidTimestamp</literal> is returned and <varname>errno</> is
        set to <literal>PGTYPES_TS_BAD_TIMESTAMP</>. See <xref linkend="PGTYPESInvalidTimestamp"> for important notes on this value.
        
       </para>
       <para>
        In general, the input string can contain any combination of an allowed
        date specification, a whitespace character and an allowed time
        specification. Note that timezones are not supported by ECPG. It can
        parse them but does not apply any calculation as the
        <productname>PostgreSQL</> server does for example. Timezone
        specifiers are silently discarded.
       </para>
       <para>
        <xref linkend="ecpg-pgtypestimestamp-from-asc-example-table"> contains a few examples for input strings.
       </para>
        <table id="ecpg-pgtypestimestamp-from-asc-example-table">
         <title>Valid input formats for <function>PGTYPEStimestamp_from_asc</function></title>
         <tgroup cols="2">
          <thead>
           <row>
            <entry>Input</entry>
            <entry>Result</entry>
           </row>
          </thead>
          <tbody>
           <row>
            <entry><literal>1999-01-08 04:05:06</literal></entry>
            <entry><literal>1999-01-08 04:05:06</literal></entry>
           </row>
           <row>
            <entry><literal>January 8 04:05:06 1999 PST</literal></entry>
            <entry><literal>1999-01-08 04:05:06</literal></entry>
           </row>
           <row>
            <entry><literal>1999-Jan-08 04:05:06.789-8</literal></entry>
            <entry><literal>1999-01-08 04:05:06.789 (time zone specifier ignored)</literal></entry>
           </row>
           <row>
            <entry><literal>J2451187 04:05-08:00</literal></entry>
            <entry><literal>1999-01-08 04:05:00 (time zone specifier ignored)</literal></entry>
           </row>
          </tbody>
         </tgroup>
        </table>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPEStimestamptoasc">
      <term><function>PGTYPEStimestamp_to_asc</function></term>
      <listitem>
       <para>
        Converts a date to a C char* string.
<synopsis>
char *PGTYPEStimestamp_to_asc(timestamp tstamp);
</synopsis>
        The function receives the timestamp <literal>tstamp</> as
        its only argument and returns an allocated string that contains the
        textual representation of the timestamp.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPEStimestampcurrent">
      <term><function>PGTYPEStimestamp_current</function></term>
      <listitem>
       <para>
        Retrieve the current timestamp.
<synopsis>
void PGTYPEStimestamp_current(timestamp *ts);
</synopsis>
        The function retrieves the current timestamp and saves it into the
        timestamp variable that <literal>ts</> points to.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPEStimestampfmtasc">
      <term><function>PGTYPEStimestamp_fmt_asc</function></term>
      <listitem>
       <para>
        Convert a timestamp variable to a C char* using a format mask.
<synopsis>
int PGTYPEStimestamp_fmt_asc(timestamp *ts, char *output, int str_len, char *fmtstr);
</synopsis>
        The function receives a pointer to the timestamp to convert as its
        first argument (<literal>ts</>), a pointer to the output buffer
        (<literal>output</>), the maximal length that has been allocated for
        the output buffer (<literal>str_len</literal>) and the format mask to
        use for the conversion (<literal>fmtstr</literal>).
       </para>
       <para>
        Upon success, the function returns 0 and a negative value if an
        error occurred.
       </para>
       <para>
        You can use the following format specifiers for the format mask. The
        format specifiers are the same ones that are used in the
        <function>strftime</> function in <productname>libc</productname>. Any
        non-format specifier will be copied into the output buffer. 
        <!-- This is from the FreeBSD man page:
             http://www.freebsd.org/cgi/man.cgi?query=strftime&apropos=0&sektion=3&manpath=FreeBSD+7.0-current&format=html
        -->
        <itemizedlist>
         <listitem>
          <para>
           <literal>%A</literal> - is replaced by national representation of
           the full weekday name.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%a</literal> - is replaced by national representation of
           the abbreviated weekday name.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%B</literal> - is replaced by national representation of
           the full month name.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%b</literal> - is replaced by national representation of
           the abbreviated month name.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%C</literal> - is replaced by (year / 100) as decimal
           number; single digits are preceded by a zero.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%c</literal> - is replaced by national representation of
           time and date.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%D</literal> - is equivalent to
           <literal>%m/%d/%y</literal>.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%d</literal> - is replaced by the day of the month as a
           decimal number (01-31).
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%E*</literal> <literal>%O*</literal> -  POSIX locale
           extensions. The sequences
           <literal>%Ec</literal>
           <literal>%EC</literal> 
           <literal>%Ex</literal> 
           <literal>%EX</literal> 
           <literal>%Ey</literal> 
           <literal>%EY</literal> 
           <literal>%Od</literal> 
           <literal>%Oe</literal>
           <literal>%OH</literal> 
           <literal>%OI</literal> 
           <literal>%Om</literal> 
           <literal>%OM</literal> 
           <literal>%OS</literal> 
           <literal>%Ou</literal> 
           <literal>%OU</literal> 
           <literal>%OV</literal> 
           <literal>%Ow</literal> 
           <literal>%OW</literal> 
           <literal>%Oy</literal> 
           are supposed to provide alternative representations.
          </para>
          <para>
           Additionally <literal>%OB</literal> implemented to represent
           alternative months names (used standalone, without day mentioned).
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%e</literal> - is replaced by the day of month as a decimal
           number (1-31); single digits are preceded by a blank.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%F</literal> - is equivalent to <literal>%Y-%m-%d</literal>.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%G</literal> - is replaced by a year as a decimal number
           with century. This year is the one that contains the greater part of
           the week (Monday as the first day of the week).
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%g</literal> - is replaced by the same year as in
           <literal>%G</literal>, but as a decimal number without century
           (00-99).
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%H</literal> - is replaced by the hour (24-hour clock) as a
           decimal number (00-23).
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%h</literal> - the same as <literal>%b</literal>.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%I</literal> - is replaced by the hour (12-hour clock) as a
           decimal number (01-12).
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%j</literal> - is replaced by the day of the year as a
           decimal number (001-366).
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%k</literal> - is replaced by the hour (24-hour clock) as a
           decimal number (0-23); single digits are preceded by a blank.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%l</literal> - is replaced by the hour (12-hour clock) as a
           decimal number (1-12); single digits are preceded by a blank.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%M</literal> - is replaced by the minute as a decimal
           number (00-59).
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%m</literal> - is replaced by the month as a decimal number
           (01-12).
          </para>
         </listitem>
         <listitem>
          <para>
          <literal>%n</literal> - is replaced by a newline.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%O*</literal> - the same as <literal>%E*</literal>.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%p</literal> - is replaced by national representation of
           either "ante meridiem" or "post meridiem" as appropriate.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%R</literal> - is equivalent to <literal>%H:%M</literal>.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%r</literal> - is equivalent to <literal>%I:%M:%S
           %p</literal>.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%S</literal> - is replaced by the second as a decimal
           number (00-60).
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%s</literal> - is replaced by the number of seconds since
           the Epoch, UTC.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%T</literal> - is equivalent to <literal>%H:%M:%S</literal>
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%t</literal> - is replaced by a tab.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%U</literal> - is replaced by the week number of the year
           (Sunday as the first day of the week) as a decimal number (00-53).
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%u</literal> - is replaced by the weekday (Monday as the
           first day of the week) as a decimal number (1-7).
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%V</literal> - is replaced by the week number of the year
           (Monday as the first day of the week) as a decimal number (01-53).
           If the week containing January 1 has four or more days in the new
           year, then it is week 1; otherwise it is the last week of the
           previous year, and the next week is week 1.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%v</literal> - is equivalent to
           <literal>%e-%b-%Y</literal>.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%W</literal> - is replaced by the week number of the year
           (Monday as the first day of the week) as a decimal number (00-53).
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%w</literal> - is replaced by the weekday (Sunday as the
           first day of the week) as a decimal number (0-6).
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%X</literal> - is replaced by national representation of
           the time.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%x</literal> - is replaced by national representation of
           the date.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%Y</literal> - is replaced by the year with century as a
           decimal number.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%y</literal> - is replaced by the year without century as a
           decimal number (00-99).
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%Z</literal> - is replaced by the time zone name.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%z</literal> - is replaced by the time zone offset from
           UTC; a leading plus sign stands for east of UTC, a minus sign for
           west of UTC, hours and minutes follow with two digits each and no
           delimiter between them (common form for RFC 822 date headers).
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%+</literal> - is replaced by national representation of
           the date and time.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%-*</literal> - GNU libc extension. Do not do any padding
           when performing numerical outputs.
          </para>
         </listitem>
         <listitem>
          <para>
           $_* - GNU libc extension.    Explicitly specify space for padding.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%0*</literal> - GNU libc extension. Explicitly specify zero
           for padding.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>%%</literal> - is replaced by <literal>%</literal>.
          </para>
         </listitem>
        </itemizedlist>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPEStimestampsub">
      <term><function>PGTYPEStimestamp_sub</function></term>
      <listitem>
       <para>
        Subtract one timestamp from another one and save the result in a
        variable of type interval.
<synopsis>
int PGTYPEStimestamp_sub(timestamp *ts1, timestamp *ts2, interval *iv);
</synopsis>
        The function will subtract the timestamp variable that <literal>ts2</>
        points to from the timestamp variable that <literal>ts1</> points to
        and will store the result in the interval variable that <literal>iv</>
        points to.
       </para>
       <para>
        Upon success, the function returns 0 and a negative value if an
        error occurred.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPEStimestampdefmtasc">
      <term><function>PGTYPEStimestamp_defmt_asc</function></term>
      <listitem>
       <para>
        Parse a timestamp value from its textual representation using a
        formatting mask.
<synopsis>
int PGTYPEStimestamp_defmt_asc(char *str, char *fmt, timestamp *d);
</synopsis>
        The function receives the textual representation of a timestamp in the
        variable <literal>str</> as well as the formatting mask to use in the
        variable <literal>fmt</>. The result will be stored in the variable
        that <literal>d</> points to.
       </para>
       <para>
        If the formatting mask <literal>fmt</> is NULL, the function will fall
        back to the default formatting mask which is <literal>%Y-%m-%d
        %H:%M:%S</literal>.
       </para>
       <para>
        This is the reverse function to <xref
        linkend="PGTYPEStimestampfmtasc">.  See the documentation there in
        order to find out about the possible formatting mask entries.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPEStimestampaddinterval">
      <term><function>PGTYPEStimestamp_add_interval</function></term>
      <listitem>
       <para>
        Add an interval variable to a timestamp variable.
<synopsis>
int PGTYPEStimestamp_add_interval(timestamp *tin, interval *span, timestamp *tout);
</synopsis>
        The function receives a pointer to a timestamp variable <literal>tin</>
        and a pointer to an interval variable <literal>span</>. It adds the
        interval to the timestamp and saves the resulting timestamp in the
        variable that <literal>tout</> points to.
       </para>
       <para>
        Upon success, the function returns 0 and a negative value if an
        error occurred.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPEStimestampsubinterval">
      <term><function>PGTYPEStimestamp_sub_interval</function></term>
      <listitem>
       <para>
        Subtract an interval variable from a timestamp variable.
<synopsis>
int PGTYPEStimestamp_sub_interval(timestamp *tin, interval *span, timestamp *tout);
</synopsis>
        The function subtracts the interval variable that <literal>span</>
        points to from the timestamp variable that <literal>tin</> points to
        and saves the result into the variable that <literal>tout</> points
        to.
       </para>
       <para>
        Upon success, the function returns 0 and a negative value if an
        error occurred.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </sect2>

  <sect2>
   <title>The interval type</title>
   <para>
    The interval type in C enables your programs to deal with data of the SQL
    type interval. See <xref linkend="datatype-datetime"> for the equivalent
    type in the <productname>PostgreSQL</> server.
   </para>
   <para>
    The following functions can be used to work with the interval type:
    <variablelist>

     <varlistentry id="PGTYPESintervalnew">
      <term><function>PGTYPESinterval_new</function></term>
      <listitem>
       <para>
        Return a pointer to a newly allocated interval variable.
<synopsis>
interval *PGTYPESinterval_new(void);
</synopsis>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPESintervalfree">
      <term><function>PGTYPESinterval_free</function></term>
      <listitem>
       <para>
        Release the memory of a previously allocated interval variable.
<synopsis>
void PGTYPESinterval_new(interval *intvl);
</synopsis>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPESintervalfromasc">
      <term><function>PGTYPESinterval_from_asc</function></term>
      <listitem>
       <para>
        Parse an interval from its textual representation.
<synopsis>
interval *PGTYPESinterval_from_asc(char *str, char **endptr);
</synopsis>
        The function parses the input string <literal>str</> and returns a
        pointer to an allocated interval variable.
        At the moment ECPG always parses
        the complete string and so it currently does not support to store the
        address of the first invalid character in <literal>*endptr</literal>.
        You can safely set <literal>endptr</literal> to NULL.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPESintervaltoasc">
      <term><function>PGTYPESinterval_to_asc</function></term>
      <listitem>
       <para>
        Convert a variable of type interval to its textual representation.
<synopsis>
char *PGTYPESinterval_to_asc(interval *span);
</synopsis>
        The function converts the interval variable that <literal>span</>
        points to into a C char*. The output looks like this example:
        <literal>@@ 1 day 12 hours 59 mins 10 secs</literal>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPESintervalcopy">
      <term><function>PGTYPESinterval_copy</function></term>
      <listitem>
       <para>
        Copy a variable of type interval.
<synopsis>
int PGTYPESinterval_copy(interval *intvlsrc, interval *intvldest);
</synopsis>
        The function copies the interval variable that <literal>intvlsrc</>
        points to into the variable that <literal>intvldest</> points to. Note
        that you need to allocate the memory for the destination variable
        before.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </sect2>

  <sect2>
   <title>The decimal type</title>
   <para>
     The decimal type is similar to the numeric type. However it is limited to
     a maximum precision of 30 significant digits. In contrast to the numeric
     type which can be created on the heap only, the decimal type can be
     created either on the stack or on the heap (by means of the functions
     <function>PGTYPESdecimal_new</> and
     <function>PGTYPESdecimal_free</>).
     There are a lot of other functions that deal with the decimal type in the
     <productname>Informix</productname> compatibility mode described in <xref
     linkend="ecpg-informix-compat">.
   </para>
   <para>
    The following functions can be used to work with the decimal type and are
    not only contained in the <literal>libcompat</> library.
    <variablelist>
     <varlistentry>
      <term><function>PGTYPESdecimal_new</function></term>
      <listitem>
       <para>
       Request a pointer to a newly allocated decimal variable.
<synopsis>
decimal *PGTYPESdecimal_new(void);
</synopsis>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>PGTYPESdecimal_free</function></term>
      <listitem>
       <para>
       Free a decimal type, release all of its memory.
<synopsis>
void PGTYPESdecimal_free(decimal *var);
</synopsis>
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </sect2>
 
   <sect2>
    <title>errno values of pgtypeslib</title>
   <para>
    <variablelist>
     <varlistentry>
      <term><literal>PGTYPES_NUM_BAD_NUMERIC</literal></term>
      <listitem>
       <para>
        An argument should contain a numeric variable (or point to a numeric
        variable) but in fact its in-memory representation was invalid.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>PGTYPES_NUM_OVERFLOW</literal></term>
      <listitem>
       <para>
        An overflow occurred. Since the numeric type can deal with almost
        arbitrary precision, converting a numeric variable into other types
        might cause overflow.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>PGTYPES_NUM_UNDERFLOW</literal></term>
      <listitem>
       <para>
        An underflow occurred. Since the numeric type can deal with almost
        arbitrary precision, converting a numeric variable into other types
        might cause underflow.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>PGTYPES_NUM_DIVIDE_ZERO</literal></term>
      <listitem>
       <para>
        A division by zero has been attempted.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>PGTYPES_DATE_BAD_DATE</literal></term>
      <listitem>
       <para>
        
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>PGTYPES_DATE_ERR_EARGS</literal></term>
      <listitem>
       <para>
        
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>PGTYPES_DATE_ERR_ENOSHORTDATE</literal></term>
      <listitem>
       <para>
        
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>PGTYPES_INTVL_BAD_INTERVAL</literal></term>
      <listitem>
       <para>
        
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>PGTYPES_DATE_ERR_ENOTDMY</literal></term>
      <listitem>
       <para>
        
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>PGTYPES_DATE_BAD_DAY</literal></term>
      <listitem>
       <para>
        
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>PGTYPES_DATE_BAD_MONTH</literal></term>
      <listitem>
       <para>
        
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>PGTYPES_TS_BAD_TIMESTAMP</literal></term>
      <listitem>
       <para>
        
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </sect2>

   <sect2>
    <title>Special constants of pgtypeslib</title>
   <para>
    <variablelist>
     <varlistentry id="PGTYPESInvalidTimestamp">
      <term><literal>PGTYPESInvalidTimestamp</literal></term>
      <listitem>
       <para>
        A value of type timestamp representing an invalid time stamp. This is
        returned by the function <function>PGTYPEStimestamp_from_asc</> on
        parse error.
        Note that due to the internal representation of the <type>timestamp</type> data type,
        <literal>PGTYPESInvalidTimestamp</literal> is also a valid timestamp at
        the same time. It is set to <literal>1899-12-31 23:59:59</>. In order
        to detect errors, make sure that your application does not only test
        for <literal>PGTYPESInvalidTimestamp</literal> but also for
        <literal>errno != 0</> after each call to
        <function>PGTYPEStimestamp_from_asc</>.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </sect2>
 </sect1>

 <sect1 id="ecpg-descriptors">
  <title>Using Descriptor Areas</title>

  <para>
   An SQL descriptor area is a more sophisticated method for processing
   the result of a <command>SELECT</command>, <command>FETCH</command> or
   a <command>DESCRIBE</command> statement. An SQL descriptor area groups
   the data of one row of data together with metadata items into one
   data structure.  The metadata is particularly useful when executing
   dynamic SQL statements, where the nature of the result columns might
   not be known ahead of time. PostgreSQL provides two ways to use
   Descriptor Areas: the named SQL Descriptor Areas and the C-structure
   SQLDAs.
  </para>

  <sect2 id="ecpg-named-descriptors">
   <title>Named SQL Descriptor Areas</title>

   <para>
    A named SQL descriptor area consists of a header, which contains
    information concerning the entire descriptor, and one or more item
    descriptor areas, which basically each describe one column in the
    result row.
   </para>

   <para>
    Before you can use an SQL descriptor area, you need to allocate one:
<programlisting>
EXEC SQL ALLOCATE DESCRIPTOR <replaceable>identifier</replaceable>;
</programlisting>
    The identifier serves as the <quote>variable name</quote> of the
    descriptor area.  <remark>The scope of the allocated descriptor is WHAT?.</remark>
    When you don't need the descriptor anymore, you should deallocate
    it:
<programlisting>
EXEC SQL DEALLOCATE DESCRIPTOR <replaceable>identifier</replaceable>;
</programlisting>
   </para>

   <para>
    To use a descriptor area, specify it as the storage target in an
    <literal>INTO</literal> clause, instead of listing host variables:
<programlisting>
EXEC SQL FETCH NEXT FROM mycursor INTO SQL DESCRIPTOR mydesc;
</programlisting>
    If the result set is empty, the Descriptor Area will still contain
    the metadata from the query, i.e. the field names.
   </para>

   <para>
    For not yet executed prepared queries, the <command>DESCRIBE</command>
    statement can be used to get the metadata of the result set:
<programlisting> 
EXEC SQL BEGIN DECLARE SECTION;
char *sql_stmt = "SELECT * FROM table1";
EXEC SQL END DECLARE SECTION;

EXEC SQL PREPARE stmt1 FROM :sql_stmt;
EXEC SQL DESCRIBE stmt1 INTO SQL DESCRIPTOR mydesc;
</programlisting>
   </para>

   <para>
    Before PostgreSQL 9.0, the <literal>SQL</literal> keyword was optional,
    so using <literal>DESCRIPTOR</literal> and <literal>SQL DESCRIPTOR</literal>
    produced named SQL Descriptor Areas. Now it is mandatory, omitting
    the <literal>SQL</literal> keyword produces SQLDA Descriptor Areas,
    see <xref linkend="ecpg-sqlda-descriptors">. 
   </para>

   <para>
    In <command>DESCRIBE</command> and <command>FETCH</command> statements,
    the <literal>INTO</literal> and <literal>USING</literal> keywords can be
    used to similarly: they produce the result set and the metadata in a
    Descriptor Area.
   </para>

   <para>
    Now how do you get the data out of the descriptor area?  You can
    think of the descriptor area as a structure with named fields.  To
    retrieve the value of a field from the header and store it into a
    host variable, use the following command:
<programlisting>
EXEC SQL GET DESCRIPTOR <replaceable>name</replaceable> :<replaceable>hostvar</replaceable> = <replaceable>field</replaceable>;
</programlisting>
    Currently, there is only one header field defined:
    <replaceable>COUNT</replaceable>, which tells how many item
    descriptor areas exist (that is, how many columns are contained in
    the result).  The host variable needs to be of an integer type.  To
    get a field from the item descriptor area, use the following
    command:
<programlisting>
EXEC SQL GET DESCRIPTOR <replaceable>name</replaceable> VALUE <replaceable>num</replaceable> :<replaceable>hostvar</replaceable> = <replaceable>field</replaceable>;
</programlisting>
    <replaceable>num</replaceable> can be a literal integer or a host
    variable containing an integer. Possible fields are:

    <variablelist>
     <varlistentry>
      <term><literal>CARDINALITY</literal> (integer)</term>
      <listitem>
       <para>
        number of rows in the result set
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>DATA</literal></term>
      <listitem>
       <para>
        actual data item (therefore, the data type of this field
        depends on the query)
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>DATETIME_INTERVAL_CODE</literal> (integer)</term>
      <listitem>
       <para>
        ?
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>DATETIME_INTERVAL_PRECISION</literal> (integer)</term>
      <listitem>
       <para>
        not implemented
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>INDICATOR</literal> (integer)</term>
      <listitem>
       <para>
        the indicator (indicating a null value or a value truncation)
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>KEY_MEMBER</literal> (integer)</term>
      <listitem>
       <para>
        not implemented
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>LENGTH</literal> (integer)</term>
      <listitem>
       <para>
        length of the datum in characters
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>NAME</literal> (string)</term>
      <listitem>
       <para>
        name of the column
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>NULLABLE</literal> (integer)</term>
      <listitem>
       <para>
        not implemented
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>OCTET_LENGTH</literal> (integer)</term>
      <listitem>
       <para>
        length of the character representation of the datum in bytes
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>PRECISION</literal> (integer)</term>
      <listitem>
       <para>
        precision (for type <type>numeric</type>)
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>RETURNED_LENGTH</literal> (integer)</term>
      <listitem>
       <para>
        length of the datum in characters
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>RETURNED_OCTET_LENGTH</literal> (integer)</term>
      <listitem>
       <para>
        length of the character representation of the datum in bytes
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>SCALE</literal> (integer)</term>
      <listitem>
       <para>
        scale (for type <type>numeric</type>)
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>TYPE</literal> (integer)</term>
      <listitem>
       <para>
        numeric code of the data type of the column
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>

   <para>
    In <command>EXECUTE</command>, <command>DECLARE</command> and <command>OPEN</command>
    statements, the effect of the <literal>INTO</literal> and <literal>USING</literal>
    keywords are different. A Descriptor Area can also be manually built to
    provide the input parameters for a query or a cursor and
    <literal>USING SQL DESCRIPTOR <replaceable>name</replaceable></literal>
    is the way to pass the input parameters into a parametrized query. The statement
    to build a named SQL Descriptor Area is below:
<programlisting>
EXEC SQL SET DESCRIPTOR <replaceable>name</replaceable> VALUE <replaceable>num</replaceable> <replaceable>field</replaceable> = :<replaceable>hostvar</replaceable>;
</programlisting>
   </para>

   <para>
    PostgreSQL supports retrieving more that one record in one <command>FETCH</command>
    statement and storing the data in host variables in this case assumes that the
    variable is an array. E.g.:
<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
int id[5];
EXEC SQL END DECLARE SECTION;

EXEC SQL FETCH 5 FROM mycursor INTO SQL DESCRIPTOR mydesc;

EXEC SQL GET DESCRIPTOR mydesc VALUE 1 :id = DATA;
</programlisting>

   </para>

  </sect2>

  <sect2 id="ecpg-sqlda-descriptors">
   <title>SQLDA Descriptor Areas</title>

   <para>
    An SQLDA Descriptor Area is a C language structure which can be also used
    to get the result set and the metadata of a query. One structure stores one
    record from the result set.
<programlisting>
EXEC SQL include sqlda.h;
sqlda_t         *mysqlda;

EXEC SQL FETCH 3 FROM mycursor INTO DESCRIPTOR mysqlda;
</programlisting>
    Note that the <literal>SQL</literal> keyword is omitted. The paragraphs about
    the use cases of the <literal>INTO</literal> and <literal>USING</literal>
    keywords in <xref linkend="ecpg-named-descriptors"> also apply here with an addition.
    In a <command>DESCRIBE</command> statement the <literal>DESCRIPTOR</literal>
    keyword can be completely omitted if the <literal>INTO</literal> keyword is used:
<programlisting>
EXEC SQL DESCRIBE prepared_statement INTO mysqlda;
</programlisting>
   </para>

   <para>
    The structure of SQLDA is:
<programlisting>
#define NAMEDATALEN 64

struct sqlname
{
        short           length;
        char            data[NAMEDATALEN];
};

struct sqlvar_struct
{
        short           sqltype;
        short           sqllen;
        char       *sqldata;
        short      *sqlind;
        struct sqlname sqlname;
};

struct sqlda_struct
{
        char            sqldaid[8];
        long            sqldabc;
        short           sqln;
        short           sqld;
        struct sqlda_struct *desc_next;
        struct sqlvar_struct    sqlvar[1];
};

typedef struct sqlvar_struct    sqlvar_t;
typedef struct sqlda_struct     sqlda_t;
</programlisting>
   </para>

   <para>
    The allocated data for an SQLDA structure is variable as it depends on the
    number of fields in a result set and also depends on the length of the string
    data values in a record. The individual fields of the <literal>SQLDA</literal>
    structure are:

    <variablelist>
     <varlistentry>
      <term><literal>sqldaid</></term>
      <listitem>
       <para>
        It contains the "<literal>SQLDA  </literal>" literal string.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><literal>sqldabc</></term>
      <listitem>
       <para>
        It contains the size of the allocated space in bytes.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><literal>sqln</></term>
      <listitem>
       <para>
        It contains the number of input parameters for a parametrized query
        case it's passed into <command>OPEN</command>, <command>DECLARE</command> or
        <command>EXECUTE</command> statements using the <literal>USING</literal>
        keyword. In case it's used as output of <command>SELECT</command>,
        <command>EXECUTE</command> or <command>FETCH</command> statements,
        its value is the same as <literal>sqld</literal>
        statement
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><literal>sqld</></term>
      <listitem>
       <para>
        It contains the number of fields in a result set.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><literal>desc_next</></term>
      <listitem>
       <para>
        If the query returns more than one records, multiple linked SQLDA structures
        are returned, the first record is stored in the SQLDA returned in the
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><literal>sqlvar</></term>
      <listitem>
       <para>
        This is the array of the fields in the result set. The fields are:

        <variablelist>

         <varlistentry>
         <term><literal>sqltype</></term>
          <listitem>
           <para>
            It contains the type identifier of the field. For values,
            see <literal>enum ECPGttype</literal> in <literal>ecpgtype.h</literal>.
           </para>
          </listitem>
         </varlistentry>

         <varlistentry>
         <term><literal>sqllen</></term>
          <listitem>
           <para>
            It contains the binary length of the field. E.g. 4 bytes for <type>ECPGt_int</type>.
           </para>
          </listitem>
         </varlistentry>

         <varlistentry>
         <term><literal>sqldata</></term>
          <listitem>
           <para>
            <literal>(char *)sqldata</literal> points to the data.
           </para>
          </listitem>
         </varlistentry>

         <varlistentry>
         <term><literal>sqlind</></term>
          <listitem>
           <para>
            <literal>(char *)sqlind</literal> points to the NULL indicator for data.
            0 means NOT NULL, -1 means NULL.
           </para>
          </listitem>
         </varlistentry>

         <varlistentry>
         <term><literal>sqlname</></term>
          <listitem>
           <para>
            <literal>struct sqlname sqlname</literal> contains the name of the field
            in a structure:
<programlisting>
struct sqlname
{
        short           length;
        char            data[NAMEDATALEN];
};
</programlisting>

            <variablelist>
             <varlistentry>
              <term><literal>length</></term>
               <listitem>
                <para>
                 <literal>sqlname.length</literal> contains the length of the field name.
                </para>
               </listitem>
              </varlistentry>
             <varlistentry>
              <term><literal>data</></term>
               <listitem>
                <para>
                 <literal>sqlname.data</literal> contains the actual field name.
                </para>
               </listitem>
              </varlistentry>
            </variablelist>
           </para>
          </listitem>
         </varlistentry>

        </variablelist>
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>

  </sect2>

 </sect1>

 <sect1 id="ecpg-informix-compat">
  <title><productname>Informix</productname> compatibility mode</title>
  <para>
   <command>ecpg</command> can be run in a so-called <firstterm>Informix compatibility mode</>. If
   this mode is active, it tries to behave as if it were the <productname>Informix</productname>
   precompiler for <productname>Informix</productname> E/SQL. Generally spoken this will allow you to use
   the dollar sign instead of the <literal>EXEC SQL</> primitive to introduce
   embedded SQL commands.:
<programlisting>
$int j = 3;
$CONNECT TO :dbname;
$CREATE TABLE test(i INT PRIMARY KEY, j INT);
$INSERT INTO test(i, j) VALUES (7, :j);
$COMMIT;
</programlisting>
  </para>
  <para>
   There are two compatibility modes: <literal>INFORMIX</>, <literal>INFORMIX_SE</>
  </para>
  <para>
   When linking programs that use this compatibility mode, remember to link
   against <literal>libcompat</> that is shipped with ECPG.
  </para>
  <para>
   Besides the previously explained syntactic sugar, the <productname>Informix</productname> compatibility
   mode ports some functions for input, output and transformation of data as
   well as embedded SQL statements known from E/SQL to ECPG.
  </para>
  <para>
   <productname>Informix</productname> compatibility mode is closely connected to the pgtypeslib library
   of ECPG. pgtypeslib maps SQL data types to data types within the C host
   program and most of the additional functions of the <productname>Informix</productname> compatibility
   mode allow you to operate on those C host program types. Note however that
   the extent of the compatibility is limited. It does not try to copy <productname>Informix</productname>
   behavior; it allows you to do more or less the same operations and gives
   you functions that have the same name and the same basic behavior but it is
   no drop-in replacement if you are using <productname>Informix</productname> at the moment. Moreover,
   some of the data types are different. For example,
   <productname>PostgreSQL's</productname> datetime and interval types do not
   know about ranges like for example <literal>YEAR TO MINUTE</> so you won't
   find support in ECPG for that either.
  </para>

  <sect2>
   <title>Additional types</title>
   <para>
    The Informix-special "string" pseudo-type for storing right-trimmed character string data is now
    supported in Informix-mode without using <literal>typedef</literal>. In fact, in Informix-mode,
    ECPG refuses to process source files that contain <literal>typedef sometype string;</literal>
<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
string userid; /* this variable will contain trimmed data */
EXEC SQL END DECLARE SECTION;

EXEC SQL FETCH MYCUR INTO :userid;
</programlisting>
   </para>
  </sect2>

  <sect2>
   <title>Additional/missing embedded SQL statements</title>
   <para>
    <variablelist>
     <varlistentry>
      <term><literal>CLOSE DATABASE</></term>
      <listitem>
       <para>
        This statement closes the current connection. In fact, this is a
        synonym for ECPG's <literal>DISCONNECT CURRENT</>.:
<programlisting>
$CLOSE DATABASE;                /* close the current connection */
EXEC SQL CLOSE DATABASE;
</programlisting>
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><literal>FREE cursor_name</></term>
      <listitem>
       <para>
        Due to the differences how ECPG works compared to Informix's ESQL/C (i.e. which steps
        are purely grammar transformations and which steps rely on the underlying run-time library)
        there is no <literal>FREE cursor_name</> statement in ECPG. This is because in ECPG,
        <literal>DECLARE CURSOR</literal> doesn't translate to a function call into
        the run-time library that uses to the cursor name. This means that there's no run-time
        bookkeeping of SQL cursors in the ECPG run-time library, only in the PostgreSQL server.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><literal>FREE statement_name</></term>
      <listitem>
       <para>
        <literal>FREE statement_name</> is a synonym for <literal>DEALLOCATE PREPARE statement_name</>.
       </para>      
      </listitem>   
     </varlistentry>
    </variablelist>
   </para>
  </sect2>

  <sect2>
   <title>Informix-compatible SQLDA Descriptor Areas</title>
   <para>
    Informix-compatible mode supports a different structure than the one described in
    <xref linkend="ecpg-sqlda-descriptors">. See below:
<programlisting>
struct sqlvar_compat
{
        short   sqltype;
        int     sqllen;
        char       *sqldata;
        short      *sqlind;
        char       *sqlname;
        char       *sqlformat;
        short   sqlitype;
        short   sqlilen;
        char       *sqlidata;
        int     sqlxid;
        char       *sqltypename;
        short   sqltypelen;
        short   sqlownerlen;
        short   sqlsourcetype;
        char       *sqlownername;
        int     sqlsourceid;

        char       *sqlilongdata;
        int     sqlflags;
        void       *sqlreserved;
};

struct sqlda_compat
{
        short           sqld;
        struct sqlvar_compat *sqlvar;
        char            desc_name[19];
        short           desc_occ;
        struct sqlda_compat *desc_next;
        void               *reserved;
};

typedef struct sqlvar_compat    sqlvar_t;
typedef struct sqlda_compat     sqlda_t;
</programlisting>
   </para>

   <para>
    The global properties are:
    <variablelist>  

     <varlistentry>
     <term><literal>sqld</></term>
      <listitem>
       <para>
        The number of fields in the <literal>SQLDA</> descriptor.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
     <term><literal>sqlvar</></term>   
      <listitem>
       <para>
        Pointer to the per-field properties.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
     <term><literal>desc_name</></term>
      <listitem>
       <para>
        Unused, filled with zero-bytes.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
     <term><literal>desc_occ</></term>
      <listitem>
       <para>
        Size of the allocated structure.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
     <term><literal>desc_next</></term>
      <listitem>
       <para>
        Pointer to the next SQLDA structure if the result set contains more than one records.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
     <term><literal>reserved</></term>
      <listitem>
       <para>
        Unused pointer, contains NULL. Kept for Informix-compatibility.
       </para>
      </listitem>
     </varlistentry>

    </variablelist>

    The per-field properties are below, they are stored in the <literal>sqlvar</literal> array:

    <variablelist>

     <varlistentry>
     <term><literal>sqltype</></term>
      <listitem>
       <para>
        Type of the field. Constants are in <literal>sqltypes.h</literal>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
     <term><literal>sqllen</></term>
      <listitem>
       <para>
        Length of the field data.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
     <term><literal>sqldata</></term>
      <listitem>
       <para>
        Pointer to the field data. The pointer is of <literal>char *</literal> type,
        the data pointed by it is in a binary format. Example:
<programlisting>
int intval; 

switch (sqldata->sqlvar[i].sqltype)
{
    case SQLINTEGER:
        intval = *(int *)sqldata->sqlvar[i].sqldata;
        break;
  ...
}
</programlisting>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
     <term><literal>sqlind</></term>
      <listitem>
       <para>
        Pointer to the NULL indicator. If returned by DESCRIBE or FETCH then it's always a valid pointer.
        If used as input for <literal>EXECUTE ... USING sqlda;</literal> then NULL-pointer value means   
        that the value for this field is non-NULL. Otherwise a valid pointer and <literal>sqlitype</literal>
        has to be properly set. Example:
<programlisting>
if (*(int2 *)sqldata->sqlvar[i].sqlind != 0)
    printf("value is NULL\n");
</programlisting>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
     <term><literal>sqlname</></term>
      <listitem>
       <para>
        Name of the field. 0-terminated string.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
     <term><literal>sqlformat</></term>
      <listitem>
       <para>
        Reserved in Informix, value of <function>PQfformat()</> for the field.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
     <term><literal>sqlitype</></term>
      <listitem>
       <para>
        Type of the NULL indicator data. It's always SQLSMINT when returning data from the server.
        When the <literal>SQLDA</literal> is used for a parametrized query, the data is treated   
        according to the set type.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
     <term><literal>sqlilen</></term>
      <listitem>
       <para>
        Length of the NULL indicator data.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
     <term><literal>sqlxid</></term>
      <listitem>
       <para>
        Extended type of the field, result of <function>PQftype()</>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
     <term><literal>sqltypename</></term>
     <term><literal>sqltypelen</></term> 
     <term><literal>sqlownerlen</></term>
     <term><literal>sqlsourcetype</></term>
     <term><literal>sqlownername</></term> 
     <term><literal>sqlsourceid</></term>  
     <term><literal>sqlflags</></term>     
     <term><literal>sqlreserved</></term>  
      <listitem>
       <para>
        Unused.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
     <term><literal>sqlilongdata</></term>
      <listitem>
       <para>
        It equals to <literal>sqldata</literal> if <literal>sqllen</literal> is larger than 32KB.
       </para>
      </listitem>
     </varlistentry>

    </variablelist>

    Example:
<programlisting>
EXEC SQL INCLUDE sqlda.h;

    sqlda_t        *sqlda; /* This doesn't need to be under embedded DECLARE SECTION */

    EXEC SQL BEGIN DECLARE SECTION;
    char *prep_stmt = "select * from table1";
    int i;
    EXEC SQL END DECLARE SECTION;

    ...

    EXEC SQL PREPARE mystmt FROM :prep_stmt;

    EXEC SQL DESCRIBE mystmt INTO sqlda;

    printf("# of fields: %d\n", sqlda-&gt;sqld);
    for (i = 0; i &lt; sqlda-&gt;sqld; i++)
      printf("field %d: \"%s\"\n", sqlda-&gt;sqlvar[i]-&gt;sqlname);

    EXEC SQL DECLARE mycursor CURSOR FOR mystmt;
    EXEC SQL OPEN mycursor;
    EXEC SQL WHENEVER NOT FOUND GOTO out;

    while (1)
    {
      EXEC SQL FETCH mycursor USING sqlda;
    }

    EXEC SQL CLOSE mycursor;

    free(sqlda); /* The main structure is all to be free(),
                  * sqlda and sqlda-&gt;sqlvar is in one allocated area */
</programlisting>
    For more information, see the <literal>sqlda.h</> header and the
    <literal>src/interfaces/ecpg/test/compat_informix/sqlda.pgc</literal> regression test.
   </para>
  </sect2>

  <sect2>
   <title>Additional functions</title>
   <para>
    <variablelist>
     <varlistentry>
      <term><function>decadd</></term>
      <listitem>
       <para>
        Add two decimal type values.
<synopsis>
int decadd(decimal *arg1, decimal *arg2, decimal *sum);
</synopsis>
        The function receives a pointer to the first operand of type decimal
        (<literal>arg1</>), a pointer to the second operand of type decimal
        (<literal>arg2</>) and a pointer to a value of type decimal that will
        contain the sum (<literal>sum</>). On success, the function returns 0.
        <symbol>ECPG_INFORMIX_NUM_OVERFLOW</> is returned in case of overflow and 
        <symbol>ECPG_INFORMIX_NUM_UNDERFLOW</> in case of underflow. -1 is returned for
        other failures and <varname>errno</> is set to the respective <varname>errno</> number of the
        pgtypeslib.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>deccmp</></term>
      <listitem>
       <para>
        Compare two variables of type decimal.
<synopsis>
int deccmp(decimal *arg1, decimal *arg2);
</synopsis>
        The function receives a pointer to the first decimal value
        (<literal>arg1</>), a pointer to the second decimal value
        (<literal>arg2</>) and returns an integer value that indicates which is
        the bigger value.
        <itemizedlist>
         <listitem>
          <para>
           1, if the value that <literal>arg1</> points to is bigger than the
           value that <literal>var2</> points to
          </para>
         </listitem>
         <listitem>
          <para>
           -1, if the value that <literal>arg1</> points to is smaller than the
           value that <literal>arg2</> points to </para>
         </listitem>
         <listitem>
          <para>
           0, if the value that <literal>arg1</> points to and the value that
           <literal>arg2</> points to are equal
          </para>
         </listitem>
        </itemizedlist>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>deccopy</></term>
      <listitem>
       <para>
        Copy a decimal value.
<synopsis>
void deccopy(decimal *src, decimal *target);
</synopsis>
        The function receives a pointer to the decimal value that should be
        copied as the first argument (<literal>src</>) and a pointer to the
        target structure of type decimal (<literal>target</>) as the second
        argument.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>deccvasc</></term>
      <listitem>
       <para>
        Convert a value from its ASCII representation into a decimal type.
<synopsis>
int deccvasc(char *cp, int len, decimal *np);
</synopsis>
        The function receives a pointer to string that contains the string
        representation of the number to be converted (<literal>cp</>) as well
        as its length <literal>len</>. <literal>np</> is a pointer to the
        decimal value that saves the result of the operation.
       </para>
       <para>
        Valid formats are for example:
         <literal>-2</literal>,
         <literal>.794</literal>,
         <literal>+3.44</literal>,
         <literal>592.49E07</literal> or
         <literal>-32.84e-4</literal>.
       </para>
       <para>
        The function returns 0 on success. If overflow or underflow occurred,
        <literal>ECPG_INFORMIX_NUM_OVERFLOW</> or
        <literal>ECPG_INFORMIX_NUM_UNDERFLOW</> is returned. If the ASCII
        representation could not be parsed,
        <literal>ECPG_INFORMIX_BAD_NUMERIC</> is returned or
        <literal>ECPG_INFORMIX_BAD_EXPONENT</> if this problem occurred while
        parsing the exponent.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>deccvdbl</></term>
      <listitem>
       <para>
        Convert a value of type double to a value of type decimal.
<synopsis>
int deccvdbl(double dbl, decimal *np);
</synopsis>
        The function receives the variable of type double that should be
        converted as its first argument (<literal>dbl</>). As the second
        argument (<literal>np</>), the function receives a pointer to the
        decimal variable that should hold the result of the operation.
       </para>
       <para>
        The function returns 0 on success and a negative value if the
        conversion failed.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>deccvint</></term>
      <listitem>
       <para>
        Convert a value of type int to a value of type decimal.
<synopsis>
int deccvint(int in, decimal *np);
</synopsis>
        The function receives the variable of type int that should be
        converted as its first argument (<literal>in</>). As the second
        argument (<literal>np</>), the function receives a pointer to the
        decimal variable that should hold the result of the operation.
       </para>
       <para>
        The function returns 0 on success and a negative value if the
        conversion failed.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>deccvlong</></term>
      <listitem>
       <para>
        Convert a value of type long to a value of type decimal.
<synopsis>
int deccvlong(long lng, decimal *np);
</synopsis>
        The function receives the variable of type long that should be
        converted as its first argument (<literal>lng</>). As the second
        argument (<literal>np</>), the function receives a pointer to the
        decimal variable that should hold the result of the operation.
       </para>
       <para>
        The function returns 0 on success and a negative value if the
        conversion failed.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>decdiv</></term>
      <listitem>
       <para>
        Divide two variables of type decimal.
<synopsis>
int decdiv(decimal *n1, decimal *n2, decimal *result);
</synopsis>
        The function receives pointers to the variables that are the first
        (<literal>n1</>) and the second (<literal>n2</>) operands and
        calculates <literal>n1</>/<literal>n2</>. <literal>result</> is a
        pointer to the variable that should hold the result of the operation.
       </para>
       <para>
        On success, 0 is returned and a negative value if the division fails.
        If overflow or underflow occurred, the function returns
        <literal>ECPG_INFORMIX_NUM_OVERFLOW</> or
        <literal>ECPG_INFORMIX_NUM_UNDERFLOW</> respectively. If an attempt to
        divide by zero is observed, the function returns
        <literal>ECPG_INFORMIX_DIVIDE_ZERO</literal>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>decmul</></term>
      <listitem>
       <para>
        Multiply two decimal values.
<synopsis>
int decmul(decimal *n1, decimal *n2, decimal *result);
</synopsis>
        The function receives pointers to the variables that are the first
        (<literal>n1</>) and the second (<literal>n2</>) operands and
        calculates <literal>n1</>*<literal>n2</>. <literal>result</> is a
        pointer to the variable that should hold the result of the operation.
       </para>
       <para>
        On success, 0 is returned and a negative value if the multiplication
        fails. If overflow or underflow occurred, the function returns
        <literal>ECPG_INFORMIX_NUM_OVERFLOW</> or
        <literal>ECPG_INFORMIX_NUM_UNDERFLOW</> respectively.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>decsub</></term>
      <listitem>
       <para>
        Subtract one decimal value from another.
<synopsis>
int decsub(decimal *n1, decimal *n2, decimal *result);
</synopsis>
        The function receives pointers to the variables that are the first
        (<literal>n1</>) and the second (<literal>n2</>) operands and
        calculates <literal>n1</>-<literal>n2</>. <literal>result</> is a
        pointer to the variable that should hold the result of the operation.
       </para>
       <para>
        On success, 0 is returned and a negative value if the subtraction
        fails. If overflow or underflow occurred, the function returns
        <literal>ECPG_INFORMIX_NUM_OVERFLOW</> or
        <literal>ECPG_INFORMIX_NUM_UNDERFLOW</> respectively.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>dectoasc</></term>
      <listitem>
       <para>
        Convert a variable of type decimal to its ASCII representation in a C
        char* string.
<synopsis>
int dectoasc(decimal *np, char *cp, int len, int right)
</synopsis>
        The function receives a pointer to a variable of type decimal
        (<literal>np</>) that it converts to its textual representation.
        <literal>cp</> is the buffer that should hold the result of the
        operation. The parameter <literal>right</> specifies, how many digits
        right of the decimal point should be included in the output. The result
        will be rounded to this number of decimal digits. Setting
        <literal>right</> to -1 indicates that all available decimal digits
        should be included in the output. If the length of the output buffer,
        which is indicated by <literal>len</> is not sufficient to hold the
        textual representation including the trailing NUL character, only a
        single <literal>*</> character is stored in the result and -1 is
        returned.
       </para>
       <para>
        The function returns either -1 if the buffer <literal>cp</> was too
        small or <literal>ECPG_INFORMIX_OUT_OF_MEMORY</> if memory was
        exhausted. 
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>dectodbl</></term>
      <listitem>
       <para>
        Convert a variable of type decimal to a double.
<synopsis>
int dectodbl(decimal *np, double *dblp);
</synopsis>
        The function receives a pointer to the decimal value to convert
        (<literal>np</>) and a pointer to the double variable that
        should hold the result of the operation (<literal>dblp</>).
       </para>
       <para>
        On success, 0 is returned and a negative value if the conversion
        failed.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>dectoint</></term>
      <listitem>
       <para>
        Convert a variable to type decimal to an integer.
<synopsis>
int dectoint(decimal *np, int *ip);
</synopsis>
        The function receives a pointer to the decimal value to convert
        (<literal>np</>) and a pointer to the integer variable that
        should hold the result of the operation (<literal>ip</>).
       </para>
       <para>
        On success, 0 is returned and a negative value if the conversion
        failed. If an overflow occurred, <literal>ECPG_INFORMIX_NUM_OVERFLOW</>
        is returned.
       </para>
       <para>
        Note that the ECPG implementation differs from the <productname>Informix</productname>
        implementation. <productname>Informix</productname> limits an integer to the range from -32767 to
        32767, while the limits in the ECPG implementation depend on the
        architecture (<literal>-INT_MAX .. INT_MAX</>).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>dectolong</></term>
      <listitem>
       <para>
        Convert a variable to type decimal to a long integer.
<synopsis>
int dectolong(decimal *np, long *lngp);
</synopsis>
        The function receives a pointer to the decimal value to convert
        (<literal>np</>) and a pointer to the long variable that
        should hold the result of the operation (<literal>lngp</>).
       </para>
       <para>
        On success, 0 is returned and a negative value if the conversion
        failed. If an overflow occurred, <literal>ECPG_INFORMIX_NUM_OVERFLOW</>
        is returned.
       </para>
       <para>
        Note that the ECPG implementation differs from the <productname>Informix</productname>
        implementation. <productname>Informix</productname> limits a long integer to the range from
        -2,147,483,647 to 2,147,483,647, while the limits in the ECPG
        implementation depend on the architecture (<literal>-LONG_MAX ..
        LONG_MAX</>).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rdatestr</></term>
      <listitem>
       <para>
        Converts a date to a C char* string.
<synopsis>
int rdatestr(date d, char *str);
</synopsis>
        The function receives two arguments, the first one is the date to
        convert (<literal>d</> and the second one is a pointer to the target
        string. The output format is always <literal>yyyy-mm-dd</>, so you need
        to allocate at least 11 bytes (including the NUL-terminator) for the
        string.
       </para>
       <para>
        The function returns 0 on success and a negative value in case of
        error.
       </para>
       <para>
        Note that ECPG's implementation differs from the <productname>Informix</productname>
        implementation. In <productname>Informix</productname> the format can be influenced by setting
        environment variables. In ECPG however, you cannot change the output
        format.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rstrdate</></term>
      <listitem>
       <para>
        Parse the textual representation of a date.
<synopsis>
int rstrdate(char *str, date *d);
</synopsis>
        The function receives the textual representation of the date to convert
        (<literal>str</>) and a pointer to a variable of type date
        (<literal>d</>). This function does not allow you to specify a format
        mask. It uses the default format mask of <productname>Informix</productname> which is
        <literal>mm/dd/yyyy</>. Internally, this function is implemented by
        means of <function>rdefmtdate</>. Therefore, <function>rstrdate</> is
        not faster and if you have the choice you should opt for
        <function>rdefmtdate</> which allows you to specify the format mask
        explicitly.
       </para>
       <para>
        The function returns the same values as <function>rdefmtdate</>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rtoday</></term>
      <listitem>
       <para>
        Get the current date.
<synopsis>
void rtoday(date *d);
</synopsis>
        The function receives a pointer to a date variable (<literal>d</>)
        that it sets to the current date.
       </para>
       <para>
        Internally this function uses the <xref linkend="PGTYPESdatetoday">
        function.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rjulmdy</></term>
      <listitem>
       <para>
        Extract the values for the day, the month and the year from a variable
        of type date.
<synopsis>
int rjulmdy(date d, short mdy[3]);
</synopsis>
        The function receives the date <literal>d</> and a pointer to an array
        of 3 short integer values <literal>mdy</>. The variable name indicates
        the sequential order: <literal>mdy[0]</> will be set to contain the
        number of the month, <literal>mdy[1]</> will be set to the value of the
        day and <literal>mdy[2]</> will contain the year.
       </para>
       <para>
        The function always returns 0 at the moment.
       </para>
       <para>
        Internally the function uses the <xref linkend="PGTYPESdatejulmdy">
        function.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rdefmtdate</></term>
      <listitem>
       <para>
        Use a format mask to convert a character string to a value of type
        date.
<synopsis>
int rdefmtdate(date *d, char *fmt, char *str);
</synopsis>
        The function receives a pointer to the date value that should hold the
        result of the operation (<literal>d</>), the format mask to use for
        parsing the date (<literal>fmt</>) and the C char* string containing
        the textual representation of the date (<literal>str</>). The textual
        representation is expected to match the format mask. However you do not
        need to have a 1:1 mapping of the string to the format mask. The
        function only analyzes the sequential order and looks for the literals
        <literal>yy</literal> or <literal>yyyy</literal> that indicate the
        position of the year, <literal>mm</literal> to indicate the position of
        the month and <literal>dd</literal> to indicate the position of the
        day.
       </para>
       <para>
        The function returns the following values:
        <itemizedlist>
         <listitem>
          <para>
           0 - The function terminated successfully.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>ECPG_INFORMIX_ENOSHORTDATE</> - The date does not contain
           delimiters between day, month and year. In this case the input
           string must be exactly 6 or 8 bytes long but isn't.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>ECPG_INFORMIX_ENOTDMY</> - The format string did not
           correctly indicate the sequential order of year, month and day.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>ECPG_INFORMIX_BAD_DAY</> - The input string does not
           contain a valid day.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>ECPG_INFORMIX_BAD_MONTH</> - The input string does not
           contain a valid month.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>ECPG_INFORMIX_BAD_YEAR</> - The input string does not
           contain a valid year.
          </para>
         </listitem>
        </itemizedlist>
       </para>
       <para>
        Internally this function is implemented to use the <xref
        linkend="PGTYPESdatedefmtasc"> function. See the reference there for a
        table of example input.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rfmtdate</></term>
      <listitem>
       <para>
        Convert a variable of type date to its textual representation using a
        format mask.
<synopsis>
int rfmtdate(date d, char *fmt, char *str);
</synopsis>
        The function receives the date to convert (<literal>d</>), the format
        mask (<literal>fmt</>) and the string that will hold the textual
        representation of the date (<literal>str</>).
       </para>
       <para>
        On success, 0 is returned and a negative value if an error occurred.
       </para>
       <para>
        Internally this function uses the <xref linkend="PGTYPESdatefmtasc">
        function, see the reference there for examples.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rmdyjul</></term>
      <listitem>
       <para>
        Create a date value from an array of 3 short integers that specify the
        day, the month and the year of the date.
<synopsis>
int rmdyjul(short mdy[3], date *d);
</synopsis>
        The function receives the array of the 3 short integers
        (<literal>mdy</>) and a pointer to a variable of type date that should
        hold the result of the operation.
       </para>
       <para>
        Currently the function returns always 0.
       </para>
       <para>
        Internally the function is implemented to use the function <xref
        linkend="PGTYPESdatemdyjul">.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rdayofweek</></term>
      <listitem>
       <para>
        Return a number representing the day of the week for a date value.
<synopsis>
int rdayofweek(date d);
</synopsis>
        The function receives the date variable <literal>d</> as its only
        argument and returns an integer that indicates the day of the week for
        this date.
        <itemizedlist>
         <listitem>
          <para>
           0 - Sunday
          </para>
         </listitem>
         <listitem>
          <para>
           1 - Monday
          </para>
         </listitem>
         <listitem>
          <para>
           2 - Tuesday
          </para>
         </listitem>
         <listitem>
          <para>
           3 - Wednesday
          </para>
         </listitem>
         <listitem>
          <para>
           4 - Thursday
          </para>
         </listitem>
         <listitem>
          <para>
           5 - Friday
          </para>
         </listitem>
         <listitem>
          <para>
           6 - Saturday
          </para>
         </listitem>
        </itemizedlist>
       </para>
       <para>
        Internally the function is implemented to use the function <xref
        linkend="PGTYPESdatedayofweek">.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>dtcurrent</></term>
      <listitem>
       <para>
        Retrieve the current timestamp.
<synopsis>
void dtcurrent(timestamp *ts);
</synopsis>
        The function retrieves the current timestamp and saves it into the
        timestamp variable that <literal>ts</> points to.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>dtcvasc</></term>
      <listitem>
       <para>
        Parses a timestamp from its textual representation
        into a timestamp variable.
<synopsis>
int dtcvasc(char *str, timestamp *ts);
</synopsis>
        The function receives the string to parse (<literal>str</>) and a
        pointer to the timestamp variable that should hold the result of the
        operation (<literal>ts</>).
       </para>
       <para>
        The function returns 0 on success and a negative value in case of
        error.
       </para>
       <para>
        Internally this function uses the <xref
        linkend="PGTYPEStimestampfromasc"> function. See the reference there
        for a table with example inputs.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>dtcvfmtasc</></term>
      <listitem>
       <para>
        Parses a timestamp from its textual representation
        using a format mask into a timestamp variable.
<synopsis>
dtcvfmtasc(char *inbuf, char *fmtstr, timestamp *dtvalue)
</synopsis>
        The function receives the string to parse (<literal>inbuf</>), the
        format mask to use (<literal>fmtstr</>) and a pointer to the timestamp
        variable that should hold the result of the operation
        (<literal>dtvalue</>).
       </para>
       <para>
        This function is implemented by means of the <xref
        linkend="PGTYPEStimestampdefmtasc"> function. See the documentation
        there for a list of format specifiers that can be used.
       </para>
       <para>
        The function returns 0 on success and a negative value in case of
        error.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>dtsub</></term>
      <listitem>
       <para>
        Subtract one timestamp from another and return a variable of type
        interval.
<synopsis>
int dtsub(timestamp *ts1, timestamp *ts2, interval *iv);
</synopsis>
        The function will subtract the timestamp variable that <literal>ts2</>
        points to from the timestamp variable that <literal>ts1</> points to
        and will store the result in the interval variable that <literal>iv</>
        points to.
       </para>
       <para>
        Upon success, the function returns 0 and a negative value if an
        error occurred.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>dttoasc</></term>
      <listitem>
       <para>
        Convert a timestamp variable to a C char* string.
<synopsis>
int dttoasc(timestamp *ts, char *output);
</synopsis>
        The function receives a pointer to the timestamp variable to convert
        (<literal>ts</>) and the string that should hold the result of the
        operation <literal>output</>). It converts <literal>ts</> to its
        textual representation according to the SQL standard, which is
        be <literal>YYYY-MM-DD HH:MM:SS</literal>.
       </para>
       <para>
        Upon success, the function returns 0 and a negative value if an
        error occurred.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>dttofmtasc</></term>
      <listitem>
       <para>
        Convert a timestamp variable to a C char* using a format mask.
<synopsis>
int dttofmtasc(timestamp *ts, char *output, int str_len, char *fmtstr);
</synopsis>
        The function receives a pointer to the timestamp to convert as its
        first argument (<literal>ts</>), a pointer to the output buffer
        (<literal>output</>), the maximal length that has been allocated for
        the output buffer (<literal>str_len</literal>) and the format mask to
        use for the conversion (<literal>fmtstr</literal>).
       </para>
       <para>
        Upon success, the function returns 0 and a negative value if an
        error occurred.
       </para>
       <para>
        Internally, this function uses the <xref
        linkend="PGTYPEStimestampfmtasc"> function. See the reference there for
        information on what format mask specifiers can be used.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>intoasc</></term>
      <listitem>
       <para>
        Convert an interval variable to a C char* string.
<synopsis>
int intoasc(interval *i, char *str);
</synopsis>
        The function receives a pointer to the interval variable to convert
        (<literal>i</>) and the string that should hold the result of the
        operation <literal>str</>). It converts <literal>i</> to its
        textual representation according to the SQL standard, which is
        be <literal>YYYY-MM-DD HH:MM:SS</literal>.
       </para>
       <para>
        Upon success, the function returns 0 and a negative value if an
        error occurred.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rfmtlong</></term>
      <listitem>
       <para>
        Convert a long integer value to its textual representation using a
        format mask.
<synopsis>
int rfmtlong(long lng_val, char *fmt, char *outbuf);
</synopsis>
        The function receives the long value <literal>lng_val</>, the format
        mask <literal>fmt</> and a pointer to the output buffer
        <literal>outbuf</>. It converts the long value according to the format
        mask to its textual representation.
       </para>
       <para>
        The format mask can be composed of the following format specifying
        characters:
        <itemizedlist>
         <listitem>
          <para>
           <literal>*</literal> (asterisk) - if this position would be blank
           otherwise, fill it with an asterisk.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>&amp;</literal> (ampersand) - if this position would be
           blank otherwise, fill it with a zero.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>#</literal> - turn leading zeroes into blanks.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>&lt;</literal> - left-justify the number in the string.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>,</literal> (comma) - group numbers of four or more digits
           into groups of three digits separated by a comma.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>.</literal> (period) - this character separates the
           whole-number part of the number from the fractional part.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>-</literal> (minus) - the minus sign appears if the number
           is a negative value.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>+</literal> (plus) - the plus sign appears if the number is
           a positive value.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>(</literal> - this replaces the minus sign in front of the
           negative number. The minus sign will not appear.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>)</literal> - this character replaces the minus and is
           printed behind the negative value.
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>$</literal> - the currency symbol.
          </para>
         </listitem>
        </itemizedlist>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rupshift</></term>
      <listitem>
       <para>
        Convert a string to upper case.
<synopsis>
void rupshift(char *str);
</synopsis>
        The function receives a pointer to the string and transforms every
        lower case character to upper case.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>byleng</></term>
      <listitem>
       <para>
        Return the number of characters in a string without counting trailing
        blanks.
<synopsis>
int byleng(char *str, int len);
</synopsis>
        The function expects a fixed-length string as its first argument
        (<literal>str</>) and its length as its second argument
        (<literal>len</>). It returns the number of significant characters,
        that is the length of the string without trailing blanks.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>ldchar</></term>
      <listitem>
       <para>
        Copy a fixed-length string into a null-terminated string.
<synopsis>
void ldchar(char *src, int len, char *dest);
</synopsis>
        The function receives the fixed-length string to copy
        (<literal>src</>), its length (<literal>len</>) and a pointer to the
        destination memory (<literal>dest</>). Note that you need to reserve at
        least <literal>len+1</> bytes for the string that <literal>dest</>
        points to. The function copies at most <literal>len</> bytes to the new
        location (less if the source string has trailing blanks) and adds the
        null-terminator.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rgetmsg</></term>
      <listitem>
       <para>
<synopsis>
int rgetmsg(int msgnum, char *s, int maxsize);
</synopsis>
        This function exists but is not implemented at the moment!
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rtypalign</></term>
      <listitem>
       <para>
<synopsis>
int rtypalign(int offset, int type);
</synopsis>
        This function exists but is not implemented at the moment!
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rtypmsize</></term>
      <listitem>
       <para>
<synopsis>
int rtypmsize(int type, int len);
</synopsis>
        This function exists but is not implemented at the moment!
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rtypwidth</></term>
      <listitem>
       <para>
<synopsis>
int rtypwidth(int sqltype, int sqllen);
</synopsis>
        This function exists but is not implemented at the moment!
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="rsetnull">
      <term><function>rsetnull</></term>
      <listitem>
       <para>
        Set a variable to NULL.
<synopsis>
int rsetnull(int t, char *ptr);
</synopsis>
        The function receives an integer that indicates the type of the
        variable and a pointer to the variable itself that is casted to a C
        char* pointer.
       </para>
       <para>
        The following types exist:
        <itemizedlist>
         <listitem>
          <para>
           <literal>CCHARTYPE</literal> - For a variable of type <type>char</type> or <type>char*</type>
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>CSHORTTYPE</literal> - For a variable of type <type>short int</type>
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>CINTTYPE</literal> - For a variable of type <type>int</type>
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>CBOOLTYPE</literal> - For a variable of type <type>boolean</type>
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>CFLOATTYPE</literal> - For a variable of type <type>float</type>
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>CLONGTYPE</literal> - For a variable of type <type>long</type>
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>CDOUBLETYPE</literal> - For a variable of type <type>double</type>
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>CDECIMALTYPE</literal> - For a variable of type <type>decimal</type>
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>CDATETYPE</literal> - For a variable of type <type>date</type>
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>CDTIMETYPE</literal> - For a variable of type <type>timestamp</type>
          </para>
         </listitem>
        </itemizedlist>
       </para>

       <para>
        Here is an example of a call to this function:
<programlisting><![CDATA[
$char c[] = "abc       ";
$short s = 17;
$int i = -74874;

rsetnull(CCHARTYPE, (char *) c);
rsetnull(CSHORTTYPE, (char *) &s);
rsetnull(CINTTYPE, (char *) &i);
]]>
</programlisting>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>risnull</></term>
      <listitem>
       <para>
        Test if a variable is NULL.
<synopsis>
int risnull(int t, char *ptr);
</synopsis>
        The function receives the type of the variable to test (<literal>t</>)
        as well a pointer to this variable (<literal>ptr</>). Note that the
        latter needs to be casted to a char*. See the function <xref
        linkend="rsetnull"> for a list of possible variable types.
       </para>
       <para>
        Here is an example of how to use this function:
<programlisting><![CDATA[
$char c[] = "abc       ";
$short s = 17;
$int i = -74874;

risnull(CCHARTYPE, (char *) c);
risnull(CSHORTTYPE, (char *) &s);
risnull(CINTTYPE, (char *) &i);
]]>
</programlisting>
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </sect2>

  <sect2>
   <title>Additional constants</title>
   <para>
    Note that all constants here describe errors and all of them are defined
    to represent negative values. In the descriptions of the different
    constants you can also find the value that the constants represent in the
    current implementation. However you should not rely on this number. You can
    however rely on the fact all of them are defined to represent negative
    values.
    <variablelist>
     <varlistentry>
      <term><literal>ECPG_INFORMIX_NUM_OVERFLOW</></term>
      <listitem>
       <para>
        Functions return this value if an overflow occurred in a
        calculation. Internally it is defined to -1200 (the <productname>Informix</productname>
        definition).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ECPG_INFORMIX_NUM_UNDERFLOW</></term>
      <listitem>
       <para>
        Functions return this value if an underflow occurred in a calculation.
        Internally it is defined to -1201 (the <productname>Informix</productname> definition).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ECPG_INFORMIX_DIVIDE_ZERO</></term>
      <listitem>
       <para>
        Functions return this value if an attempt to divide by zero is
        observed. Internally it is defined to -1202 (the <productname>Informix</productname> definition).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ECPG_INFORMIX_BAD_YEAR</></term>
      <listitem>
       <para>
        Functions return this value if a bad value for a year was found while
        parsing a date. Internally it is defined to -1204 (the <productname>Informix</productname>
        definition).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ECPG_INFORMIX_BAD_MONTH</></term>
      <listitem>
       <para>
        Functions return this value if a bad value for a month was found while
        parsing a date. Internally it is defined to -1205 (the <productname>Informix</productname>
        definition).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ECPG_INFORMIX_BAD_DAY</></term>
      <listitem>
       <para>
        Functions return this value if a bad value for a day was found while
        parsing a date. Internally it is defined to -1206 (the <productname>Informix</productname>
        definition).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ECPG_INFORMIX_ENOSHORTDATE</></term>
      <listitem>
       <para>
        Functions return this value if a parsing routine needs a short date
        representation but did not get the date string in the right length.
        Internally it is defined to -1209 (the <productname>Informix</productname> definition).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ECPG_INFORMIX_DATE_CONVERT</></term>
      <listitem>
       <para>
        Functions return this value if Internally it is defined to -1210 (the
        <productname>Informix</productname> definition).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ECPG_INFORMIX_OUT_OF_MEMORY</></term>
      <listitem>
       <para>
        Functions return this value if Internally it is defined to -1211 (the
        <productname>Informix</productname> definition).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ECPG_INFORMIX_ENOTDMY</></term>
      <listitem>
       <para>
        Functions return this value if a parsing routine was supposed to get a
        format mask (like <literal>mmddyy</>) but not all fields were listed
        correctly. Internally it is defined to -1212 (the <productname>Informix</productname> definition).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ECPG_INFORMIX_BAD_NUMERIC</></term>
      <listitem>
       <para>
        Functions return this value either if a parsing routine cannot parse
        the textual representation for a numeric value because it contains
        errors or if a routine cannot complete a calculation involving numeric
        variables because at least one of the numeric variables is invalid.
        Internally it is defined to -1213 (the <productname>Informix</productname> definition).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ECPG_INFORMIX_BAD_EXPONENT</></term>
      <listitem>
       <para>
        Functions return this value if Internally it is defined to -1216 (the
        <productname>Informix</productname> definition).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ECPG_INFORMIX_BAD_DATE</></term>
      <listitem>
       <para>
        Functions return this value if Internally it is defined to -1218 (the
        <productname>Informix</productname> definition).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ECPG_INFORMIX_EXTRA_CHARS</></term>
      <listitem>
       <para>
        Functions return this value if Internally it is defined to -1264 (the
        <productname>Informix</productname> definition).
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </sect2>
 </sect1>

 <sect1 id="ecpg-errors">
  <title>Error Handling</title>

  <para>
   This section describes how you can handle exceptional conditions
   and warnings in an embedded SQL program.  There are several
   nonexclusive facilities for this.
  </para>

  <sect2>
   <title>Setting Callbacks</title>

   <para>
    One simple method to catch errors and warnings is to set a
    specific action to be executed whenever a particular condition
    occurs.  In general:
<programlisting>
EXEC SQL WHENEVER <replaceable>condition</replaceable> <replaceable>action</replaceable>;
</programlisting>
   </para>

   <para>
    <replaceable>condition</replaceable> can be one of the following:

    <variablelist>
     <varlistentry>
      <term><literal>SQLERROR</literal></term>
      <listitem>
       <para>
        The specified action is called whenever an error occurs during
        the execution of an SQL statement.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>SQLWARNING</literal></term>
      <listitem>
       <para>
        The specified action is called whenever a warning occurs
        during the execution of an SQL statement.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>NOT FOUND</literal></term>
      <listitem>
       <para>
        The specified action is called whenever an SQL statement
        retrieves or affects zero rows.  (This condition is not an
        error, but you might be interested in handling it specially.)
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>

   <para>
    <replaceable>action</replaceable> can be one of the following:

    <variablelist>
     <varlistentry>
      <term><literal>CONTINUE</literal></term>
      <listitem>
       <para>
        This effectively means that the condition is ignored.  This is
        the default.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>GOTO <replaceable>label</replaceable></literal></term>
      <term><literal>GO TO <replaceable>label</replaceable></literal></term>
      <listitem>
       <para>
        Jump to the specified label (using a C <literal>goto</literal>
        statement).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>SQLPRINT</literal></term>
      <listitem>
       <para>
        Print a message to standard error.  This is useful for simple
        programs or during prototyping.  The details of the message
        cannot be configured.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>STOP</literal></term>
      <listitem>
       <para>
        Call <literal>exit(1)</literal>, which will terminate the
        program.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>DO BREAK</literal></term>
      <listitem>
       <para>
        Execute the C statement <literal>break</literal>.  This should
        only be used in loops or <literal>switch</literal> statements.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>CALL <replaceable>name</replaceable> (<replaceable>args</replaceable>)</literal></term>
      <term><literal>DO <replaceable>name</replaceable> (<replaceable>args</replaceable>)</literal></term>
      <listitem>
       <para>
        Call the specified C functions with the specified arguments.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>

    The SQL standard only provides for the actions
    <literal>CONTINUE</literal> and <literal>GOTO</literal> (and
    <literal>GO TO</literal>).
   </para>

   <para>
    Here is an example that you might want to use in a simple program.
    It prints a simple message when a warning occurs and aborts the
    program when an error happens:
<programlisting>
EXEC SQL WHENEVER SQLWARNING SQLPRINT;
EXEC SQL WHENEVER SQLERROR STOP;
</programlisting>
   </para>

   <para>
    The statement <literal>EXEC SQL WHENEVER</literal> is a directive
    of the SQL preprocessor, not a C statement.  The error or warning
    actions that it sets apply to all embedded SQL statements that
    appear below the point where the handler is set, unless a
    different action was set for the same condition between the first
    <literal>EXEC SQL WHENEVER</literal> and the SQL statement causing
    the condition, regardless of the flow of control in the C program.
    So neither of the two following C program excerpts will have the
    desired effect:
<programlisting>
/*
 * WRONG
 */
int main(int argc, char *argv[])
{
    ...
    if (verbose) {
        EXEC SQL WHENEVER SQLWARNING SQLPRINT;
    }
    ...
    EXEC SQL SELECT ...;
    ...
}
</programlisting>

<programlisting>
/*
 * WRONG
 */
int main(int argc, char *argv[])
{
    ...
    set_error_handler();
    ...
    EXEC SQL SELECT ...;
    ...
}

static void set_error_handler(void)
{
    EXEC SQL WHENEVER SQLERROR STOP;
}
</programlisting>
   </para>
  </sect2>

  <sect2>
   <title>sqlca</title>

   <para>
    For more powerful error handling, the embedded SQL interface
    provides a global variable with the name <varname>sqlca</varname>
    that has the following structure:
<programlisting>
struct
{
    char sqlcaid[8];
    long sqlabc;
    long sqlcode;
    struct
    {
        int sqlerrml;
        char sqlerrmc[SQLERRMC_LEN];
    } sqlerrm;
    char sqlerrp[8];
    long sqlerrd[6];
    char sqlwarn[8];
    char sqlstate[5];
} sqlca;
</programlisting>
    (In a multithreaded program, every thread automatically gets its
    own copy of <varname>sqlca</varname>.  This works similarly to the
    handling of the standard C global variable
    <varname>errno</varname>.)
   </para>

   <para>
    <varname>sqlca</varname> covers both warnings and errors.  If
    multiple warnings or errors occur during the execution of a
    statement, then <varname>sqlca</varname> will only contain
    information about the last one.
   </para>

   <para>
    If no error occurred in the last <acronym>SQL</acronym> statement,
    <literal>sqlca.sqlcode</literal> will be 0 and
    <literal>sqlca.sqlstate</literal> will be
    <literal>"00000"</literal>.  If a warning or error occurred, then
    <literal>sqlca.sqlcode</literal> will be negative and
    <literal>sqlca.sqlstate</literal> will be different from
    <literal>"00000"</literal>.  A positive
    <literal>sqlca.sqlcode</literal> indicates a harmless condition,
    such as that the last query returned zero rows.
    <literal>sqlcode</literal> and <literal>sqlstate</literal> are two
    different error code schemes; details appear below.
   </para>

   <para>
    If the last SQL statement was successful, then
    <literal>sqlca.sqlerrd[1]</literal> contains the OID of the
    processed row, if applicable, and
    <literal>sqlca.sqlerrd[2]</literal> contains the number of
    processed or returned rows, if applicable to the command.
   </para>

   <para>
    In case of an error or warning,
    <literal>sqlca.sqlerrm.sqlerrmc</literal> will contain a string
    that describes the error.  The field
    <literal>sqlca.sqlerrm.sqlerrml</literal> contains the length of
    the error message that is stored in
    <literal>sqlca.sqlerrm.sqlerrmc</literal> (the result of
    <function>strlen()</function>, not really interesting for a C
    programmer).  Note that some messages are too long to fit in the
    fixed-size <literal>sqlerrmc</literal> array; they will be truncated.
   </para>

   <para>
    In case of a warning, <literal>sqlca.sqlwarn[2]</literal> is set
    to <literal>W</literal>.  (In all other cases, it is set to
    something different from <literal>W</literal>.)  If
    <literal>sqlca.sqlwarn[1]</literal> is set to
    <literal>W</literal>, then a value was truncated when it was
    stored in a host variable.  <literal>sqlca.sqlwarn[0]</literal> is
    set to <literal>W</literal> if any of the other elements are set
    to indicate a warning.
   </para>

   <para>
    The fields <structfield>sqlcaid</structfield>,
    <structfield>sqlcabc</structfield>,
    <structfield>sqlerrp</structfield>, and the remaining elements of
    <structfield>sqlerrd</structfield> and
    <structfield>sqlwarn</structfield> currently contain no useful
    information.
   </para>

   <para>
    The structure <varname>sqlca</varname> is not defined in the SQL
    standard, but is implemented in several other SQL database
    systems.  The definitions are similar at the core, but if you want
    to write portable applications, then you should investigate the
    different implementations carefully.
   </para>
  </sect2>

  <sect2>
   <title><literal>SQLSTATE</literal> vs <literal>SQLCODE</literal></title>

   <para>
    The fields <literal>sqlca.sqlstate</literal> and
    <literal>sqlca.sqlcode</literal> are two different schemes that
    provide error codes.  Both are derived from the SQL standard, but
    <literal>SQLCODE</literal> has been marked deprecated in the SQL-92
    edition of the standard and has been dropped in later editions.
    Therefore, new applications are strongly encouraged to use
    <literal>SQLSTATE</literal>.
   </para>

   <para>
    <literal>SQLSTATE</literal> is a five-character array.  The five
    characters contain digits or upper-case letters that represent
    codes of various error and warning conditions.
    <literal>SQLSTATE</literal> has a hierarchical scheme: the first
    two characters indicate the general class of the condition, the
    last three characters indicate a subclass of the general
    condition.  A successful state is indicated by the code
    <literal>00000</literal>.  The <literal>SQLSTATE</literal> codes are for
    the most part defined in the SQL standard.  The
    <productname>PostgreSQL</productname> server natively supports
    <literal>SQLSTATE</literal> error codes; therefore a high degree
    of consistency can be achieved by using this error code scheme
    throughout all applications.  For further information see
    <xref linkend="errcodes-appendix">.
   </para>

   <para>
    <literal>SQLCODE</literal>, the deprecated error code scheme, is a
    simple integer.  A value of 0 indicates success, a positive value
    indicates success with additional information, a negative value
    indicates an error.  The SQL standard only defines the positive
    value +100, which indicates that the last command returned or
    affected zero rows, and no specific negative values.  Therefore,
    this scheme can only achieve poor portability and does not have a
    hierarchical code assignment.  Historically, the embedded SQL
    processor for <productname>PostgreSQL</productname> has assigned
    some specific <literal>SQLCODE</literal> values for its use, which
    are listed below with their numeric value and their symbolic name.
    Remember that these are not portable to other SQL implementations.
    To simplify the porting of applications to the
    <literal>SQLSTATE</literal> scheme, the corresponding
    <literal>SQLSTATE</literal> is also listed.  There is, however, no
    one-to-one or one-to-many mapping between the two schemes (indeed
    it is many-to-many), so you should consult the global
    <literal>SQLSTATE</literal> listing in <xref linkend="errcodes-appendix">
    in each case.
   </para>

   <para>
    These are the assigned <literal>SQLCODE</literal> values:

    <variablelist>
     <varlistentry>
      <term>-12 (<symbol>ECPG_OUT_OF_MEMORY</symbol>)</term>
      <listitem>
       <para>
        Indicates that your virtual memory is exhausted. (SQLSTATE
        YE001)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-200 (<symbol>ECPG_UNSUPPORTED</symbol>)</term>
     <listitem>
      <para>
       Indicates the preprocessor has generated something that the
       library does not know about.  Perhaps you are running
       incompatible versions of the preprocessor and the
       library. (SQLSTATE YE002)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-201 (<symbol>ECPG_TOO_MANY_ARGUMENTS</symbol>)</term>
     <listitem>
      <para>
       This means that the command specified more host variables than
       the command expected.  (SQLSTATE 07001 or 07002)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-202 (<symbol>ECPG_TOO_FEW_ARGUMENTS</symbol>)</term>
     <listitem>
      <para>
       This means that the command specified fewer host variables than
       the command expected.  (SQLSTATE 07001 or 07002)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-203 (<symbol>ECPG_TOO_MANY_MATCHES</symbol>)</term>
     <listitem>
      <para>
       This means a query has returned multiple rows but the statement
       was only prepared to store one result row (for example, because
       the specified variables are not arrays).  (SQLSTATE 21000)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-204 (<symbol>ECPG_INT_FORMAT</symbol>)</term>
     <listitem>
      <para>
       The host variable is of type <type>int</type> and the datum in
       the database is of a different type and contains a value that
       cannot be interpreted as an <type>int</type>.  The library uses
       <function>strtol()</function> for this conversion.  (SQLSTATE
       42804)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-205 (<symbol>ECPG_UINT_FORMAT</symbol>)</term>
     <listitem>
      <para>
       The host variable is of type <type>unsigned int</type> and the
       datum in the database is of a different type and contains a
       value that cannot be interpreted as an <type>unsigned
       int</type>.  The library uses <function>strtoul()</function>
       for this conversion.  (SQLSTATE 42804)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-206 (<symbol>ECPG_FLOAT_FORMAT</symbol>)</term>
     <listitem>
      <para>
       The host variable is of type <type>float</type> and the datum
       in the database is of another type and contains a value that
       cannot be interpreted as a <type>float</type>.  The library
       uses <function>strtod()</function> for this conversion.
       (SQLSTATE 42804)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-211 (<symbol>ECPG_CONVERT_BOOL</symbol>)</term>
     <listitem>
      <para>
       This means the host variable is of type <type>bool</type> and
       the datum in the database is neither <literal>'t'</> nor
       <literal>'f'</>.  (SQLSTATE 42804)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-212 (<symbol>ECPG_EMPTY</symbol>)</term>
     <listitem>
      <para>
       The statement sent to the <productname>PostgreSQL</productname>
       server was empty.  (This cannot normally happen in an embedded
       SQL program, so it might point to an internal error.)  (SQLSTATE
       YE002)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-213 (<symbol>ECPG_MISSING_INDICATOR</symbol>)</term>
     <listitem>
      <para>
       A null value was returned and no null indicator variable was
       supplied.  (SQLSTATE 22002)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-214 (<symbol>ECPG_NO_ARRAY</symbol>)</term>
     <listitem>
      <para>
       An ordinary variable was used in a place that requires an
       array.  (SQLSTATE 42804)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-215 (<symbol>ECPG_DATA_NOT_ARRAY</symbol>)</term>
     <listitem>
      <para>
       The database returned an ordinary variable in a place that
       requires array value.  (SQLSTATE 42804)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-220 (<symbol>ECPG_NO_CONN</symbol>)</term>
     <listitem>
      <para>
       The program tried to access a connection that does not exist.
       (SQLSTATE 08003)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-221 (<symbol>ECPG_NOT_CONN</symbol>)</term>
     <listitem>
      <para>
       The program tried to access a connection that does exist but is
       not open.  (This is an internal error.)  (SQLSTATE YE002)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-230 (<symbol>ECPG_INVALID_STMT</symbol>)</term>
     <listitem>
      <para>
       The statement you are trying to use has not been prepared.
       (SQLSTATE 26000)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-240 (<symbol>ECPG_UNKNOWN_DESCRIPTOR</symbol>)</term>
     <listitem>
      <para>
       The descriptor specified was not found.  The statement you are
       trying to use has not been prepared.  (SQLSTATE 33000)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-241 (<symbol>ECPG_INVALID_DESCRIPTOR_INDEX</symbol>)</term>
     <listitem>
      <para>
       The descriptor index specified was out of range.  (SQLSTATE
       07009)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-242 (<symbol>ECPG_UNKNOWN_DESCRIPTOR_ITEM</symbol>)</term>
     <listitem>
      <para>
       An invalid descriptor item was requested.  (This is an internal
       error.)  (SQLSTATE YE002)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-243 (<symbol>ECPG_VAR_NOT_NUMERIC</symbol>)</term>
     <listitem>
      <para>
       During the execution of a dynamic statement, the database
       returned a numeric value and the host variable was not numeric.
       (SQLSTATE 07006)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-244 (<symbol>ECPG_VAR_NOT_CHAR</symbol>)</term>
     <listitem>
      <para>
       During the execution of a dynamic statement, the database
       returned a non-numeric value and the host variable was numeric.
       (SQLSTATE 07006)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-400 (<symbol>ECPG_PGSQL</symbol>)</term>
     <listitem>
      <para>
       Some error caused by the <productname>PostgreSQL</productname>
       server.  The message contains the error message from the
       <productname>PostgreSQL</productname> server.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-401 (<symbol>ECPG_TRANS</symbol>)</term>
     <listitem>
      <para>
       The <productname>PostgreSQL</productname> server signaled that
       we cannot start, commit, or rollback the transaction.
       (SQLSTATE 08007)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-402 (<symbol>ECPG_CONNECT</symbol>)</term>
     <listitem>
      <para>
       The connection attempt to the database did not succeed.
       (SQLSTATE 08001)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>100 (<symbol>ECPG_NOT_FOUND</symbol>)</term>
     <listitem>
      <para>
       This is a harmless condition indicating that the last command
       retrieved or processed zero rows, or that you are at the end of
       the cursor.  (SQLSTATE 02000)
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
  </sect2>
 </sect1>

 <sect1 id="ecpg-preproc">
  <title>Preprocessor directives</title>

  <sect2>
   <title>Including files</title>

   <para>
    To include an external file into your embedded SQL program, use:
<programlisting>
EXEC SQL INCLUDE <replaceable>filename</replaceable>;
</programlisting>
    The embedded SQL preprocessor will look for a file named
    <literal><replaceable>filename</replaceable>.h</literal>,
    preprocess it, and include it in the resulting C output.  Thus,
    embedded SQL statements in the included file are handled correctly.
   </para>

   <para>
    Note that this is <emphasis>not</emphasis> the same as:
<programlisting>
#include &lt;<replaceable>filename</replaceable>.h&gt;
</programlisting>
    because this file would not be subject to SQL command preprocessing.
    Naturally, you can continue to use the C
    <literal>#include</literal> directive to include other header
    files.
   </para>

   <note>
    <para>
     The include file name is case-sensitive, even though the rest of
     the <literal>EXEC SQL INCLUDE</literal> command follows the normal
     SQL case-sensitivity rules.
    </para>
   </note>
  </sect2>

  <sect2>
   <title>The #define and #undef directives</title>
   <para>
    Similar to the directive <literal>#define</literal> that is known from C,
    embedded SQL has a similar concept:
<programlisting>
EXEC SQL DEFINE <replaceable>name</>;
EXEC SQL DEFINE <replaceable>name</> <replaceable>value</>;
</programlisting>
    So you can define a name:
<programlisting>
EXEC SQL DEFINE HAVE_FEATURE;
</programlisting>
    And you can also define constants:
<programlisting>
EXEC SQL DEFINE MYNUMBER 12;
EXEC SQL DEFINE MYSTRING 'abc';
</programlisting>
    Use <literal>undef</> to remove a previous definition:
<programlisting>
EXEC SQL UNDEF MYNUMBER;
</programlisting>
   </para>

   <para>
    Of course you can continue to use the C versions <literal>#define</literal>
    and <literal>#undef</literal> in your embedded SQL program. The difference
    is where your defined values get evaluated. If you use <literal>EXEC SQL
    DEFINE</> then the <command>ecpg</> preprocessor evaluates the defines and substitutes
    the values. For example if you write:
<programlisting>
EXEC SQL DEFINE MYNUMBER 12;
...
EXEC SQL UPDATE Tbl SET col = MYNUMBER;
</programlisting>
    then <command>ecpg</> will already do the substitution and your C compiler will never
    see any name or identifier <literal>MYNUMBER</>. Note that you cannot use
    <literal>#define</literal> for a constant that you are going to use in an
    embedded SQL query because in this case the embedded SQL precompiler is not
    able to see this declaration.
   </para>
  </sect2>

  <sect2>
   <title>ifdef, ifndef, else, elif, and endif directives</title>
   <para>
   You can use the following directives to compile code sections conditionally:

   <variablelist>
    <varlistentry>
     <term><literal>EXEC SQL ifdef <replaceable>name</>;</literal></term>
     <listitem>
     <para>
      Checks a <replaceable>name</> and processes subsequent lines if
      <replaceable>name</> has been created with <literal>EXEC SQL define
      <replaceable>name</></literal>.
     </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>EXEC SQL ifndef <replaceable>name</>;</literal></term>
     <listitem>
     <para>
      Checks a <replaceable>name</> and processes subsequent lines if
      <replaceable>name</> has <emphasis>not</emphasis> been created with
      <literal>EXEC SQL define <replaceable>name</></literal>.
     </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>EXEC SQL else;</literal></term>
     <listitem>
     <para>
      Starts processing an alternative section to a section introduced by
      either <literal>EXEC SQL ifdef <replaceable>name</></literal> or
      <literal>EXEC SQL ifndef <replaceable>name</></literal>.
     </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>EXEC SQL elif <replaceable>name</>;</literal></term>
     <listitem>
     <para>
      Checks <replaceable>name</> and starts an alternative section if
      <replaceable>name</> has been created with <literal>EXEC SQL define
      <replaceable>name</></literal>.
     </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>EXEC SQL endif;</literal></term>
     <listitem>
     <para>
      Ends an alternative section.
     </para>
     </listitem>
    </varlistentry>
   </variablelist>
   </para>

   <para>
    Example:
<programlisting>
EXEC SQL ifndef TZVAR;
EXEC SQL SET TIMEZONE TO 'GMT';
EXEC SQL elif TZNAME;
EXEC SQL SET TIMEZONE TO TZNAME;
EXEC SQL else;
EXEC SQL SET TIMEZONE TO TZVAR;
EXEC SQL endif;
</programlisting>
   </para>

  </sect2>
 </sect1>
 
  <sect1 id="ecpg-process">
  <title>Processing Embedded SQL Programs</title>

  <para>
   Now that you have an idea how to form embedded SQL C programs, you
   probably want to know how to compile them.  Before compiling you
   run the file through the embedded <acronym>SQL</acronym>
   <acronym>C</acronym> preprocessor, which converts the
   <acronym>SQL</acronym> statements you used to special function
   calls.  After compiling, you must link with a special library that
   contains the needed functions. These functions fetch information
   from the arguments, perform the <acronym>SQL</acronym> command using
   the <application>libpq</application> interface, and put the result
   in the arguments specified for output.
  </para>

  <para>
   The preprocessor program is called <filename>ecpg</filename> and is
   included in a normal <productname>PostgreSQL</> installation.
   Embedded SQL programs are typically named with an extension
   <filename>.pgc</filename>.  If you have a program file called
   <filename>prog1.pgc</filename>, you can preprocess it by simply
   calling:
<programlisting>
ecpg prog1.pgc
</programlisting>
   This will create a file called <filename>prog1.c</filename>.  If
   your input files do not follow the suggested naming pattern, you
   can specify the output file explicitly using the
   <option>-o</option> option.
  </para>

  <para>
   The preprocessed file can be compiled normally, for example:
<programlisting>
cc -c prog1.c
</programlisting>
   The generated C source files include header files from the
   <productname>PostgreSQL</> installation, so if you installed
   <productname>PostgreSQL</> in a location that is not searched by
   default, you have to add an option such as
   <literal>-I/usr/local/pgsql/include</literal> to the compilation
   command line.
  </para>

  <para>
   To link an embedded SQL program, you need to include the
   <filename>libecpg</filename> library, like so:
<programlisting>
cc -o myprog prog1.o prog2.o ... -lecpg
</programlisting>
   Again, you might have to add an option like
   <literal>-L/usr/local/pgsql/lib</literal> to that command line.
  </para>

  <para>
   If you manage the build process of a larger project using
   <application>make</application>, it might be convenient to include
   the following implicit rule to your makefiles:
<programlisting>
ECPG = ecpg

%.c: %.pgc
        $(ECPG) $&lt;
</programlisting>
  </para>

  <para>
   The complete syntax of the <command>ecpg</command> command is
   detailed in <xref linkend="app-ecpg">.
  </para>

  <para>
   The <application>ecpg</application> library is thread-safe by
   default.  However, you might need to use some threading
   command-line options to compile your client code.
  </para>
 </sect1>

 <sect1 id="ecpg-library">
  <title>Library Functions</title>

  <para>
   The <filename>libecpg</filename> library primarily contains
   <quote>hidden</quote> functions that are used to implement the
   functionality expressed by the embedded SQL commands.  But there
   are some functions that can usefully be called directly.  Note that
   this makes your code unportable.
  </para>

  <itemizedlist>
   <listitem>
    <para>
     <function>ECPGdebug(int <replaceable>on</replaceable>, FILE
     *<replaceable>stream</replaceable>)</function> turns on debug
     logging if called with the first argument non-zero. Debug logging
     is done on <replaceable>stream</replaceable>.  The log contains
     all <acronym>SQL</acronym> statements with all the input
     variables inserted, and the results from the
     <productname>PostgreSQL</productname> server. This can be very
     useful when searching for errors in your <acronym>SQL</acronym>
     statements.
    </para>
    <note>
    <para>
    On Windows, if the <application>ecpg</> libraries and an application are
    compiled with different flags, this function call will crash the 
    application because the internal representation of the 
    <literal>FILE</> pointers differ.  Specifically,
    multithreaded/single-threaded, release/debug, and static/dynamic 
    flags should be the same for the library and all applications using
    that library.
    </para>
    </note>
   </listitem>

   <listitem>
     <para>
       <function>ECPGget_PGconn(const char *<replaceable>connection_name</replaceable>)
       </function> returns the library database connection handle identified by the given name.
       If <replaceable>connection_name</replaceable> is set to <literal>NULL</literal>, the current
       connection handle is returned. If no connection handle can be identified, the function returns 
       <literal>NULL</literal>. The returned connection handle can be used to call any other functions
       from <application>libpq</application>, if necessary.
     </para>
     <note>
     <para>
       It is a bad idea to manipulate database connection handles made from <application>ecpg</application> directly
       with <application>libpq</application> routines.
     </para>
     </note>
   </listitem>

   <listitem>
     <para>
       <function>ECPGtransactionStatus(const char *<replaceable>connection_name</replaceable>)</function>
       returns the current transaction status of the given connection identified by <replaceable>connection_name</replaceable>.
       See <xref linkend="libpq-status"> and libpq's <function>PQtransactionStatus()</function> for details about the returned status codes.
     </para>
   </listitem>

   <listitem>
    <para>
     <function>ECPGstatus(int <replaceable>lineno</replaceable>,
     const char* <replaceable>connection_name</replaceable>)</function>
     returns true if you are connected to a database and false if not.
     <replaceable>connection_name</replaceable> can be <literal>NULL</> 
     if a single connection is being used.
    </para>
   </listitem>
  </itemizedlist>
 </sect1>

 <sect1 id="ecpg-develop">
  <title>Internals</title>

  <para>
   This section explains how <application>ECPG</application> works
   internally. This information can occasionally be useful to help
   users understand how to use <application>ECPG</application>.
  </para>

   <para>
    The first four lines written by <command>ecpg</command> to the
    output are fixed lines.  Two are comments and two are include
    lines necessary to interface to the library.  Then the
    preprocessor reads through the file and writes output.  Normally
    it just echoes everything to the output.
   </para>

   <para>
    When it sees an <command>EXEC SQL</command> statement, it
    intervenes and changes it. The command starts with <command>EXEC
    SQL</command> and ends with <command>;</command>. Everything in
    between is treated as an <acronym>SQL</acronym> statement and
    parsed for variable substitution.
   </para>

   <para>
    Variable substitution occurs when a symbol starts with a colon
    (<literal>:</literal>). The variable with that name is looked up
    among the variables that were previously declared within a
    <literal>EXEC SQL DECLARE</> section.
   </para>

   <para>
    The most important function in the library is
    <function>ECPGdo</function>, which takes care of executing most
    commands. It takes a variable number of arguments. This can easily
    add up to 50 or so arguments, and we hope this will not be a
    problem on any platform.
   </para>

   <para>
    The arguments are:

    <variablelist>
     <varlistentry>
      <term>A line number</term>
      <listitem>
       <para>
        This is the line number of the original line; used in error
        messages only.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>A string</term>
      <listitem>
       <para>
        This is the <acronym>SQL</acronym> command that is to be issued.
        It is modified by the input variables, i.e., the variables that
        where not known at compile time but are to be entered in the
        command. Where the variables should go the string contains
        <literal>?</literal>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Input variables</term>
      <listitem>
       <para>
        Every input variable causes ten arguments to be created.  (See below.)
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><parameter>ECPGt_EOIT</></term>
      <listitem>
       <para>
        An <type>enum</> telling that there are no more input
        variables.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Output variables</term>
      <listitem>
       <para>
        Every output variable causes ten arguments to be created.
        (See below.)  These variables are filled by the function.
       </para>
      </listitem>
     </varlistentry>

      <varlistentry>
       <term><parameter>ECPGt_EORT</></term>
       <listitem>
       <para>
        An <type>enum</> telling that there are no more variables.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>

   <para>
    For every variable that is part of the <acronym>SQL</acronym>
    command, the function gets ten arguments:

    <orderedlist>
     <listitem>
      <para>
       The type as a special symbol.
      </para>
     </listitem>

     <listitem>
      <para> 
       A pointer to the value or a pointer to the pointer.
      </para>
     </listitem>

     <listitem>
      <para>
       The size of the variable if it is a <type>char</type> or <type>varchar</type>.
      </para>
     </listitem>

     <listitem>
      <para>
       The number of elements in the array (for array fetches).
      </para>
     </listitem>

     <listitem>
      <para>
       The offset to the next element in the array (for array fetches).
      </para>
     </listitem>

     <listitem>
      <para>
       The type of the indicator variable as a special symbol.
      </para>
     </listitem>

     <listitem>
      <para>
       A pointer to the indicator variable.
      </para>
     </listitem>

     <listitem>
      <para>
       0
      </para>
     </listitem>

     <listitem>
      <para>
       The number of elements in the indicator array (for array fetches).
      </para>
     </listitem>

     <listitem>
      <para>
       The offset to the next element in the indicator array (for
       array fetches).
      </para>
     </listitem>
    </orderedlist>
   </para>

   <para>
    Note that not all SQL commands are treated in this way.  For
    instance, an open cursor statement like:
<programlisting>
EXEC SQL OPEN <replaceable>cursor</replaceable>;
</programlisting>
    is not copied to the output. Instead, the cursor's
    <command>DECLARE</> command is used at the position of the <command>OPEN</> command
    because it indeed opens the cursor.
   </para>

   <para>
    Here is a complete example describing the output of the
    preprocessor of a file <filename>foo.pgc</filename> (details might
    change with each particular version of the preprocessor):
<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
int index;
int result;
EXEC SQL END DECLARE SECTION;
...
EXEC SQL SELECT res INTO :result FROM mytable WHERE index = :index;
</programlisting>
    is translated into:
<programlisting><![CDATA[
/* Processed by ecpg (2.6.0) */
/* These two include files are added by the preprocessor */
#include <ecpgtype.h>;
#include <ecpglib.h>;

/* exec sql begin declare section */

#line 1 "foo.pgc"

 int index;
 int result;
/* exec sql end declare section */
...
ECPGdo(__LINE__, NULL, "SELECT res FROM mytable WHERE index = ?     ",
        ECPGt_int,&(index),1L,1L,sizeof(int),
        ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EOIT,
        ECPGt_int,&(result),1L,1L,sizeof(int),
        ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EORT);
#line 147 "foo.pgc"
]]>
</programlisting>
    (The indentation here is added for readability and not
    something the preprocessor does.)
   </para>
 </sect1>
</chapter>
@


1.105
log
@Clean up some bad grammar and punctuation in description of ecpg's decimal
type.  Per KOIZUMI Satoru.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.104 2010/08/17 04:37:20 petere Exp $ -->
d3886 2
a3887 1
        variable that should hold the result of the operation (<literal>ts</>).
d3890 2
a3891 2
        This functions is implemented by means of the <xref
        linkend="PGTYPEStimestampdefmtasc">. See the documentation
@


1.104
log
@Spell and markup checking
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.103 2010/08/11 19:03:16 rhaas Exp $ -->
d781 1
a781 1
    can only create variables on the heap by means of the
d783 1
a783 1
    functions. The decimal type, which is similar but limited in the precision,
d2195 1
a2195 1
     a maximal precision of 30 significant digits. In contrast to the numeric
d2198 5
a2202 3
     <function>PGTYPESdecimal_new()</> and <function>PGTYPESdecimal_free()</>. There are a lot of other
     functions that deal with the decimal type in the <productname>Informix</productname> compatibility
     mode described in <xref linkend="ecpg-informix-compat">.
@


1.103
log
@Fix one more incorrect errno definition in the ECPG manual.

Again, back-patch all the way to 7.4.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.102 2010/08/11 18:52:02 rhaas Exp $ -->
d828 1
a828 1
       else the NULL pointer. At the moment ecpg always parses the complete
d1130 1
a1130 1
        a C char* string <literal>endptr</>. At the moment ecpg always parses
d1137 1
a1137 1
        currently no variable to change that within ecpg.
d1404 2
a1405 2
            <entry>fmt</entry>
            <entry>result</entry>
d1467 1
a1467 1
        Use a format mask to convert a C char* string to a value of type
d1494 3
a1496 3
            <entry>fmt</entry>
            <entry>str</entry>
            <entry>result</entry>
d1595 1
a1595 1
        At the moment ecpg always parses
d1602 1
a1602 1
        <literal>PGTYPESInvalidTimestamp</literal> is returned and errno is
d1609 1
a1609 1
        specification. Note that timezones are not supported by ecpg. It can
d2149 1
a2149 1
        At the moment ecpg always parses
d2198 1
a2198 1
     PGTYPESdecimal_new() and PGTYPESdecimal_free(). There are a lot of other
d2234 1
a2234 1
    <title>errno values of pgtypeslib </title>
d2354 1
a2354 1
    <title>Special constants of pgtypeslib </title>
d2364 1
a2364 1
        Note that due to the internal representation of the timestamp datatype,
d2424 1
a2424 1
    If the resultset is empty, the Descriptor Area will still contain
d2430 1
a2430 1
    statement can be used to get the metadata of the resultset:
d2452 1
a2452 1
    used to similarly: they produce the resultset and the metadata in a
d2651 2
a2652 2
    to get the resultset and the metadata of a query. One structure stores one
    record from the resultset.
d2706 1
a2706 1
    number of fields in a resultset and also depends on the length of the string
d2745 1
a2745 1
        It contains the number of fields in a resultset.
d2762 1
a2762 1
        This is the array of the fields in the resultset. The fields are:
d2780 1
a2780 1
            It contains the binary length of the field. E.g. 4 bytes for ECPGt_int.
d2854 1
a2854 1
   ecpg can be run in a so-called <firstterm>Informix compatibility mode</>. If
d2868 1
a2868 1
   There are two compatibility modes: INFORMIX, INFORMIX_SE
d2872 1
a2872 1
   against <literal>libcompat</> that is shipped with ecpg.
d2877 1
a2877 1
   well as embedded SQL statements known from E/SQL to ecpg.
d2881 1
a2881 1
   of ecpg. pgtypeslib maps SQL data types to data types within the C host
d2891 1
a2891 1
   find support in ecpg for that either.
d2919 1
a2919 1
        synonym for ecpg's <literal>DISCONNECT CURRENT</>.:
d2932 1
a2932 1
        are purely grammar transformations and which steps rely on the underlying runtime library)
d2935 2
a2936 2
        the runtime library that uses to the cursor name. This means that there's no runtime
        bookkeeping of SQL cursors in the ECPG runtime library, only in the PostgreSQL server.
d3023 1
a3023 1
        Unused, filled with zerobytes.
d3041 1
a3041 1
        Pointer to the next SQLDA structure if the resultset contains more than one records.
d3129 1
a3129 1
        Reserved in Informix, value of PQfformat() for the field.
d3158 1
a3158 1
        Extended type of the field, result of PQftype().
d3246 3
a3248 3
        ECPG_INFORMIX_NUM_OVERFLOW is returned in case of overflow and 
        ECPG_INFORMIX_NUM_UNDERFLOW in case of underflow. -1 is returned for
        other failures and errno is set to the respective errno number of the
d3533 1
a3533 1
        Note that the ecpg implementation differs from the <productname>Informix</productname>
d3535 1
a3535 1
        32767, while the limits in the ecpg implementation depend on the
d3559 1
a3559 1
        Note that the ecpg implementation differs from the <productname>Informix</productname>
d3561 1
a3561 1
        -2,147,483,647 to 2,147,483,647, while the limits in the ecpg
d3587 1
a3587 1
        Note that ecpg's implementation differs from the <productname>Informix</productname>
d3589 1
a3589 1
        environment variables. In ecpg however, you cannot change the output
d5132 1
a5132 1
    DEFINE</> then the ecpg preprocessor evaluates the defines and substitutes
d5139 1
a5139 1
    then ecpg will already do the substitution and your C compiler will never
d5148 1
a5148 1
   <title>ifdef, ifndef, else, elif and endif directives</title>
@


1.102
log
@Fix incorrect errno definitions in ECPG manual.

ecpgerrno.h hasn't materially changed since PostgreSQL 7.4, so this has
been wrong for a very long time.  Back-patch all the way.

Satoshi Nagayasu
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.101 2010/07/29 19:34:40 petere Exp $ -->
d4886 1
a4886 1
     <term>-207 (<symbol>ECPG_CONVERT_BOOL</symbol>)</term>
@


1.101
log
@Fix indentation of verbatim block elements

Block elements with verbatim formatting (literallayout, programlisting,
screen, synopsis) should be aligned at column 0 independent of the surrounding
SGML, because whitespace is significant, and indenting them creates erratic
whitespace in the output.  The CSS stylesheets already take care of indenting
the output.

Assorted markup improvements to go along with it.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.100 2010/05/13 14:16:41 mha Exp $ -->
d4897 1
a4897 1
     <term>-208 (<symbol>ECPG_EMPTY</symbol>)</term>
d4909 1
a4909 1
     <term>-209 (<symbol>ECPG_MISSING_INDICATOR</symbol>)</term>
d4919 1
a4919 1
     <term>-210 (<symbol>ECPG_NO_ARRAY</symbol>)</term>
d4929 1
a4929 1
     <term>-211 (<symbol>ECPG_DATA_NOT_ARRAY</symbol>)</term>
@


1.100
log
@Fix some spelling errors.

Thom Brown
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.99 2010/05/09 16:30:31 tgl Exp $ -->
d2860 5
a2864 5
   $int j = 3;
   $CONNECT TO :dbname;
   $CREATE TABLE test(i INT PRIMARY KEY, j INT);
   $INSERT INTO test(i, j) VALUES (7, :j);
   $COMMIT;
d2901 3
a2903 3
    EXEC SQL BEGIN DECLARE SECTION;
    string userid; /* this variable will contain trimmed data */
    EXEC SQL END DECLARE SECTION;
d2905 1
a2905 1
    EXEC SQL FETCH MYCUR INTO :userid;
d2921 2
a2922 2
    $CLOSE DATABASE;                /* close the current connection */
    EXEC SQL CLOSE DATABASE;
d3086 1
a3086 1
    int intval; 
d3088 3
a3090 3
    switch (sqldata->sqlvar[i].sqltype)
    {
      case SQLINTEGER:
d3093 2
a3094 2
      ...
    }
d3109 2
a3110 2
    if (*(int2 *)sqldata->sqlvar[i].sqlind != 0)
      printf("value is NULL\n");
d5211 7
a5217 7
   exec sql ifndef TZVAR;
   exec sql SET TIMEZONE TO 'GMT';
   exec sql elif TZNAME;
   exec sql SET TIMEZONE TO TZNAME;
   exec sql else;
   exec sql SET TIMEZONE TO TZVAR;
   exec sql endif;
@


1.100.2.1
log
@Fix indentation of verbatim block elements

Block elements with verbatim formatting (literallayout, programlisting,
screen, synopsis) should be aligned at column 0 independent of the surrounding
SGML, because whitespace is significant, and indenting them creates erratic
whitespace in the output.  The CSS stylesheets already take care of indenting
the output.

Assorted markup improvements to go along with it.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.100 2010/05/13 14:16:41 mha Exp $ -->
d2860 5
a2864 5
$int j = 3;
$CONNECT TO :dbname;
$CREATE TABLE test(i INT PRIMARY KEY, j INT);
$INSERT INTO test(i, j) VALUES (7, :j);
$COMMIT;
d2901 3
a2903 3
EXEC SQL BEGIN DECLARE SECTION;
string userid; /* this variable will contain trimmed data */
EXEC SQL END DECLARE SECTION;
d2905 1
a2905 1
EXEC SQL FETCH MYCUR INTO :userid;
d2921 2
a2922 2
$CLOSE DATABASE;                /* close the current connection */
EXEC SQL CLOSE DATABASE;
d3086 1
a3086 1
int intval; 
d3088 3
a3090 3
switch (sqldata->sqlvar[i].sqltype)
{
    case SQLINTEGER:
d3093 2
a3094 2
  ...
}
d3109 2
a3110 2
if (*(int2 *)sqldata->sqlvar[i].sqlind != 0)
    printf("value is NULL\n");
d5211 7
a5217 7
EXEC SQL ifndef TZVAR;
EXEC SQL SET TIMEZONE TO 'GMT';
EXEC SQL elif TZNAME;
EXEC SQL SET TIMEZONE TO TZNAME;
EXEC SQL else;
EXEC SQL SET TIMEZONE TO TZVAR;
EXEC SQL endif;
@


1.100.2.2
log
@Fix incorrect errno definitions in ECPG manual.

ecpgerrno.h hasn't materially changed since PostgreSQL 7.4, so this has
been wrong for a very long time.  Back-patch all the way.

Satoshi Nagayasu
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.100.2.1 2010/07/29 19:34:36 petere Exp $ -->
d4897 1
a4897 1
     <term>-212 (<symbol>ECPG_EMPTY</symbol>)</term>
d4909 1
a4909 1
     <term>-213 (<symbol>ECPG_MISSING_INDICATOR</symbol>)</term>
d4919 1
a4919 1
     <term>-214 (<symbol>ECPG_NO_ARRAY</symbol>)</term>
d4929 1
a4929 1
     <term>-215 (<symbol>ECPG_DATA_NOT_ARRAY</symbol>)</term>
@


1.100.2.3
log
@Fix one more incorrect errno definition in the ECPG manual.

Again, back-patch all the way to 7.4.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.100.2.2 2010/08/11 18:52:12 rhaas Exp $ -->
d4886 1
a4886 1
     <term>-211 (<symbol>ECPG_CONVERT_BOOL</symbol>)</term>
@


1.100.2.4
log
@Spell and markup checking
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.100.2.3 2010/08/11 19:03:25 rhaas Exp $ -->
d828 1
a828 1
       else the NULL pointer. At the moment ECPG always parses the complete
d1130 1
a1130 1
        a C char* string <literal>endptr</>. At the moment ECPG always parses
d1137 1
a1137 1
        currently no variable to change that within ECPG.
d1404 2
a1405 2
            <entry>Format</entry>
            <entry>Result</entry>
d1467 1
a1467 1
        Use a format mask to convert a C <type>char*</type> string to a value of type
d1494 3
a1496 3
            <entry>Format</entry>
            <entry>String</entry>
            <entry>Result</entry>
d1595 1
a1595 1
        At the moment ECPG always parses
d1602 1
a1602 1
        <literal>PGTYPESInvalidTimestamp</literal> is returned and <varname>errno</> is
d1609 1
a1609 1
        specification. Note that timezones are not supported by ECPG. It can
d2149 1
a2149 1
        At the moment ECPG always parses
d2198 1
a2198 1
     <function>PGTYPESdecimal_new()</> and <function>PGTYPESdecimal_free()</>. There are a lot of other
d2234 1
a2234 1
    <title>errno values of pgtypeslib</title>
d2354 1
a2354 1
    <title>Special constants of pgtypeslib</title>
d2364 1
a2364 1
        Note that due to the internal representation of the <type>timestamp</type> data type,
d2424 1
a2424 1
    If the result set is empty, the Descriptor Area will still contain
d2430 1
a2430 1
    statement can be used to get the metadata of the result set:
d2452 1
a2452 1
    used to similarly: they produce the result set and the metadata in a
d2651 2
a2652 2
    to get the result set and the metadata of a query. One structure stores one
    record from the result set.
d2706 1
a2706 1
    number of fields in a result set and also depends on the length of the string
d2745 1
a2745 1
        It contains the number of fields in a result set.
d2762 1
a2762 1
        This is the array of the fields in the result set. The fields are:
d2780 1
a2780 1
            It contains the binary length of the field. E.g. 4 bytes for <type>ECPGt_int</type>.
d2854 1
a2854 1
   <command>ecpg</command> can be run in a so-called <firstterm>Informix compatibility mode</>. If
d2868 1
a2868 1
   There are two compatibility modes: <literal>INFORMIX</>, <literal>INFORMIX_SE</>
d2872 1
a2872 1
   against <literal>libcompat</> that is shipped with ECPG.
d2877 1
a2877 1
   well as embedded SQL statements known from E/SQL to ECPG.
d2881 1
a2881 1
   of ECPG. pgtypeslib maps SQL data types to data types within the C host
d2891 1
a2891 1
   find support in ECPG for that either.
d2919 1
a2919 1
        synonym for ECPG's <literal>DISCONNECT CURRENT</>.:
d2932 1
a2932 1
        are purely grammar transformations and which steps rely on the underlying run-time library)
d2935 2
a2936 2
        the run-time library that uses to the cursor name. This means that there's no run-time
        bookkeeping of SQL cursors in the ECPG run-time library, only in the PostgreSQL server.
d3023 1
a3023 1
        Unused, filled with zero-bytes.
d3041 1
a3041 1
        Pointer to the next SQLDA structure if the result set contains more than one records.
d3129 1
a3129 1
        Reserved in Informix, value of <function>PQfformat()</> for the field.
d3158 1
a3158 1
        Extended type of the field, result of <function>PQftype()</>.
d3246 3
a3248 3
        <symbol>ECPG_INFORMIX_NUM_OVERFLOW</> is returned in case of overflow and 
        <symbol>ECPG_INFORMIX_NUM_UNDERFLOW</> in case of underflow. -1 is returned for
        other failures and <varname>errno</> is set to the respective <varname>errno</> number of the
d3533 1
a3533 1
        Note that the ECPG implementation differs from the <productname>Informix</productname>
d3535 1
a3535 1
        32767, while the limits in the ECPG implementation depend on the
d3559 1
a3559 1
        Note that the ECPG implementation differs from the <productname>Informix</productname>
d3561 1
a3561 1
        -2,147,483,647 to 2,147,483,647, while the limits in the ECPG
d3587 1
a3587 1
        Note that ECPG's implementation differs from the <productname>Informix</productname>
d3589 1
a3589 1
        environment variables. In ECPG however, you cannot change the output
d5132 1
a5132 1
    DEFINE</> then the <command>ecpg</> preprocessor evaluates the defines and substitutes
d5139 1
a5139 1
    then <command>ecpg</> will already do the substitution and your C compiler will never
d5148 1
a5148 1
   <title>ifdef, ifndef, else, elif, and endif directives</title>
@


1.100.2.5
log
@Clean up some bad grammar and punctuation in description of ecpg's decimal
type.  Per KOIZUMI Satoru.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.100.2.4 2010/08/17 04:37:16 petere Exp $ -->
d781 1
a781 1
    can only create numeric variables on the heap, by means of the
d783 1
a783 1
    functions. The decimal type, which is similar but limited in precision,
d2195 1
a2195 1
     a maximum precision of 30 significant digits. In contrast to the numeric
d2198 3
a2200 5
     <function>PGTYPESdecimal_new</> and
     <function>PGTYPESdecimal_free</>).
     There are a lot of other functions that deal with the decimal type in the
     <productname>Informix</productname> compatibility mode described in <xref
     linkend="ecpg-informix-compat">.
@


1.100.2.6
log
@Clean up description of ecpg's dtcvfmtasc function.
Per KOIZUMI Satoru.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.100.2.5 2010/09/02 14:46:51 tgl Exp $ -->
d3886 1
a3886 2
        variable that should hold the result of the operation
        (<literal>dtvalue</>).
d3889 2
a3890 2
        This function is implemented by means of the <xref
        linkend="PGTYPEStimestampdefmtasc"> function. See the documentation
@


1.99
log
@Fix typo: PGTYPES_NUM_OVERFLOW should be PGTYPES_NUM_UNDERFLOW.
Noted by KOIZUMI Satoru.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.98 2010/02/27 04:29:44 tgl Exp $ -->
d2868 1
a2868 1
   There are two compatiblity modes: INFORMIX, INFORMIX_SE
@


1.98
log
@Entity-ify a few new uses of literal <, >, and &.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.97 2010/02/19 00:15:25 momjian Exp $ -->
d2259 1
a2259 1
      <term><literal>PGTYPES_NUM_OVERFLOW</literal></term>
@


1.97
log
@Hot Standby documentation updates

Greg Smith
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.96 2010/02/17 04:19:37 tgl Exp $ -->
d3207 3
a3209 3
    printf("# of fields: %d\n", sqlda->sqld);
    for (i = 0; i < sqlda->sqld; i++)
      printf("field %d: \"%s\"\n", sqlda->sqlvar[i]->sqlname);
d3223 1
a3223 1
                  * sqlda and sqlda->sqlvar is in one allocated area */
@


1.96
log
@Stamp HEAD as 9.0devel, and update various places that were referring to 8.5
(hope I got 'em all).  Per discussion, this release will be 9.0 not 8.5.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.95 2010/01/26 14:21:29 momjian Exp $ -->
d2885 1
a2885 1
   behaviour; it allows you to do more or less the same operations and gives
@


1.95
log
@Remove tabs in SGML.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.94 2010/01/26 09:10:11 meskes Exp $ -->
d2442 1
a2442 1
    Before PostgreSQL 8.5, the <literal>SQL</literal> keyword was optional,
@


1.94
log
@Finally applied patch by Boszormenyi Zoltan <zb@@cybertec.at> to add the new features his patches added to the docs.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.93 2009/12/02 14:07:25 momjian Exp $ -->
d2655 1
a2655 1
sqlda_t	*mysqlda;
d2936 1
a2936 1
	bookkeeping of SQL cursors in the ECPG runtime library, only in the PostgreSQL server.
@


1.93
log
@thread-safety

Apply full patch to enable thread-safety by default, e.g. doc changes.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.92 2009/11/30 14:47:37 momjian Exp $ -->
d2379 472
d2858 227
a3084 1
   embedded SQL commands.:
d3086 9
a3094 5
   $int j = 3;
   $CONNECT TO :dbname;
   $CREATE TABLE test(i INT PRIMARY KEY, j INT);
   $INSERT INTO test(i, j) VALUES (7, :j);
   $COMMIT;
d3096 3
a3098 27
  </para>
  <para>
   There are two compatiblity modes: INFORMIX, INFORMIX_SE
  </para>
  <para>
   When linking programs that use this compatibility mode, remember to link
   against <literal>libcompat</> that is shipped with ecpg.
  </para>
  <para>
   Besides the previously explained syntactic sugar, the <productname>Informix</productname> compatibility
   mode ports some functions for input, output and transformation of data as
   well as embedded SQL statements known from E/SQL to ecpg.
  </para>
  <para>
   <productname>Informix</productname> compatibility mode is closely connected to the pgtypeslib library
   of ecpg. pgtypeslib maps SQL data types to data types within the C host
   program and most of the additional functions of the <productname>Informix</productname> compatibility
   mode allow you to operate on those C host program types. Note however that
   the extent of the compatibility is limited. It does not try to copy <productname>Informix</productname>
   behaviour; it allows you to do more or less the same operations and gives
   you functions that have the same name and the same basic behavior but it is
   no drop-in replacement if you are using <productname>Informix</productname> at the moment. Moreover,
   some of the data types are different. For example,
   <productname>PostgreSQL's</productname> datetime and interval types do not
   know about ranges like for example <literal>YEAR TO MINUTE</> so you won't
   find support in ecpg for that either.
  </para>
a3099 4
  <sect2>
   <title>Additional embedded SQL statements</title>
   <para>
    <variablelist>
d3101 1
a3101 1
      <term><literal>CLOSE DATABASE</></term>
d3104 4
a3107 2
        This statement closes the current connection. In fact, this is a
        synonym for ecpg's <literal>DISCONNECT CURRENT</>.:
d3109 2
a3110 2
    $CLOSE DATABASE;                /* close the current connection */
    EXEC SQL CLOSE DATABASE;
d3115 73
d3189 38
a4449 202
 <sect1 id="ecpg-descriptors">
  <title>Using SQL Descriptor Areas</title>

  <para>
   An SQL descriptor area is a more sophisticated method for
   processing the result of a <command>SELECT</command> or
   <command>FETCH</command> statement.  An SQL descriptor area groups
   the data of one row of data together with metadata items into one
   data structure.  The metadata is particularly useful when executing
   dynamic SQL statements, where the nature of the result columns might
   not be known ahead of time.
  </para>

  <para>
   An SQL descriptor area consists of a header, which contains
   information concerning the entire descriptor, and one or more item
   descriptor areas, which basically each describe one column in the
   result row.
  </para>

  <para>
   Before you can use an SQL descriptor area, you need to allocate one:
<programlisting>
EXEC SQL ALLOCATE DESCRIPTOR <replaceable>identifier</replaceable>;
</programlisting>
   The identifier serves as the <quote>variable name</quote> of the
   descriptor area.  <remark>The scope of the allocated descriptor is WHAT?.</remark>
   When you don't need the descriptor anymore, you should deallocate
   it:
<programlisting>
EXEC SQL DEALLOCATE DESCRIPTOR <replaceable>identifier</replaceable>;
</programlisting>
  </para>

  <para>
   To use a descriptor area, specify it as the storage target in an
   <literal>INTO</literal> clause, instead of listing host variables:
<programlisting>
EXEC SQL FETCH NEXT FROM mycursor INTO DESCRIPTOR mydesc;
</programlisting>
  </para>

  <para>
   Now how do you get the data out of the descriptor area?  You can
   think of the descriptor area as a structure with named fields.  To
   retrieve the value of a field from the header and store it into a
   host variable, use the following command:
<programlisting>
EXEC SQL GET DESCRIPTOR <replaceable>name</replaceable> :<replaceable>hostvar</replaceable> = <replaceable>field</replaceable>;
</programlisting>
   Currently, there is only one header field defined:
   <replaceable>COUNT</replaceable>, which tells how many item
   descriptor areas exist (that is, how many columns are contained in
   the result).  The host variable needs to be of an integer type.  To
   get a field from the item descriptor area, use the following
   command:
<programlisting>
EXEC SQL GET DESCRIPTOR <replaceable>name</replaceable> VALUE <replaceable>num</replaceable> :<replaceable>hostvar</replaceable> = <replaceable>field</replaceable>;
</programlisting>
   <replaceable>num</replaceable> can be a literal integer or a host
   variable containing an integer. Possible fields are:

   <variablelist>
    <varlistentry>
     <term><literal>CARDINALITY</literal> (integer)</term>
     <listitem>
      <para>
       number of rows in the result set
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>DATA</literal></term>
     <listitem>
      <para>
       actual data item (therefore, the data type of this field
       depends on the query)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>DATETIME_INTERVAL_CODE</literal> (integer)</term>
     <listitem>
      <para>
       ?
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>DATETIME_INTERVAL_PRECISION</literal> (integer)</term>
     <listitem>
      <para>
       not implemented
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>INDICATOR</literal> (integer)</term>
     <listitem>
      <para>
       the indicator (indicating a null value or a value truncation)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>KEY_MEMBER</literal> (integer)</term>
     <listitem>
      <para>
       not implemented
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>LENGTH</literal> (integer)</term>
     <listitem>
      <para>
       length of the datum in characters
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>NAME</literal> (string)</term>
     <listitem>
      <para>
       name of the column
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>NULLABLE</literal> (integer)</term>
     <listitem>
      <para>
       not implemented
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>OCTET_LENGTH</literal> (integer)</term>
     <listitem>
      <para>
       length of the character representation of the datum in bytes
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>PRECISION</literal> (integer)</term>
     <listitem>
      <para>
       precision (for type <type>numeric</type>)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>RETURNED_LENGTH</literal> (integer)</term>
     <listitem>
      <para>
       length of the datum in characters
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>RETURNED_OCTET_LENGTH</literal> (integer)</term>
     <listitem>
      <para>
       length of the character representation of the datum in bytes
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>SCALE</literal> (integer)</term>
     <listitem>
      <para>
       scale (for type <type>numeric</type>)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>TYPE</literal> (integer)</term>
     <listitem>
      <para>
       numeric code of the data type of the column
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </sect1>

@


1.92
log
@Properly indent SGML.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.91 2009/09/18 13:13:32 meskes Exp $ -->
d4712 3
a4714 4
   The <application>ecpg</application> library is thread-safe if it is built
   using the <option>--enable-thread-safety</> command-line option to
   <filename>configure</filename>.  (You might need to use other threading
   command-line options to compile your client code.)
@


1.91
log
@Added patch by Bernd Helmle <bernd.helmle@@credativ.de> that adds a low level
function that returns the current transaction status.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.90 2009/07/11 21:15:32 petere Exp $ -->
d355 1
a355 1
      </para>
d357 5
a361 5
      <para>
      If your application uses multiple threads of execution, they cannot share a
      connection concurrently. You must either explicitly control access to the connection
      (using mutexes) or use a connection for each thread. If each thread uses its own connection,
      you will need to use the AT clause to specify which connection the thread will use.
@


1.90
log
@Alter some gratuitous uses of "ANSI" when "SQL standard" might have been
meant or the reference to a standard was unnecessary.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.89 2009/05/18 11:08:24 petere Exp $ -->
d4757 25
@


1.89
log
@Refer to tables by id, not by "the following table", because tables are in
theory floating elements.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.88 2009/04/27 16:27:35 momjian Exp $ -->
d3065 1
a3065 1
        Parses a timestamp from its textual representation in ANSI standard
d3090 1
a3090 1
        Parses a timestamp from its textual representation in ANSI standard
d3143 1
a3143 1
        textual representation in the ANSI SQL standard which is defined to
d3190 1
a3190 1
        textual representation in the ANSI SQL standard which is defined to
@


1.89.2.1
log
@Fix some spelling errors.

Thom Brown
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.89 2009/05/18 11:08:24 petere Exp $ -->
d2396 1
a2396 1
   There are two compatibility modes: INFORMIX, INFORMIX_SE
@


1.89.2.2
log
@Fix incorrect errno definitions in ECPG manual.

ecpgerrno.h hasn't materially changed since PostgreSQL 7.4, so this has
been wrong for a very long time.  Back-patch all the way.

Satoshi Nagayasu
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.89.2.1 2010/05/13 14:16:57 mha Exp $ -->
d4312 1
a4312 1
     <term>-212 (<symbol>ECPG_EMPTY</symbol>)</term>
d4324 1
a4324 1
     <term>-213 (<symbol>ECPG_MISSING_INDICATOR</symbol>)</term>
d4334 1
a4334 1
     <term>-214 (<symbol>ECPG_NO_ARRAY</symbol>)</term>
d4344 1
a4344 1
     <term>-215 (<symbol>ECPG_DATA_NOT_ARRAY</symbol>)</term>
@


1.89.2.3
log
@Fix one more incorrect errno definition in the ECPG manual.

Again, back-patch all the way to 7.4.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.89.2.2 2010/08/11 18:52:23 rhaas Exp $ -->
d4301 1
a4301 1
     <term>-211 (<symbol>ECPG_CONVERT_BOOL</symbol>)</term>
@


1.88
log
@Proofreading adjustments for first two parts of documentation (Tutorial
and SQL).
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.87 2008/12/07 23:46:39 alvherre Exp $ -->
d1140 3
a1142 2
        The following input formats are allowed:
        <table>
a1222 1
       </para>
d1395 1
a1395 1
        The following table indicates a few possible formats. This will give
d1397 3
a1399 2
        the same date: November, 23rd, 1959.
        <table>
a1459 1
       </para>
d1486 1
a1486 1
        The following table indicates a few possible formats. This will give
d1488 2
a1489 1
        <table>
a1567 1
       </para>
d1615 3
a1617 2
        The following table contains a few examples for input strings:
        <table>
a1645 1
       </para>
@


1.87
log
@Desultorily enclose programlisting tags in CDATA, to get rid of some obnoxious
SGML-escaping.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.86 2008/06/12 19:15:40 momjian Exp $ -->
d753 1
a753 1
   functions to do basic calculations with those types within C, i.e. without
d1235 1
a1235 1
        It will output the date in the form <literal>1999-01-18</>, i.e. in the
@


1.86
log
@Use macro to document size of ecpg sqlerrmc string.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.85 2007/12/03 23:49:50 tgl Exp $ -->
d720 1
a720 1
<programlisting>
d722 1
a722 1
const char *stmt = "SELECT a, b, c FROM test1 WHERE a &gt; ?";
d730 1
d756 1
a756 1
<programlisting>
d764 1
a764 1
PGTYPESdate_today(&amp;date1);
d766 2
a767 2
PGTYPEStimestamp_add_interval(&amp;ts1, &amp;iv1, &amp;tsout);
out = PGTYPEStimestamp_to_asc(&amp;tsout);
d770 1
d3454 1
a3454 1
<programlisting>
d3460 3
a3462 2
rsetnull(CSHORTTYPE, (char *) &amp;s);
rsetnull(CINTTYPE, (char *) &amp;i);
d3483 1
a3483 1
<programlisting>
d3489 3
a3491 2
risnull(CSHORTTYPE, (char *) &amp;s);
risnull(CINTTYPE, (char *) &amp;i);
d4967 1
a4967 1
<programlisting>
d4970 2
a4971 2
#include &lt;ecpgtype.h&gt;;
#include &lt;ecpglib.h&gt;;
d4982 1
a4982 1
        ECPGt_int,&amp;(index),1L,1L,sizeof(int),
d4984 1
a4984 1
        ECPGt_int,&amp;(result),1L,1L,sizeof(int),
d4987 1
@


1.85
log
@Entity-ify a passel of & < > characters.  Per gripe from Devrim.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.84 2007/11/07 12:24:23 petere Exp $ -->
d4064 1
a4064 1
        char sqlerrmc[70];
@


1.85.2.1
log
@Fix some spelling errors.

Thom Brown
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.85 2007/12/03 23:49:50 tgl Exp $ -->
d2394 1
a2394 1
   There are two compatibility modes: INFORMIX, INFORMIX_SE
@


1.85.2.2
log
@Fix incorrect errno definitions in ECPG manual.

ecpgerrno.h hasn't materially changed since PostgreSQL 7.4, so this has
been wrong for a very long time.  Back-patch all the way.

Satoshi Nagayasu
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.85.2.1 2010/05/13 14:16:51 mha Exp $ -->
d4308 1
a4308 1
     <term>-212 (<symbol>ECPG_EMPTY</symbol>)</term>
d4320 1
a4320 1
     <term>-213 (<symbol>ECPG_MISSING_INDICATOR</symbol>)</term>
d4330 1
a4330 1
     <term>-214 (<symbol>ECPG_NO_ARRAY</symbol>)</term>
d4340 1
a4340 1
     <term>-215 (<symbol>ECPG_DATA_NOT_ARRAY</symbol>)</term>
@


1.85.2.3
log
@Fix one more incorrect errno definition in the ECPG manual.

Again, back-patch all the way to 7.4.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.85.2.2 2010/08/11 18:52:33 rhaas Exp $ -->
d4297 1
a4297 1
     <term>-211 (<symbol>ECPG_CONVERT_BOOL</symbol>)</term>
@


1.84
log
@Use "alternative" instead of "alternate" where it is clearer.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.83 2007/04/17 17:30:35 tgl Exp $ -->
d4698 1
a4698 1
        $(ECPG) $<
@


1.83
log
@Fix erroneous column counts in some documentation tables.  Brian Gough
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.82 2007/02/16 03:56:45 momjian Exp $ -->
d1774 1
a1774 1
           are supposed to provide alternate representations.
@


1.82
log
@Remove extra character erroneously added.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.81 2007/02/16 03:50:29 momjian Exp $ -->
d1488 1
a1488 1
         <tgroup cols="2">
@


1.81
log
@Remove tabs from SGML files to help tag alingment and improve
detection of tabs are added in the future.
@
text
@d1 1
a1 1
`<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.80 2007/02/01 19:10:24 momjian Exp $ -->
@


1.80
log
@Wording cleanup for error messages.  Also change can't -> cannot.

Standard English uses "may", "can", and "might" in different ways:

        may - permission, "You may borrow my rake."

        can - ability, "I can lift that log."

        might - possibility, "It might rain today."

Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice.  Similarly, "It may crash" is better stated, "It might crash".
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.79 2007/02/01 00:28:16 momjian Exp $ -->
d1113 2
a1114 2
	The function receives a timestamp as its only argument and returns the
	extracted date part from this timestamp.
d1127 5
a1131 5
	The function receives a C char* string <literal>str</> and a pointer to
	a C char* string <literal>endptr</>. At the moment ecpg always parses
	the complete string and so it currently does not support to store the
	address of the first invalid character in <literal>*endptr</literal>.
	You can safely set <literal>endptr</literal> to NULL.
d1134 2
a1135 2
	Note that the function always assumes MDY-formatted dates and there is
	currently no variable to change that within ecpg.
d1140 77
a1216 77
	 <title>Valid input formats for <function>PGTYPESdate_from_asc</function></title>
	 <tgroup cols="2">
	  <thead>
	   <row>
	    <entry>Input</entry>
	    <entry>Result</entry>
	   </row>
	  </thead>
	  <tbody>
	   <row>
	    <entry><literal>January 8, 1999</literal></entry>
	    <entry><literal>January 8, 1999</literal></entry>
	   </row>
	   <row>
	    <entry><literal>1999-01-08</literal></entry>
	    <entry><literal>January 8, 1999</literal></entry>
	   </row>
	   <row>
	    <entry><literal>1/8/1999</literal></entry>
	    <entry><literal>January 8, 1999</literal></entry>
	   </row>
	   <row>
	    <entry><literal>1/18/1999</literal></entry>
	    <entry><literal>January 18, 1999</literal></entry>
	   </row>
	   <row>
	    <entry><literal>01/02/03</literal></entry>
	    <entry><literal>February 1, 2003</literal></entry>
	   </row>
	   <row>
	    <entry><literal>1999-Jan-08</literal></entry>
	    <entry><literal>January 8, 1999</literal></entry>
	   </row>
	   <row>
	    <entry><literal>Jan-08-1999</literal></entry>
	    <entry><literal>January 8, 1999</literal></entry>
	   </row>
	   <row>
	    <entry><literal>08-Jan-1999</literal></entry>
	    <entry><literal>January 8, 1999</literal></entry>
	   </row>
	   <row>
	    <entry><literal>99-Jan-08</literal></entry>
	    <entry><literal>January 8, 1999</literal></entry>
	   </row>
	   <row>
	    <entry><literal>08-Jan-99</literal></entry>
	    <entry><literal>January 8, 1999</literal></entry>
	   </row>
	   <row>
	    <entry><literal>08-Jan-06</literal></entry>
	    <entry><literal>January 8, 2006</literal></entry>
	   </row>
	   <row>
	    <entry><literal>Jan-08-99</literal></entry>
	    <entry><literal>January 8, 1999</literal></entry>
	   </row>
	   <row>
	    <entry><literal>19990108</literal></entry>
	    <entry><literal>ISO 8601; January 8, 1999</literal></entry>
	   </row>
	   <row>
	    <entry><literal>990108</literal></entry>
	    <entry><literal>ISO 8601; January 8, 1999</literal></entry>
	   </row>
	   <row>
	    <entry><literal>1999.008</literal></entry>
	    <entry><literal>year and day of year</literal></entry>
	   </row>
	   <row>
	    <entry><literal>J2451187</literal></entry>
	    <entry><literal>Julian day</literal></entry>
	   </row>
	   <row>
	    <entry><literal>January 8, 99 BC</literal></entry>
	    <entry><literal>year 99 before the Common Era</literal></entry>
	   </row>
d1232 3
a1234 3
	The function receives the date <literal>dDate</> as its only parameter.
	It will output the date in the form <literal>1999-01-18</>, i.e. in the
	<literal>YYYY-MM-DD</> format.
d1243 2
a1244 2
	Extract the values for the day, the month and the year from a variable
	of type date.
d1249 5
a1253 5
	The function receives the date <literal>d</> and a pointer to an array
	of 3 integer values <literal>mdy</>. The variable name indicates
	the sequential order: <literal>mdy[0]</> will be set to contain the
	number of the month, <literal>mdy[1]</> will be set to the value of the
	day and <literal>mdy[2]</> will contain the year.
d1262 2
a1263 2
	Create a date value from an array of 3 integers that specify the
	day, the month and the year of the date.
d1267 3
a1269 3
	The function receives the array of the 3 integers (<literal>mdy</>) as
	its first argument and as its second argument a pointer to a variable
	of type date that should hold the result of the operation.
d1282 3
a1284 3
	The function receives the date variable <literal>d</> as its only
	argument and returns an integer that indicates the day of the week for
	this date.
d1288 1
a1288 1
	   0 - Sunday
d1293 1
a1293 1
	   1 - Monday
d1298 1
a1298 1
	   2 - Tuesday
d1303 1
a1303 1
	   3 - Wednesday
d1308 1
a1308 1
	   4 - Thursday
d1313 1
a1313 1
	   5 - Friday
d1318 1
a1318 1
	   6 - Saturday
d1334 2
a1335 2
	The function receives a pointer to a date variable (<literal>d</>)
	that it sets to the current date.
d1344 2
a1345 2
	Convert a variable of type date to its textual representation using a
	format mask.
d1349 3
a1351 3
	The function receives the date to convert (<literal>dDate</>), the
	format mask (<literal>fmtstring</>) and the string that will hold the
	textual representation of the date (<literal>outbuf</>).
d1390 1
a1390 1
	All other characters are copied 1:1 to the output string.
d1393 3
a1395 3
	The following table indicates a few possible formats. This will give
	you an idea of how to use this function. All output lines are based on
	the same date: November, 23rd, 1959.
d1397 57
a1453 57
	 <title>Valid input formats for <function>PGTYPESdate_fmt_asc</function></title>
	 <tgroup cols="2">
	  <thead>
	   <row>
	    <entry>fmt</entry>
	    <entry>result</entry>
	   </row>
	  </thead>
	  <tbody>
	   <row>
	    <entry><literal>mmddyy</literal></entry>
	    <entry><literal>112359</literal></entry>
	   </row>
	   <row>
	    <entry><literal>ddmmyy</literal></entry>
	    <entry><literal>231159</literal></entry>
	   </row>
	   <row>
	    <entry><literal>yymmdd</literal></entry>
	    <entry><literal>591123</literal></entry>
	   </row>
	   <row>
	    <entry><literal>yy/mm/dd</literal></entry>
	    <entry><literal>59/11/23</literal></entry>
	   </row>
	   <row>
	    <entry><literal>yy mm dd</literal></entry>
	    <entry><literal>59 11 23</literal></entry>
	   </row>
	   <row>
	    <entry><literal>yy.mm.dd</literal></entry>
	    <entry><literal>59.11.23</literal></entry>
	   </row>
	   <row>
	    <entry><literal>.mm.yyyy.dd.</literal></entry>
	    <entry><literal>.11.1959.23.</literal></entry>
	   </row>
	   <row>
	    <entry><literal>mmm. dd, yyyy</literal></entry>
	    <entry><literal>Nov. 23, 1959</literal></entry>
	   </row>
	   <row>
	    <entry><literal>mmm dd yyyy</literal></entry>
	    <entry><literal>Nov 23 1959</literal></entry>
	   </row>
	   <row>
	    <entry><literal>yyyy dd mm</literal></entry>
	    <entry><literal>1959 23 11</literal></entry>
	   </row>
	   <row>
	    <entry><literal>ddd, mmm. dd, yyyy</literal></entry>
	    <entry><literal>Mon, Nov. 23, 1959</literal></entry>
	   </row>
	   <row>
	    <entry><literal>(ddd) mmm. dd, yyyy</literal></entry>
	    <entry><literal>(Mon) Nov. 23, 1959</literal></entry>
	   </row>
d1465 2
a1466 2
	Use a format mask to convert a C char* string to a value of type
	date.
d1470 12
a1481 12
	<!-- same description as rdefmtdate -->
	The function receives a pointer to the date value that should hold the
	result of the operation (<literal>d</>), the format mask to use for
	parsing the date (<literal>fmt</>) and the C char* string containing
	the textual representation of the date (<literal>str</>). The textual
	representation is expected to match the format mask. However you do not
	need to have a 1:1 mapping of the string to the format mask. The
	function only analyzes the sequential order and looks for the literals
	<literal>yy</literal> or <literal>yyyy</literal> that indicate the
	position of the year, <literal>mm</literal> to indicate the position of
	the month and <literal>dd</literal> to indicate the position of the
	day.
d1484 2
a1485 2
	The following table indicates a few possible formats. This will give
	you an idea of how to use this function.
d1487 75
a1561 75
	 <title>Valid input formats for <function>rdefmtdate</function></title>
	 <tgroup cols="2">
	  <thead>
	   <row>
	    <entry>fmt</entry>
	    <entry>str</entry>
	    <entry>result</entry>
	   </row>
	  </thead>
	  <tbody>
	   <row>
	    <entry><literal>ddmmyy</literal></entry>
	    <entry><literal>21-2-54</literal></entry>
	    <entry><literal>1954-02-21</literal></entry>
	   </row>
	   <row>
	    <entry><literal>ddmmyy</literal></entry>
	    <entry><literal>2-12-54</literal></entry>
	    <entry><literal>1954-12-02</literal></entry>
	   </row>
	   <row>
	    <entry><literal>ddmmyy</literal></entry>
	    <entry><literal>20111954</literal></entry>
	    <entry><literal>1954-11-20</literal></entry>
	   </row>
	   <row>
	    <entry><literal>ddmmyy</literal></entry>
	    <entry><literal>130464</literal></entry>
	    <entry><literal>1964-04-13</literal></entry>
	   </row>
	   <row>
	    <entry><literal>mmm.dd.yyyy</literal></entry>
	    <entry><literal>MAR-12-1967</literal></entry>
	    <entry><literal>1967-03-12</literal></entry>
	   </row>
	   <row>
	    <entry><literal>yy/mm/dd</literal></entry>
	    <entry><literal>1954, February 3rd</literal></entry>
	    <entry><literal>1954-02-03</literal></entry>
	   </row>
	   <row>
	    <entry><literal>mmm.dd.yyyy</literal></entry>
	    <entry><literal>041269</literal></entry>
	    <entry><literal>1969-04-12</literal></entry>
	   </row>
	   <row>
	    <entry><literal>yy/mm/dd</literal></entry>
	    <entry><literal>In the year 2525, in the month of July, mankind will be alive on the 28th day</literal></entry>
	    <entry><literal>2525-07-28</literal></entry>
	   </row>
	   <row>
	    <entry><literal>dd-mm-yy</literal></entry>
	    <entry><literal>I said on the 28th of July in the year 2525</literal></entry>
	    <entry><literal>2525-07-28</literal></entry>
	   </row>
	   <row>
	    <entry><literal>mmm.dd.yyyy</literal></entry>
	    <entry><literal>9/14/58</literal></entry>
	    <entry><literal>1958-09-14</literal></entry>
	   </row>
	   <row>
	    <entry><literal>yy/mm/dd</literal></entry>
	    <entry><literal>47/03/29</literal></entry>
	    <entry><literal>1947-03-29</literal></entry>
	   </row>
	   <row>
	    <entry><literal>mmm.dd.yyyy</literal></entry>
	    <entry><literal>oct 28 1975</literal></entry>
	    <entry><literal>1975-10-28</literal></entry>
	   </row>
	   <row>
	    <entry><literal>mmddyy</literal></entry>
	    <entry><literal>Nov 14th, 1985</literal></entry>
	    <entry><literal>1985-11-14</literal></entry>
	   </row>
d1586 2
a1587 2
	Parse a timestamp from its textual representation into a timestamp
	variable.
d1591 20
a1610 20
	The function receives the string to parse (<literal>str</>) and a
	pointer to a C char* (<literal>endptr</>).
	At the moment ecpg always parses
	the complete string and so it currently does not support to store the
	address of the first invalid character in <literal>*endptr</literal>.
	You can safely set <literal>endptr</literal> to NULL.
       </para>
       <para>
	The function returns the parsed timestamp on success. On error,
	<literal>PGTYPESInvalidTimestamp</literal> is returned and errno is
	set to <literal>PGTYPES_TS_BAD_TIMESTAMP</>. See <xref linkend="PGTYPESInvalidTimestamp"> for important notes on this value.
	
       </para>
       <para>
	In general, the input string can contain any combination of an allowed
	date specification, a whitespace character and an allowed time
	specification. Note that timezones are not supported by ecpg. It can
	parse them but does not apply any calculation as the
	<productname>PostgreSQL</> server does for example. Timezone
	specifiers are silently discarded.
d1615 25
a1639 25
	 <title>Valid input formats for <function>PGTYPEStimestamp_from_asc</function></title>
	 <tgroup cols="2">
	  <thead>
	   <row>
	    <entry>Input</entry>
	    <entry>Result</entry>
	   </row>
	  </thead>
	  <tbody>
	   <row>
	    <entry><literal>1999-01-08 04:05:06</literal></entry>
	    <entry><literal>1999-01-08 04:05:06</literal></entry>
	   </row>
	   <row>
	    <entry><literal>January 8 04:05:06 1999 PST</literal></entry>
	    <entry><literal>1999-01-08 04:05:06</literal></entry>
	   </row>
	   <row>
	    <entry><literal>1999-Jan-08 04:05:06.789-8</literal></entry>
	    <entry><literal>1999-01-08 04:05:06.789 (time zone specifier ignored)</literal></entry>
	   </row>
	   <row>
	    <entry><literal>J2451187 04:05-08:00</literal></entry>
	    <entry><literal>1999-01-08 04:05:00 (time zone specifier ignored)</literal></entry>
	   </row>
d1655 3
a1657 3
	The function receives the timestamp <literal>tstamp</> as
	its only argument and returns an allocated string that contains the
	textual representation of the timestamp.
d1670 2
a1671 2
	The function retrieves the current timestamp and saves it into the
	timestamp variable that <literal>ts</> points to.
d1684 18
a1701 18
	The function receives a pointer to the timestamp to convert as its
	first argument (<literal>ts</>), a pointer to the output buffer
	(<literal>output</>), the maximal length that has been allocated for
	the output buffer (<literal>str_len</literal>) and the format mask to
	use for the conversion (<literal>fmtstr</literal>).
       </para>
       <para>
	Upon success, the function returns 0 and a negative value if an
	error occurred.
       </para>
       <para>
	You can use the following format specifiers for the format mask. The
	format specifiers are the same ones that are used in the
	<function>strftime</> function in <productname>libc</productname>. Any
	non-format specifier will be copied into the output buffer. 
	<!-- This is from the FreeBSD man page:
	     http://www.freebsd.org/cgi/man.cgi?query=strftime&apropos=0&sektion=3&manpath=FreeBSD+7.0-current&format=html
	-->
d1705 2
a1706 2
	   <literal>%A</literal> - is replaced by national representation of
	   the full weekday name.
d1711 2
a1712 2
	   <literal>%a</literal> - is replaced by national representation of
	   the abbreviated weekday name.
d1717 2
a1718 2
	   <literal>%B</literal> - is replaced by national representation of
	   the full month name.
d1723 2
a1724 2
	   <literal>%b</literal> - is replaced by national representation of
	   the abbreviated month name.
d1729 2
a1730 2
	   <literal>%C</literal> - is replaced by (year / 100) as decimal
	   number; single digits are preceded by a zero.
d1735 2
a1736 2
	   <literal>%c</literal> - is replaced by national representation of
	   time and date.
d1741 2
a1742 2
	   <literal>%D</literal> - is equivalent to
	   <literal>%m/%d/%y</literal>.
d1747 2
a1748 2
	   <literal>%d</literal> - is replaced by the day of the month as a
	   decimal number (01-31).
d1753 22
a1774 22
	   <literal>%E*</literal> <literal>%O*</literal> -  POSIX locale
	   extensions. The sequences
	   <literal>%Ec</literal>
	   <literal>%EC</literal> 
	   <literal>%Ex</literal> 
	   <literal>%EX</literal> 
	   <literal>%Ey</literal> 
	   <literal>%EY</literal> 
	   <literal>%Od</literal> 
	   <literal>%Oe</literal>
	   <literal>%OH</literal> 
	   <literal>%OI</literal> 
	   <literal>%Om</literal> 
	   <literal>%OM</literal> 
	   <literal>%OS</literal> 
	   <literal>%Ou</literal> 
	   <literal>%OU</literal> 
	   <literal>%OV</literal> 
	   <literal>%Ow</literal> 
	   <literal>%OW</literal> 
	   <literal>%Oy</literal> 
	   are supposed to provide alternate representations.
d1777 2
a1778 2
	   Additionally <literal>%OB</literal> implemented to represent
	   alternative months names (used standalone, without day mentioned).
d1783 2
a1784 2
	   <literal>%e</literal> - is replaced by the day of month as a decimal
	   number (1-31); single digits are preceded by a blank.
d1789 1
a1789 1
	   <literal>%F</literal> - is equivalent to <literal>%Y-%m-%d</literal>.
d1794 3
a1796 3
	   <literal>%G</literal> - is replaced by a year as a decimal number
	   with century. This year is the one that contains the greater part of
	   the week (Monday as the first day of the week).
d1801 3
a1803 3
	   <literal>%g</literal> - is replaced by the same year as in
	   <literal>%G</literal>, but as a decimal number without century
	   (00-99).
d1808 2
a1809 2
	   <literal>%H</literal> - is replaced by the hour (24-hour clock) as a
	   decimal number (00-23).
d1814 1
a1814 1
	   <literal>%h</literal> - the same as <literal>%b</literal>.
d1819 2
a1820 2
	   <literal>%I</literal> - is replaced by the hour (12-hour clock) as a
	   decimal number (01-12).
d1825 2
a1826 2
	   <literal>%j</literal> - is replaced by the day of the year as a
	   decimal number (001-366).
d1831 2
a1832 2
	   <literal>%k</literal> - is replaced by the hour (24-hour clock) as a
	   decimal number (0-23); single digits are preceded by a blank.
d1837 2
a1838 2
	   <literal>%l</literal> - is replaced by the hour (12-hour clock) as a
	   decimal number (1-12); single digits are preceded by a blank.
d1843 2
a1844 2
	   <literal>%M</literal> - is replaced by the minute as a decimal
	   number (00-59).
d1849 2
a1850 2
	   <literal>%m</literal> - is replaced by the month as a decimal number
	   (01-12).
d1855 1
a1855 1
	  <literal>%n</literal> - is replaced by a newline.
d1860 1
a1860 1
	   <literal>%O*</literal> - the same as <literal>%E*</literal>.
d1865 2
a1866 2
	   <literal>%p</literal> - is replaced by national representation of
	   either "ante meridiem" or "post meridiem" as appropriate.
d1871 1
a1871 1
	   <literal>%R</literal> - is equivalent to <literal>%H:%M</literal>.
d1876 2
a1877 2
	   <literal>%r</literal> - is equivalent to <literal>%I:%M:%S
	   %p</literal>.
d1882 2
a1883 2
	   <literal>%S</literal> - is replaced by the second as a decimal
	   number (00-60).
d1888 2
a1889 2
	   <literal>%s</literal> - is replaced by the number of seconds since
	   the Epoch, UTC.
d1894 1
a1894 1
	   <literal>%T</literal> - is equivalent to <literal>%H:%M:%S</literal>
d1899 1
a1899 1
	   <literal>%t</literal> - is replaced by a tab.
d1904 2
a1905 2
	   <literal>%U</literal> - is replaced by the week number of the year
	   (Sunday as the first day of the week) as a decimal number (00-53).
d1910 2
a1911 2
	   <literal>%u</literal> - is replaced by the weekday (Monday as the
	   first day of the week) as a decimal number (1-7).
d1916 5
a1920 5
	   <literal>%V</literal> - is replaced by the week number of the year
	   (Monday as the first day of the week) as a decimal number (01-53).
	   If the week containing January 1 has four or more days in the new
	   year, then it is week 1; otherwise it is the last week of the
	   previous year, and the next week is week 1.
d1925 2
a1926 2
	   <literal>%v</literal> - is equivalent to
	   <literal>%e-%b-%Y</literal>.
d1931 2
a1932 2
	   <literal>%W</literal> - is replaced by the week number of the year
	   (Monday as the first day of the week) as a decimal number (00-53).
d1937 2
a1938 2
	   <literal>%w</literal> - is replaced by the weekday (Sunday as the
	   first day of the week) as a decimal number (0-6).
d1943 2
a1944 2
	   <literal>%X</literal> - is replaced by national representation of
	   the time.
d1949 2
a1950 2
	   <literal>%x</literal> - is replaced by national representation of
	   the date.
d1955 2
a1956 2
	   <literal>%Y</literal> - is replaced by the year with century as a
	   decimal number.
d1961 2
a1962 2
	   <literal>%y</literal> - is replaced by the year without century as a
	   decimal number (00-99).
d1967 1
a1967 1
	   <literal>%Z</literal> - is replaced by the time zone name.
d1972 4
a1975 4
	   <literal>%z</literal> - is replaced by the time zone offset from
	   UTC; a leading plus sign stands for east of UTC, a minus sign for
	   west of UTC, hours and minutes follow with two digits each and no
	   delimiter between them (common form for RFC 822 date headers).
d1980 2
a1981 2
	   <literal>%+</literal> - is replaced by national representation of
	   the date and time.
d1986 2
a1987 2
	   <literal>%-*</literal> - GNU libc extension.	Do not do any padding
	   when performing numerical outputs.
d1992 1
a1992 1
	   $_* - GNU libc extension.	Explicitly specify space for padding.
d1997 2
a1998 2
	   <literal>%0*</literal> - GNU libc extension.	Explicitly specify zero
	   for padding.
d2003 1
a2003 1
	   <literal>%%</literal> - is replaced by <literal>%</literal>.
d2015 2
a2016 2
	Subtract one timestamp from another one and save the result in a
	variable of type interval.
d2020 4
a2023 4
	The function will subtract the timestamp variable that <literal>ts2</>
	points to from the timestamp variable that <literal>ts1</> points to
	and will store the result in the interval variable that <literal>iv</>
	points to.
d2026 2
a2027 2
	Upon success, the function returns 0 and a negative value if an
	error occurred.
d2036 2
a2037 2
	Parse a timestamp value from its textual representation using a
	formatting mask.
d2041 4
a2044 4
	The function receives the textual representation of a timestamp in the
	variable <literal>str</> as well as the formatting mask to use in the
	variable <literal>fmt</>. The result will be stored in the variable
	that <literal>d</> points to.
d2047 3
a2049 3
	If the formatting mask <literal>fmt</> is NULL, the function will fall
	back to the default formatting mask which is <literal>%Y-%m-%d
	%H:%M:%S</literal>.
d2052 3
a2054 3
	This is the reverse function to <xref
	linkend="PGTYPEStimestampfmtasc">.  See the documentation there in
	order to find out about the possible formatting mask entries.
d2067 4
a2070 4
	The function receives a pointer to a timestamp variable <literal>tin</>
	and a pointer to an interval variable <literal>span</>. It adds the
	interval to the timestamp and saves the resulting timestamp in the
	variable that <literal>tout</> points to.
d2073 2
a2074 2
	Upon success, the function returns 0 and a negative value if an
	error occurred.
d2087 4
a2090 4
	The function subtracts the interval variable that <literal>span</>
	points to from the timestamp variable that <literal>tin</> points to
	and saves the result into the variable that <literal>tout</> points
	to.
d2093 2
a2094 2
	Upon success, the function returns 0 and a negative value if an
	error occurred.
d2145 6
a2150 6
	The function parses the input string <literal>str</> and returns a
	pointer to an allocated interval variable.
	At the moment ecpg always parses
	the complete string and so it currently does not support to store the
	address of the first invalid character in <literal>*endptr</literal>.
	You can safely set <literal>endptr</literal> to NULL.
d2163 3
a2165 3
	The function converts the interval variable that <literal>span</>
	points to into a C char*. The output looks like this example:
	<literal>@@ 1 day 12 hours 59 mins 10 secs</literal>.
d2178 4
a2181 4
	The function copies the interval variable that <literal>intvlsrc</>
	points to into the variable that <literal>intvldest</> points to. Note
	that you need to allocate the memory for the destination variable
	before.
d2239 2
a2240 2
	An argument should contain a numeric variable (or point to a numeric
	variable) but in fact its in-memory representation was invalid.
d2249 3
a2251 3
	An overflow occurred. Since the numeric type can deal with almost
	arbitrary precision, converting a numeric variable into other types
	might cause overflow.
d2260 3
a2262 3
	An underflow occurred. Since the numeric type can deal with almost
	arbitrary precision, converting a numeric variable into other types
	might cause underflow.
d2359 10
a2368 10
	A value of type timestamp representing an invalid time stamp. This is
	returned by the function <function>PGTYPEStimestamp_from_asc</> on
	parse error.
	Note that due to the internal representation of the timestamp datatype,
	<literal>PGTYPESInvalidTimestamp</literal> is also a valid timestamp at
	the same time. It is set to <literal>1899-12-31 23:59:59</>. In order
	to detect errors, make sure that your application does not only test
	for <literal>PGTYPESInvalidTimestamp</literal> but also for
	<literal>errno != 0</> after each call to
	<function>PGTYPEStimestamp_from_asc</>.
d2428 2
a2429 2
	This statement closes the current connection. In fact, this is a
	synonym for ecpg's <literal>DISCONNECT CURRENT</>.:
d2453 8
a2460 8
	The function receives a pointer to the first operand of type decimal
	(<literal>arg1</>), a pointer to the second operand of type decimal
	(<literal>arg2</>) and a pointer to a value of type decimal that will
	contain the sum (<literal>sum</>). On success, the function returns 0.
	ECPG_INFORMIX_NUM_OVERFLOW is returned in case of overflow and 
	ECPG_INFORMIX_NUM_UNDERFLOW in case of underflow. -1 is returned for
	other failures and errno is set to the respective errno number of the
	pgtypeslib.
d2473 4
a2476 4
	The function receives a pointer to the first decimal value
	(<literal>arg1</>), a pointer to the second decimal value
	(<literal>arg2</>) and returns an integer value that indicates which is
	the bigger value.
d2480 2
a2481 2
	   1, if the value that <literal>arg1</> points to is bigger than the
	   value that <literal>var2</> points to
d2486 2
a2487 2
	   -1, if the value that <literal>arg1</> points to is smaller than the
	   value that <literal>arg2</> points to </para>
d2491 2
a2492 2
	   0, if the value that <literal>arg1</> points to and the value that
	   <literal>arg2</> points to are equal
d2508 4
a2511 4
	The function receives a pointer to the decimal value that should be
	copied as the first argument (<literal>src</>) and a pointer to the
	target structure of type decimal (<literal>target</>) as the second
	argument.
d2524 4
a2527 4
	The function receives a pointer to string that contains the string
	representation of the number to be converted (<literal>cp</>) as well
	as its length <literal>len</>. <literal>np</> is a pointer to the
	decimal value that saves the result of the operation.
d2538 7
a2544 7
	The function returns 0 on success. If overflow or underflow occurred,
	<literal>ECPG_INFORMIX_NUM_OVERFLOW</> or
	<literal>ECPG_INFORMIX_NUM_UNDERFLOW</> is returned. If the ASCII
	representation could not be parsed,
	<literal>ECPG_INFORMIX_BAD_NUMERIC</> is returned or
	<literal>ECPG_INFORMIX_BAD_EXPONENT</> if this problem occurred while
	parsing the exponent.
d2557 4
a2560 4
	The function receives the variable of type double that should be
	converted as its first argument (<literal>dbl</>). As the second
	argument (<literal>np</>), the function receives a pointer to the
	decimal variable that should hold the result of the operation.
d2563 2
a2564 2
	The function returns 0 on success and a negative value if the
	conversion failed.
d2577 4
a2580 4
	The function receives the variable of type int that should be
	converted as its first argument (<literal>in</>). As the second
	argument (<literal>np</>), the function receives a pointer to the
	decimal variable that should hold the result of the operation.
d2583 2
a2584 2
	The function returns 0 on success and a negative value if the
	conversion failed.
d2597 4
a2600 4
	The function receives the variable of type long that should be
	converted as its first argument (<literal>lng</>). As the second
	argument (<literal>np</>), the function receives a pointer to the
	decimal variable that should hold the result of the operation.
d2603 2
a2604 2
	The function returns 0 on success and a negative value if the
	conversion failed.
d2617 4
a2620 4
	The function receives pointers to the variables that are the first
	(<literal>n1</>) and the second (<literal>n2</>) operands and
	calculates <literal>n1</>/<literal>n2</>. <literal>result</> is a
	pointer to the variable that should hold the result of the operation.
d2623 6
a2628 6
	On success, 0 is returned and a negative value if the division fails.
	If overflow or underflow occurred, the function returns
	<literal>ECPG_INFORMIX_NUM_OVERFLOW</> or
	<literal>ECPG_INFORMIX_NUM_UNDERFLOW</> respectively. If an attempt to
	divide by zero is observed, the function returns
	<literal>ECPG_INFORMIX_DIVIDE_ZERO</literal>.
d2641 4
a2644 4
	The function receives pointers to the variables that are the first
	(<literal>n1</>) and the second (<literal>n2</>) operands and
	calculates <literal>n1</>*<literal>n2</>. <literal>result</> is a
	pointer to the variable that should hold the result of the operation.
d2647 4
a2650 4
	On success, 0 is returned and a negative value if the multiplication
	fails. If overflow or underflow occurred, the function returns
	<literal>ECPG_INFORMIX_NUM_OVERFLOW</> or
	<literal>ECPG_INFORMIX_NUM_UNDERFLOW</> respectively.
d2663 4
a2666 4
	The function receives pointers to the variables that are the first
	(<literal>n1</>) and the second (<literal>n2</>) operands and
	calculates <literal>n1</>-<literal>n2</>. <literal>result</> is a
	pointer to the variable that should hold the result of the operation.
d2669 4
a2672 4
	On success, 0 is returned and a negative value if the subtraction
	fails. If overflow or underflow occurred, the function returns
	<literal>ECPG_INFORMIX_NUM_OVERFLOW</> or
	<literal>ECPG_INFORMIX_NUM_UNDERFLOW</> respectively.
d2681 2
a2682 2
	Convert a variable of type decimal to its ASCII representation in a C
	char* string.
d2686 17
a2702 17
	The function receives a pointer to a variable of type decimal
	(<literal>np</>) that it converts to its textual representation.
	<literal>cp</> is the buffer that should hold the result of the
	operation. The parameter <literal>right</> specifies, how many digits
	right of the decimal point should be included in the output. The result
	will be rounded to this number of decimal digits. Setting
	<literal>right</> to -1 indicates that all available decimal digits
	should be included in the output. If the length of the output buffer,
	which is indicated by <literal>len</> is not sufficient to hold the
	textual representation including the trailing NUL character, only a
	single <literal>*</> character is stored in the result and -1 is
	returned.
       </para>
       <para>
	The function returns either -1 if the buffer <literal>cp</> was too
	small or <literal>ECPG_INFORMIX_OUT_OF_MEMORY</> if memory was
	exhausted. 
d2715 3
a2717 3
	The function receives a pointer to the decimal value to convert
	(<literal>np</>) and a pointer to the double variable that
	should hold the result of the operation (<literal>dblp</>).
d2720 2
a2721 2
	On success, 0 is returned and a negative value if the conversion
	failed.
d2734 3
a2736 3
	The function receives a pointer to the decimal value to convert
	(<literal>np</>) and a pointer to the integer variable that
	should hold the result of the operation (<literal>ip</>).
d2739 3
a2741 3
	On success, 0 is returned and a negative value if the conversion
	failed. If an overflow occurred, <literal>ECPG_INFORMIX_NUM_OVERFLOW</>
	is returned.
d2744 4
a2747 4
	Note that the ecpg implementation differs from the <productname>Informix</productname>
	implementation. <productname>Informix</productname> limits an integer to the range from -32767 to
	32767, while the limits in the ecpg implementation depend on the
	architecture (<literal>-INT_MAX .. INT_MAX</>).
d2760 3
a2762 3
	The function receives a pointer to the decimal value to convert
	(<literal>np</>) and a pointer to the long variable that
	should hold the result of the operation (<literal>lngp</>).
d2765 3
a2767 3
	On success, 0 is returned and a negative value if the conversion
	failed. If an overflow occurred, <literal>ECPG_INFORMIX_NUM_OVERFLOW</>
	is returned.
d2770 5
a2774 5
	Note that the ecpg implementation differs from the <productname>Informix</productname>
	implementation. <productname>Informix</productname> limits a long integer to the range from
	-2,147,483,647 to 2,147,483,647, while the limits in the ecpg
	implementation depend on the architecture (<literal>-LONG_MAX ..
	LONG_MAX</>).
d2787 5
a2791 5
	The function receives two arguments, the first one is the date to
	convert (<literal>d</> and the second one is a pointer to the target
	string. The output format is always <literal>yyyy-mm-dd</>, so you need
	to allocate at least 11 bytes (including the NUL-terminator) for the
	string.
d2794 2
a2795 2
	The function returns 0 on success and a negative value in case of
	error.
d2798 4
a2801 4
	Note that ecpg's implementation differs from the <productname>Informix</productname>
	implementation. In <productname>Informix</productname> the format can be influenced by setting
	environment variables. In ecpg however, you cannot change the output
	format.
d2814 9
a2822 9
	The function receives the textual representation of the date to convert
	(<literal>str</>) and a pointer to a variable of type date
	(<literal>d</>). This function does not allow you to specify a format
	mask. It uses the default format mask of <productname>Informix</productname> which is
	<literal>mm/dd/yyyy</>. Internally, this function is implemented by
	means of <function>rdefmtdate</>. Therefore, <function>rstrdate</> is
	not faster and if you have the choice you should opt for
	<function>rdefmtdate</> which allows you to specify the format mask
	explicitly.
d2838 2
a2839 2
	The function receives a pointer to a date variable (<literal>d</>)
	that it sets to the current date.
d2842 2
a2843 2
	Internally this function uses the <xref linkend="PGTYPESdatetoday">
	function.
d2852 2
a2853 2
	Extract the values for the day, the month and the year from a variable
	of type date.
d2857 5
a2861 5
	The function receives the date <literal>d</> and a pointer to an array
	of 3 short integer values <literal>mdy</>. The variable name indicates
	the sequential order: <literal>mdy[0]</> will be set to contain the
	number of the month, <literal>mdy[1]</> will be set to the value of the
	day and <literal>mdy[2]</> will contain the year.
d2867 2
a2868 2
	Internally the function uses the <xref linkend="PGTYPESdatejulmdy">
	function.
d2877 2
a2878 2
	Use a format mask to convert a character string to a value of type
	date.
d2882 11
a2892 11
	The function receives a pointer to the date value that should hold the
	result of the operation (<literal>d</>), the format mask to use for
	parsing the date (<literal>fmt</>) and the C char* string containing
	the textual representation of the date (<literal>str</>). The textual
	representation is expected to match the format mask. However you do not
	need to have a 1:1 mapping of the string to the format mask. The
	function only analyzes the sequential order and looks for the literals
	<literal>yy</literal> or <literal>yyyy</literal> that indicate the
	position of the year, <literal>mm</literal> to indicate the position of
	the month and <literal>dd</literal> to indicate the position of the
	day.
d2904 3
a2906 3
	   <literal>ECPG_INFORMIX_ENOSHORTDATE</> - The date does not contain
	   delimiters between day, month and year. In this case the input
	   string must be exactly 6 or 8 bytes long but isn't.
d2911 2
a2912 2
	   <literal>ECPG_INFORMIX_ENOTDMY</> - The format string did not
	   correctly indicate the sequential order of year, month and day.
d2917 2
a2918 2
	   <literal>ECPG_INFORMIX_BAD_DAY</> - The input string does not
	   contain a valid day.
d2923 2
a2924 2
	   <literal>ECPG_INFORMIX_BAD_MONTH</> - The input string does not
	   contain a valid month.
d2929 2
a2930 2
	   <literal>ECPG_INFORMIX_BAD_YEAR</> - The input string does not
	   contain a valid year.
d2933 1
a2933 1
	</itemizedlist>
d2936 3
a2938 3
	Internally this function is implemented to use the <xref
	linkend="PGTYPESdatedefmtasc"> function. See the reference there for a
	table of example input.
d2947 2
a2948 2
	Convert a variable of type date to its textual representation using a
	format mask.
d2952 3
a2954 3
	The function receives the date to convert (<literal>d</>), the format
	mask (<literal>fmt</>) and the string that will hold the textual
	representation of the date (<literal>str</>).
d2960 2
a2961 2
	Internally this function uses the <xref linkend="PGTYPESdatefmtasc">
	function, see the reference there for examples.
d2970 2
a2971 2
	Create a date value from an array of 3 short integers that specify the
	day, the month and the year of the date.
d2975 3
a2977 3
	The function receives the array of the 3 short integers
	(<literal>mdy</>) and a pointer to a variable of type date that should
	hold the result of the operation.
d2983 2
a2984 2
	Internally the function is implemented to use the function <xref
	linkend="PGTYPESdatemdyjul">.
d2997 3
a2999 3
	The function receives the date variable <literal>d</> as its only
	argument and returns an integer that indicates the day of the week for
	this date.
d3003 1
a3003 1
	   0 - Sunday
d3008 1
a3008 1
	   1 - Monday
d3013 1
a3013 1
	   2 - Tuesday
d3018 1
a3018 1
	   3 - Wednesday
d3023 1
a3023 1
	   4 - Thursday
d3028 1
a3028 1
	   5 - Friday
d3033 1
a3033 1
	   6 - Saturday
d3039 2
a3040 2
	Internally the function is implemented to use the function <xref
	linkend="PGTYPESdatedayofweek">.
d3053 2
a3054 2
	The function retrieves the current timestamp and saves it into the
	timestamp variable that <literal>ts</> points to.
d3063 2
a3064 2
	Parses a timestamp from its textual representation in ANSI standard
	into a timestamp variable.
d3068 3
a3070 3
	The function receives the string to parse (<literal>str</>) and a
	pointer to the timestamp variable that should hold the result of the
	operation (<literal>ts</>).
d3073 2
a3074 2
	The function returns 0 on success and a negative value in case of
	error.
d3077 3
a3079 3
	Internally this function uses the <xref
	linkend="PGTYPEStimestampfromasc"> function. See the reference there
	for a table with example inputs.
d3088 2
a3089 2
	Parses a timestamp from its textual representation in ANSI standard
	using a format mask into a timestamp variable.
d3093 3
a3095 3
	The function receives the string to parse (<literal>inbuf</>), the
	format mask to use (<literal>fmtstr</>) and a pointer to the timestamp
	variable that should hold the result of the operation (<literal>ts</>).
d3098 3
a3100 3
	This functions is implemented by means of the <xref
	linkend="PGTYPEStimestampdefmtasc">. See the documentation
	there for a list of format specifiers that can be used.
d3103 2
a3104 2
	The function returns 0 on success and a negative value in case of
	error.
d3113 2
a3114 2
	Subtract one timestamp from another and return a variable of type
	interval.
d3118 4
a3121 4
	The function will subtract the timestamp variable that <literal>ts2</>
	points to from the timestamp variable that <literal>ts1</> points to
	and will store the result in the interval variable that <literal>iv</>
	points to.
d3124 2
a3125 2
	Upon success, the function returns 0 and a negative value if an
	error occurred.
d3138 5
a3142 5
	The function receives a pointer to the timestamp variable to convert
	(<literal>ts</>) and the string that should hold the result of the
	operation <literal>output</>). It converts <literal>ts</> to its
	textual representation in the ANSI SQL standard which is defined to
	be <literal>YYYY-MM-DD HH:MM:SS</literal>.
d3145 2
a3146 2
	Upon success, the function returns 0 and a negative value if an
	error occurred.
d3159 5
a3163 5
	The function receives a pointer to the timestamp to convert as its
	first argument (<literal>ts</>), a pointer to the output buffer
	(<literal>output</>), the maximal length that has been allocated for
	the output buffer (<literal>str_len</literal>) and the format mask to
	use for the conversion (<literal>fmtstr</literal>).
d3166 2
a3167 2
	Upon success, the function returns 0 and a negative value if an
	error occurred.
d3170 3
a3172 3
	Internally, this function uses the <xref
	linkend="PGTYPEStimestampfmtasc"> function. See the reference there for
	information on what format mask specifiers can be used.
d3185 5
a3189 5
	The function receives a pointer to the interval variable to convert
	(<literal>i</>) and the string that should hold the result of the
	operation <literal>str</>). It converts <literal>i</> to its
	textual representation in the ANSI SQL standard which is defined to
	be <literal>YYYY-MM-DD HH:MM:SS</literal>.
d3192 2
a3193 2
	Upon success, the function returns 0 and a negative value if an
	error occurred.
d3202 2
a3203 2
	Convert a long integer value to its textual representation using a
	format mask.
d3207 4
a3210 4
	The function receives the long value <literal>lng_val</>, the format
	mask <literal>fmt</> and a pointer to the output buffer
	<literal>outbuf</>. It converts the long value according to the format
	mask to its textual representation.
d3213 2
a3214 2
	The format mask can be composed of the following format specifying
	characters:
d3218 2
a3219 2
	   <literal>*</literal> (asterisk) - if this position would be blank
	   otherwise, fill it with an asterisk.
d3224 2
a3225 2
	   <literal>&amp;</literal> (ampersand) - if this position would be
	   blank otherwise, fill it with a zero.
d3230 1
a3230 1
	   <literal>#</literal> - turn leading zeroes into blanks.
d3235 1
a3235 1
	   <literal>&lt;</literal> - left-justify the number in the string.
d3240 2
a3241 2
	   <literal>,</literal> (comma) - group numbers of four or more digits
	   into groups of three digits separated by a comma.
d3246 2
a3247 2
	   <literal>.</literal> (period) - this character separates the
	   whole-number part of the number from the fractional part.
d3252 2
a3253 2
	   <literal>-</literal> (minus) - the minus sign appears if the number
	   is a negative value.
d3258 2
a3259 2
	   <literal>+</literal> (plus) - the plus sign appears if the number is
	   a positive value.
d3264 2
a3265 2
	   <literal>(</literal> - this replaces the minus sign in front of the
	   negative number. The minus sign will not appear.
d3270 2
a3271 2
	   <literal>)</literal> - this character replaces the minus and is
	   printed behind the negative value.
d3276 1
a3276 1
	   <literal>$</literal> - the currency symbol.
d3279 1
a3279 1
	</itemizedlist>
d3292 2
a3293 2
	The function receives a pointer to the string and transforms every
	lower case character to upper case.
d3302 2
a3303 2
	Return the number of characters in a string without counting trailing
	blanks.
d3307 4
a3310 4
	The function expects a fixed-length string as its first argument
	(<literal>str</>) and its length as its second argument
	(<literal>len</>). It returns the number of significant characters,
	that is the length of the string without trailing blanks.
d3323 7
a3329 7
	The function receives the fixed-length string to copy
	(<literal>src</>), its length (<literal>len</>) and a pointer to the
	destination memory (<literal>dest</>). Note that you need to reserve at
	least <literal>len+1</> bytes for the string that <literal>dest</>
	points to. The function copies at most <literal>len</> bytes to the new
	location (less if the source string has trailing blanks) and adds the
	null-terminator.
d3390 3
a3392 3
	The function receives an integer that indicates the type of the
	variable and a pointer to the variable itself that is casted to a C
	char* pointer.
d3399 1
a3399 1
	   <literal>CCHARTYPE</literal> - For a variable of type <type>char</type> or <type>char*</type>
d3404 1
a3404 1
	   <literal>CSHORTTYPE</literal> - For a variable of type <type>short int</type>
d3409 1
a3409 1
	   <literal>CINTTYPE</literal> - For a variable of type <type>int</type>
d3414 1
a3414 1
	   <literal>CBOOLTYPE</literal> - For a variable of type <type>boolean</type>
d3419 1
a3419 1
	   <literal>CFLOATTYPE</literal> - For a variable of type <type>float</type>
d3424 1
a3424 1
	   <literal>CLONGTYPE</literal> - For a variable of type <type>long</type>
d3429 1
a3429 1
	   <literal>CDOUBLETYPE</literal> - For a variable of type <type>double</type>
d3434 1
a3434 1
	   <literal>CDECIMALTYPE</literal> - For a variable of type <type>decimal</type>
d3439 1
a3439 1
	   <literal>CDATETYPE</literal> - For a variable of type <type>date</type>
d3444 1
a3444 1
	   <literal>CDTIMETYPE</literal> - For a variable of type <type>timestamp</type>
d3473 4
a3476 4
	The function receives the type of the variable to test (<literal>t</>)
	as well a pointer to this variable (<literal>ptr</>). Note that the
	latter needs to be casted to a char*. See the function <xref
	linkend="rsetnull"> for a list of possible variable types.
d3510 3
a3512 3
	Functions return this value if an overflow occurred in a
	calculation. Internally it is defined to -1200 (the <productname>Informix</productname>
	definition).
d3521 2
a3522 2
	Functions return this value if an underflow occurred in a calculation.
	Internally it is defined to -1201 (the <productname>Informix</productname> definition).
d3531 2
a3532 2
	Functions return this value if an attempt to divide by zero is
	observed. Internally it is defined to -1202 (the <productname>Informix</productname> definition).
d3541 3
a3543 3
	Functions return this value if a bad value for a year was found while
	parsing a date. Internally it is defined to -1204 (the <productname>Informix</productname>
	definition).
d3552 3
a3554 3
	Functions return this value if a bad value for a month was found while
	parsing a date. Internally it is defined to -1205 (the <productname>Informix</productname>
	definition).
d3563 3
a3565 3
	Functions return this value if a bad value for a day was found while
	parsing a date. Internally it is defined to -1206 (the <productname>Informix</productname>
	definition).
d3574 3
a3576 3
	Functions return this value if a parsing routine needs a short date
	representation but did not get the date string in the right length.
	Internally it is defined to -1209 (the <productname>Informix</productname> definition).
d3585 2
a3586 2
	Functions return this value if Internally it is defined to -1210 (the
	<productname>Informix</productname> definition).
d3595 2
a3596 2
	Functions return this value if Internally it is defined to -1211 (the
	<productname>Informix</productname> definition).
d3605 3
a3607 3
	Functions return this value if a parsing routine was supposed to get a
	format mask (like <literal>mmddyy</>) but not all fields were listed
	correctly. Internally it is defined to -1212 (the <productname>Informix</productname> definition).
d3616 5
a3620 5
	Functions return this value either if a parsing routine cannot parse
	the textual representation for a numeric value because it contains
	errors or if a routine cannot complete a calculation involving numeric
	variables because at least one of the numeric variables is invalid.
	Internally it is defined to -1213 (the <productname>Informix</productname> definition).
d3629 2
a3630 2
	Functions return this value if Internally it is defined to -1216 (the
	<productname>Informix</productname> definition).
d3639 2
a3640 2
	Functions return this value if Internally it is defined to -1218 (the
	<productname>Informix</productname> definition).
d3649 2
a3650 2
	Functions return this value if Internally it is defined to -1264 (the
	<productname>Informix</productname> definition).
@


1.79
log
@Consistenly use colons before '<programlisting>' blocks, where
appropriate.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.78 2007/01/31 20:56:17 momjian Exp $ -->
d525 1
a525 1
       you can not use pointers as target variables of queries without
d1087 1
a1087 1
       the numeric type, overflow can not occur with this conversion.
d4551 1
a4551 1
    see any name or identifier <literal>MYNUMBER</>. Note that you can not use
@


1.78
log
@Update documentation on may/can/might:

Standard English uses "may", "can", and "might" in different ways:

        may - permission, "You may borrow my rake."

        can - ability, "I can lift that log."

        might - possibility, "It might rain today."

Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice.  Similarly, "It may crash" is better stated, "It might crash".

Also update two error messages mentioned in the documenation to match.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.77 2006/10/23 18:10:31 petere Exp $ -->
d57 1
a57 1
   code always has the form
d349 1
a349 1
   statement, for example
d431 1
a431 1
    This section starts with
d435 1
a435 1
    and ends with
d440 1
a440 1
    such as
d486 1
a486 1
       allocation of a char array as in
d511 1
a511 1
       Note that you could also use
d552 1
a552 1
        declaration like
d556 1
a556 1
         is converted into
d2384 1
a2384 1
   embedded SQL commands.
d2429 1
a2429 1
	synonym for ecpg's <literal>DISCONNECT CURRENT</>.
d3994 1
a3994 1
    program when an error happens.
d4010 1
a4010 1
    desired effect.
d4496 1
a4496 1
    Note that this is <emphasis>not</emphasis> the same as
d4657 1
a4657 1
   calling
d4941 1
a4941 1
    instance, an open cursor statement like
@


1.77
log
@Spellchecking and such
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.76 2006/09/22 15:22:04 tgl Exp $ -->
d62 1
a62 1
   Depending on the particular statement, they may appear at the
d130 1
a130 1
   user name or connection name may be specified in that case.
d163 1
a163 1
   <replaceable>password</replaceable> may be an SQL identifier, an
d697 1
a697 1
   You may not execute statements that retrieve data (e.g.,
d731 1
a731 1
   An <command>EXECUTE</command> command may have an
d3668 1
a3668 1
   dynamic SQL statements, where the nature of the result columns may
d4313 1
a4313 1
       SQL program, so it may point to an internal error.)  (SQLSTATE
d4692 1
a4692 1
   <application>make</application>, it may be convenient to include
d4952 1
a4952 1
    preprocessor of a file <filename>foo.pgc</filename> (details may
@


1.77.2.1
log
@Fix some spelling errors.

Thom Brown
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.77 2006/10/23 18:10:31 petere Exp $ -->
d2394 1
a2394 1
   There are two compatibility modes: INFORMIX, INFORMIX_SE
@


1.77.2.2
log
@Fix incorrect errno definitions in ECPG manual.

ecpgerrno.h hasn't materially changed since PostgreSQL 7.4, so this has
been wrong for a very long time.  Back-patch all the way.

Satoshi Nagayasu
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.77.2.1 2010/05/13 14:16:45 mha Exp $ -->
d4308 1
a4308 1
     <term>-212 (<symbol>ECPG_EMPTY</symbol>)</term>
d4320 1
a4320 1
     <term>-213 (<symbol>ECPG_MISSING_INDICATOR</symbol>)</term>
d4330 1
a4330 1
     <term>-214 (<symbol>ECPG_NO_ARRAY</symbol>)</term>
d4340 1
a4340 1
     <term>-215 (<symbol>ECPG_DATA_NOT_ARRAY</symbol>)</term>
@


1.77.2.3
log
@Fix one more incorrect errno definition in the ECPG manual.

Again, back-patch all the way to 7.4.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.77.2.2 2010/08/11 18:52:43 rhaas Exp $ -->
d4297 1
a4297 1
     <term>-211 (<symbol>ECPG_CONVERT_BOOL</symbol>)</term>
@


1.76
log
@Fix a lot of broken markup.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.75 2006/09/21 09:10:27 meskes Exp $ -->
d475 1
a475 1
    only in ecpg.
d542 1
a542 1
        ecpg contains some special types that help you to interact easily with
d544 1
a544 1
        the varchar, numeric, date, timestamp and interval types.
d838 1
a838 1
       Returns a pointer to a malloced string that contains the string
d1015 1
a1015 1
       to. It retuns 0 on success and -1 if an error occurs, including
d1032 1
a1032 1
       points to. It retuns 0 on success and -1 if an error occurs, including
d1049 1
a1049 1
       <literal>lp</> points to. It retuns 0 on success and -1 if an error
d1067 1
a1067 1
       <literal>dst</> points to. It retuns 0 on success and -1 if an error
d1085 1
a1085 1
       <literal>dst</> points to. It retuns 0 on success and -1 if an error
d1610 1
a1610 1
	specificiers are silently discarded.
d2197 1
a2197 1
     functions that deal with the decimal type in the Informix compatibility
d2378 1
a2378 1
  <title>Informix compatibility mode</title>
d2381 2
a2382 2
   this mode is active, it tries to behave as if it were the Informix
   precompiler for Informix E/SQL. Generally spoken this will allow you to use
d2401 1
a2401 1
   Besides the previously explained syntactic sugar, the Informix compatibility
d2406 1
a2406 1
   Informix compatibility mode is closely connected to the pgtypeslib library
d2408 1
a2408 1
   program and most of the additional functions of the Informix compatibility
d2410 1
a2410 1
   the extent of the compatibility is limited. It does not try to copy Informix
d2413 1
a2413 1
   no drop-in replacement if you are using Informix at the moment. Moreover,
d2543 1
a2543 1
	<literal>ECPG_INFORMIX_BAD_EXPONENT</> if this problem ocurred while
d2744 2
a2745 2
	Note that the ecpg implementation differs from the Informix
	implementation. Informix limits an integer to the range from -32767 to
d2770 2
a2771 2
	Note that the ecpg implementation differs from the Informix
	implementation. Informix limits a long integer to the range from
d2798 2
a2799 2
	Note that ecpg's implementation differs from the Informix
	implementation. In Informix the format can be influenced by setting
d2817 1
a2817 1
	mask. It uses the default format mask of Informix which is
d3170 1
a3170 1
	Internally this function uses the <xref
d3172 1
a3172 1
	informations on what format mask specifiers can be used.
d3399 1
a3399 1
	   <literal>CCHARTYPE</literal> - For a variable of type char or char*
d3404 1
a3404 1
	   <literal>CSHORTTYPE</literal> - For a variable of type short int
d3409 1
a3409 1
	   <literal>CINTTYPE</literal> - For a variable of type int
d3414 1
a3414 1
	   <literal>CBOOLTYPE</literal> - For a variable of type boolean
d3419 1
a3419 1
	   <literal>CFLOATTYPE</literal> - For a variable of type float
d3424 1
a3424 1
	   <literal>CLONGTYPE</literal> - For a variable of type long
d3429 1
a3429 1
	   <literal>CDOUBLETYPE</literal> - For a variable of type double
d3434 1
a3434 1
	   <literal>CDECIMALTYPE</literal> - For a variable of type decimal
d3439 1
a3439 1
	   <literal>CDATETYPE</literal> - For a variable of type date
d3444 1
a3444 1
	   <literal>CDTIMETYPE</literal> - For a variable of type timestamp
d3511 1
a3511 1
	calculation. Internally it is defined to -1200 (the Informix
d3522 1
a3522 1
	Internally it is defined to -1201 (the Informix definition).
d3532 1
a3532 1
	observed. Internally it is defined to -1202 (the Informix definition).
d3542 1
a3542 1
	parsing a date. Internally it is defined to -1204 (the Informix
d3553 1
a3553 1
	parsing a date. Internally it is defined to -1205 (the Informix
d3564 1
a3564 1
	parsing a date. Internally it is defined to -1206 (the Informix
d3576 1
a3576 1
	Internally it is defined to -1209 (the Informix definition).
d3586 1
a3586 1
	Informix definition).
d3596 1
a3596 1
	Informix definition).
d3607 1
a3607 1
	correctly. Internally it is defined to -1212 (the Informix definition).
d3620 1
a3620 1
	Internally it is defined to -1213 (the Informix definition).
d3630 1
a3630 1
	Informix definition).
d3640 1
a3640 1
	Informix definition).
d3650 1
a3650 1
	Informix definition).
@


1.75
log
@Updated several parts in particular variable handling. This is work that was part of SoC.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.74 2006/09/16 00:30:12 momjian Exp $ -->
d1140 1
a1140 1
	 <title>Valid input formats for <function>PGTYPESdate_from_asc</function>.
d1397 1
a1397 1
	 <title>Valid input formats for <function>PGTYPESdate_fmt_asc</function>.
d1487 1
a1487 1
	 <title>Valid input formats for <function>rdefmtdate</function>.
d1615 1
a1615 1
	 <title>Valid input formats for <function>PGTYPEStimestamp_from_asc</function>.
a2274 1
    <variablelist>
a2283 1
    <variablelist>
a2292 1
    <variablelist>
a2301 1
    <variablelist>
a2310 1
    <variablelist>
a2319 1
    <variablelist>
a2328 1
    <variablelist>
a2337 1
    <variablelist>
d2410 2
a2411 2
   the extend of the compatibility is limited. It does not try to copy Informix
   behaviour but it allows you to do more or less the same operations and gives
d2415 1
a2415 1
   <productname>PostgreSQL's<productname> datetime and interval types do not
d2432 1
a2432 1
    EXEC SQL ClOSE DATABASE;
d2437 1
d3448 2
d4617 1
@


1.74
log
@Remove emacs info from footer of SGML files.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.73 2006/03/10 19:10:47 momjian Exp $ -->
d387 5
a391 1
   <firstterm>host variables</firstterm>.
d415 1
a415 3
    anywhere a value expression is expected in an SQL statement.  In
    the SQL environment we call the references to C variables
    <firstterm>host variables</firstterm>.
d442 1
a442 1
int   x;
d445 8
d468 9
d479 74
a552 3
    The special type <type>VARCHAR</type> 
    is converted into a named <type>struct</> for every variable. A
    declaration like
d556 1
a556 1
    is converted into
d560 6
a565 2
    This structure is suitable for interfacing with SQL datums of type
    <type>varchar</type>.
d630 2868
a3497 4
   <para>
    Both of these methods only allow retrieving one row at a time.  If
    you need to process result sets that potentially contain more than
    one row, you need to use a cursor, as shown in the second example.
d3502 29
a3530 1
   <title>Indicators</title>
d3532 9
a3540 16
   <para>
    The examples above do not handle null values.  In fact, the
    retrieval examples will raise an error if they fetch a null value
    from the database.  To be able to pass null values to the database
    or retrieve null values from the database, you need to append a
    second host variable specification to each host variable that
    contains data.  This second host variable is called the
    <firstterm>indicator</firstterm> and contains a flag that tells
    whether the datum is null, in which case the value of the real
    host variable is ignored.  Here is an example that handles the
    retrieval of null values correctly:
<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
VARCHAR val;
int val_ind;
EXEC SQL END DECLARE SECTION:
d3542 10
a3551 1
 ...
d3553 10
a3562 6
EXEC SQL SELECT b INTO :val :val_ind FROM test1;
</programlisting>
    The indicator variable <varname>val_ind</varname> will be zero if
    the value was not null, and it will be negative if the value was
    null.
   </para>
d3564 10
a3573 7
   <para>
    The indicator has another function: if the indicator value is
    positive, it means that the value is not null, but it was
    truncated when it was stored in the host variable.
   </para>
  </sect2>
 </sect1>
d3575 10
a3584 2
 <sect1 id="ecpg-dynamic">
  <title>Dynamic SQL</title>
d3586 9
a3594 9
  <para>
   In many cases, the particular SQL statements that an application
   has to execute are known at the time the application is written.
   In some cases, however, the SQL statements are composed at run time
   or provided by an external source.  In these cases you cannot embed
   the SQL statements directly into the C source code, but there is a
   facility that allows you to call arbitrary SQL statements that you
   provide in a string variable.
  </para>
d3596 9
a3604 7
  <para>
   The simplest way to execute an arbitrary SQL statement is to use
   the command <command>EXECUTE IMMEDIATE</command>.  For example:
<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
const char *stmt = "CREATE TABLE test1 (...);";
EXEC SQL END DECLARE SECTION;
d3606 10
a3615 5
EXEC SQL EXECUTE IMMEDIATE :stmt;
</programlisting>
   You may not execute statements that retrieve data (e.g.,
   <command>SELECT</command>) this way.
  </para>
d3617 12
a3628 12
  <para>
   A more powerful way to execute arbitrary SQL statements is to
   prepare them once and execute the prepared statement as often as
   you like.  It is also possible to prepare a generalized version of
   a statement and then execute specific versions of it by
   substituting parameters.  When preparing the statement, write
   question marks where you want to substitute parameters later.  For
   example:
<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
const char *stmt = "INSERT INTO test1 VALUES(?, ?);";
EXEC SQL END DECLARE SECTION;
d3630 9
a3638 12
EXEC SQL PREPARE mystmt FROM :stmt;
 ...
EXEC SQL EXECUTE mystmt USING 42, 'foobar';
</programlisting>
   If the statement you are executing returns values, then add an
   <literal>INTO</literal> clause:
<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
const char *stmt = "SELECT a, b, c FROM test1 WHERE a &gt; ?";
int v1, v2;
VARCHAR v3;
EXEC SQL END DECLARE SECTION;
d3640 9
a3648 8
EXEC SQL PREPARE mystmt FROM :stmt;
 ...
EXEC SQL EXECUTE mystmt INTO v1, v2, v3 USING 37;
</programlisting>
   An <command>EXECUTE</command> command may have an
   <literal>INTO</literal> clause, a <literal>USING</literal> clause,
   both, or neither.
  </para>
d3650 12
a3661 7
  <para>
   When you don't need the prepared statement anymore, you should
   deallocate it:
<programlisting>
EXEC SQL DEALLOCATE PREPARE <replaceable>name</replaceable>;
</programlisting>
  </para>
d3971 1
a3971 1
      <term><literal>BREAK</literal></term>
d4483 5
a4487 2
 <sect1 id="ecpg-include">
  <title>Including Files</title>
d4489 2
a4490 2
  <para>
   To include an external file into your embedded SQL program, use:
d4494 5
a4498 5
   The embedded SQL preprocessor will look for a file named
   <literal><replaceable>filename</replaceable>.h</literal>,
   preprocess it, and include it in the resulting C output.  Thus,
   embedded SQL statements in the included file are handled correctly.
  </para>
d4500 2
a4501 2
  <para>
   Note that this is <emphasis>not</emphasis> the same as
d4505 117
a4621 5
   because this file would not be subject to SQL command preprocessing.
   Naturally, you can continue to use the C
   <literal>#include</literal> directive to include other header
   files.
  </para>
a4622 1
  <note>
d4624 10
a4633 3
    The include file name is case-sensitive, even though the rest of
    the <literal>EXEC SQL INCLUDE</literal> command follows the normal
    SQL case-sensitivity rules.
d4635 2
a4636 1
  </note>
d4638 2
a4639 2

 <sect1 id="ecpg-process">
@


1.73
log
@Make $PostgreSQL CVS tags consistent for SGML files.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/advanced.sgml,v 1.49 2005/04/09 03:52:43 momjian Exp $ -->
a1857 17

<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->
@


1.72
log
@Removed single quotes from connect to example.
@
text
@d1 1
a1 3
<!--
$PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.71 2005/11/04 23:13:59 petere Exp $
-->
@


1.71
log
@Spellchecking run, final cleanups
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.70 2005/11/04 02:56:30 tgl Exp $
d183 1
a183 1
EXEC SQL CONNECT TO 'unix:postgresql://sql.mydomain.com/mydb' AS myconnection USER john;
@


1.71.2.1
log
@Fix incorrect errno definitions in ECPG manual.

ecpgerrno.h hasn't materially changed since PostgreSQL 7.4, so this has
been wrong for a very long time.  Back-patch all the way.

Satoshi Nagayasu
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.71 2005/11/04 23:13:59 petere Exp $
d1302 1
a1302 1
     <term>-212 (<symbol>ECPG_EMPTY</symbol>)</term>
d1314 1
a1314 1
     <term>-213 (<symbol>ECPG_MISSING_INDICATOR</symbol>)</term>
d1324 1
a1324 1
     <term>-214 (<symbol>ECPG_NO_ARRAY</symbol>)</term>
d1334 1
a1334 1
     <term>-215 (<symbol>ECPG_DATA_NOT_ARRAY</symbol>)</term>
@


1.71.2.2
log
@Fix one more incorrect errno definition in the ECPG manual.

Again, back-patch all the way to 7.4.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.71.2.1 2010/08/11 18:52:52 rhaas Exp $
d1291 1
a1291 1
     <term>-211 (<symbol>ECPG_CONVERT_BOOL</symbol>)</term>
@


1.70
log
@Avoid referring to a specific version of the SQL standard except where
necessary, and be careful to refer to the right version where it is
useful to do so.  This partially reverts an ill-considered search and
replace from a few months ago.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.69 2005/10/13 17:55:18 momjian Exp $
d1612 1
a1612 1
    On Win32, if the <application>ecpg</> libraries and an application are
d1616 1
a1616 1
    multi-threaded/single-threaded, release/debug, and static/dynamic 
@


1.69
log
@Rewording, use the more common multi-threaded/single-threaded.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.68 2005/10/13 17:46:18 momjian Exp $
d1148 2
a1149 2
    provide error codes.  Both are specified in the SQL standard, but
    <literal>SQLCODE</literal> has been marked deprecated in SQL-92
@


1.68
log
@Clarify causes of possible mismatch between Win32 libraries and
applications that use FILE pointers.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.67 2005/09/25 03:12:13 momjian Exp $
d1616 3
a1618 2
    threading/non-threading, release/debug, and static/dynamic flags should 
    be the same for the library and all applications using that library.
@


1.67
log
@Wording cleanup.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.66 2005/09/25 03:06:41 momjian Exp $
d1615 3
a1617 1
    <literal>FILE</> pointers differ.
@


1.66
log
@Document why PQtrace and ecpg debug() can crash the application if the
DLL compiles to not match the application.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.65 2005/07/14 06:17:35 neilc Exp $
d1612 4
a1615 3
    On Win32, if the <application>ecpg</> libraries and application are compiled with
    different flags, this function call will crash the application because the
    internal representation of the <literal>FILE</> pointers differ.
@


1.65
log
@This doc patch replaces all inappropriate references to SQL:1999 when it
is used as if it were the latest (and/or still valid) SQL standard.
SQL:2003 is used in its place. Patch from Simon Riggs.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.64 2005/05/20 12:36:48 neilc Exp $
d1610 7
@


1.64
log
@Fix typo in ECPG docs, per Andreas Seltenreich.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.63 2005/01/22 22:56:35 momjian Exp $
d1149 2
a1150 2
    <literal>SQLCODE</literal> has been marked deprecated in the 1992
    edition of the standard and has been dropped in the 1999 edition.
@


1.63
log
@More < and > cleanups converted to ampersands.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.62 2005/01/08 22:13:25 tgl Exp $
d449 1
a449 1
    The declarations are also echoed to the output file as a normal C
@


1.62
log
@Some more small improvements in response to 7.4 interactive docs comments.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.61 2005/01/07 05:43:28 momjian Exp $
d630 1
a630 1
const char *stmt = "SELECT a, b, c FROM test1 WHERE a > ?";
@


1.62.4.1
log
@More < and > cleanups converted to ampersands.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.62 2005/01/08 22:13:25 tgl Exp $
d630 1
a630 1
const char *stmt = "SELECT a, b, c FROM test1 WHERE a &gt; ?";
@


1.62.4.2
log
@Fix typo in ECPG docs, per Andreas Seltenreich.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.62.4.1 2005/01/22 23:05:47 momjian Exp $
d449 1
a449 1
    The declarations are also echoed to the output file as normal C
@


1.62.4.3
log
@Fix incorrect errno definitions in ECPG manual.

ecpgerrno.h hasn't materially changed since PostgreSQL 7.4, so this has
been wrong for a very long time.  Back-patch all the way.

Satoshi Nagayasu
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.62.4.2 2005/05/20 12:37:51 neilc Exp $
d1302 1
a1302 1
     <term>-212 (<symbol>ECPG_EMPTY</symbol>)</term>
d1314 1
a1314 1
     <term>-213 (<symbol>ECPG_MISSING_INDICATOR</symbol>)</term>
d1324 1
a1324 1
     <term>-214 (<symbol>ECPG_NO_ARRAY</symbol>)</term>
d1334 1
a1334 1
     <term>-215 (<symbol>ECPG_DATA_NOT_ARRAY</symbol>)</term>
@


1.62.4.4
log
@Fix one more incorrect errno definition in the ECPG manual.

Again, back-patch all the way to 7.4.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.62.4.3 2010/08/11 18:52:58 rhaas Exp $
d1291 1
a1291 1
     <term>-211 (<symbol>ECPG_CONVERT_BOOL</symbol>)</term>
@


1.61
log
@Fix ECPGstatus() documentation of  parameters.

Edmund Bacon
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.60 2004/12/28 22:47:15 tgl Exp $
d1109 2
a1110 1
    programmer).
@


1.60
log
@More minor updates and copy-editing.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.59 2003/12/26 20:00:00 meskes Exp $
d1613 5
a1617 2
     <function>ECPGstatus()</function> returns true if you
     are connected to a database and false if not.
@


1.59
log
@Fixed docs to clearly note that ecpg is originally a C precompiler and C++ stuff is not 100%.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ecpg.sgml,v 1.58 2003/12/16 01:06:39 momjian Exp $
d22 1
a22 1
  Admittedly, this documentation is quite incomplete.  But since this
d34 1
a34 1
   is first passed to the embedded SQL preprocessor, which converts it
d36 1
a36 1
   compilation tool chain.
d56 1
a56 1
   As indicated, programs written for the embedded
d64 2
a65 2
   Depending on the particular statement, they may appear in the
   global context or within a function.  Embedded
d329 3
a331 3
   interface also supports autocommit of transactions (as known from
   other interfaces) via the <option>-t</option> command-line option
   to <command>ecpg</command> (see below) or via the <literal>EXEC SQL
d451 1
a451 1
    that are not intended to be used with SQL commands can be declared
d556 1
a556 1
    whether the datums is null, in which case the value of the real
d1046 1
a1046 1
    For a more powerful error handling, the embedded SQL interface
d1067 1
a1067 1
    own copy of <varname>sqlca</varname>.  This works similar to the
d1135 1
a1135 1
    systems.  The definitions are similar in the core, but if you want
d1542 1
a1542 1
   The generated C source files include headers files from the
d1578 3
a1580 3
   <application>ecpg</application> is thread-safe if it is compiled using
   the <option>--enable-thread-safety</> <filename>configure</filename>
   command-line option.  (You might need to use other threading
d1624 1
a1624 1
   This section explain how <application>ECPG</application> works
@


1.58
log
@Mention ecpg SET CONNECTION is not thread-aware.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ecpg.sgml,v 1.57 2003/12/01 22:36:40 momjian Exp $
d14 1
a14 2
  for <productname>PostgreSQL</productname>. It works with
  <acronym>C</acronym> and <acronym>C++</acronym>. It was written by
d16 3
a18 1
  (<email>meskes@@postgresql.org</email>).
@


1.57
log
@Hi, this doco patch is a quick one to add explicit mention of the need
for the AT clause in threaded ECPG applications.

Philip Yarra
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ecpg.sgml,v 1.56 2003/11/29 19:51:36 pgsql Exp $
d372 1
a372 1
   executed on the same connection.
@


1.56
log
@
$Header: -> $PostgreSQL Changes ...
@
text
@d2 1
a2 1
$PostgreSQL: /cvsroot/pgsql-server/doc/src/sgml/ecpg.sgml,v 1.55 2003/11/24 19:08:02 petere Exp $
d356 7
@


1.55
log
@Upgrade to DocBook V4.2 SGML.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ecpg.sgml,v 1.54 2003/11/12 22:47:47 petere Exp $
@


1.54
log
@Documentation cleanup
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ecpg.sgml,v 1.53 2003/10/17 18:57:00 tgl Exp $
d671 1
a671 1
   descriptor area.  <comment>The scope of the allocated descriptor is WHAT?.</comment>
@


1.53
log
@Add a listing of our SQLSTATE error codes to the documentation.
Link to it from some appropriate places.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ecpg.sgml,v 1.52 2003/09/20 20:12:04 tgl Exp $
d287 1
a287 1
   Single-row Select:
d362 1
a362 1
SET CONNECTION <replaceable>connection-name</replaceable>;
d395 1
a395 1
INSERT INTO sometable VALUES (:v1, 'foo', :v2);
d595 1
a595 1
EXECUTE IMMEDIATE :stmt;
d614 1
a614 1
PREPARE mystmt FROM :stmt;
d616 1
a616 1
EXECUTE mystmt USING 42, 'foobar';
d627 1
a627 1
PREPARE mystmt FROM :stmt;
d629 1
a629 1
EXECUTE mystmt INTO v1, v2, v3 USING 37;
d671 1
a671 1
   descriptor area.  The scope of the allocated descriptor is WHAT?.
@


1.53.2.1
log
@Documentation cleanup
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ecpg.sgml,v 1.53 2003/10/17 18:57:00 tgl Exp $
d287 1
a287 1
   Single-row select:
d362 1
a362 1
EXEC SQL SET CONNECTION <replaceable>connection-name</replaceable>;
d395 1
a395 1
EXEC SQL INSERT INTO sometable VALUES (:v1, 'foo', :v2);
d595 1
a595 1
EXEC SQL EXECUTE IMMEDIATE :stmt;
d614 1
a614 1
EXEC SQL PREPARE mystmt FROM :stmt;
d616 1
a616 1
EXEC SQL EXECUTE mystmt USING 42, 'foobar';
d627 1
a627 1
EXEC SQL PREPARE mystmt FROM :stmt;
d629 1
a629 1
EXEC SQL EXECUTE mystmt INTO v1, v2, v3 USING 37;
d671 1
a671 1
   descriptor area.  <comment>The scope of the allocated descriptor is WHAT?.</comment>
@


1.53.2.2
log
@Mention ecpg SET CONNECTION is not thread-aware.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ecpg.sgml,v 1.53.2.1 2003/11/12 20:05:14 petere Exp $
d365 1
a365 1
   executed on the same connection.  It is not thread-aware.
@


1.53.2.3
log
@Fix incorrect errno definitions in ECPG manual.

ecpgerrno.h hasn't materially changed since PostgreSQL 7.4, so this has
been wrong for a very long time.  Back-patch all the way.

Satoshi Nagayasu
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.53.2.2 2003/12/16 01:06:51 momjian Exp $
d1293 1
a1293 1
     <term>-212 (<symbol>ECPG_EMPTY</symbol>)</term>
d1305 1
a1305 1
     <term>-213 (<symbol>ECPG_MISSING_INDICATOR</symbol>)</term>
d1315 1
a1315 1
     <term>-214 (<symbol>ECPG_NO_ARRAY</symbol>)</term>
d1325 1
a1325 1
     <term>-215 (<symbol>ECPG_DATA_NOT_ARRAY</symbol>)</term>
@


1.53.2.4
log
@Fix one more incorrect errno definition in the ECPG manual.

Again, back-patch all the way to 7.4.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.53.2.3 2010/08/11 18:53:04 rhaas Exp $
d1282 1
a1282 1
     <term>-211 (<symbol>ECPG_CONVERT_BOOL</symbol>)</term>
@


1.52
log
@Fix a batch of speling misteaks identified by Peter's spell-checker tool.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ecpg.sgml,v 1.51 2003/09/11 21:42:19 momjian Exp $
d1154 2
a1155 3
    <literal>00000</literal>.  Further information about the codes can
    be found XXX.  The <literal>SQLSTATE</literal> codes are for the
    most part defined in the SQL standard.  The
d1159 2
a1160 1
    throughout all applications.
d1181 2
a1182 1
    <literal>SQLSTATE</literal> listing in XXX in each case.
@


1.51
log
@This patch fixes a few missed GUC variables that were still upper case,
makes a few more small improvements to runtime.sgml, and makes some SGML
conventions more consistent.

Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ecpg.sgml,v 1.50 2003/09/09 10:54:44 meskes Exp $
d995 1
a995 1
    So neither of the two following C program exerpts will have the
d1075 1
a1075 1
    <literal>"00000"</literal>.  If a warning or error occured, then
@


1.50
log
@Fixed a few bugs that came up on pgsql-interfaces.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ecpg.sgml,v 1.49 2003/08/31 17:32:18 petere Exp $
d1156 5
a1160 4
    most part defined in the SQL standard.  The PostgreSQL server
    natively supports <literal>SQLSTATE</literal> error codes;
    therefore a high degree of consistency can be achieved by using
    this error code scheme throughout all applications.
d1172 5
a1176 5
    processor for PostgreSQL has assigned some specific
    <literal>SQLCODE</literal> values for its use, which are listed
    below with their numeric value and their symbolic name.  Remember
    that these are not portable to other SQL implementations.  To
    simplify the porting of applications to the
d1295 4
a1298 3
       The statement sent to the PostgreSQL server was empty.  (This
       cannot normally happen in an embedded SQL program, so it may
       point to an internal error.)  (SQLSTATE YE002)
@


1.49
log
@Add/edit index entries.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ecpg.sgml,v 1.48 2003/08/07 04:17:21 momjian Exp $
d299 1
d454 2
a455 2
    The special types <type>VARCHAR</type> and <type>VARCHAR2</type>
    are converted into a named <type>struct</> for every variable. A
d1791 2
a1792 2
    <command>DECLARE</> command is used because it opens the cursor as
    well.
@


1.48
log
@Noticed broken markup in ecpg.sgml. Attached patch fixes it. Please
apply.

Joe Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ecpg.sgml,v 1.47 2003/08/01 13:53:36 petere Exp $
d9 2
@


1.48.2.1
log
@Update this branch to match CVS head, includes WIN32 improvements.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ecpg.sgml,v 1.49 2003/08/31 17:32:18 petere Exp $
a8 2
 <indexterm zone="ecpg"><primary>C</primary></indexterm>
 <indexterm zone="ecpg"><primary>ECPG</primary></indexterm>
@


1.47
log
@Make ecpg SQLSTATE-aware.  Map existing SQLCODE assignments to SQLSTATEs,
rather than parsing the message.  Add some documentation about embedded
SQL.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ecpg.sgml,v 1.46 2003/08/01 03:10:04 momjian Exp $
d706 1
a706 1
     <term><literal>CARDINALITY</literal> (integer)<term>
d715 1
a715 1
     <term><literal>DATA</literal><term>
d725 1
a725 1
     <term><literal>DATETIME_INTERVAL_CODE</literal> (integer)<term>
d734 1
a734 1
     <term><literal>DATETIME_INTERVAL_PRECISION</literal> (integer)<term>
d743 1
a743 1
     <term><literal>INDICATOR</literal> (integer)<term>
d752 1
a752 1
     <term><literal>KEY_MEMBER</literal> (integer)<term>
d761 1
a761 1
     <term><literal>LENGTH</literal> (integer)<term>
d770 1
a770 1
     <term><literal>NAME</literal> (string)<term>
d779 1
a779 1
     <term><literal>NULLABLE</literal> (integer)<term>
d788 1
a788 1
     <term><literal>OCTET_LENGTH</literal> (integer)<term>
d797 1
a797 1
     <term><literal>PRECISION</literal> (integer)<term>
d806 1
a806 1
     <term><literal>RETURNED_LENGTH</literal> (integer)<term>
d815 1
a815 1
     <term><literal>RETURNED_OCTET_LENGTH</literal> (integer)<term>
d824 1
a824 1
     <term><literal>SCALE</literal> (integer)<term>
d833 1
a833 1
     <term><literal>TYPE</literal> (integer)<term>
@


1.46
log
@--enable-thread-safeness -> --enable-thread-safety
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ecpg.sgml,v 1.45 2003/07/23 17:27:28 momjian Exp $
d40 10
a49 9
   variables in your <acronym>C</acronym> program.  Secondly, embedded
   <acronym>SQL</acronym> in C is defined in the
   <acronym>SQL</acronym> standard and supported by many other
   <acronym>SQL</acronym> databases.  The <productname>PostgreSQL</>
   implementation is designed to match this standard as much as
   possible, and it is usually possible to port embedded
   <acronym>SQL</acronym> programs written for other
   SQL databases to <productname>PostgreSQL</productname>
   with relative ease.
d104 1
a104 1
      <literal><replaceable>character variable</replaceable></literal>
d110 1
a110 1
      <literal><replaceable>character string</replaceable></literal>
d120 10
d160 4
a163 3
   The <replaceable>username</replaceable> and
   <replaceable>password</replaceable> may be an SQL name, a
   character variable, or a character string.
d169 32
a200 1
   program uses only one connection.
d240 8
d285 1
a285 1
   Singleton Select:
d292 1
a292 1
   Select using Cursors:
d318 2
a319 2
   variables in the C program.  They are explained in the next
   section.
d335 31
d367 1
a367 1
  <title>Passing Data</title>
d370 9
a378 5
   To pass data from the program to the database, for example as
   parameters in a query, or to pass data from the database back to
   the program, the C variables that are intended to contain this data
   need to be declared in a specially marked section, so the embedded
   SQL preprocessor is made aware of them.
d381 40
a420 2
  <para>
   This section starts with
d424 1
a424 1
   and ends with
d428 2
a429 1
   Between those lines, there must be normal C variable declarations, such as
d434 148
d585 11
a595 4
   The declarations are also echoed to the output file as a normal C
   variables, so there's no need to declare them again.  Variables
   that are not intended to be used with SQL commands can be declared
   normally outside these special sections.
d599 32
a630 3
   The definition of a structure or union also must be listed inside a
   <literal>DECLARE</> section. Otherwise the preprocessor cannot
   handle these types since it does not know the definition.
d634 2
a635 3
   The special types <type>VARCHAR</type> and <type>VARCHAR2</type>
   are converted into a named <type>struct</> for every variable. A
   declaration like
d637 29
a665 1
VARCHAR var[180];
d667 4
a670 1
   is converted into
d672 1
a672 1
struct varchar_var { int len; char arr[180]; } var;
a673 2
   This structure is suitable for interfacing with SQL datums of type
   <type>varchar</type>.
d677 164
a840 3
   To use a properly declared C variable in an SQL statement, write
   <literal>:<replaceable>varname</></literal> where an expression is
   expected.  See the previous section for some examples.
d848 12
a859 4
   The embedded SQL interface provides a simplistic and a complex way
   to handle exceptional conditions in a program.  The first method
   causes a message to printed automatically when a certain condition
   occurs.  For example:
d861 1
a861 1
EXEC SQL WHENEVER sqlerror sqlprint;
d863 115
a977 1
   or
d979 2
a980 1
EXEC SQL WHENEVER not found sqlprint;
d982 1
a982 2
   This error handling remains enabled throughout the entire program.
  </para>
a983 1
  <note>
d985 43
a1027 4
    This is <emphasis>not</emphasis> an exhaustive example of usage
    for the <command>EXEC SQL WHENEVER</command> statement.  Further
    examples of usage may be found in SQL manuals (e.g.,
    <citetitle>The LAN TIMES Guide to SQL</> by Groff and Weinberg).
d1029 4
a1032 1
  </note>
d1034 4
a1037 4
  <para>
   For a more powerful error handling, the embedded SQL interface
   provides a <type>struct</> and a variable with the name
   <varname>sqlca</varname> as follows:
d1039 1
a1039 1
struct sqlca
a1049 1

a1050 8
    /* 0: empty                                         */
    /* 1: OID of processed row if applicable            */
    /* 2: number of rows processed in an INSERT, UPDATE */
    /*    or DELETE statement                           */
    /* 3: empty                                         */
    /* 4: empty                                         */
    /* 5: empty                                         */

d1052 1
a1052 12
    /* 0: set to 'W' if at least one other is 'W'       */
    /* 1: if 'W' at least one character string          */
    /*    value was truncated when it was               */
    /*    stored into a host variable                   */
    /* 2: empty                                         */
    /* 3: empty                                         */
    /* 4: empty                                         */
    /* 5: empty                                         */
    /* 6: empty                                         */
    /* 7: empty                                         */

    char sqlext[8];
d1055 87
a1141 2
   (Many of the empty fields may be used in a future release.)
  </para>
d1143 15
a1157 8
  <para>
   If no error occurred in the last <acronym>SQL</acronym> statement,
   <literal>sqlca.sqlcode</literal> will be 0
   (<symbol>ECPG_NO_ERROR</>). If <literal>sqlca.sqlcode</literal> is
   less than zero, this is a serious error, like the database
   definition does not match the query. If it is greater than zero, it
   is a normal error like the table did not contain the requested row.
  </para>
d1159 20
a1178 5
  <para>
   <literal>sqlca.sqlerrm.sqlerrmc</literal> will contain a string
   that describes the error. The string ends with the line number in
   the source file.
  </para>
d1180 2
a1181 2
  <para>
   These are the errors that can occur:
d1183 7
a1189 7
   <variablelist>
    <varlistentry>
     <term><computeroutput>-12: Out of memory in line %d.</computeroutput></term>
     <listitem>
      <para>
       Should not normally occur. This indicates your virtual memory
       is exhausted.
d1195 1
a1195 1
     <term><computeroutput>-200 (ECPG_UNSUPPORTED): Unsupported type %s on line %d.</computeroutput></term>
d1198 4
a1201 4
       Should not normally occur. This indicates the preprocessor has
       generated something that the library does not know about.
       Perhaps you are running incompatible versions of the
       preprocessor and the library.
d1207 1
a1207 1
     <term><computeroutput>-201 (ECPG_TOO_MANY_ARGUMENTS): Too many arguments line %d.</computeroutput></term>
d1210 2
a1211 4
       This means that the server has returned more arguments than we
       have matching variables.  Perhaps you have forgotten a couple
       of the host variables in the <command>INTO
       :var1, :var2</command> list.
d1217 1
a1217 1
     <term><computeroutput>-202 (ECPG_TOO_FEW_ARGUMENTS): Too few arguments line %d.</computeroutput></term>
d1220 3
a1222 3
       This means that the server has returned fewer arguments than we
       have host variables. Perhaps you have too many host variables
       in the <command>INTO :var1,:var2</command> list.  </para>
d1227 1
a1227 1
     <term><computeroutput>-203 (ECPG_TOO_MANY_MATCHES): Too many matches line %d.</computeroutput></term>
d1230 3
a1232 3
       This means the query has returned multiple rows but the
       variables specified are not arrays. The
       <command>SELECT</command> command was not unique.
d1238 1
a1238 1
     <term><computeroutput>-204 (ECPG_INT_FORMAT): Not correctly formatted int type: %s line %d.</computeroutput></term>
d1241 5
a1245 5
       This means the host variable is of type <type>int</type> and
       the field in the <productname>PostgreSQL</productname> database
       is of another type and contains a value that cannot be
       interpreted as an <type>int</type>. The library uses
       <function>strtol()</function> for this conversion.
d1251 1
a1251 1
     <term><computeroutput>-205 (ECPG_UINT_FORMAT): Not correctly formatted unsigned type: %s line %d.</computeroutput></term>
d1254 5
a1258 6
       This means the host variable is of type <type>unsigned
       int</type> and the field in the
       <productname>PostgreSQL</productname> database is of another
       type and contains a value that cannot be interpreted as an
       <type>unsigned int</type>. The library uses
       <function>strtoul()</function> for this conversion.
d1264 1
a1264 1
     <term><computeroutput>-206 (ECPG_FLOAT_FORMAT): Not correctly formatted floating-point type: %s line %d.</computeroutput></term>
d1267 5
a1271 5
       This means the host variable is of type <type>float</type> and
       the field in the <productname>PostgreSQL</productname> database
       is of another type and contains a value that cannot be
       interpreted as a <type>float</type>. The library uses
       <function>strtod()</function> for this conversion.
d1277 1
a1277 1
     <term><computeroutput>-207 (ECPG_CONVERT_BOOL): Unable to convert %s to bool on line %d.</computeroutput></term>
d1281 2
a1282 2
       the field in the <productname>PostgreSQL</productname> database
       is neither <literal>'t'</> nor <literal>'f'</>.
d1288 1
a1288 1
     <term><computeroutput>-208 (ECPG_EMPTY): Empty query line %d.</computeroutput></term>
d1291 3
a1293 2
       The query was empty.  (This cannot normally happen in an
       embedded SQL program, so it may point to an internal error.)
d1299 1
a1299 1
     <term><computeroutput>-209 (ECPG_MISSING_INDICATOR): NULL value without indicator in line %d.</computeroutput></term>
d1303 1
a1303 1
       supplied.
d1309 1
a1309 1
     <term><computeroutput>-210 (ECPG_NO_ARRAY): Variable is not an array in line %d.</computeroutput></term>
d1313 1
a1313 1
       array.
d1319 1
a1319 1
     <term><computeroutput>-211 (ECPG_DATA_NOT_ARRAY): Data read from backend is not an array in line %d.</computeroutput></term>
d1323 1
a1323 1
       requires array value.
d1329 1
a1329 1
     <term><computeroutput>-220 (ECPG_NO_CONN): No such connection %s in line %d.</computeroutput></term>
d1333 1
d1339 1
a1339 1
     <term><computeroutput>-221 (ECPG_NOT_CONN): Not connected in line %d.</computeroutput></term>
d1343 1
a1343 1
       not open.
d1349 1
a1349 1
     <term><computeroutput>-230 (ECPG_INVALID_STMT): Invalid statement name %s in line %d.</computeroutput></term>
d1353 1
d1359 1
a1359 1
     <term><computeroutput>-240 (ECPG_UNKNOWN_DESCRIPTOR): Descriptor %s not found in line %d.</computeroutput></term>
d1362 2
a1363 2
       The descriptor specified was not found. The statement you are
       trying to use has not been prepared.
d1369 1
a1369 1
     <term><computeroutput>-241 (ECPG_INVALID_DESCRIPTOR_INDEX): Descriptor index out of range in line %d.</computeroutput></term>
d1372 2
a1373 1
       The descriptor index specified was out of range.
d1379 1
a1379 1
     <term><computeroutput>-242 (ECPG_UNKNOWN_DESCRIPTOR_ITEM): Unknown descriptor item %s in line %d.</computeroutput></term>
d1382 2
a1383 1
       The descriptor specified was not found. The statement you are trying to use has not been prepared.
d1389 1
a1389 1
     <term><computeroutput>-243 (ECPG_VAR_NOT_NUMERIC): Variable is not a numeric type in line %d.</computeroutput></term>
d1392 3
a1394 2
       The database returned a numeric value and the variable was not
       numeric.
d1400 1
a1400 1
     <term><computeroutput>-244 (ECPG_VAR_NOT_CHAR): Variable is not a character type in line %d.</computeroutput></term>
d1403 3
a1405 2
       The database returned a non-numeric value and the variable was
       numeric.
d1411 1
a1411 1
     <term><computeroutput>-400 (ECPG_PGSQL): '%s' in line %d.</computeroutput></term>
d1414 2
a1415 2
       Some <productname>PostgreSQL</productname> error. The message
       contains the error message from the
d1422 1
a1422 1
     <term><computeroutput>-401 (ECPG_TRANS): Error in transaction processing line %d.</computeroutput></term>
d1425 3
a1427 2
       The <productname>PostgreSQL</productname> server signaled that we cannot
       start, commit, or rollback the transaction.
d1433 1
a1433 1
     <term><computeroutput>-402 (ECPG_CONNECT): Could not connect to database %s in line %d.</computeroutput></term>
d1436 2
a1437 1
       The connection attempt to the database did not work.
d1443 1
a1443 1
     <term><computeroutput>100 (ECPG_NOT_FOUND): Data not found line %d.</computeroutput></term>
d1446 3
a1448 3
       This is a <quote>normal</quote> error that tells you that what
       you are querying cannot be found or you are at the end of the
       cursor.
d1454 1
a1507 7
   <application>ecpg</application> is thread-safe if it is compiled using
   the <literal>--enable-thread-safety</> <filename>configure</filename>
   command-line option.  (You might need to use other threading
   command-line options to compile your client code.)
  </para>

  <para>
d1561 7
@


1.45
log
@Rename --with-threads to --enable-thread-safeness, per Peter.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ecpg.sgml,v 1.44 2003/06/15 04:07:58 momjian Exp $
d754 1
a754 1
   the <literal>--enable-thread-safeness</> <filename>configure</filename>
@


1.44
log
@Make ecpg thread safe.

Lee Kindness
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ecpg.sgml,v 1.43 2003/03/25 16:15:35 petere Exp $
d754 1
a754 1
   the <literal>--with-threads</> <filename>configure</filename>
@


1.43
log
@Merge documentation into one book.  (Build with "make html".)  Replace
vague cross-references with real links.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ecpg.sgml,v 1.42 2003/03/13 01:30:28 petere Exp $
d750 7
@


1.42
log
@Big editing for consistent content and presentation.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ecpg.sgml,v 1.41 2003/01/19 00:13:28 momjian Exp $
d805 1
a805 1
   detailed in the &cite-reference;.
@


1.41
log
@This patch includes a lot of minor cleanups to the SGML documentation,
including:

- replacing all the appropriate usages of <citetitle>PostgreSQL
...</citetitle> with &cite-user;, &cite-admin;, and so on

- fix an omission in the EXECUTE documentation

- add some more text to the EXPLAIN documentation

- improve the PL/PgSQL RETURN NEXT documentation (more work to do here)

- minor markup fixes


Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ecpg.sgml,v 1.40 2002/11/15 03:11:16 momjian Exp $
d47 1
a47 1
   <acronym>RDBMS</acronym> to <productname>PostgreSQL</productname>
d127 1
a127 1
      <literal><replaceable>userid</replaceable></literal>
d133 1
a133 1
      <literal><replaceable>userid</replaceable>/<replaceable>password</replaceable></literal>
d139 1
a139 1
      <literal><replaceable>userid</replaceable> IDENTIFIED BY <replaceable>password</replaceable></literal>
d145 1
a145 1
      <literal><replaceable>userid</replaceable> USING <replaceable>password</replaceable></literal>
d149 2
a150 2
   The <replaceable>userid</replaceable> and
   <replaceable>password</replaceable> may be a constant text, a
d167 1
a167 1
EXEC SQL DISCONNECT [<replaceable>connection</replaceable>];
d278 1
a278 1
   query is automatically committed unless it is inside an explicit
d327 1
a327 1
   declaration like:
d331 1
a331 1
   is converted into:
d336 1
a336 1
   <type>VARCHAR</type>.
d392 1
a392 1
    /* 1: OID of processed tuple if applicable          */
d403 1
a403 1
    /*    stored into a host variable.                  */
d421 1
a421 1
   less that zero, this is a serious error, like the database
d437 1
a437 1
     <term><computeroutput>-12, Out of memory in line %d.</computeroutput></term>
d465 1
a465 1
       :var1,:var2</command> list.
d484 1
a484 1
       This means the query has returned several rows but the
d630 1
a630 1
     <term><computeroutput>-242 (ECPG_UNKNOWN_DESCRIPTOR_ITEM): Descriptor %s not found in line %d.</computeroutput></term>
d659 1
a659 1
     <term><computeroutput>-400 (ECPG_PGSQL): Postgres error: %s line %d.</computeroutput></term>
d664 1
a664 1
       <productname>PostgreSQL</productname> backend.
d673 1
a673 1
       <productname>PostgreSQL</productname> signaled that we cannot
d683 1
a683 1
       The connect to the database did not work.
d721 1
a721 1
   because the file would not be subject to SQL command preprocessing.
d747 1
a747 1
   from the arguments, perform the <acronym>SQL</acronym> query using
d769 1
a769 1
   The preprocessed file can be compiled normally, for example
d826 6
a831 11
     is done on <replaceable>stream</replaceable>. Most
     <acronym>SQL</acronym> statement log their arguments and results.
    </para>

    <para>
     The most important function, <function>ECPGdo</function>, logs
     all <acronym>SQL</acronym> statements with both the expanded
     string, i.e. the string with all the input variables inserted,
     and the result from the <productname>PostgreSQL</productname>
     server. This can be very useful when searching for errors in your
     <acronym>SQL</acronym> statements.
d837 1
a837 1
     <function>ECPGstatus()</function> This method returns true if we
a843 42
 <sect1 id="ecpg-porting">
  <title>Porting From Other <acronym>RDBMS</acronym> Packages</title>

  <para>
   The design of <application>ecpg</application> follows the SQL
   standard. Porting from a standard RDBMS should not be a problem.
   Unfortunately there is no such thing as a standard RDBMS. Therefore
   <application>ecpg</application> tries to understand syntax
   extensions as long as they do not create conflicts with the
   standard.
  </para>

  <para>
   The following list shows all the known incompatibilities. If you
   find one not listed please notify the developers. Note, however,
   that we list only incompatibilities from a preprocessor of another
   RDBMS to <application>ecpg</application> and not
   <application>ecpg</application> features that these RDBMS do not
   support.
  </para>

  <variablelist>
   <varlistentry>
    <term>Syntax of <command>FETCH</command></term>
    <indexterm><primary>FETCH</><secondary>embedded SQL</></indexterm>

    <listitem>
     <para>
      The standard syntax for <command>FETCH</command> is:
<synopsis>
FETCH <optional><replaceable>direction</></> <optional><replaceable>amount</></> IN|FROM <replaceable>cursor</replaceable>
</synopsis>
      <indexterm><primary>Oracle</></>
      <productname>Oracle</productname>, however, does not use the
      keywords <literal>IN</literal> or <literal>FROM</literal>. This
      feature cannot be added since it would create parsing conflicts.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </sect1>

d845 1
a845 1
  <title>For the Developer</title>
d848 1
a848 1
   This section explain how <application>ecpg</application> works
d850 1
a850 1
   users understand how to use <application>ecpg</application>.
a852 3
  <sect2>
   <title>The Preprocessor</title>

d863 2
a864 2
    intervenes and changes it. The command starts with <command>exec
    sql</command> and ends with <command>;</command>. Everything in
d873 76
a948 3
    <literal>EXEC SQL DECLARE</> section. Depending on whether the
    variable is being use for input or output, a pointer to the
    variable is output to allow access by the function.
d953 1
a953 1
    query, the function gets other arguments:
d955 1
a955 1
    <itemizedlist>
d994 1
a994 2
       A pointer to the value of the indicator variable or a pointer
       to the pointer of the indicator variable.
d1006 1
a1006 1
       Number of elements in the indicator array (for array fetches).
d1016 1
a1016 1
    </itemizedlist>
d1064 1
a1064 1
    (The indentation in this manual is added for readability and not
a1066 83
  </sect2>

  <sect2>
   <title>The Library</title>

   <para>
    The most important function in the library is
    <function>ECPGdo</function>. It takes a variable number of
    arguments. Hopefully there are no computers that limit the number
    of variables that can be accepted by a
    <function>varargs()</function> function. This can easily add up to
    50 or so arguments.
   </para>

   <para>
    The arguments are:

    <variablelist>
     <varlistentry>
      <term>A line number</term>
      <listitem>
       <para>
        This is a line number of the original line; used in error
        messages only.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>A string</term>
      <listitem>
       <para>
        This is the <acronym>SQL</acronym> query that is to be issued.
        It is modified by the input variables, i.e. the variables that
        where not known at compile time but are to be entered in the
        query. Where the variables should go the string contains
        <literal>?</literal>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Input variables</term>
      <listitem>
       <para>
        As described in the section about the preprocessor, every
        input variable gets ten arguments.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><parameter>ECPGt_EOIT</></term>
      <listitem>
       <para>
        An <type>enum</> telling that there are no more input
        variables.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Output variables</term>
      <listitem>
       <para>
        As described in the section about the preprocessor, every
        input variable gets ten arguments. These variables are filled
        by the function.
       </para>
      </listitem>
     </varlistentry>

      <varlistentry>
       <term><parameter>ECPGt_EORT</></term>
       <listitem>
       <para>
        An <type>enum</> telling that there are no more variables.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </sect2>
@


1.40
log
@SGML improvements.

Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ecpg.sgml,v 1.39 2002/10/24 17:48:54 petere Exp $
d882 1
a882 1
      <application>Oracle</application>, however, does not use the
@


1.39
log
@Add introductory sections explaining what each book is about.  Remove Y2K
statement.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ecpg.sgml,v 1.38 2002/10/21 18:04:05 petere Exp $
d41 6
a46 4
   SQL in C is defined in the SQL standard and supported by many other
   SQL databases.  The PostgreSQL implementation is designed to match
   this standard as much as possible, and it is usually possible to
   port embedded <acronym>SQL</acronym> programs written for other
d52 4
a55 3
   As indicated, programs written for the embedded SQL interface are
   normal C programs with special code inserted to perform
   database-related actions.  This special code always has the form
d61 3
a63 3
   global context or within a function.  Embedded SQL statements
   follow the case-sensitivity rules of normal SQL code, and not those
   of C.
d754 2
a755 2
   included in a normal PostgreSQL installation.  Embedded SQL
   programs are typically named with an extension
d774 5
a778 4
   PostgreSQL installation, so if you installed PostgreSQL in a
   location that is not searched by default, you have to add an option
   such as <literal>-I/usr/local/pgsql/include</literal> to the
   compilation command line.
@


1.38
log
@Improve ECPG documentation.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ecpg.sgml,v 1.37 2002/09/21 18:32:52 petere Exp $
d801 1
a801 1
   detailed in &cite-reference;.
@


1.37
log
@Add more appropriate markup.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ecpg.sgml,v 1.36 2002/01/20 22:19:55 petere Exp $
d5 4
a8 36
 <chapter id="ecpg">
  <docinfo>
   <authorgroup>
    <author>
     <firstname>Linus</firstname>
     <surname>Tolke</surname>
    </author>
    <author>
     <firstname>Michael</firstname>
     <surname>Meskes</surname>
    </author>
   </authorgroup>
   <copyright>
    <year>1996-1997</year>
    <holder>Linus Tolke</holder>
   </copyright>
   <copyright>
    <year>1998</year>
    <holder>Michael Meskes</holder>
   </copyright>
   <date>Transcribed 1998-02-12</date>
  </docinfo>

  <title><application>ecpg</application> - Embedded <acronym>SQL</acronym> 
   in <acronym>C</acronym></title>

  <indexterm zone="ecpg"><primary>embedded SQL</primary><secondary>in C</secondary></indexterm>

  <para>
   This describes the embedded <acronym>SQL</acronym> package for
   <productname>PostgreSQL</productname>. It works with
   <acronym>C</acronym> and <acronym>C++</acronym>. It was written by
   Linus Tolke (<email>linus@@epact.se</email>) and Michael Meskes
   (<email>meskes@@debian.org</email>). The package is installed with the
   <productname>PostgreSQL</> distribution, and carries a similar license.
  </para>
d10 13
a22 2
  <sect1 id="ecpg-why">
   <title>Why Embedded <acronym>SQL</acronym>?</title>
d24 2
a25 7
   <para>
    Embedded <acronym>SQL</acronym> has advantages over other methods
    for handling <acronym>SQL</acronym> queries. It takes care of
    the tedious passing of information to and from variables in your
    <acronym>C</acronym> or <acronym>C++</acronym> program. Many
    <acronym>RDBMS</acronym> packages support this embedded language.
   </para>
d27 8
a34 8
   <para> 
    There is an ANSI standard describing how the embedded language
    should work. <application>ecpg</application> was designed to match
    this standard as much as possible. It is possible to port embedded
    <acronym>SQL</acronym> programs written for other
    <acronym>RDBMS</acronym> to <productname>PostgreSQL</productname>.
   </para>
  </sect1>
d36 12
a47 2
  <sect1 id="ecpg-concept">
   <title>The Concept</title>
d49 13
a61 7
   <para>
    You write your program in <acronym>C/C++</acronym> with special
    <acronym>SQL</acronym> constructs. When declaring variables to be
    used in <acronym>SQL</acronym> statements, you need to put them in a
    special <command>declare</> section. You use a special syntax for the
    <acronym>SQL</acronym> queries.
   </para>
d63 4
a66 7
   <para>
    Before compiling you run the file through the embedded
    <acronym>SQL</acronym> <acronym>C</acronym> preprocessor and it
    converts the <acronym>SQL</acronym> statements you used to function
    calls with the variables used as arguments. Both query input and
    result output variables are passed.
   </para>
d68 2
a69 8
   <para>
    After compiling, you must link with a special library that contains
    needed functions. These functions fetch information from the
    arguments, perform the <acronym>SQL</acronym> query using the
    <filename>libpq</filename> interface, and put the result in the
    arguments specified for output.
   </para>
  </sect1>
d71 7
a77 2
  <sect1 id="ecpg-use">
   <title>How To Use <application>ecpg</application></title>
d79 38
a116 3
   <para>
    This section describes how to use <application>ecpg</application>.
   </para>
d118 2
a119 2
   <sect2>
    <title>Preprocessor</title>
d121 29
a149 8
    <para>
     The preprocessor is called <application>ecpg</application>. After
     installation it resides in the <productname>PostgreSQL</productname>
     <filename>bin/</filename> directory.
    </para>
   </sect2>
   <sect2>
    <title>Library</title>
d151 6
a156 8
    <para>
     The <application>ecpg</application> library is called
     <filename>libecpg.a</filename> or <filename>libecpg.so</filename>.
     Additionally, the library uses the <filename>libpq</filename>
     library for communication to the
     <productname>PostgreSQL</productname> server. You will have to link
     your program using <parameter>-lecpg -lpq</parameter>.
    </para>
d158 2
a159 3
    <para>
     The library has some methods that are <quote>hidden</quote> but may prove
     useful.
d161 7
a167 9
     <itemizedlist>
      <listitem>
       <para>
        <function>ECPGdebug(int <replaceable>on</replaceable>, FILE
        *<replaceable>stream</replaceable>)</function> turns on debug
        logging if called with the first argument non-zero. Debug
        logging is done on <replaceable>stream</replaceable>. Most
        <acronym>SQL</acronym> statement log their arguments and results.
       </para>
d169 27
a195 9
       <para>
        The most important function , <function>ECPGdo</function>, logs
        all <acronym>SQL</acronym> statements with both the expanded
        string, i.e. the string with all the input variables inserted,
        and the result from the <productname>PostgreSQL</productname>
        server. This can be very useful when searching for errors in
        your <acronym>SQL</acronym> statements.
       </para>
      </listitem>
d197 2
a198 9
      <listitem>
       <para>
        <function>ECPGstatus()</function>
        This method returns TRUE if we are connected to a database and FALSE if not.
       </para>
      </listitem>
     </itemizedlist>
    </para>
   </sect2>
d200 4
a203 2
   <sect2>
    <title>Error handling</title>
d205 2
a206 3
    <para>
     To detect errors from the <productname>PostgreSQL</productname>
     server, include a line like: 
d208 3
a210 1
exec sql include sqlca; 
d212 4
a215 2
     in the include section of your file. This will define a <type>struct</> and
     a variable with the name <varname>sqlca</varname> as follows:
d217 2
a218 32
struct sqlca
{
 char sqlcaid[8];
 long sqlabc;
 long sqlcode;
 struct
 {
  int sqlerrml;
  char sqlerrmc[70];
 } sqlerrm;
 char sqlerrp[8];
 long sqlerrd[6];
 /* 0: empty                                         */
 /* 1: OID of processed tuple if applicable          */
 /* 2: number of rows processed in an INSERT, UPDATE */
 /*    or DELETE statement                           */
 /* 3: empty                                         */
 /* 4: empty                                         */
 /* 5: empty                                         */
 char sqlwarn[8];
 /* 0: set to 'W' if at least one other is 'W'       */
 /* 1: if 'W' at least one character string          */
 /*    value was truncated when it was               */
 /*    stored into a host variable.                  */
 /* 2: empty                                         */
 /* 3: empty                                         */
 /* 4: empty                                         */
 /* 5: empty                                         */
 /* 6: empty                                         */
 /* 7: empty                                         */
 char sqlext[8];
} sqlca;
d220 1
a220 1
    </para>
d222 7
a228 8
    <para>
     If an no error occurred in the last <acronym>SQL</acronym> statement.
     <parameter>sqlca.sqlcode</parameter> will be 0 (<symbol>ECPG_NO_ERROR</>). If
     <parameter>sqlca.sqlcode</parameter> is less that zero, this is a
     serious error, like the database definition does not match the
     query. If it is greater than zero, it is a normal error like the
     table did not contain the requested row.
    </para>
d230 6
a235 5
    <para>
     <parameter>sqlca.sqlerrm.sqlerrmc</parameter> will contain a string
     that describes the error. The string ends with the line number in
     the source file.
    </para>
d237 12
a248 2
    <para>
     These are the errors that can occur:
d250 9
a258 10
     <variablelist>
      <varlistentry>
       <term><computeroutput>-12, Out of memory in line %d.</computeroutput></term>
       <listitem>
        <para>
         Should not normally occur. This indicates your virtual memory is
         exhausted.
        </para>
       </listitem>
      </varlistentry>
d260 7
a266 11
      <varlistentry>
       <term><computeroutput>-200 (ECPG_UNSUPPORTED): Unsupported type %s on line %d.</computeroutput></term>
       <listitem>
        <para>
         Should not normally occur. This indicates the preprocessor has
         generated something that the library does not know about.
         Perhaps you are running incompatible versions of the
         preprocessor and the library.
        </para>
       </listitem>
      </varlistentry>
d268 12
a279 11
      <varlistentry>
       <term><computeroutput>-201 (ECPG_TOO_MANY_ARGUMENTS): Too many arguments line %d.</computeroutput></term>
       <listitem>
        <para>
         This means that <productname>PostgreSQL</productname> has
         returned more arguments than we have matching variables.
         Perhaps you have forgotten a couple of the host variables in
         the <command>INTO :var1,:var2</command>-list.
        </para>
       </listitem>
      </varlistentry>
d281 2
a282 11
      <varlistentry>
       <term><computeroutput>-202 (ECPG_TOO_FEW_ARGUMENTS): Too few arguments line %d.</computeroutput></term>
       <listitem>
        <para>
         This means that <productname>PostgreSQL</productname> has
         returned fewer arguments than we have host variables. Perhaps
         you have too many host variables in the <command>INTO
         :var1,:var2</command>-list.
        </para> 
       </listitem>
      </varlistentry>
d284 7
a290 10
      <varlistentry>
       <term><computeroutput>-203 (ECPG_TOO_MANY_MATCHES): Too many matches line %d.</computeroutput></term>
       <listitem>
        <para>
         This means the query has returned several rows but the
         variables specified are not arrays. The
         <command>SELECT</command> command was not unique.
        </para>
       </listitem>
      </varlistentry>
d292 15
a306 12
      <varlistentry>
       <term><computeroutput>-204 (ECPG_INT_FORMAT): Not correctly formatted int type: %s line %d.</computeroutput></term>
       <listitem>
        <para>
         This means the host variable is of type <type>int</type> and
         the field in the <productname>PostgreSQL</productname> database
         is of another type and contains a value that cannot be
         interpreted as an <type>int</type>. The library uses
         <function>strtol()</function> for this conversion.
        </para>
       </listitem>
      </varlistentry>
d308 6
a313 13
      <varlistentry>
       <term><computeroutput>-205 (ECPG_UINT_FORMAT): Not correctly formatted unsigned type: %s line %d.</computeroutput></term>
       <listitem>
        <para>
         This means the host variable is of type <type>unsigned
         int</type> and the field in the
         <productname>PostgreSQL</productname> database is of another type
         and contains a value that cannot be interpreted as an
         <type>unsigned int</type>. The library uses
         <function>strtoul()</function> for this conversion.
        </para>
       </listitem>
      </varlistentry>
d315 5
a319 12
      <varlistentry>
       <term><computeroutput>-206 (ECPG_FLOAT_FORMAT): Not correctly formatted floating-point type: %s line %d.</computeroutput></term>
       <listitem>
        <para>
         This means the host variable is of type <type>float</type> and
         the field in the <productname>PostgreSQL</productname> database
         is of another type and contains a value that cannot be
         interpreted as a <type>float</type>. The library uses
         <function>strtod()</function> for this conversion.
        </para>
       </listitem>
      </varlistentry>
d321 14
a334 10
      <varlistentry>
       <term><computeroutput>-207 (ECPG_CONVERT_BOOL): Unable to convert %s to bool on line %d.</computeroutput></term>
       <listitem>
        <para>
         This means the host variable is of type <type>bool</type> and
         the field in the <productname>PostgreSQL</productname> database
         is neither <literal>'t'</> nor <literal>'f'</>.
        </para>
       </listitem>
      </varlistentry>
d336 6
a341 9
      <varlistentry>
       <term><computeroutput>-208 (ECPG_EMPTY): Empty query line %d.</computeroutput></term>
       <listitem>
        <para>
         <productname>PostgreSQL</productname> returned <symbol>PGRES_EMPTY_QUERY</symbol>, probably
         because the query indeed was empty.
        </para>
       </listitem>
      </varlistentry>
d343 2
a344 9
      <varlistentry>
       <term><computeroutput>-209 (ECPG_MISSING_INDICATOR): NULL value without indicator in line %d.</computeroutput></term>
       <listitem>
        <para>
         <productname>PostgreSQL</productname> returned <symbol>ECPG_MISSING_INDICATOR</symbol>
         because a NULL was returned and no NULL indicator variable was supplied.
        </para>
       </listitem>
      </varlistentry>
d346 14
a359 10
      <varlistentry>
       <term><computeroutput>-210 (ECPG_NO_ARRAY): Variable is not an array in line %d.</computeroutput></term>
       <listitem>
        <para>
         <productname>PostgreSQL</productname> returned <symbol>ECPG_NO_ARRAY</symbol>
         because an ordinary variable was used in a place that requires
         an array.
        </para>
       </listitem>
      </varlistentry>
d361 8
a368 10
      <varlistentry>
       <term><computeroutput>-211 (ECPG_DATA_NOT_ARRAY): Data read from backend is not an array in line %d.</computeroutput></term>
       <listitem>
        <para>
         <productname>PostgreSQL</productname> returned <symbol>ECPG_DATA_NOT_ARRAY</symbol>
         because the database returned an ordinary variable in a place
         that requires array value.
        </para>
       </listitem>
      </varlistentry>
d370 37
a406 8
      <varlistentry>
       <term><computeroutput>-220 (ECPG_NO_CONN): No such connection %s in line %d.</computeroutput></term>
       <listitem>
        <para>
         The program tried to access a connection that does not exist.
        </para>
       </listitem>
      </varlistentry>
d408 5
a412 9
      <varlistentry>
       <term><computeroutput>-221 (ECPG_NOT_CONN): Not connected in line %d.</computeroutput></term>
       <listitem>
        <para>
         The program tried to access a connection that does exist but is
         not open.
        </para>
       </listitem>
      </varlistentry>
d414 8
a421 8
      <varlistentry>
       <term><computeroutput>-230 (ECPG_INVALID_STMT): Invalid statement name %s in line %d.</computeroutput></term>
       <listitem>
        <para>
         The statement you are trying to use has not been prepared.
        </para>
       </listitem>
      </varlistentry>
d423 5
a427 8
      <varlistentry>
       <term><computeroutput>-240 (ECPG_UNKNOWN_DESCRIPTOR): Descriptor %s not found in line %d.</computeroutput></term>
       <listitem>
        <para>
         The descriptor specified was not found. The statement you are trying to use has not been prepared.
        </para>
       </listitem>
      </varlistentry>
d429 2
a430 8
      <varlistentry>
       <term><computeroutput>-241 (ECPG_INVALID_DESCRIPTOR_INDEX): Descriptor index out of range in line %d.</computeroutput></term>
       <listitem>
        <para>
         The descriptor index specified was out of range.
        </para>
       </listitem>
      </varlistentry>
d432 266
a697 8
      <varlistentry>
       <term><computeroutput>-242 (ECPG_UNKNOWN_DESCRIPTOR_ITEM): Descriptor %s not found in line %d.</computeroutput></term>
       <listitem>
        <para>
         The descriptor specified was not found. The statement you are trying to use has not been prepared.
        </para>
       </listitem>
      </varlistentry>
d699 2
a700 9
      <varlistentry>
       <term><computeroutput>-243 (ECPG_VAR_NOT_NUMERIC): Variable is not a numeric type in line %d.</computeroutput></term>
       <listitem>
        <para>
         The database returned a numeric value and the variable was not
         numeric.
        </para>
       </listitem>
      </varlistentry>
d702 10
a711 9
      <varlistentry>
       <term><computeroutput>-244 (ECPG_VAR_NOT_CHAR): Variable is not a character type in line %d.</computeroutput></term>
       <listitem>
        <para>
         The database returned a non-numeric value and the variable was
         numeric.
        </para>
       </listitem>
      </varlistentry>
d713 10
a722 10
      <varlistentry>
       <term><computeroutput>-400 (ECPG_PGSQL): Postgres error: %s line %d.</computeroutput></term>
       <listitem>
        <para>
         Some <productname>PostgreSQL</productname> error. 
         The message contains the error message from the
         <productname>PostgreSQL</productname> backend.
        </para>
       </listitem>
      </varlistentry>
d724 8
a731 9
      <varlistentry>
       <term><computeroutput>-401 (ECPG_TRANS): Error in transaction processing line %d.</computeroutput></term>
       <listitem>
        <para>
         <productname>PostgreSQL</productname> signaled that we cannot start,
         commit or rollback the transaction.
        </para>
       </listitem>
      </varlistentry>
d733 2
a734 8
      <varlistentry>
       <term><computeroutput>-402 (ECPG_CONNECT): Could not connect to database %s in line %d.</computeroutput></term>
       <listitem>
        <para>
         The connect to the database did not work.
        </para>
       </listitem>
      </varlistentry>
d736 12
a747 9
      <varlistentry>
       <term><computeroutput>100 (ECPG_NOT_FOUND): Data not found line %d.</computeroutput></term>
       <listitem>
        <para>
         This is a <quote>normal</quote> error that tells you that what you are querying cannot
         be found or you are at the end of the cursor.
        </para>
       </listitem>
      </varlistentry>
d749 15
a763 4
     </variablelist>
    </para>
   </sect2>
  </sect1>
d765 11
a775 2
  <sect1 id="ecpg-limitations">
   <title>Limitations</title>
d777 9
a785 2
   <para>
    What will never be included and why it cannot be done:
d787 6
a792 12
    <variablelist>
     <varlistentry>
      <term>Oracle's single tasking</term>
      <listitem>
       <para>
        Oracle version 7.0 on <systemitem class="osname">AIX</> 3 uses OS-supported locks in shared
        memory that allow an application designer to link an application
        in a <quote>single tasking</quote> way. Instead of starting one client
        process per application process, both the database part and the
        application part run in the same process. In later versions of
        Oracle this is no longer supported.
       </para>
d794 4
a797 10
       <para>
        This would require a total redesign of the
        <productname>PostgreSQL</productname> access model and the
        performance gain does not justify the effort.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </sect1>
d799 5
a803 2
  <sect1 id="ecpg-porting">
   <title>Porting From Other <acronym>RDBMS</acronym> Packages</title>
d805 2
a806 8
   <para>
    The design of <application>ecpg</application> follows the SQL
    standard. Porting from a standard RDBMS should not be a problem.
    Unfortunately there is no such thing as a standard RDBMS. Therefore
    <application>ecpg</application> tries to understand syntax
    extensions as long as they do not create conflicts with the
    standard.
   </para>
d808 7
a814 8
   <para>
    The following list shows all the known incompatibilities. If you
    find one not listed please notify the developers. Note, however, that
    we list only incompatibilities from a precompiler of another RDBMS
    to <application>ecpg</application> and not
    <application>ecpg</application> features that these RDBMS do not
    support.
   </para>
d816 9
a824 35
   <para>
    <variablelist>
     <varlistentry>
      <term>Syntax of FETCH</term>
      <indexterm><primary>FETCH</><secondary>embedded SQL</></indexterm>
      <listitem>
       <para>
        The standard syntax for FETCH is:
       </para>
       <para>
        FETCH [direction] [amount] IN|FROM <replaceable>cursor</replaceable>.
       </para>
       <para>
        <indexterm><primary>Oracle</></>
        <application>Oracle</application>, however, does not use the keywords IN
        or FROM. This feature cannot be added since it would create parsing
        conflicts.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </sect1>

  <sect1 id="ecpg-develop">
   <title>For the Developer</title>

   <para>
    This section explain how <application>ecpg</application>
    works internally. It contains valuable information to help users
    understand how to use <application>ecpg</application>.
   </para>

   <sect2>
    <title>The Preprocessor</title>
d827 6
a832 3
     The first four lines written by <command>ecpg</command> to the output are fixed lines.
     Two are comments and two are include lines necessary to interface
     to the library.
d834 1
d836 1
d838 2
a839 2
     Then the preprocessor reads through the file and writes output.
     Normally it just echoes everything to the output.
d841 3
d845 41
a885 4
    <para>
     When it sees an <command>EXEC SQL</command> statement, it
     intervenes and changes it. The <command>EXEC SQL</command>
     statement can be one of these:
d887 2
a888 45
     <variablelist>
      <varlistentry>
       <term>Declare sections</term>
       <listitem>
        <para>
         <command>Declare</> sections begin with:
<programlisting>
exec sql begin declare section;
</programlisting>
         and end with:
<programlisting>
exec sql end declare section;
</programlisting>
         In this section only variable declarations are allowed. Every
         variable declared within this section is stored in a list
         of variables indexed by name together with its corresponding
         type.
        </para>

        <para>
         In particular the definition of a structure or union also must
         be listed inside a <command>declare</> section. Otherwise
         <application>ecpg</application> cannot handle these types since
         it does not know the definition.
        </para>

        <para>
         The declaration is also echoed to the file to make it a normal
         C variable.
        </para>

        <para>
         The special types <type>VARCHAR</type> and
         <type>VARCHAR2</type> are converted into a named <type>struct</> for
         every variable. A declaration like:
<programlisting>
VARCHAR var[180];
</programlisting>
         is converted into:
<programlisting>
struct varchar_var { int len; char arr[180]; } var;
</programlisting>
        </para>
       </listitem>
      </varlistentry>
d890 5
a894 13
      <varlistentry>
       <term>Include statements</term>
       <listitem>
        <para>
         An include statement looks like:
<programlisting>
exec sql include filename;
</programlisting>
         Note that this is NOT the same as:
<programlisting>
#include &lt;filename.h&gt;
</programlisting>
        </para>
d896 2
a897 8
        <para>
         Instead the file specified is parsed by
         <application>ecpg</application> so the contents of the file are
         included in the resulting C code. This way you are able to
         specify EXEC SQL commands in an include file.
        </para>
       </listitem>
      </varlistentry>
d899 7
a905 10
      <varlistentry>
       <term>Connect statement</term>
       <listitem>
        <para>
         A connect statement looks like:
<programlisting>
exec sql connect to <replaceable>connection target</replaceable>;
</programlisting>
         It creates a connection to the specified database.
        </para>
d907 7
a913 89
        <para>
         The <replaceable>connection target</replaceable> can be specified in the
         following ways:
         <itemizedlist>
          <listitem>
           <simpara>
            <literal>dbname[@@server][:port][as <replaceable>connection
            name</replaceable>][user <replaceable>user name</replaceable>]</literal>
           </simpara>
          </listitem>

          <listitem>
           <simpara>
            <literal>tcp:postgresql://server[:port][/dbname][as
            <replaceable>connection name</replaceable>][user <replaceable>user name</replaceable>]</literal>
           </simpara>
          </listitem>

          <listitem>
           <simpara>
            <literal>unix:postgresql://server[:port][/dbname][as
            <replaceable>connection name</replaceable>][user <replaceable>user name</replaceable>]</literal>
           </simpara>
          </listitem>
 
          <listitem>
           <simpara>
            <literal><replaceable>character variable</replaceable>[as
            <replaceable>connection name</replaceable>][user <replaceable>user name</replaceable>]</literal>
           </simpara>
          </listitem>
 
          <listitem>
           <simpara>
            <literal><replaceable>character string</replaceable>[as
            <replaceable>connection name</replaceable>][<replaceable>user</replaceable>]</literal>
           </simpara>
          </listitem>
 
          <listitem>
           <simpara>
            <literal>default</literal>
           </simpara>
          </listitem>
 
          <listitem>
           <simpara>
            <literal>user</literal>
           </simpara>
          </listitem>
         </itemizedlist>
        </para>

        <para>
         There are also different ways to specify the user name:

         <itemizedlist>
          <listitem>
           <simpara>
            <literal><replaceable>userid</replaceable></literal>
           </simpara>
          </listitem>

          <listitem>
           <simpara>
            <literal><replaceable>userid</replaceable>/<replaceable>password</replaceable></literal>
           </simpara>
          </listitem>

          <listitem>
           <simpara>
            <literal><replaceable>userid</replaceable> identified by <replaceable>password</replaceable></literal>
           </simpara>
          </listitem>

          <listitem>
           <simpara>
            <literal><replaceable>userid</replaceable> using <replaceable>password</replaceable></literal>
           </simpara>
          </listitem>
         </itemizedlist>
        </para>

        <para> 
         Finally, the <replaceable>userid</replaceable> and <replaceable>password</replaceable> may be a constant text, a
         character variable, or a character string.
        </para>
       </listitem>
      </varlistentry>
d915 8
a922 43
      <varlistentry>
       <term>Disconnect statements</term>
       <listitem>
        <para>
         A disconnect statement looks like:
         <programlisting>
exec sql disconnect [<replaceable>connection target</replaceable>];
         </programlisting>
         It closes the connection to the specified database.
        </para>

        <para>
         The <replaceable>connection target</replaceable> can be specified in the
         following ways:

         <itemizedlist>
          <listitem>
           <simpara>
            <literal><replaceable>connection name</replaceable></literal>
           </simpara>
          </listitem>

          <listitem>
           <simpara>
           <literal>default</literal>
           </simpara>
          </listitem>

          <listitem>
           <simpara>
           <literal>current</literal>
           </simpara>
          </listitem>

          <listitem>
           <simpara>
           <literal>all</literal>
           </simpara>
          </listitem>
         </itemizedlist>
        </para>
       </listitem>
      </varlistentry>
d924 3
a926 14
      <varlistentry>
       <term>Open cursor statement</term>
       <listitem>
        <para>
         An open cursor statement looks like:
<programlisting>
exec sql open <replaceable>cursor</replaceable>;
</programlisting>
         and is not copied to the output. Instead, the cursor's
         <command>DECLARE</> command is used because it opens the cursor
         as well.
        </para>
       </listitem>
      </varlistentry>
d928 64
a991 11
      <varlistentry>
       <term>Commit statement</term>
       <listitem>
        <para>
         A commit statement looks like:
<programlisting>
exec sql commit;
</programlisting>
        </para>
       </listitem>
      </varlistentry>
d993 3
a995 5
      <varlistentry>
       <term>Rollback statement</term>
       <listitem>
        <para>
         A rollback statement looks like:
d997 1
a997 1
exec sql rollback;
d999 4
a1002 3
        </para>
       </listitem>
      </varlistentry>
d1004 4
a1007 100
      <varlistentry>
       <term>Other statements</term>
       <listitem>
        <para>
         Other <acronym>SQL</acronym> statements are used by
         starting with <command>exec sql</command> and ending with
         <command>;</command>. Everything in between is treated as an
         <acronym>SQL</acronym> statement and parsed for variable
         substitution.
        </para>

        <para>
         Variable substitution occurs when a symbol starts with a colon
         (<command>:</command>). The variable with that name is looked
         up among the variables that were previously declared within a
         <command>declare</> section. Depending on whether the variable is
         being use for input or output, a pointer to the variable is
         output to allow access by the function.
        </para>

        <para>
         For every variable that is part of the <acronym>SQL</acronym>
         query, the function gets other arguments:

         <itemizedlist>
          <listitem>
           <para>
            The type as a special symbol.
           </para>
          </listitem>

          <listitem>
           <para> 
            A pointer to the value or a pointer to the pointer.
           </para>
          </listitem>

          <listitem>
           <para>
            The size of the variable if it is a <type>char</type> or <type>varchar</type>.
           </para>
          </listitem>

          <listitem>
           <para>
            The number of elements in the array (for array fetches).
           </para>
          </listitem>

          <listitem>
           <para>
            The offset to the next element in the array (for array fetches).
           </para>
          </listitem>

          <listitem>
           <para>
            The type of the indicator variable as a special symbol.
           </para>
          </listitem>

          <listitem>
           <para>
            A pointer to the value of the indicator variable or a pointer to the pointer of the indicator variable.
           </para>
          </listitem>

          <listitem>
           <para>
            0.
           </para>
          </listitem>

          <listitem>
           <para>
            Number of elements in the indicator array (for array fetches).
           </para>
          </listitem>

          <listitem>
           <para>
            The offset to the next element in the indicator array (for
            array fetches).
           </para>
          </listitem>
         </itemizedlist>
        </para>

       </listitem>
      </varlistentry>
     </variablelist>
    </para>
   </sect2>

   <sect2>
    <title>A Complete Example</title>

    <para>
     Here is a complete example describing the output of the preprocessor of a
     file <filename>foo.pgc</filename>:
d1009 1
a1009 1
exec sql begin declare section;
d1012 1
a1012 1
exec sql end declare section;
d1014 1
a1014 1
exec sql select res into :result from mytable where index = :index;
d1016 1
a1016 1
     is translated into:
d1031 1
a1031 1
ECPGdo(__LINE__, NULL, "select  res  from mytable where index = ?     ",
d1038 4
a1041 4
     (The indentation in this manual is added for readability and not
     something the preprocessor does.)
    </para>
   </sect2>
d1043 2
a1044 2
   <sect2>
    <title>The Library</title>
d1046 8
a1053 7
    <para>
     The most important function in the library is
     <function>ECPGdo</function>. It takes a variable number of
     arguments. Hopefully there are no computers that limit the
     number of variables that can be accepted by a <function>varargs()</function> function. This
     can easily add up to 50 or so arguments.
    </para>
d1055 2
a1056 2
    <para>
     The arguments are:
d1058 10
a1067 9
     <variablelist>
      <varlistentry>
       <term>A line number</term>
       <listitem>
        <para>
         This is a line number of the original line; used in error messages only.
        </para>
       </listitem>
      </varlistentry>
d1069 12
a1080 12
      <varlistentry>
       <term>A string</term>
       <listitem>
        <para>
         This is the <acronym>SQL</acronym> query that is to be issued.
         It is modified by the input variables, i.e. the variables that
         where not known at compile time but are to be entered in the
         query. Where the variables should go the string contains
         <literal>?</literal>.
        </para>
       </listitem>
      </varlistentry>
d1082 9
a1090 9
      <varlistentry>
       <term>Input variables</term>
       <listitem>
        <para>
         As described in the section about the preprocessor, every input variable
         gets ten arguments.
        </para>
       </listitem>
      </varlistentry>
d1092 9
a1100 8
      <varlistentry>
       <term><parameter>ECPGt_EOIT</></term>
       <listitem>
        <para>
         An <type>enum</> telling that there are no more input variables.
        </para>
       </listitem>
      </varlistentry>
d1102 10
a1111 9
      <varlistentry>
       <term>Output variables</term>
       <listitem>
        <para>
         As described in the section about the preprocessor, every input variable
         gets ten arguments. These variables are filled by the function.
        </para>
       </listitem>
      </varlistentry>
d1116 10
a1125 22
        <para>
         An <type>enum</> telling that there are no more variables.
        </para>
       </listitem>
      </varlistentry>
     </variablelist>
    </para>

    <para>
     In the default mode, queries are committed only when <command>exec
     sql commit</command> is issued. <application>Ecpg</application>
     also supports auto-commit of transactions via the
     <option>-t</option> command-line option or via the <literal>exec
     sql set autocommit to on</literal> statement. In
     <literal>autocommit</literal> mode, each query is automatically
     committed unless it is inside an explicit transaction block. This
     mode can be explicitly turned off using <literal>exec sql set
     autocommit to off</literal>.
    </para>
   </sect2>
  </sect1>
 </chapter>
@


1.36
log
@Spell-check and markup police
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.35 2002/01/18 21:17:07 momjian Exp $
d161 2
a162 2
     in the include section of your file. This will define a struct and
     a variable with the name <parameter>sqlca</parameter> as follows:
d201 1
a201 1
     <parameter>sqlca.sqlcode</parameter> will be 0 (ECPG_NO_ERROR). If
d623 3
a625 2
         The special types <type>VARCHAR</type> and <type>VARCHAR2</type> are converted into a named struct
         for every variable. A declaration like:
d1027 1
a1027 1
       <term><literal>ECPGt_EOIT</literal></term>
d1030 1
a1030 1
         An enum telling that there are no more input variables.
d1046 1
a1046 1
       <term>ECPGt_EORT</term>
d1049 1
a1049 1
         An enum telling that there are no more variables.
@


1.35
log
@Add missing literal endtag.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.34 2002/01/18 20:32:53 momjian Exp $
d400 1
a400 1
         The descriptor specified was not foundstatement you are trying to use has not been prepared.
d418 1
a418 1
         The descriptor specified was not foundstatement you are trying to use has not been prepared.
@


1.34
log
@Improve description of autocommit behavior in ecpg manual pages.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.33 2002/01/07 02:29:11 petere Exp $
d1061 1
a1061 1
     <literal>autocommit<literal> mode, each query is automatically
@


1.33
log
@Editorial review
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.32 2002/01/06 17:54:14 momjian Exp $
d1056 9
a1064 6
     All <acronym>SQL</acronym> statements are performed in one
     transaction unless you issue a commit transaction. To accomplish
     this auto-transaction behavior, the first statement and the first
     statement after a commit or rollback always begins a new transaction. To
     disable this feature, use the <option>-t</option> command-line
     option.
a1065 1

@


1.32
log
@Remove ecpg TODO section:

> Looking at this I also found an ecpg TODO list in the docs:
>
>
http://candle.pha.pa.us/main/writings/pgsql/sgml/ecpg-develop.html
>
> Seems that TODO section should be removed.  Some items are done,
others
> are on the main TODO list.

That's correct. I did not fix the docs for quite some time.

Michael
--
Michael Meskes
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.31 2001/11/21 05:53:41 thomas Exp $
d303 1
a303 1
       <term><computeroutput>-206 (ECPG_FLOAT_FORMAT): Not correctly formatted floating point type: %s line %d.</computeroutput></term>
@


1.31
log
@Deprecate 'current' for date/time input.
Fix up references to "PostgreSQL" rather than "Postgres". Was roughly
 evenly split between the two before. ref/ files not yet done.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.30 2001/11/12 19:19:39 petere Exp $
a570 84

   <sect2>
    <title>ToDo List</title>

    <para>
     This version of the preprocessor has some flaws:

     <variablelist>
      <varlistentry>
       <term>Library functions</term>
       <listitem>
        <para>
         to_date et al. does not exist. However,
         <productname>PostgreSQL</productname> has some good conversion
         routines so you probably won't miss them.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>Structures and unions</term>
       <listitem>
        <para>
         Structures and unions have to be defined in the
         <command>declare</> section.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>Missing statements</term>
       <listitem>
        <para>
         The following statements are not implemented thus far:

         <itemizedlist>
          <listitem>
           <para>
            <literal>exec sql allocate</>
           </para>
          </listitem>

          <listitem>
           <para>
            <literal>exec sql deallocate</>
           </para>
          </listitem>
 
          <listitem>
           <para>
            <literal>SQLSTATE</>
           </para>
          </listitem>
         </itemizedlist>
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>message 'no data found'</term>
       <listitem>
        <para>
         The error message for <quote>no data</quote> in:
         <programlisting>
exec sql insert select from statement
        </programlisting>
         has to be <literal>100</>.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><literal>sqlwarn[6]</literal></term>
       <listitem>
        <para>
         <literal>sqlwarn[6]</literal> should be <literal>W</> if the <command>PRECISION</>
         or <command>SCALE</> value specified in a <command>SET
         DESCRIPTOR</> statement was ignored.
        </para>
       </listitem>
      </varlistentry>
     </variablelist>
    </para>
   </sect2>
@


1.30
log
@Add some more index entries.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.29 2001/11/08 23:37:50 petere Exp $
d35 1
a35 1
   <productname>Postgres</productname>. It works with
d39 1
a39 1
   <productname>Postgres</> distribution, and carries a similar license.
d58 1
a58 1
    <acronym>RDBMS</acronym> to <productname>Postgres</productname>.
d102 1
a102 1
     installation it resides in the <productname>Postgres</productname>
d114 1
a114 1
     <productname>Postgres</productname> server. You will have to link
d136 1
a136 1
        and the result from the <productname>Postgres</productname>
d156 1
a156 1
     To detect errors from the <productname>Postgres</productname>
d244 1
a244 1
         This means that <productname>Postgres</productname> has
d256 1
a256 1
         This means that <productname>Postgres</productname> has
d280 1
a280 1
         the field in the <productname>Postgres</productname> database
d294 1
a294 1
         <productname>Postgres</productname> database is of another type
d307 1
a307 1
         the field in the <productname>Postgres</productname> database
d320 1
a320 1
         the field in the <productname>Postgres</productname> database
d330 1
a330 1
         <productname>Postgres</productname> returned <symbol>PGRES_EMPTY_QUERY</symbol>, probably
d340 1
a340 1
         <productname>Postgres</productname> returned <symbol>ECPG_MISSING_INDICATOR</symbol>
d350 1
a350 1
         <productname>Postgres</productname> returned <symbol>ECPG_NO_ARRAY</symbol>
d361 1
a361 1
         <productname>Postgres</productname> returned <symbol>ECPG_DATA_NOT_ARRAY</symbol>
d447 1
a447 1
         Some <productname>Postgres</productname> error. 
d449 1
a449 1
         <productname>Postgres</productname> backend.
d458 1
a458 1
         <productname>Postgres</productname> signaled that we cannot start,
d509 1
a509 1
        <productname>Postgres</productname> access model and the
d584 1
a584 1
         <productname>Postgres</productname> has some good conversion
@


1.29
log
@Small tuning
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.28 2001/11/01 04:48:00 tgl Exp $
d31 2
d543 1
d552 2
a553 1
        <application>ORACLE</application>, however, does not use the keywords IN
@


1.28
log
@Fix broken markup.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.27 2001/10/31 20:37:39 petere Exp $
d530 1
a530 2
    find one not listed please notify <ulink
    url="meskes@@debian.org">Michael Meskes</ulink>. Note, however, that
@


1.27
log
@Reformat some non-sensical markup.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.26 2001/10/18 20:43:05 momjian Exp $
d612 1
a612 1
            <literal>exec sql deallocate</></term>
d618 1
a618 1
            <literal>SQLSTATE</></term>
d877 1
a877 1
           <term>all</term>
@


1.26
log
@Change error code docs to use colons.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.25 2001/10/18 20:32:58 momjian Exp $
d123 5
a127 5
	<function>ECPGdebug(int <replaceable>on</replaceable>, FILE
	*<replaceable>stream</replaceable>)</function> turns on debug
	logging if called with the first argument non-zero. Debug
	logging is done on <replaceable>stream</replaceable>. Most
	<acronym>SQL</acronym> statement log their arguments and results.
d131 6
a136 6
	The most important function , <function>ECPGdo</function>, logs
	all <acronym>SQL</acronym> statements with both the expanded
	string, i.e. the string with all the input variables inserted,
	and the result from the <productname>Postgres</productname>
	server. This can be very useful when searching for errors in
	your <acronym>SQL</acronym> statements.
d142 2
a143 2
	<function>ECPGstatus()</function>
	This method returns TRUE if we are connected to a database and FALSE if not.
d183 1
a183 1
 /* 1: if 'W' at least one character string	     */
d219 4
a222 4
	<para>
	 Should not normally occur. This indicates your virtual memory is
	 exhausted.
	</para>
d229 6
a234 6
	<para>
	 Should not normally occur. This indicates the preprocessor has
	 generated something that the library does not know about.
	 Perhaps you are running incompatible versions of the
	 preprocessor and the library.
	</para>
d241 6
a246 6
	<para>
	 This means that <productname>Postgres</productname> has
	 returned more arguments than we have matching variables.
	 Perhaps you have forgotten a couple of the host variables in
	 the <command>INTO :var1,:var2</command>-list.
	</para>
d253 6
a258 6
	<para>
	 This means that <productname>Postgres</productname> has
	 returned fewer arguments than we have host variables. Perhaps
	 you have too many host variables in the <command>INTO
	 :var1,:var2</command>-list.
	</para> 
d265 5
a269 5
	<para>
	 This means the query has returned several rows but the
	 variables specified are not arrays. The
	 <command>SELECT</command> command was not unique.
	</para>
d276 7
a282 7
	<para>
	 This means the host variable is of type <type>int</type> and
	 the field in the <productname>Postgres</productname> database
	 is of another type and contains a value that cannot be
	 interpreted as an <type>int</type>. The library uses
	 <function>strtol()</function> for this conversion.
	</para>
d289 8
a296 8
	<para>
	 This means the host variable is of type <type>unsigned
	 int</type> and the field in the
	 <productname>Postgres</productname> database is of another type
	 and contains a value that cannot be interpreted as an
	 <type>unsigned int</type>. The library uses
	 <function>strtoul()</function> for this conversion.
	</para>
d303 7
a309 7
	<para>
	 This means the host variable is of type <type>float</type> and
	 the field in the <productname>Postgres</productname> database
	 is of another type and contains a value that cannot be
	 interpreted as a <type>float</type>. The library uses
	 <function>strtod()</function> for this conversion.
	</para>
d316 5
a320 5
	<para>
	 This means the host variable is of type <type>bool</type> and
	 the field in the <productname>Postgres</productname> database
	 is neither <literal>'t'</> nor <literal>'f'</>.
	</para>
d327 4
a330 4
	<para>
	 <productname>Postgres</productname> returned <symbol>PGRES_EMPTY_QUERY</symbol>, probably
	 because the query indeed was empty.
	</para>
d337 4
a340 4
	<para>
	 <productname>Postgres</productname> returned <symbol>ECPG_MISSING_INDICATOR</symbol>
	 because a NULL was returned and no NULL indicator variable was supplied.
	</para>
d347 5
a351 5
	<para>
	 <productname>Postgres</productname> returned <symbol>ECPG_NO_ARRAY</symbol>
	 because an ordinary variable was used in a place that requires
	 an array.
	</para>
d358 5
a362 5
	<para>
	 <productname>Postgres</productname> returned <symbol>ECPG_DATA_NOT_ARRAY</symbol>
	 because the database returned an ordinary variable in a place
	 that requires array value.
	</para>
d369 3
a371 3
	<para>
	 The program tried to access a connection that does not exist.
	</para>
d378 4
a381 4
	<para>
	 The program tried to access a connection that does exist but is
	 not open.
	</para>
d388 3
a390 3
	<para>
	 The statement you are trying to use has not been prepared.
	</para>
d397 3
a399 3
	<para>
	 The descriptor specified was not foundstatement you are trying to use has not been prepared.
	</para>
d406 3
a408 3
	<para>
	 The descriptor index specified was out of range.
	</para>
d415 3
a417 3
	<para>
	 The descriptor specified was not foundstatement you are trying to use has not been prepared.
	</para>
d424 4
a427 4
	<para>
	 The database returned a numeric value and the variable was not
	 numeric.
	</para>
d434 4
a437 4
	<para>
	 The database returned a non-numeric value and the variable was
	 numeric.
	</para>
d444 5
a448 5
	<para>
	 Some <productname>Postgres</productname> error. 
	 The message contains the error message from the
	 <productname>Postgres</productname> backend.
	</para>
d455 4
a458 4
	<para>
	 <productname>Postgres</productname> signaled that we cannot start,
	 commit or rollback the transaction.
	</para>
d465 3
a467 3
	<para>
	 The connect to the database did not work.
	</para>
d474 4
a477 4
	<para>
	 This is a <quote>normal</quote> error that tells you that what you are querying cannot
	 be found or you are at the end of the cursor.
	</para>
d489 2
a490 5
   <abstract>
    <para>
     What will never be included and why it cannot be done.
    </para>
   </abstract>
a491 1
   <para>
d497 6
a502 6
	Oracle version 7.0 on <systemitem class="osname">AIX</> 3 uses OS-supported locks in shared
	memory that allow an application designer to link an application
	in a <quote>single tasking</quote> way. Instead of starting one client
	process per application process, both the database part and the
	application part run in the same process. In later versions of
	Oracle this is no longer supported.
d506 3
a508 3
	This would require a total redesign of the
	<productname>Postgres</productname> access model and the
	performance gain does not justify the effort.
d544 1
a544 1
	The standard syntax for FETCH is:
d547 1
a547 1
	FETCH [direction] [amount] IN|FROM <replaceable>cursor</replaceable>.
d550 3
a552 3
	<application>ORACLE</application>, however, does not use the keywords IN
	or FROM. This feature cannot be added since it would create parsing
	conflicts.
d579 5
a583 5
	<para>
	 to_date et al. does not exist. However,
	 <productname>Postgres</productname> has some good conversion
	 routines so you probably won't miss them.
	</para>
d590 4
a593 4
	<para>
	 Structures and unions have to be defined in the
	 <command>declare</> section.
	</para>
d600 23
a622 26
	<para>
	 The following statements are not implemented thus far:
	 <variablelist>
	  <varlistentry>
	   <term><literal>exec sql allocate</></term>
	   <listitem>
	    <para>
	    </para>
	   </listitem>
	  </varlistentry>
	  <varlistentry>
	   <term><literal>exec sql deallocate</></term>
	   <listitem>
	    <para>
	    </para>
	   </listitem>
	  </varlistentry>
	  <varlistentry>
	   <term><literal>SQLSTATE</></term>
	   <listitem>
	    <para>
	    </para>
	   </listitem>
	  </varlistentry>
	 </variablelist>
	</para>
d629 3
a631 3
	<para>
	 The error message for <quote>no data</quote> in:
	 <programlisting>
d633 3
a635 3
	</programlisting>
	 has to be <literal>100</>.
	</para>
d642 5
a646 5
	<para>
	 <literal>sqlwarn[6]</literal> should be <literal>W</> if the <command>PRECISION</>
	 or <command>SCALE</> value specified in a <command>SET
	 DESCRIPTOR</> statement was ignored.
	</para>
d676 3
a678 3
	<para>
	 <command>Declare</> sections begin with:
	 <programlisting>
d680 3
a682 3
	 </programlisting>
	 and end with:
	 <programlisting>
d684 23
a706 23
	 </programlisting>
	 In this section only variable declarations are allowed. Every
	 variable declared within this section is stored in a list
	 of variables indexed by name together with its corresponding
	 type.
	</para>

	<para>
	 In particular the definition of a structure or union also must
	 be listed inside a <command>declare</> section. Otherwise
	 <application>ecpg</application> cannot handle these types since
	 it does not know the definition.
	</para>

	<para>
	 The declaration is also echoed to the file to make it a normal
	 C variable.
	</para>

	<para>
	 The special types <type>VARCHAR</type> and <type>VARCHAR2</type> are converted into a named struct
	 for every variable. A declaration like:
	 <programlisting>
d708 3
a710 3
	 </programlisting>
	 is converted into:
	 <programlisting>
d712 2
a713 2
	 </programlisting>
	</para>
d720 3
a722 3
	<para>
	 An include statement looks like:
	 <programlisting>
d724 3
a726 3
	 </programlisting>
	 Note that this is NOT the same as:
	 <programlisting>
d728 2
a729 2
	 </programlisting>
	</para>
d731 6
a736 6
	<para>
	 Instead the file specified is parsed by
	 <application>ecpg</application> so the contents of the file are
	 included in the resulting C code. This way you are able to
	 specify EXEC SQL commands in an include file.
	</para>
d743 3
a745 3
	<para>
	 A connect statement looks like:
	 <programlisting>
d747 91
a837 76
	 </programlisting>
	 It creates a connection to the specified database.
	</para>

	<para>
	 The <replaceable>connection target</replaceable> can be specified in the
	 following ways:
	 <variablelist>
	  <varlistentry>
	   <term>dbname[@@server][:port][as <replaceable>connection
	     name</replaceable>][user <replaceable>user name</replaceable>]</term>
	   <listitem><para></para></listitem>
	  </varlistentry>

	  <varlistentry>
	   <term>tcp:postgresql://server[:port][/dbname][as
	    <replaceable>connection name</replaceable>][user <replaceable>user name</replaceable>]</term>
	   <listitem><para></para></listitem>
	  </varlistentry>

	  <varlistentry>
	   <term>unix:postgresql://server[:port][/dbname][as
	    <replaceable>connection name</replaceable>][user <replaceable>user name</replaceable>]</term>
	   <listitem><para></para></listitem>
	  </varlistentry>

	  <varlistentry>
	   <term><replaceable>character variable</replaceable>[as
	    <replaceable>connection name</replaceable>][user <replaceable>user name</replaceable>]</term>
	   <listitem><para></para></listitem>
	  </varlistentry>

	  <varlistentry>
	   <term><replaceable>character string</replaceable>[as
	    <replaceable>connection name</replaceable>][<replaceable>user</replaceable>]</term>
	   <listitem><para></para></listitem>
	  </varlistentry>

	  <varlistentry>
	   <term>default</term>
	   <listitem><para></para></listitem>
	  </varlistentry>

	  <varlistentry>
	   <term>user</term>
	   <listitem><para></para></listitem>
	  </varlistentry>
	 </variablelist>
	</para>

	<para>
	 There are also different ways to specify the user name:
	 <variablelist>
	  <varlistentry>
	   <term><replaceable>userid</replaceable></term>
	   <listitem><para></para></listitem>
	  </varlistentry>
	  <varlistentry>
	   <term><replaceable>userid</replaceable>/<replaceable>password</replaceable></term>
	   <listitem><para></para></listitem>
	  </varlistentry>
	  <varlistentry>
	   <term><replaceable>userid</replaceable> identified by <replaceable>password</replaceable></term>
	   <listitem><para></para></listitem>
	  </varlistentry>
	  <varlistentry>
	   <term><replaceable>userid</replaceable> using <replaceable>password</replaceable></term>
	   <listitem><para></para></listitem>
	  </varlistentry>
	 </variablelist>
	</para>

	<para> 
	 Finally, the <replaceable>userid</replaceable> and <replaceable>password</replaceable> may be a constant text, a
	 character variable, or a character string.
	</para>
d844 3
a846 3
	<para>
	 A disconnect statement looks like:
	 <programlisting>
d848 34
a881 26
	 </programlisting>
	 It closes the connection to the specified database.
	</para>

	<para>
	 The <replaceable>connection target</replaceable> can be specified in the
	 following ways:
	 <variablelist>
	  <varlistentry>
	   <term><replaceable>connection name</replaceable></term>
	   <listitem><para></para></listitem>
	  </varlistentry>
	  <varlistentry>
	   <term>default</term>
	   <listitem><para></para></listitem>
	  </varlistentry>
	  <varlistentry>
	   <term>current</term>
	   <listitem><para></para></listitem>
	  </varlistentry>
	  <varlistentry>
	   <term>all</term>
	   <listitem><para></para></listitem>
	  </varlistentry>
	 </variablelist>
	</para>
d888 3
a890 3
	<para>
	 An open cursor statement looks like:
	 <programlisting>
d892 5
a896 5
	 </programlisting>
	 and is not copied to the output. Instead, the cursor's
	 <command>DECLARE</> command is used because it opens the cursor
	 as well.
	</para>
d903 3
a905 3
	<para>
	 A commit statement looks like:
	 <programlisting>
d907 2
a908 2
	 </programlisting>
	</para>
d915 3
a917 3
	<para>
	 A rollback statement looks like:
	 <programlisting>
d919 2
a920 2
	 </programlisting>
	</para>
d927 84
a1010 35
	<para>
	 Other <acronym>SQL</acronym> statements are used by
	 starting with <command>exec sql</command> and ending with
	 <command>;</command>. Everything in between is treated as an
	 <acronym>SQL</acronym> statement and parsed for variable
	 substitution.
	</para>

	<para>
	 Variable substitution occurs when a symbol starts with a colon
	 (<command>:</command>). The variable with that name is looked
	 up among the variables that were previously declared within a
	 <command>declare</> section. Depending on whether the variable is
	 being use for input or output, a pointer to the variable is
	 output to allow access by the function.
	</para>

	<para>
	 For every variable that is part of the <acronym>SQL</acronym>
	 query, the function gets other arguments:

	 <simplelist>
	  <member>The type as a special symbol.</member>
	  <member>A pointer to the value or a pointer to the pointer.</member>
	  <member>The size of the variable if it is a <type>char</type> or <type>varchar</type>.</member>
	  <member>The number of elements in the array (for array fetches).</member>
	  <member>The offset to the next element in the array (for array fetches).</member>
	  <member>The type of the indicator variable as a special symbol.</member>
	  <member>A pointer to the value of the indicator variable or a pointer to the pointer of the indicator variable.</member>
	  <member>0.</member>
	  <member>Number of elements in the indicator array (for array fetches).</member>
	  <member>The offset to the next element in the indicator array
	  (for array fetches).</member>
	 </simplelist>
	</para>
d1024 1
a1024 1
     <programlisting>
d1031 1
a1031 1
     </programlisting>
d1033 1
a1033 1
     <programlisting>
d1048 1
a1048 1
	ECPGt_int,&amp;(index),1L,1L,sizeof(int),
d1053 1
a1053 1
     </programlisting>
d1077 3
a1079 3
	<para>
	 This is a line number of the original line; used in error messages only.
	</para>
d1086 7
a1092 7
	<para>
	 This is the <acronym>SQL</acronym> query that is to be issued.
	 It is modified by the input variables, i.e. the variables that
	 where not known at compile time but are to be entered in the
	 query. Where the variables should go the string contains
	 <literal>?</literal>.
	</para>
d1099 4
a1102 4
	<para>
	 As described in the section about the preprocessor, every input variable
	 gets ten arguments.
	</para>
d1109 3
a1111 3
	<para>
	 An enum telling that there are no more input variables.
	</para>
d1118 4
a1121 4
	<para>
	 As described in the section about the preprocessor, every input variable
	 gets ten arguments. These variables are filled by the function.
	</para>
d1128 3
a1130 3
	<para>
	 An enum telling that there are no more variables.
	</para>
@


1.25
log
@Document all the ecpg error codes.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.24 2001/10/11 20:25:42 momjian Exp $
d227 1
a227 1
       <term><computeroutput>-200 (ECPG_UNSUPPORTED), Unsupported type %s on line %d.</computeroutput></term>
d239 1
a239 1
       <term><computeroutput>-201 (ECPG_TOO_MANY_ARGUMENTS), Too many arguments line %d.</computeroutput></term>
d251 1
a251 1
       <term><computeroutput>-202 (ECPG_TOO_FEW_ARGUMENTS), Too few arguments line %d.</computeroutput></term>
d263 1
a263 1
       <term><computeroutput>-203 (ECPG_TOO_MANY_MATCHES), Too many matches line %d.</computeroutput></term>
d274 1
a274 1
       <term><computeroutput>-204 (ECPG_INT_FORMAT), Not correctly formatted int type: %s line %d.</computeroutput></term>
d287 1
a287 1
       <term><computeroutput>-205 (ECPG_UINT_FORMAT), Not correctly formatted unsigned type: %s line %d.</computeroutput></term>
d301 1
a301 1
       <term><computeroutput>-206 (ECPG_FLOAT_FORMAT), Not correctly formatted floating point type: %s line %d.</computeroutput></term>
d314 1
a314 1
       <term><computeroutput>-207 (ECPG_CONVERT_BOOL), Unable to convert %s to bool on line %d.</computeroutput></term>
d325 1
a325 1
       <term><computeroutput>-208 (ECPG_EMPTY), Empty query line %d.</computeroutput></term>
d335 1
a335 1
       <term><computeroutput>-209 (ECPG_MISSING_INDICATOR), NULL value without indicator in line %d.</computeroutput></term>
d345 1
a345 1
       <term><computeroutput>-210 (ECPG_NO_ARRAY), Variable is not an array in line %d.</computeroutput></term>
d356 1
a356 1
       <term><computeroutput>-211 (ECPG_DATA_NOT_ARRAY), Data read from backend is not an array in line %d.</computeroutput></term>
d367 1
a367 1
       <term><computeroutput>-220 (ECPG_NO_CONN), No such connection %s in line %d.</computeroutput></term>
d376 1
a376 1
       <term><computeroutput>-221 (ECPG_NOT_CONN), Not connected in line %d.</computeroutput></term>
d386 1
a386 1
       <term><computeroutput>-230 (ECPG_INVALID_STMT), Invalid statement name %s in line %d.</computeroutput></term>
d395 1
a395 1
       <term><computeroutput>-240 (ECPG_UNKNOWN_DESCRIPTOR), Descriptor %s not found in line %d.</computeroutput></term>
d404 1
a404 1
       <term><computeroutput>-241 (ECPG_INVALID_DESCRIPTOR_INDEX), Descriptor index out of range in line %d.</computeroutput></term>
d413 1
a413 1
       <term><computeroutput>-242 (ECPG_UNKNOWN_DESCRIPTOR_ITEM), Descriptor %s not found in line %d.</computeroutput></term>
d422 1
a422 1
       <term><computeroutput>-243 (ECPG_VAR_NOT_NUMERIC), Variable is not a numeric type in line %d.</computeroutput></term>
d432 1
a432 1
       <term><computeroutput>-244 (ECPG_VAR_NOT_CHAR), Variable is not a character type in line %d.</computeroutput></term>
d442 1
a442 1
       <term><computeroutput>-400 (ECPG_PGSQL), Postgres error: %s line %d.</computeroutput></term>
d453 1
a453 1
       <term><computeroutput>-401 (ECPG_TRANS), Error in transaction processing line %d.</computeroutput></term>
d463 1
a463 1
       <term><computeroutput>-402 (ECPG_CONNECT), Could not connect to database %s in line %d.</computeroutput></term>
d472 1
a472 1
       <term><computeroutput>100 (ECPG_NOT_FOUND), Data not found line %d.</computeroutput></term>
@


1.24
log
@Add documention for ecpg -209 error.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.23 2001/09/13 15:55:22 petere Exp $
d198 3
a200 3
     If an error occurred in the last <acronym>SQL</acronym> statement.
     <parameter>sqlca.sqlcode</parameter> will be non-zero. If
     <parameter>sqlca.sqlcode</parameter> is less that 0, this is a
d202 1
a202 1
     query. If it is greater than 0, it is a normal error like the
d213 1
a213 1
     List of errors that can occur:
d227 1
a227 1
       <term><computeroutput>-200, Unsupported type %s on line %d.</computeroutput></term>
d239 1
a239 1
       <term><computeroutput>-201, Too many arguments line %d.</computeroutput></term>
d251 1
a251 1
       <term><computeroutput>-202, Too few arguments line %d.</computeroutput></term>
d263 1
a263 1
       <term><computeroutput>-203, Too many matches line %d.</computeroutput></term>
d274 1
a274 1
       <term><computeroutput>-204, Not correctly formatted int type: %s line %d.</computeroutput></term>
d287 1
a287 1
       <term><computeroutput>-205, Not correctly formatted unsigned type: %s line %d.</computeroutput></term>
d301 1
a301 1
       <term><computeroutput>-206, Not correctly formatted floating point type: %s line %d.</computeroutput></term>
d314 1
a314 1
       <term><computeroutput>-207, Unable to convert %s to bool on line %d.</computeroutput></term>
d325 1
a325 1
       <term><computeroutput>-208, Empty query line %d.</computeroutput></term>
d335 1
a335 1
       <term><computeroutput>-209, NULL value without indicator in line %d.</computeroutput></term>
d345 23
a367 1
       <term><computeroutput>-220, No such connection %s in line %d.</computeroutput></term>
d376 1
a376 1
       <term><computeroutput>-221, Not connected in line %d.</computeroutput></term>
d386 1
a386 1
       <term><computeroutput>-230, Invalid statement name %s in line %d.</computeroutput></term>
d395 48
a442 1
       <term><computeroutput>-400, Postgres error: %s line %d.</computeroutput></term>
d453 1
a453 1
       <term><computeroutput>-401, Error in transaction processing line %d.</computeroutput></term>
d463 1
a463 1
       <term><computeroutput>-402, connect: could not open database %s.</computeroutput></term>
d472 1
a472 1
       <term><computeroutput>100, Data not found line %d.</computeroutput></term>
@


1.23
log
@Replace ASCII-quotes with proper markup.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.22 2001/09/10 21:58:46 petere Exp $
d330 10
@


1.22
log
@Markup and spell-check run over Programmer's Guide (rather incomplete still).
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.21 2001/09/06 00:23:42 momjian Exp $
d117 1
a117 1
     The library has some methods that are "hidden" but may prove
d319 1
a319 1
	 is neither 't' nor 'f'.
d396 1
a396 1
	 This is a "normal" error that tells you that what you are querying cannot
d424 1
a424 1
	in a "single tasking" way. Instead of starting one client
d558 1
a558 1
	 The error message for "no data" in:
@


1.21
log
@Overhaul ecpg manual page.

Update Italian jdbc error messages.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.20 2001/08/26 17:04:02 momjian Exp $
d156 1
a156 1
     <programlisting>
d158 1
a158 1
     </programlisting>
d161 1
a161 1
     <programlisting>
d194 1
a194 1
     </programlisting>
d198 1
a198 1
     If an error occured in the last <acronym>SQL</acronym> statement.
d217 1
a217 1
       <term>-12, Out of memory in line %d.</term>
d227 1
a227 1
       <term>-200, Unsupported type %s on line %d.</term>
d239 1
a239 1
       <term>-201, Too many arguments line %d.</term>
d251 1
a251 1
       <term>-202, Too few arguments line %d.</term>
d263 1
a263 1
       <term>-203, Too many matches line %d.</term>
d274 1
a274 1
       <term>-204, Not correctly formatted int type: %s line %d.</term>
d287 1
a287 1
       <term>-205, Not correctly formatted unsigned type: %s line %d.</term>
d301 1
a301 1
       <term>-206, Not correctly formatted floating point type: %s line %d.</term>
d314 1
a314 1
       <term>-207, Unable to convert %s to bool on line %d.</term>
d325 1
a325 1
       <term>-208, Empty query line %d.</term>
d328 1
a328 1
	 <productname>Postgres</productname> returned PGRES_EMPTY_QUERY, probably
d335 1
a335 1
       <term>-220, No such connection %s in line %d.</term>
d344 1
a344 1
       <term>-221, Not connected in line %d.</term>
d354 1
a354 1
       <term>-230, Invalid statement name %s in line %d.</term>
d363 1
a363 1
       <term>-400, Postgres error: %s line %d.</term>
d374 1
a374 1
       <term>-401, Error in transaction processing line %d. </term>
d384 1
a384 1
       <term>-402, connect: could not open database %s.</term>
d393 1
a393 1
       <term>100, Data not found line %d.</term>
d396 1
a396 1
	 This is a "normal" error that tells you that what you are quering cannot
d422 1
a422 1
	Oracle version 7.0 on AIX 3 uses OS-supported locks in shared
d529 1
a529 1
	   <term> exec sql allocate</term>
d536 1
a536 1
	   <term> exec sql deallocate</term>
d543 1
a543 1
	   <term> SQLSTATE</term>
d568 1
a568 1
       <term>sqlwarn[6]</term>
d571 1
a571 1
	 sqlwarn[6] should be <literal>W</> if the <command>PRECISION</>
d585 1
a585 1
     The first four lines written by ecpg to the output are fixed lines.
d632 1
a632 1
	 The special types VARCHAR and VARCHAR2 are converted into a named struct
d748 1
a748 1
	 Finally, the userid and password may be a constant text, a
d856 1
a856 1
	  <member>The size of the variable if it is a char or varchar.</member>
d879 1
a879 1
     file foo.pgc:
d922 1
a922 1
     number of variables that can be accepted by a varargs() function. This
d963 1
a963 1
       <term>ECPGt_EOIT</term>
@


1.20
log
@Back out "Remove outdated documentation section of ecpg." for Michael.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.18 2000/12/22 21:51:57 petere Exp $
d32 6
a37 12
   This describes an embedded <acronym>SQL</acronym> in <acronym>C</acronym> 
   package for <productname>Postgres</productname>.
   It was written by Linus Tolke (<email>linus@@epact.se</email>)
   and Michael Meskes (<email>meskes@@debian.org</email>).
   The package is installed with the <productname>Postgres</> distribution.

   <note>
    <para>
     Permission is granted to copy and use in the same way as you are allowed
     to copy and use the rest of <productname>PostgreSQL</productname>.
    </para>
   </note>
d44 5
a48 6
    Embedded <acronym>SQL</acronym> has some small advantages over other ways 
    to handle <acronym>SQL</acronym>
    queries. It takes care of all the tedious moving of information to and
    from variables in your <acronym>C</acronym> program. 
    Many <acronym>RDBMS</acronym> packages
    support this embedded language.
d51 6
a56 7
   <para> There is an ANSI-standard describing how the embedded language should
    work. <application>ecpg</application> was designed to meet this standard 
    as much as possible. So it is
    possible to port programs with embedded <acronym>SQL</acronym> written for
    other <acronym>RDBMS</acronym> packages to
    <productname>Postgres</productname> and thus promoting the spirit of free
    software.
d64 5
a68 6
    You write your program in <acronym>C</acronym> with some 
    special <acronym>SQL</acronym> things.
    For declaring variables that can be used in 
    <acronym>SQL</acronym> statements you need to
    put them in a special declare section.
    You use a special syntax for the <acronym>SQL</acronym> queries.
d72 5
a76 8
    Before compiling you run the file through 
    the embedded <acronym>SQL</acronym> <acronym>C</acronym>
    preprocessor and it converts the <acronym>SQL</acronym> statements you used 
    to function
    calls with the variables used as arguments. Both variables that are used
    as input to the <acronym>SQL</acronym> statements and variables that will 
    contain the
    result are passed.
d80 5
a84 14
    Then you compile and at link time you link with a special library that
    contains the functions used. These functions (actually it is mostly one
    single function) fetches the information from the arguments, performs
    the <acronym>SQL</acronym> query using the ordinary interface 
    (<filename>libpq</filename>) and puts back
    the result in the arguments dedicated for output.
   </para>

   <para>
    Then you run your program and when the control arrives to 
    the <acronym>SQL</acronym>
    statement the <acronym>SQL</acronym> statement is performed against 
    the database and you
    can continue with the result.
d92 1
a92 1
    This section describes how to use the <application>ecpg</application> tool.
d99 3
a101 3
     The preprocessor is called <application>ecpg</application>. 
     After installation it resides in
     the <productname>Postgres</productname> <filename>bin/</filename> directory. 
d108 6
a113 6
     The <application>ecpg</application> library is called 
     <filename>libecpg.a</filename> or
     <filename>libecpg.so</filename>. Additionally, the library
     uses the <filename>libpq</filename> library for communication to the 
     <productname>Postgres</productname> server so you will
     have to link your program with <parameter>-lecpg -lpq</parameter>.
d117 2
a118 2
     The library has some methods that are "hidden" but that could prove very
     useful sometime.
d124 4
a127 4
	 *<replaceable>stream</replaceable>)</function>
	turns on debug logging if called with the first argument non-zero.
	Debug logging is done on <replaceable>stream</replaceable>.
	Most <acronym>SQL</acronym> statement logs its arguments and result.
d131 6
a136 8
	The most important one (<function>ECPGdo</function>) 
	that is called on almost all <acronym>SQL</acronym>
	statements logs both its expanded string,
	i.e. the string
	with all the input variables inserted, and the result from the
	<productname>Postgres</productname> server.
	This can be very useful when searching for errors
	in your <acronym>SQL</acronym> statements.
d154 2
a155 2
     To be able to detect errors from the <productname>Postgres</productname> 
     server you include a line like
d157 1
a157 1
      exec sql include sqlca;
d159 2
a160 2
     in the include section of your file. This will define a struct and a
     variable with the name <parameter>sqlca</parameter> as following:
d198 6
a203 7
     If an error occured in the last <acronym>SQL</acronym> statement 
     then <parameter>sqlca.sqlcode</parameter>
     will be non-zero. If <parameter>sqlca.sqlcode</parameter> is less that 0
     then this is
     some kind of serious error, like the database definition does not match
     the query given. If it is bigger than 0 then this is a normal error like
     the table did not contain the requested row.
d207 3
a209 3
     sqlca.sqlerrm.sqlerrmc will contain a string that describes the error.
     The string ends with the line number
     in the source file.
d220 1
a220 1
	 Does not normally occur. This is a sign that your virtual memory is
d230 4
a233 3
	 Does not normally occur. This is a sign that the preprocessor has
	 generated something that the library does not know about. Perhaps you
	 are running incompatible versions of the preprocessor and the library.
d242 4
a245 4
	 This means that <productname>Postgres</productname> has returned more
	 arguments than we have
	 matching variables. Perhaps you have forgotten a couple of the host
	 variables in the <command>INTO :var1,:var2</command>-list.
d254 4
a257 4
	 This means that <productname>Postgres</productname> has returned fewer
	 arguments than we have
	 host variables. Perhaps you have too many host variables in the 
	 <command>INTO :var1,:var2</command>-list.
d266 3
a268 3
	 This means that the query has returned several lines but the
	 variables specified are no arrays. The <command>SELECT</command> you made
	 probably was not unique.
d277 5
a281 5
	 This means that the host variable is of an <type>int</type> type and the field
	 in the <productname>Postgres</productname> database is of another type and 
	 contains a value that cannot be interpreted as an <type>int</type>. 
	 The library uses <function>strtol</function>
	 for this conversion.
d290 6
a295 5
	 This means that the host variable is of an <type>unsigned int</type> type and
	 the field in the <productname>Postgres</productname> database is of another 
	 type and contains a
	 value that cannot be interpreted as an <type>unsigned int</type>. The library
	 uses <function>strtoul</function> for this conversion.
d304 5
a308 5
	 This means that the host variable is of a <type>float</type> type and
	 the field in the <productname>Postgres</productname> database is of another 
	 type and contains a
	 value that cannot be interpreted as an <type>float</type>. The library
	 uses <function>strtod</function> for this conversion.
d317 3
a319 3
	 This means that the host variable is of a <type>bool</type> type and
	 the field in the <productname>Postgres</productname> database is neither 't'
	 nor 'f'.
d338 1
a338 1
	 The program tries to access a connection that does not exist.
d347 2
a348 1
	 The program tries to access a connection that does exist but is not open.
d377 1
a377 1
	 <productname>Postgres</productname> signalled to us that we cannot start,
d397 1
a397 1
	 be found or we have gone through the cursor.
d412 1
a412 2
     What will never be included and why or what cannot be done with this
     concept.
d419 1
a419 1
      <term>Oracle's single tasking possibility</term>
d422 6
a427 6
	Oracle version 7.0 on AIX 3 uses the OS-supported locks on the shared
	memory segments and allows the application designer to link an
	application in a so called single tasking way. Instead of starting one
	client process per application process both the database part and the
	application part is run in the same process. In later versions of Oracle
	this is no longer supported.
d432 2
a433 2
	<productname>Postgres</productname> access model and
	that effort can not justify the performance gained.
d445 6
a450 5
    The design of <application>ecpg</application> follows SQL standard. So
    porting from a standard RDBMS should not be a problem. Unfortunately there
    is no such thing as a standard RDBMS. So <application>ecpg</application>
    also tries to understand syntax additions as long as they do not create
    conflicts with the standard. 
d454 7
a460 7
    The following list shows all the known incompatibilities. If you find one
    not listed please notify 
    <ulink url="meskes@@debian.org">Michael Meskes</ulink>.
    Note, however, that we list only incompatibilities from
    a precompiler of another RDBMS to <application>ecpg</application> and not
    additional <application>ecpg</application> features that these RDBMS do not
    have.
d466 1
a466 1
      <term>Syntax of FETCH command</term>
d469 1
a469 1
	The standard syntax of the FETCH command is:
d472 1
a472 1
	FETCH [direction] [amount] IN|FROM <replaceable>cursor name</replaceable>.
d476 1
a476 1
	resp. FROM. This feature cannot be added since it would create parsing
d489 3
a491 9
    This section is for those who want to develop the 
    <application>ecpg</application> interface. It
    describes how the things work. The ambition is to make this section
    contain things for those that want to have a look inside and the section
    on How to use it should be enough for all normal questions.

    So, read this before looking at the internals of the 
    <application>ecpg</application>. If
    you are not interested in how it really works, skip this section.
d498 1
a498 1
     This version the preprocessor has some flaws:
d505 3
a507 2
	 to_date et al. do not exists. But then <productname>Postgres</productname>
	 has some good conversion routines itself. So you probably won't miss these.
d513 1
a513 1
       <term>Structures ans unions</term>
d516 2
a517 1
	 Structures and unions have to be defined in the declare section.
d558 5
a562 2
	 The error message for "no data" in an exec sql insert select from statement
	 has to be 100.
d571 3
a573 2
	 sqlwarn[6] should be 'W' if the PRECISION or SCALE value specified in a SET
	 DESCRIPTOR statement will be ignored.
d585 3
a587 3
     The first four lines written to the output are constant additions by ecpg.
     These are two comments and two include lines necessary for the interface to the
     library.
d591 2
a592 3
     Then the preprocessor works in one pass only, reading the input file and
     writing to the output as it goes along. Normally it just echoes
     everything to the output without looking at it further.
d596 3
a598 3
     When it comes to an <command>EXEC SQL</command> statements it intervenes and
     changes them depending on what it is. 
     The <command>EXEC SQL</command> statement can be one of these:
d605 1
a605 1
	 Declare sections begins with
d609 1
a609 1
	 and ends with
d613 4
a616 3
	 In the section only variable declarations are allowed. Every variable
	 declare within this section is also entered in a list of variables
	 indexed on their name together with the corresponding type.
d620 4
a623 3
	 In particular the definition of a structure or union also has to be listed
	 inside a declare section. Otherwise <application>ecpg</application> cannot
	 handle these types since it simply does not know the definition.
d627 2
a628 2
	 The declaration is echoed to the file to make the variable a normal
	 C-variable also.
d637 1
a637 1
	 is converted into
d653 1
a653 1
	 Note that this is NOT the same as
d660 4
a663 3
	 Instead the file specified is parsed by <application>ecpg</application>
	 itself. So the contents of the specified file is included in the resulting C
	 code. This way you are able to specify EXEC SQL commands in an include file.
d747 3
a749 2
	<para> Finally the userid and the password. Each may be a constant text, a
	 character variable or a chararcter string.
d758 1
a758 1
	 A disconnect statement looks loke:
a789 1
      <!--WARNING: FROM HERE ON THE TEXT IS OUTDATED!-->
d798 3
a800 1
	 and is ignore and not copied from the output.
d809 1
a809 1
	 A commit statement looks like
a812 4
	 and is translated on the output to
	 <programlisting>
ECPGcommit(__LINE__);
	 </programlisting>
d821 1
a821 1
	 A rollback statement looks like
a824 4
	 and is translated on the output to
	 <programlisting>
ECPGrollback(__LINE__);
	 </programlisting>
a828 1
      <!--STARTING HERE IT IS OKAY AGAIN!-->
d833 5
a837 4
	 Other <acronym>SQL</acronym> statements are other statements that start with 
	 <command>exec sql</command> and ends with <command>;</command>. 
	 Everything inbetween is treated
	 as an <acronym>SQL</acronym> statement and parsed for variable substitution.
d841 6
a846 5
	 Variable substitution occur when a symbol starts with a colon
	 (<command>:</command>). Then a variable with that name is looked for among
	 the variables that were previously declared within a declare section and
	 depending on the variable being for input or output the pointers to the
	 variables are written to the output to allow for access by the function.
d850 2
a851 2
	 For every variable that is part of the <acronym>SQL</acronym> request 
	 the function gets another ten arguments:
d857 2
a858 2
	  <member>Number of elements in the array (for array fetches).</member>
	  <member>The offset to the next element in the array (for array fetches)</member>
d863 2
a864 1
	  <member>The offset to the next element in the indicator array (for array fetches)</member>
a908 1

d910 2
a911 2
     (the indentation in this manual is added for readability and not
     something that the preprocessor can do.)
d919 5
a923 5
     The most important function in the library is the <function>ECPGdo</function>
     function. It takes a variable amount of arguments. Hopefully we will not run
     into machines with limits on the amount of variables that can be
     accepted by a vararg function. This could easily add up to 50 or so
     arguments.
d934 1
a934 1
	 This is a line number for the original line used in error messages only.
d943 5
a947 5
	 This is the <acronym>SQL</acronym> request that is to be issued. 
	 This request is modified
	 by the input variables, i.e. the variables that where not known at
	 compile time but are to be entered in the request. Where the variables
	 should go the string contains ";".
d956 1
a956 1
	 As described in the section about the preprocessor every input variable
d975 1
a975 1
	 As described in the section about the preprocessor every input variable
d993 6
a998 5
     All the <acronym>SQL</acronym> statements are performed in one transaction
     unless you issue a commit transaction. To get this auto-transaction going
     the first statement or the first after statement after a commit or rollback
     always begins a transaction. To disable this feature per default use the
     <option>-t</option> option on the commandline.
a1000 3
    <para>
     To be completed: entries describing the other entries.
    </para>
@


1.19
log
@Remove outdated documentation section of ecpg.
@
text
@d808 47
@


1.18
log
@Make use of <email> tag for marking up email addresses.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.17 2000/09/29 20:21:33 petere Exp $
a807 47
      <!--WARNING: FROM HERE ON THE TEXT IS OUTDATED!-->
      <varlistentry>
       <term>Open cursor statement</term>
       <listitem>
	<para>
	 An open cursor statement looks like:
	 <programlisting>
exec sql open <replaceable>cursor</replaceable>;
	 </programlisting>
	 and is ignore and not copied from the output.
	</para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>Commit statement</term>
       <listitem>
	<para>
	 A commit statement looks like
	 <programlisting>
exec sql commit;
	 </programlisting>
	 and is translated on the output to
	 <programlisting>
ECPGcommit(__LINE__);
	 </programlisting>
	</para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>Rollback statement</term>
       <listitem>
	<para>
	 A rollback statement looks like
	 <programlisting>
exec sql rollback;
	 </programlisting>
	 and is translated on the output to
	 <programlisting>
ECPGrollback(__LINE__);
	 </programlisting>
	</para>
       </listitem>
      </varlistentry>

      <!--STARTING HERE IT IS OKAY AGAIN!-->
@


1.17
log
@Add `id' attributes to all `chapter' and `sect1' tags, to generate useful
names for the HTML files (e.g., not x4856.htm).
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.16 2000/09/18 20:11:36 petere Exp $
d34 2
a35 2
   It is written by <ulink url="mailto:linus@@epact.se">Linus Tolke</ulink>
   and <ulink url="mailto:meskes@@debian.org">Michael Meskes</ulink>.
@


1.16
log
@Move contrib/odbc/odbc.sql together with odbc driver, remove old files;
revise ODBC "installation instructions"; update some other outdated
documentation; update contrib documentation
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.15 2000/08/23 05:59:01 thomas Exp $
d5 1
a5 1
 <chapter>
d46 1
a46 1
  <sect1>
d68 1
a68 1
  <sect1>
d109 1
a109 1
  <sect1>
d428 1
a428 1
  <sect1>
d463 1
a463 1
  <sect1>
d506 1
a506 1
  <sect1>
@


1.15
log
@Fix several <ulink> tags which refer to e-mail addresses
 but were missing the "mailto:" prefix.
Fix typo.
Thanks to Neil Conway <nconway@@klamath.dyndns.org> for the heads-up.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.14 2000/05/02 20:01:51 thomas Exp $
a33 1

d36 1
a502 11
   </para>
  </sect1>

  <sect1>
   <title>Installation</title>

   <para>
    Since version 0.5 <application>ecpg</application> is distributed 
    together with <productname>Postgres</productname>. So you
    should get your precompiler, libraries and header files compiled and
    installed by default as a part of your installation.
@


1.14
log
@Fixups in content and markup for 7.0 release.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.13 2000/03/31 03:27:40 thomas Exp $
d35 2
a36 2
   It is written by <ulink url="linus@@epact.se">Linus Tolke</ulink>
   and <ulink url="meskes@@debian.org">Michael Meskes</ulink>.
@


1.13
log
@Minor markup changes. Refer to (".../catalog") in the emacs hints.
@
text
@d2 1
a2 1
$Header$
d35 2
a36 2
   It is written by <ulink url="">Linus Tolke</ulink>
   and <ulink url="">Michael Meskes</ulink>.
d41 1
a41 1
     to copy and use the rest of the <productname>PostgreSQL</productname>.
d45 1
d476 3
a478 2
    not listed please notify <ulink url="">Michael
     Meskes</ulink>. Note, however, that we list only incompatibilities from
d982 1
a982 1
	 should go the string contains <quote>;</quote>.
@


1.12
log
@Accumulated fixups.
Add some chapters on new topics.
Change to referencing OASIS/Docbook v3.1 rather than Davenport/Docbook v3.0
Grepped for and fixed apparent tag mangling from emacs
 "Normalize" operation. Should be the last of those.
@
text
@d1 4
d1052 1
a1052 1
sgml-local-catalogs:("/usr/lib/sgml/CATALOG")
@


1.11
log
@*** empty log message ***
@
text
@d1 179
a179 177
<Chapter Id="ecpg">
<DocInfo>
<AuthorGroup>
<Author>
<FirstName>Linus</FirstName>
<Surname>Tolke</Surname>
</Author>
<Author>
<FirstName>Michael</FirstName>
<Surname>Meskes</Surname>
</Author>
</AuthorGroup>
<Copyright>
<Year>1996-1997</Year>
<Holder>Linus Tolke</Holder>
</Copyright>
<Copyright>
<Year>1998</Year>
<Holder>Michael Meskes</Holder>
</Copyright>
<Date>Transcribed 1998-02-12</Date>
</DocInfo>

<Title><Application>ecpg</Application> - Embedded <Acronym>SQL</Acronym> 
in <Acronym>C</Acronym></Title>

<Para>
This describes an embedded <Acronym>SQL</Acronym> in <Acronym>C</Acronym> 
package for <ProductName>Postgres</ProductName>.

It is written by <ULink url="mailto:linus@@epact.se">Linus Tolke</ULink>
and <ULink url="mailto:meskes@@postgresql.org">Michael Meskes</ULink>.

<Note>
<Para>
Permission is granted to copy and use in the same way as you are allowed
to copy and use the rest of the <ProductName>PostgreSQL</ProductName>.
</Para>
</Note>
</para>
<Sect1>
<Title>Why Embedded <Acronym>SQL</Acronym>?</Title>

<Para>
Embedded <Acronym>SQL</Acronym> has some small advantages over other ways 
to handle <Acronym>SQL</Acronym>
queries. It takes care of all the tedious moving of information to and
from variables in your <Acronym>C</Acronym> program. 
Many <Acronym>RDBMS</Acronym> packages
support this embedded language.
</Para>

<Para> There is an ANSI-standard describing how the embedded language should
work. <Application>ecpg</Application> was designed to meet this standard 
as much as possible. So it is
possible to port programs with embedded <Acronym>SQL</Acronym> written for
other <Acronym>RDBMS</Acronym> packages to
<ProductName>Postgres</ProductName> and thus promoting the spirit of free
software.
</Para>
</sect1>
<Sect1>
<Title>The Concept</Title>

<Para>
You write your program in <Acronym>C</Acronym> with some 
special <Acronym>SQL</Acronym> things.
For declaring variables that can be used in 
<Acronym>SQL</Acronym> statements you need to
put them in a special declare section.
You use a special syntax for the <Acronym>SQL</Acronym> queries.
</Para>

<Para>
Before compiling you run the file through 
the embedded <Acronym>SQL</Acronym> <Acronym>C</Acronym>
preprocessor and it converts the <Acronym>SQL</Acronym> statements you used 
to function
calls with the variables used as arguments. Both variables that are used
as input to the <Acronym>SQL</Acronym> statements and variables that will 
contain the
result are passed.
</Para>

<Para>
Then you compile and at link time you link with a special library that
contains the functions used. These functions (actually it is mostly one
single function) fetches the information from the arguments, performs
the <Acronym>SQL</Acronym> query using the ordinary interface 
(<FileName>libpq</FileName>) and puts back
the result in the arguments dedicated for output.
</Para>

<Para>
Then you run your program and when the control arrives to 
the <Acronym>SQL</Acronym>
statement the <Acronym>SQL</Acronym> statement is performed against 
the database and you
can continue with the result.
</Para>
</sect1>

<Sect1>
<Title>How To Use <Application>egpc</Application></Title>

<Para>
This section describes how to use the <Application>egpc</Application> tool.
</Para>

<Sect2>
<Title>Preprocessor</title>

<Para>
The preprocessor is called <Application>ecpg</Application>. 
After installation it resides in
the <ProductName>Postgres</ProductName> <FileName>bin/</FileName> directory. 
</Para>
</sect2>
<Sect2>
<Title>Library</title>

<Para>
The <Application>ecpg</Application> library is called 
<FileName>libecpg.a</FileName> or
<FileName>libecpg.so</FileName>. Additionally, the library
uses the <FileName>libpq</FileName> library for communication to the 
<ProductName>Postgres</ProductName> server so you will
have to link your program with <Parameter>-lecpg -lpq</Parameter>.
</Para>

<Para>
The library has some methods that are "hidden" but that could prove very
useful sometime.

<itemizedlist>
<listitem>
<para>
<function>ECPGdebug(int <replaceable class="parameter">on</replaceable>, FILE *<replaceable class="parameter">stream</replaceable>)</function>
turns on debug logging if called with the first argument non-zero.
Debug logging is done on <replaceable class="parameter">stream</replaceable>.
 Most <Acronym>SQL</Acronym> statement logs its arguments and result.
</Para>

<Para>
The most important one (<Function>ECPGdo</Function>) 
that is called on almost all <Acronym>SQL</Acronym>
statements logs both its expanded string,
 i.e. the string
with all the input variables inserted, and the result from the
<ProductName>Postgres</ProductName> server.
 This can be very useful when searching for errors
in your <Acronym>SQL</Acronym> statements.
</Para>
</ListItem>

<listitem>
<para>
<function>ECPGstatus()</function>
This method returns TRUE if we are connected to a database and FALSE if not.
</Para>
</ListItem>
</itemizedlist>
</Para>
</sect2>

<Sect2>
<Title>Error handling</title>

<Para>
To be able to detect errors from the <ProductName>Postgres</ProductName> 
server you include a line like
<ProgramListing>
exec sql include sqlca;
</ProgramListing>
in the include section of your file. This will define a struct and a
variable with the name <Parameter>sqlca</Parameter> as following:
<ProgramListing>
d212 2
a213 2
</ProgramListing>
</Para>
d215 419
a633 414
<Para>
If an error occured in the last <Acronym>SQL</Acronym> statement 
then <Parameter>sqlca.sqlcode</Parameter>
will be non-zero. If <Parameter>sqlca.sqlcode</Parameter> is less that 0
 then this is
some kind of serious error, like the database definition does not match
the query given. If it is bigger than 0 then this is a normal error like
the table did not contain the requested row.
</Para>

<Para>
sqlca.sqlerrm.sqlerrmc will contain a string that describes the error.
The string ends with the line number
in the source file.
</Para>

<Para>
List of errors that can occur:

<VariableList>
<VarListEntry>
<Term>-12, Out of memory in line %d.</Term>
<ListItem>
<Para>
Does not normally occur. This is a sign that your virtual memory is
exhausted.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>-200, Unsupported type %s on line %d.</Term>
<ListItem>
<Para>
Does not normally occur. This is a sign that the preprocessor has
generated something that the library does not know about. Perhaps you
are running incompatible versions of the preprocessor and the library.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>-201, Too many arguments line %d.</Term>
<ListItem>
<Para>
This means that <ProductName>Postgres</ProductName> has returned more
arguments than we have
matching variables. Perhaps you have forgotten a couple of the host
variables in the <Command>INTO :var1,:var2</Command>-list.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>-202, Too few arguments line %d.</Term>
<ListItem>
<Para>
This means that <ProductName>Postgres</ProductName> has returned fewer
arguments than we have
host variables. Perhaps you have too many host variables in the 
<Command>INTO :var1,:var2</Command>-list.
</Para> 
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>-203, Too many matches line %d.</Term>
<ListItem>
<Para>
This means that the query has returned several lines but the
variables specified are no arrays. The <Command>SELECT</Command> you made
probably was not unique.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>-204, Not correctly formatted int type: %s line %d.</Term>
<ListItem>
<Para>
This means that the host variable is of an <Type>int</Type> type and the field
in the <ProductName>Postgres</ProductName> database is of another type and 
contains a value that cannot be interpreted as an <Type>int</Type>. 
The library uses <Function>strtol</Function>
for this conversion.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>-205, Not correctly formatted unsigned type: %s line %d.</Term>
<ListItem>
<Para>
This means that the host variable is of an <Type>unsigned int</Type> type and
the field in the <ProductName>Postgres</ProductName> database is of another 
type and contains a
value that cannot be interpreted as an <Type>unsigned int</Type>. The library
uses <Function>strtoul</Function> for this conversion.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>-206, Not correctly formatted floating point type: %s line %d.</Term>
<ListItem>
<Para>
This means that the host variable is of a <Type>float</Type> type and
the field in the <ProductName>Postgres</ProductName> database is of another 
type and contains a
value that cannot be interpreted as an <Type>float</Type>. The library
uses <Function>strtod</Function> for this conversion.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>-207, Unable to convert %s to bool on line %d.</Term>
<ListItem>
<Para>
This means that the host variable is of a <Type>bool</Type> type and
the field in the <ProductName>Postgres</ProductName> database is neither 't'
nor 'f'.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>-208, Empty query line %d.</Term>
<ListItem>
<Para>
<ProductName>Postgres</ProductName> returned PGRES_EMPTY_QUERY, probably
because the query indeed was empty.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>-220, No such connection %s in line %d.</Term>
<ListItem>
<Para>
The program tries to access a connection that does not exist.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>-221, Not connected in line %d.</Term>
<ListItem>
<Para>
The program tries to access a connection that does exist but is not open.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>-230, Invalid statement name %s in line %d.</Term>
<ListItem>
<Para>
The statement you are trying to use has not been prepared.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>-400, Postgres error: %s line %d.</Term>
<ListItem>
<Para>
Some <ProductName>Postgres</ProductName> error. 
The message contains the error message from the
<ProductName>Postgres</ProductName> backend.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>-401, Error in transaction processing line %d. </Term>
<ListItem>
<Para>
<ProductName>Postgres</ProductName> signalled to us that we cannot start,
commit or rollback the transaction.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>-402, connect: could not open database %s.</Term>
<ListItem>
<Para>
The connect to the database did not work.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>100, Data not found line %d.</Term>
<ListItem>
<Para>
This is a "normal" error that tells you that what you are quering cannot
be found or we have gone through the cursor.
</Para>
</ListItem>
</VarListEntry>

</VariableList>
</Para>
</Sect2>
</sect1>

<Sect1>
<Title>Limitations</Title>

<Para>
What will never be included and why or what cannot be done with this
concept.

<VariableList>
<VarListEntry>
<Term>oracles single tasking possibility</Term>
<ListItem>
<Para>
Oracle version 7.0 on AIX 3 uses the OS-supported locks on the shared
memory segments and allows the application designer to link an
application in a so called single tasking way. Instead of starting one
client process per application process both the database part and the
application part is run in the same process. In later versions of oracle
this is no longer supported.
</Para>

<Para>
This would require a total redesign of the <ProductName>Postgres</ProductName> access model and
that effort can not justify the performance gained.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>
</sect1>

<Sect1>
<Title>Porting From Other <Acronym>RDBMS</Acronym> Packages</Title>

<Para>
The design of <Application>ecpg</Application> follows SQL standard. So
porting from a standard RDBMS should not be a problem. Unfortunately there
is no such thing as a standard RDBMS. So <Application>ecpg</Application>
also tries to understand syntax additions as long as they do not create
conflicts with the standard. 
</Para>

<Para>
The following list shows all the known incompatibilities. If you find one
not listed please notify <ULink url="mailto:meskes@@postgresql.org">Michael
Meskes</ULink>. Note, however, that we list only incompatibilities from
a precompiler of another RDBMS to <Application>ecpg</Application> and not
additional <Application>ecpg</Application> features that these RDBMS do not
have.
</Para>

<Para>
<VariableList>
<VarListEntry>
<Term>Syntax of FETCH command</Term>
<ListItem>
<Para>
The standard syntax of the FETCH command is:
</para>
<Para>
FETCH [direction] [amount] IN|FROM <Replaceable>cursor name</Replaceable>.
</Para>
<para>
<Application>ORACLE</Application>, however, does not use the keywords IN
resp. FROM. This feature cannot be added since it would create parsing
conflicts.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>
</sect1>

<Sect1>
<Title>Installation</Title>

<Para>
Since version 0.5 <Application>ecpg</Application> is distributed 
together with <ProductName>Postgres</ProductName>. So you
should get your precompiler, libraries and header files compiled and
installed by default as a part of your installation.
</Para>
</sect1>

<Sect1>
<Title>For the Developer</Title>

<Para>
This section is for those who want to develop the 
<Application>ecpg</Application> interface. It
describes how the things work. The ambition is to make this section
contain things for those that want to have a look inside and the section
on How to use it should be enough for all normal questions.

So, read this before looking at the internals of the 
<Application>ecpg</Application>. If
you are not interested in how it really works, skip this section.
</Para>

<Sect2>
<Title>ToDo List</Title>

<Para>
This version the preprocessor has some flaws:

<VariableList>
<VarListEntry>
<Term>Library functions</Term>
<ListItem>
<Para>
to_date et al. do not exists. But then <ProductName>Postgres</ProductName>
has some good conversion routines itself. So you probably won't miss these.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>Structures ans unions</Term>
<ListItem>
<Para>
Structures and unions have to be defined in the declare section.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>Missing statements</Term>
<ListItem>
<Para>
The following statements are not implemented thus far:
<VariableList>
<VarListEntry>
<Term> exec sql allocate</Term>
<ListItem>
<Para>
</Para>
</listitem>
</VarListEntry>
<VarListEntry>
<Term> exec sql deallocate</Term>
<ListItem>
<Para>
</Para>
</listitem>
</VarListEntry>
<VarListEntry>
<Term> SQLSTATE</Term>
<ListItem>
<Para>
</Para>
</listitem>
</VarListEntry>
</VariableList>
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>message 'no data found'</Term>
<ListItem>
<Para>
The error message for "no data" in an exec sql insert select from statement
has to be 100.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>sqlwarn[6]</Term>
<ListItem>
<Para>
sqlwarn[6] should be 'W' if the PRECISION or SCALE value specified in a SET
DESCRIPTOR statement will be ignored.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>
</sect2>

<Sect2>
<Title>The Preprocessor</Title>

<Para>
The first four lines written to the output are constant additions by ecpg.
These are two comments and two include lines necessary for the interface to the
library.
</Para>

<Para>
Then the preprocessor works in one pass only, reading the input file and
writing to the output as it goes along. Normally it just echoes
everything to the output without looking at it further.
</Para>

<Para>
When it comes to an <Command>EXEC SQL</Command> statements it intervenes and
changes them depending on what it is. 
The <Command>EXEC SQL</Command> statement can be one of these:

<VariableList>
<VarListEntry>
<Term>Declare sections</Term>
<ListItem>
<Para>
Declare sections begins with
<ProgramListing>
d635 3
a637 3
</ProgramListing>
and ends with
<ProgramListing>
d639 21
a659 21
</ProgramListing>
In the section only variable declarations are allowed. Every variable
declare within this section is also entered in a list of variables
indexed on their name together with the corresponding type.
</Para>

<Para>
In particular the definition of a structure or union also has to be listed
inside a declare section. Otherwise <Application>ecpg</Application> cannot
handle these types since it simply does not know the definition.
</Para>

<Para>
The declaration is echoed to the file to make the variable a normal
C-variable also.
</Para>

<Para>
The special types VARCHAR and VARCHAR2 are converted into a named struct
for every variable. A declaration like:
<ProgramListing>
d661 3
a663 3
</ProgramListing>
is converted into
<ProgramListing>
d665 11
a675 11
</ProgramListing>
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>Include statements</Term>
<ListItem>
<Para>
An include statement looks like:
<ProgramListing>
d677 3
a679 3
</ProgramListing>
Not that this is NOT the same as
<ProgramListing>
d681 2
a682 2
</ProgramListing>
</Para>
d684 149
a832 144
<Para>
Instead the file specified is parsed by <Application>ecpg</Application>
itself. So the contents of the specified file is included in the resulting C
code. This way you are able to specify EXEC SQL commands in an include file.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>Connect statement</Term>
<ListItem>
<Para>
A connect statement looks like:
<ProgramListing>
exec sql connect to <Replaceable>connection target</Replaceable>;
</ProgramListing>
It creates a connection to the specified database.
</Para>

<Para>
The <Replaceable>connection target</Replaceable> can be specified in the
following ways:
<VariableList>
<VarListEntry>
<Term>dbname[@@server][:port][as <Replaceable>connection name</Replaceable>][user <Replaceable>user name</Replaceable>]</Term>
<listitem><para></para></listitem>
</VarListEntry>

<VarListEntry>
<Term>tcp:postgresql://server[:port][/dbname][as <Replaceable>connection name</Replaceable>][user <Replaceable>user name</Replaceable>]</Term>
<listitem><para></para></listitem>
</VarListEntry>

<VarListEntry>
<Term>unix:postgresql://server[:port][/dbname][as <Replaceable>connection name</Replaceable>][user <Replaceable>user name</Replaceable>]</Term>
<listitem><para></para></listitem>
</VarListEntry>

<VarListEntry>
<Term><Replaceable>character variable</Replaceable>[as <Replaceable>connection name</Replaceable>][user <Replaceable>user name</Replaceable>]</Term>
<listitem><para></para></listitem>
</VarListEntry>

<VarListEntry>
<Term><Replaceable>character string</Replaceable>[as <Replaceable>connection name</Replaceable>][<Replaceable>user</Replaceable>]</Term>
<listitem><para></para></listitem>
</VarListEntry>

<VarListEntry>
<Term>default</Term>
<listitem><para></para></listitem>
</VarListEntry>

<VarListEntry>
<Term>user</Term>
<listitem><para></para></listitem>
</VarListEntry>
</VariableList>
</Para>

<Para>
There are also different ways to specify the user name:
<VariableList>
<VarListEntry>
<Term><Replaceable>userid</Replaceable></Term>
<listitem><para></para></listitem>
</VarListEntry>
<VarListEntry>
<Term><Replaceable>userid</Replaceable>/<Replaceable>password</Replaceable></Term>
<listitem><para></para></listitem>
</VarListEntry>
<VarListEntry>
<Term><Replaceable>userid</Replaceable> identified by <Replaceable>password</Replaceable></Term>
<listitem><para></para></listitem>
</VarListEntry>
<VarListEntry>
<Term><Replaceable>userid</Replaceable> using <Replaceable>password</Replaceable></Term>
<listitem><para></para></listitem>
</VarListEntry>
</VariableList>
</Para>

<Para> Finally the userid and the password. Each may be a constant text, a
character variable or a chararcter string.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>Disconnect statements</Term>
<ListItem>
<Para>
A disconnect statement looks loke:
<ProgramListing>
exec sql disconnect [<Replaceable>connection target</Replaceable>];
</ProgramListing>
It closes the connection to the specified database.
</Para>

<Para>
The <Replaceable>connection target</Replaceable> can be specified in the
following ways:
<VariableList>
<VarListEntry>
<Term><Replaceable>connection name</Replaceable></Term>
<listitem><para></para></listitem>
</VarListEntry>
<VarListEntry>
<Term>default</Term>
<listitem><para></para></listitem>
</VarListEntry>
<VarListEntry>
<Term>current</Term>
<listitem><para></para></listitem>
</VarListEntry>
<VarListEntry>
<Term>all</Term>
<listitem><para></para></listitem>
</VarListEntry>
</VariableList>
</Para>
</ListItem>
</VarListEntry>

<!--WARNING: FROM HERE ON THE TEXT IS OUTDATED!-->
<VarListEntry>
<Term>Open cursor statement</Term>
<ListItem>
<Para>
An open cursor statement looks like:
<ProgramListing>
exec sql open <Replaceable>cursor</Replaceable>;
</ProgramListing>
and is ignore and not copied from the output.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>Commit statement</Term>
<ListItem>
<Para>
A commit statement looks like
<ProgramListing>
d834 3
a836 3
</ProgramListing>
and is translated on the output to
<ProgramListing>
d838 11
a848 11
</ProgramListing>
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>Rollback statement</Term>
<ListItem>
<Para>
A rollback statement looks like
<ProgramListing>
d850 3
a852 3
</ProgramListing>
and is translated on the output to
<ProgramListing>
d854 55
a908 55
</ProgramListing>
</Para>
</ListItem>
</VarListEntry>

<!--STARTING HERE IT IS OKAY AGAIN!-->
<VarListEntry>
<Term>Other statements</Term>
<ListItem>
<Para>
Other <Acronym>SQL</Acronym> statements are other statements that start with 
<Command>exec sql</Command> and ends with <Command>;</Command>. 
Everything inbetween is treated
as an <Acronym>SQL</Acronym> statement and parsed for variable substitution.
</Para>

<Para>
Variable substitution occur when a symbol starts with a colon
(<Command>:</Command>). Then a variable with that name is looked for among
the variables that were previously declared within a declare section and
depending on the variable being for input or output the pointers to the
variables are written to the output to allow for access by the function.
</Para>

<Para>
For every variable that is part of the <Acronym>SQL</Acronym> request 
the function gets another ten arguments:

<SimpleList>
<Member>The type as a special symbol.</Member>
<Member>A pointer to the value or a pointer to the pointer.</Member>
<Member>The size of the variable if it is a char or varchar.</Member>
<Member>Number of elements in the array (for array fetches).</Member>
<Member>The offset to the next element in the array (for array fetches)</Member>
<Member>The type of the indicator variable as a special symbol.</Member>
<Member>A pointer to the value of the indicator variable or a pointer to the pointer of the indicator variable.</Member>
<Member>0.</Member>
<Member>Number of elements in the indicator array (for array fetches).</Member>
<Member>The offset to the next element in the indicator array (for array fetches)</Member>
</SimpleList>
</Para>

</ListItem>
</VarListEntry>
</VariableList>
</Para>
</Sect2>

<Sect2>
<Title>A Complete Example</Title>

<Para>
Here is a complete example describing the output of the preprocessor of a
file foo.pgc:
<ProgramListing>
d915 3
a917 3
</ProgramListing>
is translated into:
<ProgramListing>
d938 114
a1051 97
</ProgramListing>
(the indentation in this manual is added for readability and not
something that the preprocessor can do.)
</Para>
</sect2>

<Sect2>
<Title>The Library</Title>

<Para>
The most important function in the library is the <Function>ECPGdo</Function>
function. It takes a variable amount of arguments. Hopefully we will not run
into machines with limits on the amount of variables that can be
accepted by a vararg function. This could easily add up to 50 or so
arguments.
</Para>

<Para>
The arguments are:

<VariableList>
<VarListEntry>
<Term>A line number</Term>
<ListItem>
<Para>
This is a line number for the original line used in error messages only.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>A string</Term>
<ListItem>
<Para>
This is the <Acronym>SQL</Acronym> request that is to be issued. 
This request is modified
by the input variables, i.e. the variables that where not known at
compile time but are to be entered in the request. Where the variables
should go the string contains <Quote>;</Quote>.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>Input variables</Term>
<ListItem>
<Para>
As described in the section about the preprocessor every input variable
gets ten arguments.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>ECPGt_EOIT</Term>
<ListItem>
<Para>
An enum telling that there are no more input variables.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>Output variables</Term>
<ListItem>
<Para>
As described in the section about the preprocessor every input variable
gets ten arguments. These variables are filled by the function.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>ECPGt_EORT</Term>
<ListItem>
<Para>
An enum telling that there are no more variables.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</Para>

<Para>
All the <Acronym>SQL</Acronym> statements are performed in one transaction
unless you issue a commit transaction. To get this auto-transaction going
the first statement or the first after statement after a commit or rollback
always begins a transaction. To disable this feature per default use the
'-t' option on the commandline
</Para>

<Para>
To be completed: entries describing the other entries.
</Para>
</sect2>
</sect1>
</Chapter>
@


1.10
log
@*** empty log message ***
@
text
@d5 1
a5 1
<FirstName>Linux</FirstName>
@


1.9
log
@Fix markup to include all closing tags.
Required by newest versions of DocBook and style sheets.
@
text
@d191 1
a191 1
 /* 1: empty                                         */
@


1.8
log
@Markup fixes from Vince Vielhaber.
@
text
@d490 1
@


1.7
log
@*** empty log message ***
@
text
@d478 1
a478 1

d482 1
a482 1

a489 1
</Para>
d701 1
d706 1
d711 1
d716 1
d721 1
d726 1
d731 1
d741 1
d745 1
d749 1
d753 1
d781 1
d785 1
d789 1
d793 1
d800 1
a800 1
WARNING: FROM HERE ON THE TEXT IS OUTDATED!
d846 1
a846 1
STARTING HERE IT IS OKAY AGAIN!
@


1.6
log
@Clean up to ensure tag completion as required by the newest versions
 of Norm's Modular Style Sheets and jade/docbook.
From Vince Vielhaber <vev@@michvhf.com>.
@
text
@d32 1
a32 1
and <ULink url="mailto:meskes@@debian.org">Michael Meskes</ULink>.
d146 2
a147 4
that is called on all <Acronym>SQL</Acronym>
statements except <Command>EXEC SQL COMMIT</Command>, 
<Command>EXEC SQL ROLLBACK</Command>, 
<Command>EXEC SQL CONNECT</Command> logs both its expanded string,
d178 31
a208 6
struct sqlca {
    int sqlcode;
    struct {
        int sqlerrml;
        char sqlerrmc[1000];
    } sqlerrm;
d225 2
a226 3
The string ends with <Quote>line 23.</Quote> where the line is the line number
in the source file (actually the file generated by the preprocessor but
I hope I can fix this to be the line number in the input file.)
d234 1
a234 1
<Term>-1, Unsupported type %s on line %d.</Term>
d237 2
a238 3
Does not normally occur. This is a sign that the preprocessor has
generated something that the library does not know about. Perhaps you
are running incompatible versions of the preprocessor and the library.
d244 1
a244 1
<Term>-1, Too many arguments line %d.</Term>
d247 3
a249 1
The preprocessor has goofed up and generated some incorrect code.
d255 1
a255 1
<Term>-1, Too few arguments line %d.</Term>
d258 4
a261 1
The preprocessor has goofed up and generated some incorrect code.
d267 1
a267 1
<Term>-1, Error starting transaction line %d.</Term>
d270 5
a274 24
<ProductName>Postgres</ProductName> signalled to us that we cannot open 
the connection.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>-1, Postgres error: %s line %d.</Term>
<ListItem>
<Para>
Some <ProductName>Postgres</ProductName> error. 
The message contains the error message from the
<ProductName>Postgres</ProductName> backend.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>1, Data not found line %d.</Term>
<ListItem>
<Para>
This is a "normal" error that tells you that what you are quering cannot
be found or we have gone through the cursor.
</Para>
d279 1
a279 1
<Term>-1, To many matches line %d.</Term>
d282 3
a284 2
This means that the query has returned several lines. 
The <Command>SELECT</Command> you made probably was not unique.
d290 1
a290 1
<Term>-1, Not correctly formatted int type: %s line %d.</Term>
d303 1
a303 1
<Term>-1, Not correctly formatted unsigned type: %s line %d.</Term>
d316 1
a316 1
<Term>-1, Not correctly formatted floating point type: %s line %d.</Term>
d319 1
a319 1
This means that the host variable is of an <Type>float</Type> type and
d329 1
a329 1
<Term>-1, Too few arguments line %d.</Term>
d332 3
a334 4
This means that <ProductName>Postgres</ProductName> has returned more records 
than we have
matching variables. Perhaps you have forgotten a couple of the host
variables in the <Command>INTO :var1,:var2</Command>-list.
d340 1
a340 1
<Term>-1, Too many arguments line %d.</Term>
d343 2
a344 4
This means that <ProductName>Postgres</ProductName> has returned fewer records 
than we have
host variables. Perhaps you have to many host variables in the 
<Command>INTO :var1,:var2</Command>-list.
d350 1
a350 1
<Term>-1, Empty query line %d.</Term>
d353 1
a353 1
<ProductName>Postgres</ProductName> returned PGRES_EMPTY_QUERY.
d359 1
a359 1
<Term>-1, Error: %s line %d.</Term>
d362 1
a362 3
This means that <ProductName>Postgres</ProductName> returned on of the errors
PGRES_NONFATAL_ERROR, PGRES_FATAL_ERROR or PGRES_BAD_RESPONSE. Which one
and why is explained in the message.
d368 1
a368 1
<Term>-1, Postgres error line %d.</Term>
d371 1
a371 5
<ProductName>Postgres</ProductName> returns something that the library does 
not know how to
handle. This is probably because the version of 
<ProductName>Postgres</ProductName> does not
match the version of the <Application>ecpg</Application> library.
d377 1
a377 1
<Term>-1, Error committing line %d.</Term>
d380 3
a382 5
Error during <Command>COMMIT</Command>. <Command>EXEC SQL COMMIT</Command> 
is translated to an
<Command>end</Command> operation in <ProductName>Postgres</ProductName> 
and that is the operation that could
not be performed.
d388 1
a388 1
<Term>-1, Error rolling back line %d.</Term>
d391 2
a392 5
Error during <Command>ROLLBACK</Command>. 
<Command>EXEC SQL ROLLBACK</Command> is translated to
an <Command>abort</Command> operation in <ProductName>Postgres</ProductName> 
and that is the operation that
could not be performed.
d398 1
a398 1
<Term>-1, ECPGconnect: could not open database %s.</Term>
d405 11
d455 35
a489 3
To be written by someone who knows the different 
<Acronym>RDBMS</Acronym> packages and who
actually does port something...
d527 1
a527 24
<Term>no restriction to strings only</Term>
<ListItem>
<Para>
The PQ interface, and most of all the PQexec function, that is used by
the <Application>ecpg</Application> relies on that the request is built 
up as a string. In some
cases, like when the data contains the null character, this will be a
serious problem.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>error codes</Term>
<ListItem>
<Para>
There should be different error numbers for the different errors instead
of just -1 for them all.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>library functions</Term>
d530 2
a531 1
to_date et al.
d537 1
a537 1
<Term>records</Term>
d540 1
a540 1
Records or structures have to be defined in the declare section.
d546 1
a546 1
<Term>missing statements</Term>
a551 14
<Term> exec sql type</Term>
<ListItem>
<Para>
</Para>
</listitem>
</VarListEntry>
<VarListEntry>
<Term> exec sql prepare</Term>
<ListItem>
<Para>
</Para>
</listitem>
</VarListEntry>
<VarListEntry>
d559 1
a559 8
<Term> exec sql free</Term>
<ListItem>
<Para>
</Para>
</listitem>
</VarListEntry>
<VarListEntry>
<Term> exec sql whenever sqlwarning</Term>
d578 1
a578 1
<Term>message ´no data found´</Term>
d588 1
a588 1
<Term>sqlwanr[6]</Term>
a595 19
<VarListEntry>
<Term>conversion of scripts</Term>
<ListItem>
<Para>
To set up a database you need a few scripts with table definitions and
other configuration parameters. If you have these scripts for an old
database you would like to just apply them to get a 
<ProductName>Postgres</ProductName> database that works in the same way.
</Para>

<Para>
To set up a database you need a few scripts with table definitions and
The functionality could be accomplished with some conversion scripts.
Speed will never be accomplished in this way. To do this you need a
bigger insight in the database construction and the use of the database
than could be realised in a script.
</Para>
</ListItem>
</VarListEntry>
d604 3
a606 2
First four lines are written to the output. Two comments and two include
lines necessary for the interface to the library. 
d610 1
a610 1
Then the preprocessor works in one pass only reading the input file and
d616 2
a617 2
When it comes to an <Command>EXEC SQL</Command> statements it interviens and
changes them depending on what iit is. 
d639 6
d671 1
a671 1
It is converted into
d676 6
d691 1
a691 1
exec sql connect '<Replaceable>database</Replaceable>';
d693 66
a758 1
That statement is converted into
d760 1
a760 1
ECPGconnect("<Replaceable>database</Replaceable>");
d762 20
d786 1
d832 1
d845 4
a848 7
(<Command>:</Command>). 
Then a variable with that name is found among the variables
that were previously declared within a declare section and depending on
whether or not the <Acronym>SQL</Acronym> statements knows it to be 
a variable for input or
output the pointers to the variables are written to the output to allow
for access by the function.
d853 1
a853 1
the function gets another five arguments:
d856 4
a859 4
<Member>The type as a special symbol</Member>
<Member>A pointer to the value</Member>
<Member>The size of the variable if it is a varchar</Member>
<Member>Number of elements in the array (for array fetches)</Member>
d861 5
a868 4
<Para>
Since the array fetches are not implemented yet the two last arguments
are not really important. They could perhaps have been left out.
</Para>
d879 2
a880 1
Here is a complete example describing the output of the preprocessor:
d887 1
a887 1
    exec sql select res into :result from mytable where index = :index;
d891 1
d893 3
a895 2
#include &lt;ecpgtype.h&gt;
#include &lt;ecpglib.h&gt;
d898 2
d903 7
a910 6
...
    ECPGdo(__LINE__, "select res from mytable where index = ;;", 
           ECPGt_int,&amp;index,0,0,sizeof(int), 
           ECPGt_EOIT, 
           ECPGt_int,&amp;result,0,0,sizeof(int), 
           ECPGt_EORT );
d922 1
a922 1
function. It takes a variable amount of arguments. Hopefully we wont run
d924 1
a924 1
accepted by a varchar function. This could easily add up to 50 or so
d959 1
a959 1
gets five arguments.
d978 1
a978 1
gets five arguments. These variables are filled by the function.
d995 5
a999 4
All the <Acronym>SQL</Acronym> statements are performed in one transaction 
unless you issue
a commit transaction. This works so that the first transaction or the
first after a commit or rollback always begins a transaction.
@


1.5
log
@Clean up markup.
Add new bibliographic references from Paul Aoki.
Include libpq++ docs from the old man page in the Programmer's Guide.
Update Unix installation info for ODBC.
@
text
@d40 1
a40 1

d51 1
d60 2
a61 1

d72 1
d83 1
d92 1
d100 2
a101 1

d108 1
d111 1
a111 1
<Title>Preprocessor
d117 2
a118 1

d120 1
a120 1
<Title>Library
d129 1
d142 1
d165 2
d169 1
a169 1
<Title>Error handling
d188 1
d198 1
d205 1
d412 1
a412 1

d414 1
d434 1
d443 2
d453 2
d464 2
d480 1
d526 1
a526 1

d540 2
d547 2
d554 2
d561 2
d568 2
d575 2
d610 1
d622 2
d631 1
d637 1
d660 1
d665 1
d766 1
d777 1
d790 1
d799 1
a799 1

d835 2
d847 1
d913 1
d920 1
d924 3
a926 1

@


1.4
log
@Clean up pages. Add information for operator precedence.
Split introduction sections into separate files to allow the legal notice
 and notation sections appear in all documents without having the history
 show up everplace too.
Add full list of reserved and non-reserved key words in syntax.sgml.
Add a separate chapter to the admin guide on security.
@
text
@d24 2
a25 1
<Title><Application>ecpg</Application> - Embedded <Acronym>SQL</Acronym> in <Acronym>C</Acronym></Title>
d28 2
a29 1
This describes an embedded <Acronym>SQL</Acronym> in <Acronym>C</Acronym> package for <ProductName>Postgres</ProductName>.
d45 2
a46 1
Embedded <Acronym>SQL</Acronym> has some small advantages over other ways to handle <Acronym>SQL</Acronym>
d48 2
a49 1
from variables in your <Acronym>C</Acronym> program. Many <Acronym>RDBMS</Acronym> packages
d53 2
a54 1
work. <Application>ecpg</Application> was designed to meet this standard as much as possible. So it is
d64 4
a67 2
You write your program in <Acronym>C</Acronym> with some special <Acronym>SQL</Acronym> things.
For declaring variables that can be used in <Acronym>SQL</Acronym> statements you need to
d72 4
a75 2
Before compiling you run the file through the embedded <Acronym>SQL</Acronym> <Acronym>C</Acronym>
preprocessor and it converts the <Acronym>SQL</Acronym> statements you used to function
d77 2
a78 1
as input to the <Acronym>SQL</Acronym> statements and variables that will contain the
d85 2
a86 1
the <Acronym>SQL</Acronym> query using the ordinary interface (<FileName>libpq</FileName>) and puts back
d90 4
a93 2
Then you run your program and when the control arrives to the <Acronym>SQL</Acronym>
statement the <Acronym>SQL</Acronym> statement is performed against the database and you
d107 2
a108 1
The preprocessor is called <Application>ecpg</Application>. After installation it resides in
d115 2
a116 1
The <Application>ecpg</Application> library is called <FileName>libecpg.a</FileName> or
d126 7
a132 8
<VariableList>
<VarListEntry>
<Term>ECPGdebug(int, FILE *stream)</Term>
<ListItem>
<Para>
If this is called, with the first argument non-zero, then debuglogging is turned
on. Debuglogging is done on <Function>stream</Function>. Most <Acronym>SQL</Acronym> statement logs its
arguments and result.
d135 6
a140 3
The most important one (<Function>ECPGdo</Function>) that is called on all <Acronym>SQL</Acronym>
statements except <Command>EXEC SQL COMMIT</Command>, <Command>EXEC SQL ROLLBACK</Command>, 
<Command>EXEC SQL CONNECT</Command> logs both its expanded string, i.e. the string
d142 2
a143 1
<ProductName>Postgres</ProductName> server. This can be very useful when searching for errors
a146 1
</VarListEntry>
d148 3
a150 4
<VarListEntry>
<Term>ECPGstatus()</Term>
<ListItem>
<Para>
d154 1
a154 2
</VarListEntry>
</VariableList>
d160 2
a161 2
To be able to detect errors from the <ProductName>Postgres</ProductName> server you include a line
like
d178 4
a181 2
If an error occured in the last <Acronym>SQL</Acronym> statement then <Parameter>sqlca.sqlcode</Parameter>
will be non-zero. If <Parameter>sqlca.sqlcode</Parameter> is less that 0 then this is
d229 2
a230 1
<ProductName>Postgres</ProductName> signalled to us that we cannot open the connection.
d239 2
a240 1
Some <ProductName>Postgres</ProductName> error. The message contains the error message from the
d260 2
a261 2
This means that the query has returned several lines. The <Command>SELECT</Command>
you made probably was not unique.
d271 3
a273 2
in the <ProductName>Postgres</ProductName> database is of another type and contains a value that
cannot be interpreted as an <Type>int</Type>. The library uses <Function>strtol</Function>
d284 2
a285 1
the field in the <ProductName>Postgres</ProductName> database is of another type and contains a
d297 2
a298 1
the field in the <ProductName>Postgres</ProductName> database is of another type and contains a
d309 2
a310 1
This means that <ProductName>Postgres</ProductName> has returned more records than we have
d321 2
a322 1
This means that <ProductName>Postgres</ProductName> has returned fewer records than we have
d353 4
a356 2
<ProductName>Postgres</ProductName> returns something that the library does not know how to
handle. This is probably because the version of <ProductName>Postgres</ProductName> does not
d366 4
a369 2
Error during <Command>COMMIT</Command>. <Command>EXEC SQL COMMIT</Command> is translated to an
<Command>end</Command> operation in <ProductName>Postgres</ProductName> and that is the operation that could
d379 4
a382 2
Error during <Command>ROLLBACK</Command>. <Command>EXEC SQL ROLLBACK</Command> is translated to
an <Command>abort</Command> operation in <ProductName>Postgres</ProductName> and that is the operation that
d431 2
a432 1
To be written by persons that knows the different <Acronym>RDBMS</Acronym> packages and that
d439 2
a440 1
Since version 0.5 <Application>ecpg</Application> is distributed together with <ProductName>Postgres</ProductName>. So you
d442 1
a442 1
installed on the fly.
d448 2
a449 1
This section is for those that wants to develop the <Application>ecpg</Application> interface. It
d454 2
a455 1
So, read this before looking at the internals of the <Application>ecpg</Application>. If
d470 2
a471 1
the <Application>ecpg</Application> relies on that the request is built up as a string. In some
d572 2
a573 2
database you would like to just apply them to get a <ProductName>Postgres</ProductName> database
that works in the same way.
d600 2
a601 2
changes them depending on what iit is. The <Command>EXEC SQL</Command> statement can
be one of these:
d720 2
a721 1
<Command>exec sql</Command> and ends with <Command>;</Command>. Everything inbetween is treated
d726 2
a727 1
(<Command>:</Command>). Then a variable with that name is found among the variables
d729 2
a730 1
whether or not the <Acronym>SQL</Acronym> statements knows it to be a variable for input or
d735 2
a736 2
For every variable that is part of the <Acronym>SQL</Acronym> request the function gets
another five arguments.
d817 2
a818 1
This is the <Acronym>SQL</Acronym> request that is to be issued. This request is modified
d866 2
a867 1
All the <Acronym>SQL</Acronym> statements are performed in one transaction unless you issue
@


1.3
log
@
From: Michael Meskes <meskes@@usa.net>

docs improvement for ecpg..
@
text
@d479 2
d484 2
d489 2
d494 2
d499 2
d504 2
@


1.2
log
@Add id field to chapter and book tags to allow output file names
 to be meaningful.
@
text
@d48 6
a53 9
<Para>
There is an ANSI-standard describing how the embedded language should
work. Most embedded <Acronym>SQL</Acronym> preprocessors I have seen and heard of make
extensions so it is difficult to obtain portability between them
anyway. I have not read the standard but I hope that my implementation
does not deviate too much and that it would be possible to port programs
with embedded <Acronym>SQL</Acronym> written for other <Acronym>RDBMS</Acronym> packages 
to <ProductName>Postgres</ProductName> and thus
promoting the spirit of free software.
a431 19
<Term>Preprocessor output</Term>
<ListItem>
<Para>
The variables should be static.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
<Term>Preprocessor cannot do syntax checking on your <Acronym>SQL</Acronym> statements</Term>
<ListItem>
<Para>
Whatever you write is copied more or less exactly to the <ProductName>Postgres</ProductName> and
you will not be able to locate your errors until run-time.
</Para>
</ListItem>
</VarListEntry>

<VarListEntry>
d466 1
a466 2
Possibility to define records or structures in the declare section
in a way that the record can be filled from one row in the database.
a467 3
<Para>
This is a simpler way to handle an entire row at a time.
</Para>
d472 1
a472 1
<Term>array operations</Term>
d475 21
a495 4
Oracle has array operations that enhances speed. When implementing it in
<Application>ecpg</Application> it is done for compatibility reasons only. For them to
improve speed would require a lot more insight in the <ProductName>Postgres</ProductName> internal
mechanisms than I possess.
d501 1
a501 1
<Term>indicator variables</Term>
d504 2
a505 6
Oracle has indicator variables that tell if a value is <Type>null</Type> or if
it is empty. This largely simplifies array operations and provides for a
way to hack around some design flaws in the handling of <Type>VARCHAR2</Type>
(like that an empty string isn't distinguishable from a
<Type>null</Type> value). I am not sure if this is an Oracle extension or part
of the ANSI standard.
d511 1
a511 1
<Term>typedefs</Term>
d514 2
a515 2
As well as complex types like records and arrays, typedefs would be
a good thing to take care of.
a518 1

@


1.1
log
@SGML source for new documentation.
@
text
@d1 1
a1 1
<Chapter>
@
