4D v12 Upgrade

4D v12
Upgrade
Windows®/Mac OS®
4D®
© 1985-2010 4D SAS / 4D, Inc. All Rights Reserved.
4D v12 - Upgrade
Windows® and Mac OS® Versions
Copyright© 1985 - 2010 4D SAS / 4D, Inc.
All Rights Reserved.
The software described in this manual is governed by the grant of license provided in this package. The soft-
ware and the manual are copyrighted and may not be reproduced in whole or in part except for the personal
licensee’s use and solely in accordance with the contractual terms. This includes copying the electronic
media, archiving, or using the software in any manner other than that provided for in the Software license
Agreement.
4D, 4D Draw, 4D Write, 4D View, 4th Dimension®, 4D Server and the 4D logos are registered trademarks of
4D SAS.
Microsoft, Windows, Windows XP, Windows Vista and Windows 7 are registered trademarks of Microsoft
Corporation.
Apple, Macintosh, iMac, Mac OS and QuickTime are trademarks or registered trademarks of Apple Computer
Inc.
Mac2Win Software Copyright © 1990-2010 is a product of Altura Software, Inc.
ICU Copyright © 1995-2010 International Business Machines Corporation and others. All rights reserved.
ACROBAT © Copyright 1987-2010, Secret Commercial Adobe Systems Inc. All rights reserved. ACROBAT is a
registered trademark of Adobe Systems Inc.
This product includes software developed by the Apache Software Foundation (http://www.apache.org/). 4D
includes cryptographic software written by Eric Young (eay@cryptsoft.com)
4D includes software written by Tim Hudson (tjh@cryptsoft.com).
Spellchecker © Copyright SYNAPSE Développement, Toulouse, France, 1994-2010.
All other referenced trade names are trademarks, registered trademarks, or copyrights of their respective
holders.
IMPORTANT LICENSE INFORMATION

Use of this software is subject to its license agreement included with the software. Please read the License
Agreement carefully before using the software.
Contents
Chapter 1 Welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Conversion of earlier databases . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Databases in versions 6.x, 2003.x and 2004.x . . . . . . . . . . . . . 14
Databases in version 11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Updating the Macros.xml file . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Minimum configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Phasing out obsolete functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Display of named platform appearances. . . . . . . . . . . . . . . . . . 18
Contextual mode of Web server . . . . . . . . . . . . . . . . . . . . . . . . 18
Chapter 2 Architecture and Database . . . . . . . . . . . . . . . . . . . 19

Using Universally Unique Identifiers (UUIDs). . . . . . . . . . . . . . . . 19
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
New UUID properties for fields . . . . . . . . . . . . . . . . . . . . . . . . . 20
Querying and sorting fields with style tags . . . . . . . . . . . . . . . . . . 22
Replicating data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Setting the primary key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Importing and exporting data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Selection of character set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Integrating the byte order mark . . . . . . . . . . . . . . . . . . . . . . . . 26
New XML export options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Components installed in the 4D application. . . . . . . . . . . . . . . . . 27
Choosing a location for the Components folder . . . . . . . . . . . 28
Chapter 3 Development Workshop . . . . . . . . . . . . . . . . . . . . . 29

Reorganization of Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Preferences and Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Customizing parameters and "Factory settings" . . . . . . . . . . . . 33
Interaction with the SET DATABASE PARAMETER command . 33
New preferences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
New database settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
4D v12 Upgrade 3
Contents
Structure editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Dim Others . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Move to Front . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Optimizing searches in the Design environment . . . . . . . . . . . . . . 43
Search dialog box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Examples of searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Replace and rename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Searching for unused elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Find Unused Methods and Global Variables . . . . . . . . . . . . . . . 54
Find Unused Local Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
New code editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Text entry assistance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Browsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Executing PHP scripts in 4D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Using another PHP interpreter or another php.ini file . . . . . . . 64
PHP modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Executing a PHP script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Recover by record headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
What is recovery by header markers?. . . . . . . . . . . . . . . . . . . . . 66
Recovery procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Chapter 4 Forms and Objects . . . . . . . . . . . . . . . . . . . . . . . . . .71

Extension of subform capacities . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
New properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Management of the bound variable . . . . . . . . . . . . . . . . . . . . . . 74
Advanced inter-form programming . . . . . . . . . . . . . . . . . . . . . . 76
Subforms in components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Preconfigured object library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Library objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Using the library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
SearchPicker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
DatePicker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
TimePicker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
New form objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
New stepper object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Asynchronous progress indicator . . . . . . . . . . . . . . . . . . . . . . . . 90
New 3D buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Number of states. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
4 4D v12 Upgrade
Contents
Rich text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Rich text management properties . . . . . . . . . . . . . . . . . . . . . . . 95
Processing rich text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
New properties for fields and variables . . . . . . . . . . . . . . . . . . . . . 99
Objects not enterable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Multiline objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Selection always visible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
List boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Hierarchical list boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Printing list boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Access to data of added SELECT columns . . . . . . . . . . . . . . . . 117
Toolbar button (Mac OS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Toolbar property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
On Mac toolbar button form event. . . . . . . . . . . . . . . . . . . . . 119
Chapter 5 Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

4D Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Get database localization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Get table fragmentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
OPEN 4D PREFERENCES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
SET DATABASE LOCALIZATION . . . . . . . . . . . . . . . . . . . . . . . 125
SET DATABASE PARAMETER, Get database parameter. . . . . . 127
Version type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
RESTORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Communications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
RECEIVE PACKET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Drag and Drop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Drop position. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Entry Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
GOTO OBJECT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Form Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
CALL SUBFORM CONTAINER. . . . . . . . . . . . . . . . . . . . . . . . . 133
Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Renamed commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
FORM GET HORIZONTAL RESIZING . . . . . . . . . . . . . . . . . . . 134
FORM GET VERTICAL RESIZING . . . . . . . . . . . . . . . . . . . . . . 135
Import and Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Interruptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
ASSERT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Asserted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Get assert enabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
4D v12 Upgrade 5
Contents
SET ASSERT ENABLED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Ignore repeated errors in the error window . . . . . . . . . . . . . . . 139
Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
EXECUTE METHOD IN SUBFORM. . . . . . . . . . . . . . . . . . . . . . 140
List Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
LISTBOX COLLAPSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
LISTBOX EXPAND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
LISTBOX Get column width. . . . . . . . . . . . . . . . . . . . . . . . . . . 147
LISTBOX GET HIERARCHY . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
LISTBOX GET PRINT INFORMATION . . . . . . . . . . . . . . . . . . . 149
LISTBOX SELECT BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
LISTBOX SET COLUMN WIDTH . . . . . . . . . . . . . . . . . . . . . . . 153
LISTBOX SET HIERARCHY . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Insertion or deletion commands . . . . . . . . . . . . . . . . . . . . . . . 154
Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
ENABLE BUTTON, DISABLE BUTTON . . . . . . . . . . . . . . . . . . . 156
OBJECT DUPLICATE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
OBJECT Get choice list name . . . . . . . . . . . . . . . . . . . . . . . . . . 160
OBJECT Get enabled. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
OBJECT Get enterable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
OBJECT Get filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
OBJECT Get font. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
OBJECT Get font size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
OBJECT Get font style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
OBJECT Get plain text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
OBJECT GET RGB COLORS . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
OBJECT GET SCROLLBAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
OBJECT GET SCROLL POSITION . . . . . . . . . . . . . . . . . . . . . . . 168
OBJECT Get styled text. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
OBJECT GET STYLED TEXT ATTRIBUTES . . . . . . . . . . . . . . . . 170
OBJECT Get title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
OBJECT Get visible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
OBJECT SET ENABLED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
OBJECT SET FORMAT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
OBJECT SET SCROLL POSITION . . . . . . . . . . . . . . . . . . . . . . . 174
OBJECT SET STYLED TEXT. . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
OBJECT SET STYLED TEXT ATTRIBUTES . . . . . . . . . . . . . . . . . 177
Reorganization of theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Pasteboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
SET FILE TO PASTEBOARD. . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
PHP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
PHP Execute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
PHP GET FULL RESPONSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
6 4D v12 Upgrade
Contents
PHP GET OPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

PHP SET OPTION. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Pictures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
New APIs for encoding and decoding pictures . . . . . . . . . . . . 191
CONVERT PICTURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
GET PICTURE METADATA . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Is picture file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
PICTURE CODEC LIST. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
SET PICTURE METADATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
WRITE PICTURE FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
OPEN PRINTING FORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Print object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Integration of PDFCreator driver under Windows . . . . . . . . . 203
GET PRINT OPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
SET CURRENT PRINTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
SET PRINT OPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
SQL EXECUTE SCRIPT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
SQL EXPORT DATABASE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
SQL EXPORT SELECTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
String. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Convert to text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Structure Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
GET MISSING TABLE NAMES . . . . . . . . . . . . . . . . . . . . . . . . . 213
REGENERATE MISSING TABLE . . . . . . . . . . . . . . . . . . . . . . . . 214
SVG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Note on the SVG rendering engine . . . . . . . . . . . . . . . . . . . . . 215
SVG Find element ID by rect. . . . . . . . . . . . . . . . . . . . . . . . . . 216
SVG GET ATTRIBUTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
SVG SET ATTRIBUTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
SVG SHOW ELEMENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
System Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Convert path POSIX to system . . . . . . . . . . . . . . . . . . . . . . . . 223
Convert path system to POSIX . . . . . . . . . . . . . . . . . . . . . . . . 224
Get localized document path . . . . . . . . . . . . . . . . . . . . . . . . . 225
Select folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
BASE64 DECODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
BASE64 ENCODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Generate UUID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
SET ENVIRONMENT VARIABLE . . . . . . . . . . . . . . . . . . . . . . . 230
4D v12 Upgrade 7
Contents
User Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

GET HIGHLIGHT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
HIGHLIGHT TEXT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
OBJECT Get name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
OBJECT Get pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Web Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
PROCESS HTML TAGS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Note on use of XML BLOBs in 4D v12 . . . . . . . . . . . . . . . . . . . 235
XML DECODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
XML GET OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
XML SET OPTIONS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
XML DOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
DOM Append XML child node . . . . . . . . . . . . . . . . . . . . . . . . 242
DOM Append XML element . . . . . . . . . . . . . . . . . . . . . . . . . . 245
DOM Create XML element arrays . . . . . . . . . . . . . . . . . . . . . . 245
DOM GET XML CHILD NODES . . . . . . . . . . . . . . . . . . . . . . . . 247
DOM Get XML document ref. . . . . . . . . . . . . . . . . . . . . . . . . . 248
DOM GET XML ELEMENT VALUE. . . . . . . . . . . . . . . . . . . . . . 249
DOM Insert XML element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
DOM REMOVE XML ATTRIBUTE . . . . . . . . . . . . . . . . . . . . . . 251
DOM SET XML DECLARATION . . . . . . . . . . . . . . . . . . . . . . . . 252
XML SAX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
SAX GET XML ELEMENT VALUE. . . . . . . . . . . . . . . . . . . . . . . 253
SAX OPEN XML ELEMENT ARRAYS . . . . . . . . . . . . . . . . . . . . 253
SAX SET XML DECLARATION . . . . . . . . . . . . . . . . . . . . . . . . . 254
New system variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Dynamic variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Form Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Open window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
System Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
4D Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
DatePicker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
DatePicker APPLY DEFAULT VALUES . . . . . . . . . . . . . . . . . . 258
DatePicker Display Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
DatePicker RESET DEFAULT VALUES . . . . . . . . . . . . . . . . . . 260
DatePicker SET DAYS OFF . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
DatePicker SET DEFAULT 1ST DAY . . . . . . . . . . . . . . . . . . . . 262
DatePicker SET DEFAULT DAYS OFF. . . . . . . . . . . . . . . . . . . 262
DatePicker SET DEFAULT MAX DATE. . . . . . . . . . . . . . . . . . 264
DatePicker SET DEFAULT MIN DATE . . . . . . . . . . . . . . . . . . 264
DatePicker SET MAX DATE . . . . . . . . . . . . . . . . . . . . . . . . . . 264
DatePicker SET MIN DATE . . . . . . . . . . . . . . . . . . . . . . . . . . 265
DatePicker SET WEEK FIRST DAY . . . . . . . . . . . . . . . . . . . . . 266
8 4D v12 Upgrade
Contents
SearchPicker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
SearchPicker SET HELP TEXT . . . . . . . . . . . . . . . . . . . . . . . . 267
TimePicker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
TimePicker APPLY DEFAULT VALUES . . . . . . . . . . . . . . . . . 268
TimePicker RESET DEFAULT VALUES . . . . . . . . . . . . . . . . . 268
TimePicker SET DEFAULT LABEL AM . . . . . . . . . . . . . . . . . 269
TimePicker SET DEFAULT LABEL PM. . . . . . . . . . . . . . . . . . 269
TimePicker SET DEFAULT MAX TIME . . . . . . . . . . . . . . . . . 269
TimePicker SET DEFAULT MIN TIME . . . . . . . . . . . . . . . . . 270
TimePicker SET DEFAULT STEP . . . . . . . . . . . . . . . . . . . . . . 270
TimePicker SET LABEL AM . . . . . . . . . . . . . . . . . . . . . . . . . . 271
TimePicker SET LABEL PM . . . . . . . . . . . . . . . . . . . . . . . . . . 271
TimePicker SET MAX TIME . . . . . . . . . . . . . . . . . . . . . . . . . 271
TimePicker SET MIN TIME . . . . . . . . . . . . . . . . . . . . . . . . . . 272
TimePicker SET STEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
4D SVG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
SVG_SET_CLASS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
SVG_SET_CLIP_PATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
SVG_SET_FILL_RULE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
SVG_SET_SHAPE_RENDERING . . . . . . . . . . . . . . . . . . . . . . 276
SVG_SET_STROKE_DASHARRAY . . . . . . . . . . . . . . . . . . . . . 276
SVG_SET_STROKE_MITERLIMIT . . . . . . . . . . . . . . . . . . . . . 277
Colors and Gradients. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
SVG_Color_RGB_from_CMYK . . . . . . . . . . . . . . . . . . . . . . . 278
SVG_Color_RGB_from_HLS . . . . . . . . . . . . . . . . . . . . . . . . . 279
SVG_GET_COLORS_ARRAY . . . . . . . . . . . . . . . . . . . . . . . . . 279
Drawing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
SVG_Add_object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Structure and Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
SVG_Define_clip_path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
SVG_Define_pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
SVG_Define_style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
SVG_DELETE_OBJECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
SVG_Get_default_encoding . . . . . . . . . . . . . . . . . . . . . . . . . 285
SVG_SET_DEFAULT_ENCODING . . . . . . . . . . . . . . . . . . . . 285
SVG_SET_PATTERN_CONTENT_UNITS. . . . . . . . . . . . . . . . 286
SVG_SET_PATTERN_UNITS . . . . . . . . . . . . . . . . . . . . . . . . . 286
Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
SVG_APPEND_TEXT_TO_TEXTAREA . . . . . . . . . . . . . . . . . 286
SVG_Get_text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
SVG_SET_TEXT_KERNING . . . . . . . . . . . . . . . . . . . . . . . . . . 288
SVG_SET_TEXT_LETTER_SPACING . . . . . . . . . . . . . . . . . . . 289
SVG_SET_TEXT_RENDERING . . . . . . . . . . . . . . . . . . . . . . . 290
SVG_SET_TEXT_WRITING_MODE . . . . . . . . . . . . . . . . . . . 290
4D v12 Upgrade 9
Contents
SVG_SET_TEXTAREA_TEXT . . . . . . . . . . . . . . . . . . . . . . . . . 291
SVG_New_textArea . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
SVG_SET_FONT_FAMILY . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
SVG_ABOUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
SVGTool_SET_VIEWER_CALLBACK . . . . . . . . . . . . . . . . . . . 293
SVG_References_array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Chapter 6 SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .295

Replication via SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
New virtual fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Enabling replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Update on local database side . . . . . . . . . . . . . . . . . . . . . . . . . 297
Specifying a primary key when creating columns . . . . . . . . . . . . 298
Support of joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Explicit inner joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Outer joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Using external databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Support of UUID fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Creating a UUID field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Generating UUIDs automatically . . . . . . . . . . . . . . . . . . . . . . . 308
New SQL commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
CREATE DATABASE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
USE DATABASE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
ALTER DATABASE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
REPLICATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
SYNCHRONIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
New function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
DATABASE_PATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Modified SQL commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
CREATE TABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
ALTER TABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Chapter 7 4D Server Administration . . . . . . . . . . . . . . . . . . . .321

About the 64-bit 4D Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
4D Server administration window . . . . . . . . . . . . . . . . . . . . . . . . 321
New memory information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Removal of "technical" users . . . . . . . . . . . . . . . . . . . . . . . . . . 323
10 4D v12 Upgrade
Contents
Appendix A PHP Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

Modules provided by default . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Generic modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Modules only available under Windows. . . . . . . . . . . . . . . . . 330
Disabled modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Installation of additional modules . . . . . . . . . . . . . . . . . . . . . . . . 331
PECL extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
PEAR extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Zend extensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Symphony extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
JELIX extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
eZ components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Appendix B Style Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

Font name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Font size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Font style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Font colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
Background colors (Windows only) . . . . . . . . . . . . . . . . . . . . 336
Color values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
Appendix C Metadata Constants . . . . . . . . . . . . . . . . . . . . . . . 337

Picture metadata names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
EXIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
GPS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
IPTC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
TIFF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
Picture metadata values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
4D v12 Upgrade 11
Contents
12 4D v12 Upgrade
1 Welcome
Welcome to 4D v12. Totally open towards the most widespread

technologies and full of new features intended to increase the
productivity and creativity of developers, this version is a major new
step in the evolution of the 4D product line.
Numerous functions that were much in demand by the 4D developer

community are integrated, both at the level of the architecture and the
development workshop, as well as concerning the language:
improvement of language editor, possibility of executing PHP scripts,
management of UUID numbers, improvement of commands
managing object properties and extended support of XML and SVG.
The new possibility for installing components in the 4D application

allows you to have them available automatically in all the databases.
Printing functions are enhanced with the new PRINT OBJECT

command, as well as the possibility of printing list boxes and extended
support of PDF printing.
New form objects and widgets accelerate the setting up of modern and
sophisticated interfaces: steppers, texts with styles, date or time
selectors (datepicker), textual search area and also hierarchical list boxes
are part of these new features. Subforms benefit from many
improvements more particularly to make them easier to use as
components. The new preconfigured object library provides fast access
to these functionalities.
Finally, the 4D SQL language provides powerful new functions, such as

the replication or synchronization of data and the ability to open and
close different 4D databases during the same session.
4D v12 Upgrade 13
Chapter 1 Welcome
The new features are detailed in the following chapters:

Architecture and Database
Development Workshop
Forms and Objects

Language
SQL engine
4D Server Administration
4D Server The 64-bit version of 4D Server v12 is being finalized. A beta version is
currently available for download from our Web site
(http://www.4d.com/).
Conversion of earlier databases

Databases created with versions 6.x, 2003.x, 2004.x and 11.x of
4th Dimension, 4D or 4D Server are compatible with 4D version 12
(structure and data files).
Database files in version 6.x, 2003.x, 2004.x must be converted using a
wizard and can no longer be opened with their original version.
Database files in version 11 are converted directly into version 12.
Once it is converted, the structure file can no longer be opened in ver-
sion 11; the data file can be opened in version 11 again under certain
conditions (see the “Databases in version 11” paragraph on page 16).
Note: You can convert any interpreted structure file. The file can contain
compiled code; in this case, it is necessary to compile the database
again after conversion.
Databases in Structural changes made at the 4D database engine level require in-
versions 6.x, 2003.x depth conversion of both the structure and data of earlier databases
and 2004.x using a specific wizard when converting to versions 11 and 12. As a
precaution, this wizard makes a copy of the original database before
converting it so you can revert to it any time.
14 4D v12 Upgrade
Conversion of earlier databases
We recommend that you check the integrity of the database using the
4D Tools utility (compacting, verifying and, if necessary, repairing the
database) before conversion. Use the 4D Tools version that corresponds
to your original database.
To convert a earlier database to the new version, select it in the

opening dialog box of 4D v12. The Database Conversion wizard
appears automatically:
Click on the Convert database button to start the standard process for
converting the structure and data files.
For more information about this dialog box and the conversion pro-
cess, refer to the “Converting Databases from Previous Versions” para-
graph in the 4D Design Reference manual.
Any older or obsolete mechanisms that are no longer supported are
removed or replaced during conversion. For more information, refer to
the 4D v11 SQL Update manual. For a detailed description of all the
modifications, refer to the document Conversion to 4D v11 SQL avail-
able for download here: http://doc.4d.com/home.en.html
4D v12 Upgrade 15
Chapter 1 Welcome
Databases in version A database from version 11 gets converted directly when you open the
11 structure file with 4D v12. Two successive warnings let you know that
the files are being converted and that you can no longer open them
with an earlier version:
However, you can still open the converted data file in version 11 by
explicitly authorizing this on the version 11 side. This is done using
the Allow opening v12 data file preference found on the
“Database/Data Management” page of the Preferences (beginning with
4D v11 SQL r6 only):
4D v11 SQL r6 Preferences

Option for opening a v12
data file
Use this option with care in the case where specific attributes of
version 12 have been applied to database tables (risk of altering data).
16 4D v12 Upgrade
Minimum configuration
Updating the The "Macros.xml" file lets you use macro commands in the Method
Macros.xml file editor (see the Design Reference manual). It is located in the user
preferences folder:
Windows XP: C:\Documents and Settings\UserName\Application
Data\4D\Macros v2\
Windows Vista/Windows 7: C:\Users\UserName\AppData\Roam-
ing\4D\Macros v2\
Macintosh: {Startup disk}:Users:UserName:Library:Prefer-
ences:4D:Macros v2
In version 12 of 4D, there are new macro commands available to

facilitate the use of the new SQL commands (see Chapter 6, “SQL,”).
Since you can customize the "Macros.xml" file, installing a new version
of 4D does not automatically replace the existing version of the file. To
use the new SQL macro commands of 4D v12, you must either:
delete the "Macros.xml" file in the "Macros v2" folder (if you have
never modified it), then launch 4D to create the new file automati-
cally.
add the new macros manually to the "Macros.xml" file in the "Mac-
ros v2" folder (if you have already customized the contents). The
new template file for the macros is located in the 4D application
folder 4D\Resources\en.lproj or 4D\Resources\fr.lproj.
Minimum configuration
4D version 12 product line applications require the following
minimum configurations:
Windows Mac OS
Processor Pentium IV processor Intel® processor
System Windows Vista, Windows XP, Mac OS version 10.5 and higher
Windows 7
RAM memory 1 GB (2 GB recommended)
Screen resolution 1280 * 1024 pixels
4D v12 Upgrade 17
Chapter 1 Welcome
Phasing out obsolete functions

Certain older functions maintained in 4D v12 for compatibility
purposes are targeted for removal in the next major 4D version. We
recommend that you adapt your development to avoid using these
functions as of now.
Display of named Up to 4D version 2003, you can assign a specific platform appearance
platform to the database, forms, or objects. The options available are: Mac OS 7,
appearances Windows 3.11/NT 3.51, Windows 95/95/2000/NT4, Mac OS9 and Mac
Theme.
Henceforth, 4D v12 is the last version that displays these named
appearances in converted databases. In future versions, 4D will
automatically assign the System appearance to any objects with this
type of attribute.
Contextual mode of 4D v12 is the last version to support the Web server in contextual
Web server mode. This mode and the mechanisms associated with it will no longer
work in the next major version.
18 4D v12 Upgrade
2 Architecture and
Database
Several new 4D v12 features are related to the architecture of 4D

applications and integrated database engine:
Support of UUID
New option for handling style tags in Alpha and Text fields
New option for data replication via SQL
New import and export options
Installation of components at the 4D application level.
Using Universally Unique Identifiers (UUIDs)

4D v12 offers complete support of Universally Unique Identifiers
(UUIDs), allowing 4D developers to integrate them into their
databases.
Overview A UUID is a type of unique identifier, originally standardized by the

Open Software Foundation (OSF). A UUID identifier is designed to be
unique; the risk of having several identical UUIDs generated is
practically null. So information labeled with UUIDs can subsequently
be combined without the risk of name conflicts.
A UUID is a 16-byte number (128 bits). It contains 32 hexadecimal

characters. It can be expressed either in non-canonical form (series of
32 letters [A-F, a-f] and/or numbers [0-9], e.g.
550e8400e29b41d4a716446655440000) or in canonical form (groups
of 8,4,4,4,12, e.g. 550e8400-e29b-41d4-a716-446655440000).
4D v12 Upgrade 19
Chapter 2 Architecture and Database
In 4D v12, UUID numbers are stored in a special format,

accommodated in specific alphanumeric type fields (fields with "UUID
format" property checked). The values stored in these fields can be
generated automatically or by programming.
4D v12 lets you:

designate fields whose values will be stored in UUID format (16 bytes).
automatically generate UUIDs in fields with the UUID format via a

new option.
store, in fields with the UUID format, any UUIDs generated by the new
Generate UUID command or by a custom algorithm.
search for records according to their UUID value (note that even
though they are stored in Alpha fields, UUIDs are numbers, hence it is
not possible to carry out "contains" type searches nor to use the @ as a
wildcard when searching UUID fields).
Note You can access the field properties related to UUIDs using the 4D SQL
commands (see the “Support of UUID fields” paragraph on page 307).
New UUID 4D v12 has two new options added to the field inspector to configure
properties for fields UUID support:
Management options
for UUID property
You must select the Alpha field type to access these options.
20 4D v12 Upgrade
Using Universally Unique Identifiers (UUIDs)
UUID format The UUID format property indicates that the field stores the UUID
identifiers. The stored data must conform to the UUID format
(combination of 32 letters (A-F, a-f) and numbers (0-9)). To do this, you
can use the Auto UUID property, the new Generate UUID command, or
any custom algorithm.
If you try to store a string that does not comply with the UUID format
in this field, 4D reformats it automatically: it converts the codes of the
first 16 characters of the string into hexadecimal format and stores the
result. The rest of the string is truncated. If the string has less than 16
characters, the missing characters are filled by spaces ("20" in
hexadecimal). This mechanism is also applied to the contents of
existing non-Alpha fields that are transformed into UUID fields: when
loading the records, the values are reformatted and then stored once
again.
Note that this mechanism only allows you to obtain correctly
formatted values. It does not guarantee the uniqueness of the values
stored. It is up to you to generate valid UUIDs using the appropriate
tools ("Auto UUID" option, Generate UUID command or a custom
algorithm).
Fields with the UUID format property can be displayed in forms and
remain enterable. Their contents appear in upper-case characters. You
must pass through a variable if you want to display lower-case
characters.
Notes - Fields with the UUID format cannot be associated with keyword
indexes nor with choice lists.
- You can create a relation between two fields that both have the UUID
format but you cannot link a standard Alpha field to a field that has
the UUID format.
Auto UUID This option is only active when you select the UUID format property.
You can use the Auto UUID property to generate a UUID number
automatically in the field each time a record is created.
Note When data is imported, even with this property selected, 4D does not
generate a new number but uses the imported values (and transforms
them when necessary if the format is not valid). However, if the value
of the imported field is empty, a UUID is automatically generated.
4D v12 Upgrade 21
Querying and sorting fields with style tags

The new Queries and sorts on text without tags property is available
for Text and Alpha fields:
New property for ignoring styles

in queries and sorts
When you select this option, queries and sorts carried out in the data
stored in the field do not take any style tags into account.
This option is related to a new function in 4D v12 to apply different

styles within the same text area in a form. This is described in the
“Rich text” paragraph on page 94. The setting of styles is done by
inserting HTML tags in the text. These tags are interpreted when the
text area is displayed.
Style tags are stored with the data. For example, if you write "week end"
in a Text field, 4D stores "week end". This operation is transparent for the user at
the form level. However, for queries and sorts, a specific setting is
necessary for 4D to ignore the style tags. For the word "week end", the
query can find it only if you have selected the Queries and sorts on
text without tags option for the field in the Structure editor.
Note With this option, a query for thevalue among the data of thefield is the
same as executing this statement within 4D: QUERY BY
FORMULA(OBJECT Get plain text(thefield)="thevalue").
22 4D v12 Upgrade
Replicating data
Replicating data
4D v12 has new mechanisms based on SQL that you can use to set up
an advanced data replication system.
In the 4D database structure, a new Enable Replication property lets

you enable recording of the information needed for replication for
each table.
Enabling of replication
For more information about this option as well as about the record
replication mechanisms, refer to the “Replication via SQL” paragraph
on page 295.
Setting the primary In 4D v12, you can manage the primary key of a table directly in the
key Structure editor.
In SQL, a primary key identifies the column(s) (field(s)) used for

uniquely specifying the records (rows) in a table. Setting a primary key
is necessary for the record replication function in a 4D table (see the
“Replication via SQL” paragraph on page 295). In SQL, the primary key
is set using the PRIMARY KEY clause followed by the list of columns.
You create and remove primary keys directly using the context menu
of the Structure editor.
X To create a primary key:
1 Select the field(s) that make up the table’s primary key.
4D v12 Upgrade 23
2 Right click and choose Create primary key in the context menu:
The fields included in the primary key appear as underlined in the

editor and their SQL description displays the PRIMARY KEY keyword.
The field(s) belonging to the primary key must not contain any
duplicated values. If any duplicated values already exist in the table
records, a warning dialog box appears to indicate this.
Note The column(s) belonging to the primary key do not accept NULL
values.
X To remove a primary key from a table:

1 Right click on the table containing the primary key and choose
Remove primary key in the context menu:
A confirmation dialog box appears. Click OK to remove the primary

key.
24 4D v12 Upgrade
Importing and exporting data
Importing and exporting data

New options added to the standard data import and export dialog
boxes in 4D enable better support of Unicode text exchanges and the
XML format:
Selection of a character set (import and export),
Integration of Byte Order Mark (export),
New XML export options.
Selection of In the import and export dialog boxes of 4D v12, you can now specify
character set the character set to use for data exchanges in certain formats:
Menu to select
character set
This menu is available for Text, SYLK and XML (export) file formats. It
contains a standard list of character sets as specified by the IANA (for
more information, refer to: http://www.iana.org/assignments/character-
sets).
Note The Character Set menu is locked to the "IBM437" character set for the
DIFF and DBF formats and this menu is not available for the 4D
format.
When exporting, you use this menu to specify the encoding for the
exported data.
When importing, you use this menu to specify the encoding of the
imported data. This menu is disabled if the header of the export files
includes a BOM (see the next section) because the encoding of the
imported data is automatically predefined in this case.
4D v12 Upgrade 25
The default encoding for import and export operations is UTF-8 or the
character set specified by the USE CHARACTER SET command (if it has
been executed). Note that selecting an encoding in the import or
export dialog box does not modify the current character set of the
application.
Note The Destination Platform menu, used to set the end of record
character(s), includes new options: Automatic (end of record value set
according to export platform), Unix (end of record = line break) and
Custom (displays the delimiters page).
Integrating the byte The Generate BOM option now appears on the "Header" tab of the
order mark standard data export dialog box:
New export option
This option is only available when exporting data in text format (Text
or Fixed Length Text).
When you select the Generate BOM option, 4D inserts a Byte Order
Mark (BOM) in the export file header.
This additional information facilitates the text interpretation by the

import software, if it supports this function.
This option is enabled by default but it is only taken into account

when the Unicode character set is selected for the export. If this is not
the case, the BOM is not added.
26 4D v12 Upgrade
Components installed in the 4D application
New XML export New options are available on the "XML" tab of the export dialog box:
options
Encode binary fields in Base64: This option adds the "data:;base64,"

header to exported binary fields (BLOB and/or picture type fields).
When this option is not checked, fields are encoded in Base64 without
the header.
With indentations: This option applies automatic indentation to the
exported data. Indentation makes it possible to display the hierarchy
of the XML elements.
Encode pictures as PNG: This option automatically encodes the
exported pictures in PNG format, regardless of their original format.
When this option is not checked, pictures are encoded in their native
format.
Note that when pictures are exported in SVG, we recommend not
checking this option so pictures will retain their properties.
Components installed in the 4D application

In previous versions, all 4D components had to be installed in the
Components subfolder of each database where you used them. It was
therefore necessary to duplicate the components or use an alias to
install them in other locations.
In version 12 of 4D, just like plug-ins, you can install 4D components

in the 4D or 4D Server application. This way the component is
automatically available in all the databases opened by the 4D
application.
4D v12 Upgrade 27
Choosing a location In 4D v12, you can install the Components folder in two different
for the Components locations:
folder
At the 4D executable application level.
- Windows: next to the .exe file
- Mac OS: at the first level of the Contents folder, inside the application
package.
Here the components are available in every database that the
application opens.
At the database structure file level (location used in previous 4D
versions).
Here the components are only available for this particular database.
The choice of the location depends on how you want to use the
component.
If the same component is installed in both locations, 4D only loads the

component located next to the database structure.
In the case of an application that is compiled and merged with 4D
Volume Desktop, the presence of several instances of the same
component prevents the application from opening.
Note In 4D v12, a new property lets you publish the project form of a
component as a subform in the host database. For more information
about this point, refer to the “Subforms in components” paragraph on
page 78.
28 4D v12 Upgrade
3 Development Workshop
This section outlines the new features and modifications in the

development workshop of 4D v12, related to editors, preferences
and/or the overall interface:
Reorganization of preferences
New functions in the structure editor

Redesign of search functions in the Design environment
New search functions to find unused elements
New code editor
PHP code execution
New function for recovering data in the MSC.
Note that the new features related to forms and form objects are
covered in a specific section, chapter 4, “Forms and Objects“, page 71.
Reorganization of Preferences
The management of Preferences in 4D v12 is reorganized so as to
separate parameters common to all 4D applications ("user preferences")
from those specific to each database ("database settings"). New options
are also available.
Preferences and In 4D v12, there are two separate dialog boxes to configure two sets of
Settings options with different scopes: the "User Preferences" dialog box and
the "Database Settings" dialog box.
4D v12 Upgrade 29
Chapter 3 Development Workshop
Options found in the Preferences dialog box for the previous 4D

version are now divided between these two dialog boxes according to
their scope and where they are stored (see the following sections).
Their operation remains unchanged.
Note The Language of text comparison option is found both in the

Preferences dialog box (on the "General" page) and in the Settings one
(on the "Database" page). In the first case, it applies by default to the
creation of all new databases; in the other, it modifies the current
setting of the current database.
Note This manual only describes new options or options whose operation is
modified. For more information about existing options, refer to the
Design Reference manual.
User preferences You can access the Preferences dialog box from the Edit > Preferences...
menu (Windows) or the 4D Application menu (Mac OS):
This menu option is available even when there is no open database.
30 4D v12 Upgrade
User preferences specify default behavior options for 4D applications

(4D and 4D Server). In general, these settings affect the working
environment of the developer e.g. colors used in the method editor,
automatic form creation options, default display in forms:
4D user
preferences
Settings made in this dialog box are saved in an XML format

preferences file named 4D v12 Preferences.4DPreferences that is
stored in the preferences folder of the current user:
Windows XP: C:\Documents and Settings\UserName\Application
Data\4D
Windows Vista/Windows 7:
C:\Users\UserName\AppData\Roaming\4D
Mac OS: {disk}:Users:UserName:Library:Preferences:4D
4D v12 Upgrade 31
Database settings You can access the Database Settings dialog box via the Design >
Database Settings... menu option or the corresponding button on the
4D toolbar:
Database settings configure how the current database functions. These

parameters are stored with the database and may be different for each
database. They include the listening ports, access rights to the Design
environment, SQL configurations, etc.:
Database settings
For security reasons, database settings can only be accessed via this
dialog box.
32 4D v12 Upgrade
Customizing In the Preferences and Settings dialog boxes, parameters whose values
parameters and have been modified appear in bold:
"Factory settings"
Parameters that have

been customized
Preferences indicated as customized may have been modified directly

in the dialog box, or may have been modified previously in the case of
a converted database.
A parameter still appears in bold even when its value is replaced

manually with its default values. This way it is always possible to
visually identify any parameters that have been customized.
To reset the parameters to their default values and remove the bold
style indicating that they have been customized, click on the new
Factory settings button:
Resetting parameters
This button resets all the parameters of the current page. It becomes
active when at least one parameter has been modified on the current
page.
Interaction with the You set certain settings (such as the definition of the IP number for the
SET DATABASE PHP interpreter) either in the Database Settings dialog box, or by using
PARAMETER the SET DATABASE PARAMETER command.
command
These two ways function in a complementary manner:
Parameters set in the Database Settings dialog box are always used by
default for all the machines,
Parameters modified using the SET DATABASE PARAMETER command
only apply to the machine that executed the command and during the
current session. They do not modify the Database Settings dialog box
parameters.
4D v12 Upgrade 33
This means that the developers can modify parameters locally

according to their needs (for example, using a separate PHP
interpreter).
Note Certain "former" options of the SET DATABASE PARAMETER command

have a different scope. For more information, refer to the description
of this command.
New preferences 4D v12 provides new user preferences to customize your work
environment.
Style of SQL syntax Syntax analysis in the new code editor of 4D v12 differentiates
elements between SQL elements and those of 4D (see the “New code editor”
paragraph on page 55). It is now possible to attribute a custom style to
each element type using the "Styles" tab on the "Methods" page in the
Preferences:
34 4D v12 Upgrade
Method editor and The "Options" tab of the "Methods" page of the Preferences has new
debugger options options related to the Method editor and debugger:
Matching parentheses: This option modifies the graphic signaling of

corresponding parentheses in the code. This signaling appears
whenever a parenthesis is selected. The following options are available:
None: No signaling.
Rectangle: Parentheses surrounded by a black line
Background Color: Parentheses highlighted (the color is set in the
"Colors" area, see the “Colors” paragraph on page 37)
Bold: Parentheses displayed in bold.
4D v12 Upgrade 35
By default, the Rectangle option is selected.
"Rectangle" appearance
Highlight the line running: Highlights the line that is currently

running in the debugger, in additional the regular yellow arrow
indicator:
If you deselect this option, only the yellow arrow is shown (as in
previous versions of 4D).
Suggestions The autocomplete mechanisms in the Method editor are refined and
extended in 4D v12 (see the “Autocomplete” paragraph on page 56).
The "Suggestions" area lets you configure this feature to adapt it to
your own work habits.
Compatibility note The "Allow Type-Ahead" option, found in previous versions of 4D, is
replaced by these new options.
Automatic opening of window for:

This option triggers the automatic display of the suggestion window
for constants, local and interprocess variables, and tables.
36 4D v12 Upgrade
For example, when the "Local and interprocess variables" option is

checked, a list of suggestions appears when you type the $ character:
You can disable this functioning for certain elements of the language
by deselecting their corresponding option.
Validation of a suggestion for:
This option sets the entry context that allows the Method editor to
validate automatically the current suggestion displayed in the
autocomplete window.
Tab and delimiters: When this option is selected, you can validate
the current selection with the Tab key or any delimiter that is
relevant to the context. For example, if you enter "ALE" and then
"(", 4D automatically writes "ALERT(" in the editor. Here is the list of
delimiters that are taken into account:
(;:=<[{
This works the same way as in the previous 4D version.
Tab only: When this option is selected, you can only use the Tab
key to insert the current suggestion. This can be used more
particularly to facilitate the entry of delimiter characters in element
names, such as ${1}.
Note You can double-click in the window or press the Carriage return key to
validate a suggestion.
Colors Use these options to configure the different colors used in the Method
editor interface.
Line where the cursor is (active window) / Line where the cursor is
(inactive window): Background color of line containing the cursor.
Highlight of the words found: Highlight color of words found in a
search.
Highlight of the parentheses: Highlight color of corresponding
parentheses (used when pairs of parentheses are signaled by
highlighting, see the “Method editor and debugger options”
paragraph on page 35).
4D v12 Upgrade 37
Editing area background: Background color of Method editor

window.
Suggested text: Color of autocomplete text suggested by the
Method editor.
Shortcuts On the Shortcuts page, you can configure keyboard shortcuts.
This page lists all the shortcuts used in the 4D Design environment
(except for standard "system" shortcuts, such as Ctrl+C/Command+C for
the Copy command). To modify a shortcut, you can select/deselect the
item to modify (Shift, Alt or letter key) in the list. You can also double-
click on a shortcut to configure it using a specific dialog box. Note that
each shortcut implicitly includes the Ctrl (Windows) or Command
(Mac OS) key.
Note This list is based on the 4DShortcutsv12.xml file located in the [4D
Extensions] subfolder. If you customize the list in the dialog box, this
file is duplicated in the user Preferences folder and is used instead of
the standard file. Hence, each time 4D is updated your keyboard
shortcut preferences remain.
38 4D v12 Upgrade
New database
settings
PHP In 4D v12, you can execute PHP scripts directly by configuring the PHP
page of the Database Settings (see the “Executing PHP scripts in 4D”
paragraph on page 62):
Interpreter address and port number
By default, 4D provides a PHP interpreter, compiled in FastCGI. For

reasons of internal architecture, execution requests go to the PHP
interpreter at a specific HTTP address. By default, 4D uses the address
127.0.0.1 and port 8002. You can modify this address and/or port if
they are already taken or if you have several interpreters on the same
machine. To do this, you modify the IP Address and Port number
parameters on the PHP page in the Database Settings.
Note that the HTTP address must be on the same machine as 4D.
External interpreter
If you use an external PHP interpreter, it must be compiled in FastCGI

and be on the same machine as 4D (see the “Using another PHP
interpreter or another php.ini file” paragraph on page 64).
Select this option so 4D does not attempt a connection with the
internal interpreter when executing a PHP request. Note that this
configuration requires your manual execution and control of the
external interpreter.
4D v12 Upgrade 39
PHP options
These options are related to the automatic management of the 4D PHP

interpreter and are disabled when the External interpreter option is
selected.
Number of processes: The 4D PHP interpreter drives a set of system
execution processes called "child processes". For optimization, it can
run and keep up to five child processes simultaneously by default.
You can modify the number of child processes according to your
needs. For example, you may want to increase this value if you call
on the PHP interpreter intensively. For more information, refer to
the “Architecture” paragraph on page 63.
Note Under Mac OS, all child processes share the same port.
Under Windows, each child process uses a specific port number. The
first number is the one set for the PHP interpreter; the other child
processes increment this number. For example, if the default port is
8002 and you launch 5 child processes, they will use ports 8002 to
8006.
Restart the interpreter after X requests: This sets the maximum

number of requests that the 4D PHP interpreter accepts. When this
number is reached, the interpreter restarts. For more information
about this parameter, refer to the FastCGI-PHP documentation.
Note In this dialog box, the parameters are specified by default for all
connected machines and all sessions. You can also modify and read
them separately for each machine and each session using the SET
DATABASE PARAMETER, Get database parameter commands. The
parameters modified by the SET DATABASE PARAMETER command have
priority for the current session.
40 4D v12 Upgrade
Structure editor
64-bit compilation You can compile 4D v12 applications for 32-bit and 64-bit processors.
You enable this on the "Compiler" page of the Database Settings by
selecting or deselecting the new Also compile for 64-bit processors
option:
New option
Notes - The 64-bit version of 4D Server v12 is currently available in beta

version. For more information, refer to the “About the 64-bit 4D
Server” paragraph on page 321.
- A 4D database that is not converted to Unicode mode cannot be
compiled in 64 bits.
Structure editor
The Structure editor has new functions related to display management.
Dim Others You can now dim tables and relations that are not selected in the
Structure editor. In previous 4D versions, tables could only be dimmed
by folder.
The new Dim Others function dims any table and/or relation not
selected or not connected to the selected elements in the editor
window. It is available:
in the folder management menu of the editor,
4D v12 Upgrade 41
in the context menu of the editor (click on a table or a relation)
Highlight All When elements are dimmed using Dim Others or a folder management
menu command, the new Highlight All command redisplays all the
contents of the editor. This command is in the context menu of the
structure editor.
Move to Front When a group of several tables are superimposed in the Structure
editor, it may be difficult to display one of the tables of the group.
In this case, you can right click on the top table to display the Move to
Front submenu, which lists the names of all the tables stacked under
the first one.
42 4D v12 Upgrade
Optimizing searches in the Design environment
You can then select the table you want to move to the front from this
list:
Menu for managing

stacked tables

Search and replace in the Design environment have been revised
according to the needs of 4D developers. This section describes the
new features and modifications concerning this function in 4D v12.
4D v12 Upgrade 43
Search dialog box The search dialog box appears when you select the Edit > Find in
Design menu command. In 4D v12, the options provided in this dialog
box have been modified:
Definition of a search You can specify the type of element to look for using the Find menu.
The following choices are available:
Text: In this case, 4D looks for a character string throughout the

Design environment.
The search is done in plain text mode, without taking the context into
account. For example, you can look for the text "Alert("Error
number:"+" or "button27".
In this mode, you cannot use the wildcard character because "@" is
considered to be a standard character.
44 4D v12 Upgrade
Comment: This search is basically the same as the previous one but it is
restricted to the contents of comments (lines beginning with //). For
example, you can search for any comments containing the string "To
be verified".
Note The end result of both types of searches depends on how the search
mode (which) menu is set (see the “Search mode” paragraph on
page 46).
Language expression: Used to search for any valid 4D expression.

Validity is important because 4D must be able to evaluate an
expression to be able to search for it. For example, a search for
"[clients" (invalid expression) will not return any result whereas
"[clients]" is correct.
This option is particularly suitable for searches for value assignments
and comparisons. For example:
Search for "myvar:=" (assignment)
Search for "myvar=" (comparison)
Language element: Used to search for a specific language element by
its name. 4D can distinguish between the following elements:
Project method: Name of a project method, for example "M_Add".
Note that this search (associated with the is exactly mode) is the
equivalent of the Search references contextual command in the
Method editor (see the “Search references” paragraph on page 60).
Form: Form name, for example "Input". The command searches
among project forms and table forms.
Field or Table: Name of a table or field, for example "Customers".
Variable: Any variable name, such as "$myvar".
Named constant: Any constant, such as "Is Picture".
String in quotes: Literal text constant; i.e. any value within quotes
in the code editor or inserted into text areas of the Form editor
(static text or group boxes). For example, a search for "Martin" will
return results if your code contains the line:
QUERY ([Customers];[Customers]Name="Martin")
Command: 4D command, for example "Alert".
Plug-in: Plug-in command installed in the application, for example
"WR Find".
4D v12 Upgrade 45
Anything: This option searches among all the objects in the Design
environment. Only the modification date filter is available. Use this
option, for example, to search for "all objects modified today".
Search mode The search mode menu (i.e. which, that is or whose name, depending
on the type of search) specifies how to search for the value that is
entered. The contents of this menu vary according to the type of
element to search for as selected in the previous menu.
Search options for Text or Comment:
contains: Searches all the text of the Design environment for the
specified string. Search results for "var" can include "myvar",
"variable1" or "aVariable".
contains whole word: Searches all the text of the Design
environment for the string as a whole word. Search results for "var"
only include exact occurrences. They will not include "myvar" but
will include, for example, "var:=10" or "ID+var" because the symbols
: or + are word separators.
starts with / ends with: Searches for the string at the beginning or
end of the word (text search) or at the beginning or end of the
comment line (comment search). In "Text ends with" mode,
searching for "var" will find "myvar".
Search options for Language element: The menu offers standard
options (is exactly, contains, starts with, ends with) similar to the ones
provided in previous 4D versions.
Note that you can use the search wildcard (@) with the is exactly
option (returns all objects of the type specified).
Modification date of the This menu has several new options to let you quickly specify a
parent standard search period:
is today: Period beginning at midnight (00:00 h) of the current day.

is since yesterday: Period including the current day and the
previous one.
46 4D v12 Upgrade
is this week: Period beginning on Monday of the current week.

is this month: Period beginning on the 1st day of the current
month.
Examples of An efficient search results from a judicious combination of the options

searches of the Find and search mode (which) menus. To illustrate how searches
work in 4D v12, below are a few examples of typical searches and how
to configure them.
Search for all locations where a value was directly assigned to the vTInit
variable:
4D v12 Upgrade 47
Search for all references to the "Input" form of the [Customers] table:
Search for calls to any methods whose name starts with "HR_"
48 4D v12 Upgrade
List all variables in the database:
Search for the "Designer" keyword in the comments written this week:
4D v12 Upgrade 49
Replace and rename Renaming and replacing functions are simplified in 4D v12. There are
now two commands available:
Replace in content, found in the search results window. This command
replaces one character string by another within the listed objects.
Rename, found in the Explorer and the New code editor. This
command renames a project method or variable and propagates its
new name among all its callers.
Replace in content All replacing is now done using the new Replace in content command
that is available in the options menu of the search results window.
When you select this command, a dialog box appears where you enter
the character string that will replace all the occurrences found by the
initial search:
50 4D v12 Upgrade
Replacing operations now work as follows:

Replacing is always carried out among all items found in the list and
not just for a selection. However, it is possible to narrow the replacing
operation by first reducing the contents of the list using the new
Remove command in the context menu:
Only the occurrences shown in the list will be replaced and only after
checking the initial search criteria for cases where objects were
modified between the initial search and the replacing operation.
Replacing is done in:
the contents of methods
the properties of form objects
the contents of help messages
the contents of entry filters
the contents of menu items (item text and method calls)
the contents of choice lists
the contents of comments for methods, forms, tables and fields in
the Explorer.
For each object modified, 4D checks whether it is already loaded by
another machine or in another window. In the case of conflict, a
standard dialog box appears indicating that the object is locked. You
can close the object and then try again or cancel its replacement. The
replacing operation will then continue with the other objects in the
list.
4D v12 Upgrade 51
If a method or form concerned by a "replace in content" operation is

currently being edited by the same 4D application, it will be modified
directly in the open editor (no warning appears). Forms and methods
modified in this way are not saved automatically: you will need to use
the Save or Save All command explicitly to validate the changes.
After a replacement is made in a list item, it will appear in italics. A
count of replacements made in real time appears at the bottom of the
window.
Objects are never renamed by the Replace in content function, except
for form objects. Hence it is possible that certain items in the list may
not be affected by the replacing operation. This can occur when only
the item name corresponds to the initial search criteria. In this case,
the list items do not necessarily all appear in italics and the final
replacement count may be less than the number of occurrences found
by the initial search.
Renaming Renaming with distribution throughout the entire database is now

reserved for project methods and variables. This can be carried out:
using the Rename... command of the Method editor context menu
(project methods and variables),
using the Rename Method... command of the Explorer context
menu (project methods).
52 4D v12 Upgrade
Searching for unused elements
When you select this command, a dialog box appears where you enter
the new name for the object:
This new name must comply with naming rules; otherwise a warning
appears when you validate the dialog box. For example, you cannot
rename a method with a command name such as "Alert".
Depending on the type of object you are renaming (project method or

variable), the renaming dialog box may also contain a distribution
option:
Project method: The Update callers in whole database option renames
the method in all the database objects that reference it. You can also
uncheck this option in order, for example, to rename the method only
in the Explorer itself.
Process and interprocess variable: The Rename variable in whole
database option renames the variable in all the database objects that
reference it. If you uncheck this option, the variable is only renamed in
the current method.
Local variable: No distribution option for this object; the variable is
only renamed in the current method.
Searching for unused elements

Two new search commands allow you to detect variables and methods
that are not used in your code. You can then remove them to free up
memory.
4D v12 Upgrade 53
These commands are found in the Edit menu of the Design

environment:
New commands
Find Unused The Find Unused Methods and Global Variables command looks for
Methods and Global project methods as well as "global" variables (process and interprocess
Variables variables) that are declared but not used. The search results appear in a
standard results window.
A project method is considered to be unused when:

it is not in the Trash,
it is not called anywhere in the 4D code,
it is not called by a menu command,
it is not called as a string constant in the 4D code (4D detects a
method name in a string even when it is followed by parameters in
parentheses).
A process or interprocess variable is considered to be unused when:

it is declared in the 4D code by a declaration command of the
C_XXX or ARRAY XXX type,
it is not used anywhere else in the 4D code,
it is not used in any form object.
54 4D v12 Upgrade
New code editor
Note that certain uses cannot be detected by the function - i.e. an

element considered unused may in fact be used. This is the case in the
following code:
v:="method"
EXECUTE FORMULA("my"+v+String(42))
This code builds a method name. The mymethod42 project method is

considered unused when in fact it is called.
Therefore, it is advisable to check that the elements declared as unused
are in fact unnecessary before you remove them.
Find Unused Local The Find Unused Local Variables command looks for local variables
Variables that are declared but not used. The search results appear in a standard
results window.
A local variable is considered to be unused when:

it is declared in the 4D code by a command of the C_XXX or ARRAY
XXX type,
it is not used anywhere else within the same method.
New code editor

In 4D v12, the code editor has multiple new functions intended to
increase developer productivity.
In particular, the editor now provides the same ease of use

(autocomplete function, debugging, etc.) for both 4D and SQL code.
The editor in 4D v12 retains most of the characteristics and tools of the
one in 4D v11 SQL as well as bringing in additional functions. This
manual only describes the new features and modifications. For a
description of the basic functions of the editor, refer to the Design
Reference manual of 4D v11 SQL.
Text entry assistance There are several new functions for text entry assistance and code
editing in 4D v12.
4D v12 Upgrade 55
Autocomplete Autocomplete features now apply to SQL code and take into account
previously entered parameters, such as the optional "*" parameter. Two
new features are provided:
When the characters you enter correspond to a single possible value, it
appears grayed out (and is inserted if you hit the Tab key):
Autocompletion features are extended to variables as well as table and

field names and take previously entered parameters into account, such
as the optional "*" parameter.
Note You configure the autocomplete features in the Preferences of the

application (see the “Suggestions” paragraph on page 36).
Selection The Method editor has new selection functions:

Double-click to select "words". When the name of a referenced element
(command, constant, method, etc.) contains spaces, you can select all
of it with a combination of Alt/Option + Double-click.
Move the line where the cursor is directly without selecting it first: use
the combination Alt/Option + Up Arrow or Down Arrow. You can also
do this with the new Move Lines Up and Move Lines Down commands
in the Method menu.
Select a block using two new commands: Start Of Block and End Of
Block (Method menu). These commands place the cursor at the start or
end of a block of code (delimited by a logical structure of the If...End if
type).
Furthermore, the Select Block command now initially selects the
blocks without the surrounding characters (parentheses, brackets, etc.).
56 4D v12 Upgrade
New code editor
Changing case You can now automatically modify the case of selected characters
using commands from the Case submenu in the Method menu or the
context menu of the editor:
Uppercase / Lowercase: Switch the selected characters to uppercase or

lowercase.
camelCase / CamelCase: Switch the selected characters to "camel case".
This consists in changing each first letter of a group of attached words
to uppercase. This type of notation is often used for variable
nomenclatures. hireDate and PurchaseDate are examples of two variants
of camel case notation.
When you apply one of these commands to a text selection, the spaces
and "_" characters are removed and the first letter of each word
becomes uppercase.
Entry on several rows You can now write a single statement on several lines by terminating
each line of the statement with a backslash "\" character. 4D will
consider all the lines at once.
For example, both of the following statements are equivalent:
Collapse/Expand Use the new commands in the Method menu to collapse and expand
selection parts of the code.
4D v12 Upgrade 57
Collapse / Expand Selection: collapses or expands all the code

structures in the text selection.
Collapse / Expand Current Level: collapses or expands the code
structure at the level where the cursor is located. These commands are
also available in the context menu of the editor.
IME (Windows) Under Windows, the new code editor includes an Input Method Editor
(IME) to facilitate code editing on Japanese or Chinese systems.
Browsing
Goto Definition The new Goto Definition command opens the definition of an object
referenced in the Method editor (method, field, table or form) directly
in a new window. To do this, place the cursor inside the object name
(or select it) and choose Goto Definition... from the Method menu or
from the context menu of the editor:
New command in Method editor’s

context menu
This command functions with the following objects:

project method: displays the contents of the method in a new window of
the Method editor,
Note This function is available through the keyboard shortcut Ctrl+K

(Windows) or Command+K (Mac OS) with the project method name
selected.
field: displays the properties of the field in the inspector of the

structure window,
table: displays the properties of the table in the inspector of the
structure window,
58 4D v12 Upgrade
New code editor
form: displays the form in the Form editor,
variable (local, process, interprocess or $n parameter): displays the line

declaring the variable in the current method or among the compiler
methods.
Go to start or end of Two new commands facilitate browsing among the code structures
block (If...Else...End if, etc.):
Start Of Block: Moves the cursor in front of the opening keyword of
the current structure.
End Of Block: Moves the cursor to just after the closing keyword of the
current structure.
These commands are available in the Method menu or via the context
menu of the editor. You can also use the following key combinations:
Windows: Ctrl + Ç or Ctrl + È
Mac OS: Command + Ç or Command + È
Bookmarks 4D v12 lets you associate bookmarks with certain lines in your
methods. You can then browse quickly within the code by passing
from one bookmark to another using specific commands.
Bookmark
associated with line
A bookmark moves along with its original row if additional rows are
inserted in the method. Bookmarks are saved with the methods.
4D v12 Upgrade 59
Bookmarks are managed using the Bookmarks submenu of the Method

menu:
Toggle: Associates a bookmark with the current line (where the cursor
is located) if it does not already have one or removes the existing
bookmark if it does.
This function is also available using the Toggle Bookmark command of
the editor’s context menu or using the Ctrl+F3 (Windows) or
Command+F3 (Mac OS) keyboard shortcut.
Remove All: Removes all bookmarks from the foreground window.
Goto Next / Goto Previous: Enables browsing among bookmarks in the

window. Selecting one of these commands places the cursor on the
first character of the line associated with the bookmark concerned. You
can also use the keyboard shortcuts F3 (go to next) or Shift+F3 (go to
previous).
Search references The Search references... command found in the Method menu or the
context menu of the Method editor, replaces the Search Callers
command found in previous versions of 4D. Search Callers displayed
the list of objects referencing (calling) the submethod selected in a
search results window.
The Search references... command keeps this same functioning and

extends it to variables and fields. You can use it to search for all the
methods where the selected variable or field is referenced.
60 4D v12 Upgrade
New code editor
Display New visual marks facilitate the readability and maintenance of the
code.
When you click next to a surrounding character (parentheses or
bracket), it (along with its corresponding start/end character) is framed
by a gray rectangle:
This mark also appears when you type a closing parenthesis or bracket.
Errors are indicated by an icon with a help tip to the left of the editing
area:
When a block of code is collapsed, only the first line is visible and an
expand button automatically appears:
Expand button
If you place the mouse over the expand button, a help tip appears,
displaying the first lines of the hidden code.
A help tip now shows the type of the variables:
You can now display the spaces between words using symbols instead
of "blank space". This function applies to all the code elements
(command names, variables, comments, etc.) and is available via the
View > White Spaces command of the Method menu:
Spaces not displayed
Spaces displayed
The status bar located at the bottom right part of the editor window
displays the position of the cursor at all times:
Ln: Line number
4D v12 Upgrade 61
Col: Column number, i.e., the level in the hierarchy of

programming structures. The first level is 0. The column number is
useful for debugging since this information can be provided by the
interpreter in the event of an error in the code.
Ch: Location of character in the line.
The new Bigger Font and Smaller Font commands of the Method >
View submenu temporarily modify the size of the font in the
foreground window until you close it. To modify the font size of the
method editor windows permanently, use the "Methods" page of the
application Preferences.
Change bars: colored bars instantly show you where lines of code were
modified since the method was opened:
Change bars
The change bars change colors to indicate whether or not the

modifications were saved:
yellow: row was modified and method has not yet been saved.
green: row was modified and method has been saved.
Comments Code comments are now indicated using the double slash character
(//). You can now comment/uncomment a line or block of lines using
the shortcut Ctrl+/ (Windows) or Command+/ (Mac OS).
Note For compatibility, you can still use the ` character to comment a line.
Executing PHP scripts in 4D

In 4D v12, you can directly execute PHP scripts. This gives you access
to the wealth of utility libraries available via PHP. More particularly,
these libraries provide the following functions:
Ciphering (MD5) and hashing
Handling of ZIP files
Handling of pictures
62 4D v12 Upgrade
LDAP access
COM access (control of MS Office documents)...
This list is not exhaustive. For a complete list of the PHP modules
available by default with 4D, refer to appendix A, “PHP Modules,” page
325. Also, note that it is possible to install additional custom modules
(see the “Installation of additional modules” paragraph on page 331).
Architecture 4D provides a PHP interpreter compiled in FastCGI, client-server type

communication protocol between an application and a PHP
interpreter.
The PHP interpreter drives a set of system execution processes called

"child processes". These processes are dedicated to processing requests
sent by 4D. The execution of the requests is synchronous. For
optimization reasons, by default up to five child processes can be run
simultaneously (this number can be modified via the Database Settings
or via the SET DATABASE PARAMETER command). Under Mac OS, these
processes are launched on the first request and are kept permanently
by the PHP interpreter. Under Windows, 4D creates the processes
according to its needs and recycles them if necessary. 4D automatically
supports the management PHP interpreter processes provided by
default (launching and closing).
Note If the 4D program quits unexpectedly while child PHP processes are
still active, you must delete them manually via the system process
management window.
The following diagram illustrates the 4D/PHP architecture of 4D v12:
4D v12 Upgrade 63
This architecture works with a system of internal requests sent by 4D

to a predefined TCP address (IP address and port number). You can
change this if necessary, as when several PHP interpreters run on the
same machine, using the Database Settings (see the “PHP” paragraph
on page 39) or by programming (see the SET DATABASE PARAMETER, Get
database parameter commands).
Note If you launch two 4D applications on the same machine and execute
PHP statements on each of them (via the PHP Execute command, see
below), it is imperative to modify the listening ports of the FastCGI
PHP interpreter so that you use a different one for each application.
Otherwise, PHP statements can unpredictably fail to execute.
Using another PHP You can choose to use a different PHP interpreter than the one
interpreter or provided by 4D. A custom PHP interpreter must respect two
another php.ini file conditions:
It must be compiled in FastCGI,
It must be located on the same machine as 4D.
To use a custom PHP interpreter, you must configure it to listen to a

specific address and TCP port and you must indicate to 4D not to
activate the internal interpreter. You can specify these parameters
either using database settings (see the “PHP” paragraph on page 39), or
for the session via the SET DATABASE PARAMETER command (see the SET
DATABASE PARAMETER, Get database parameter paragraph). In this case,
you must manage the starting and functioning of the interpreter
yourself.
You can also use a custom php.ini configuration file in order, for
example, to use additional modules. The php.ini file can be used, more
particularly, to declare the location of the PHP extensions.
To do this, place a custom php.ini file in the preferences folder of the
current database ("Preferences" folder located next to the structure file).
4D detects it when the interpreter executes and uses it instead of the
default 4D php.ini file. You must make sure that the contents of the
custom php.ini file are valid.
64 4D v12 Upgrade
Warning: The php.ini file must set "display_errors" to "stderr" to inform

4D of any errors during PHP code execution. For example:
; stderr - Display the errors to STDERR (only affects the CGI/CLI)
; To direct the errors to STDERR for the CGI/CLI:
display_errors = "stderr"
For more information about the configuration of custom php.ini files,

refer to the comments found in the php.ini file provided by 4D.
PHP modules The PHP interpreter provided with 4D v12 contains a selection of
integrated modules, retained in particular according to their
pertinence and relevance.
The detailed list of modules supplied with 4D as well as examples of

use are provided in the appendix A, “PHP Modules,” page 325.
You can install additional modules in order to add functionalities to

your application. For more information about adding PHP modules,
refer to the “Installation of additional modules” paragraph on
page 331.
Executing a PHP To execute a PHP script or function, you must use the new PHP Execute
script command. This command is described in the “PHP Execute” paragraph
on page 182.
By default, 4D v12 includes PHP version 5.3.2. Executed scripts must

be compatible with this version and with the modules installed. For a
complete list of the modules available with the PHP version provided
by 4D, refer to appendix A, “PHP Modules,” page 325.
For a complete description of PHP commands and syntax, refer to the

PHP documentation available on the Internet. Below are the addresses
for a few reference sites:
http://us.php.net/manual/en/
http://phpdeveloper.org/
http://php.start4all.com/
http://php.resourceindex.com/Documentation/
4D v12 Upgrade 65
Recover by record headers

The Repair page of the Maintenance and Security Center (MSC)
includes a new Recover by record headers option that you can use to
recover data via the record header markers:
New recovery
option
Use this low-level repair option only when the data file is severely
damaged and after all other solutions (restoring from a backup,
standard repair) have proven to be ineffective.
What is recovery by 4D records are variable in size. Hence it is necessary to keep the
header markers? location where they are stored on your disk in a table in order to find
them again. The program therefore accesses the address of the record
via an index and a table of addresses.
66 4D v12 Upgrade
If only the records or the indexes are damaged, the standard repair
option is usually sufficient to resolve the problem. However, when the
address table itself is affected, it requires a more sophisticated recovery
since it will be necessary to reconstitute it. To do this, the MSC uses the
marker located in the header of each record. The markers are compared
to a summary of the record, including the bulk of their information,
and from which it is possible to reconstruct the address table.
Note If you have deselected the Records definitively deleted option in the
properties of a table in the database structure, performing a recovery
by header markers may cause records that were previously deleted to
reappear.
Recovery by headers does not take integrity constraints into account.

More specifically, after this operation you may get duplicated values
with unique fields or NULL values with fields declared Never Null.
Recovery procedure To do a recovery by headers, display the "Repair" page of the MSC and
select the Recover by record headers option, then click on Scan and
repair...
Note This operation requires that you open the database in Maintenance
mode. If not, a warning dialog box informs you that the database will
be closed and reopened in this mode.
4D v12 Upgrade 67
In the first phase of the recovery procedure, 4D performs a complete

scan of the data file. When the scan is complete, the results appear in
the following window:
Note If all the records and all the tables have been assigned, only the main
area is displayed.
The "Content of the scanned data file" area includes two tables
summarizing the information from the scan of the data file.
The first table lists the information from the data file scan. Each row
shows a group of recoverable records in the data file:
The first column indicates the recovery order for the group of records.
The ## column indicates the number of the table assigned to the

group, if there is one.
The Assigned tables column indicates the names of tables that were
automatically assigned to the groups of identified records. The names
of tables assigned automatically appear in green.
The Recoverable records column indicates the number of recoverable
records in the group.
68 4D v12 Upgrade
The Recover column lets you indicate for each group whether you
want to recover the records. By default, this option is checked for every
group.
The second table lists the tables that were not assigned, i.e. tables that
could not be associated with any records.
Manual assigning If several groups of records could not be assigned to tables due to a
damaged address table, you can assign them manually.
To do this, first select an unassigned group of records in the first table.

The "Content of the records" area then displays a preview of the
contents of the first records of the group to make it easier to assign
them:
Next select the table you want to assign to the group in the
"Unassigned tables" table and click on the Assign table button. You can
also assign a table by drag and drop.
The group of records is then associated with the table and it will be
recovered in this table. The names of tables that are assigned manually
appear in black.
4D v12 Upgrade 69
Use the Unassign table button to remove the association made

manually between the table and the group of records.
Launching the recovery Once you have configured the elements to recover, click on the
Recover button to launch the repair.
Note You can click on the Back button to cancel the procedure and return to
the previous state.
4D creates a new empty data file at the location of the original file to
receive the recovered data. The original file is moved to the folder
named "\Replaced Files (Repairing) date time" whose location was
specified on the "Repair" page of the MSC (database folder by default).
When the procedure is completed, the "Repair" page of the MSC

appears. A message like the one below indicates that the repair was
successful:
In this case, you can open the database immediately.
As with all analysis functions of the MSC, the Open log file button
displays a Web page in your browser providing the details of the
operation results. This page lists all the checks or repairs performed
and indicates every error that occurred, if applicable ([OK] is displayed
when the verification is correct). The log file is generated in the Logs
folder of the database. It is created in XML and HTML format and is
named “DatabaseName_Repair_log”.
70 4D v12 Upgrade
4 Forms and Objects
4D v12 offers numerous new features related to forms and the objects
they contain. These new features facilitate and accelerate the
development of your application interfaces.
Extension of subform capacities

4D v12 increases the capacities of subforms (also called included
forms). More flexible use, programmable, usable in a component, these
new generation objects are now powerful tools for developing
advanced and easily portable functions.
Terminology In order to clearly define the concepts implemented with subforms,

here are some definitions for certain terms used:
subform: a form intended for inclusion in another form, itself called
the parent form.
parent form: a form containing one or more subform(s).
subform container: an object included in the parent form, displaying

an instance of the subform.
subform instance: the representation of a subform in a parent form.
This concept is important because it is possible to display several
instances of the same subform in a parent form.
4D v12 Upgrade 71
Chapter 4 Forms and Objects
New properties You can now associate additional properties, using the Property list, to
subform objects installed in the parent forms:
Variable Name: a variable can now be bound with a subform object. By
default, it is named "Subform", like the object itself. It has a type (see
following paragraph) and can be represented in the form of a standard
variable in the parent form. Its modification triggers form events and
can therefore synchronize the values of the parent form and the
subform:
Use the On Data Change form event to indicate to the subform
container that the variable value was modified in the subform.
Use the new On bound variable change form event to indicate to the
subform (form method of subform) that the variable was modified
in the parent form (see the “Update of subform contents”paragraph
on page 74).
Variable Type: used to set the type for the variable bound with the
subform object. By default, the Alpha type is used. The variable type
determines the nature of the values exchanged between the parent
form and the subform via the bound variable.
You can set the type to "None"; in this case, 4D automatically types the
variable during execution (see the “Dynamic variables” paragraph on
page 255).
Source: named "Source Table" in previous versions of 4D, this property
is now used to select different types of sources:
<None>: choose this type of source to use a project form or a
component form as subform. These subforms can only be used in
page form: for them to work, you must deselect the "List subform"
option.
For a component form to appear in the "Detail Form" list, it must be
published in the component (see the “Publishing a subform
(component)”paragraph on page 79).
Table name: choose this type of source to use table forms (same
behavior as previously in 4D).
Note The "Platform" appearance property no longer appears; the appearance

is set by the subform itself and cannot be modified.
72 4D v12 Upgrade
Method: a subform object can now have an object method, which

allows you to control how it works, in particular when events are
triggered (see the following paragraph). Note that the interaction
between the contents of the subform object and the parent form must
be managed by specific mechanisms (see the “Advanced inter-form
programming”paragraph on page 76).
Form events: a subform object accepts the following events:
On Load and On Unload: opening and closing (respectively) of the
subform (these events must also be enabled at the parent form level
to be taken into account). Note that these events are generated
before those of the parent form.
Also note that, in accordance with the operating principles of form
events, if the subform is located on a page other than page 0 or 1,
these events are only generated when that page is displayed/closed
(and not when the form is displayed/closed).
On Validate: validation of data entry in the subform.
On Data Change: the value of the variable of the subform object has
been modified.
On Getting Focus and On Losing Focus: subform container just got or
lost the focus. These events are generated in the method of the
subform object when they are selected. They are sent to the form
method of the subform, which means, for example, that you can
manage the display of navigation buttons in the subform according
to the focus.
Note that subform objects themselves may have the focus.
Notes - It is possible to specify any custom event type that could be generated
in a subform via the new CALL SUBFORM CONTAINER command. This
command lets you call the container object method and to pass an
event code to it.
- A new form event, On bound variable change, can be managed at the
subform level (see the “Update of subform contents”paragraph on
page 74).
- When the SET TIMER command is executed in the context of a
subform (form method of subform), the On Timer event is now
generated in the subform and not in the parent form (as with previous
4D versions). This allows On Timer events to be generated with
different intervals in each subform and in the parent form.
4D v12 Upgrade 73
Management of the The variable bound to the subform lets you link the two contexts (form
bound variable and subform) to put the finishing touches on sophisticated interfaces.
For example, imagine a subform representing a dynamic clock,
inserted into a parent form containing an enterable variable of the
Time type:
Parent form Subform
ParisTime Variable 10:15:00

Subform object
(Variable name:
ParisTime)
Both objects (time variable and subform container) have the same
variable name. In this case, when you open the parent form, 4D
synchronizes both values automatically. If the variable value is set at
several locations, 4D uses the value that was loaded last. It applies the
following loading order:
1-Object methods of subform
2-Form method of subform
3-Object methods of parent form
4-Form method of parent form
When the parent form is executed, the developer must take care to
synchronize the variables using appropriate form events. Two types of
interactions can occur: form to subform and vice versa.
Update of subform The value of the parent form variable is modified and this
contents modification must be passed on to the subform. In our example, the
time of ParisTime changes to 12:15:00, either because the user entered
it, or because it was updated dynamically (via the Current time
command for example).
74 4D v12 Upgrade
In this case, you must use the new On bound variable change form
event. This event must be selected in the properties of the subform; it
is generated in the form method of the subform.
Parent form
12:15:00 On bound variable change
The On bound variable change form event is generated:

as soon as a value is assigned to the variable of the parent form, even if
the same value is reassigned,
if the subform belongs to the current form page or to page 0.
Note that, as in the above example, it is preferable to use the OBJECT

Get pointer command which returns a pointer to the subform
container rather than its variable because it is possible to insert several
subforms in the same parent form (for example, a window displaying
different time zones will contain several clocks). In this case, only a
pointer lets you know which subform container is at the origin of the
event.
Update of parent form The contents of the subform are modified and this modification must
contents be passed on to the parent form. In our example, imagine that the
subform interface lets the user to "manually" move the hands of the
clock.
4D v12 Upgrade 75
In this case, from the subform, you must assign the object value to the
variable of the parent subform container. As in the previous example,
we recommend that you use the OBJECT Get pointer command with
the Object subform container selector which returns a pointer to the
subform container.
Assigning the value to the variable generates the On Data Change form
event in the object method of the parent subform container, which lets
you perform any type of action. The event must be selected in the
properties of the subform container.
Parent form
Reminder: same 12:30:00 On Data Change

variable name
Perform actions...
Object method of clockValue variable in

subform
Note If you "manually" move the hands of the clock, this also generates the
On Data Change form event in the object method of the clockValue
variable in the subform.
Advanced inter- Communication between the parent form and the instances of the
form programming subform may require going beyond the exchange of a value via the
bound variable. In fact, you may want to update variables in the
subforms according to the actions carried out in the parent form and
vice versa. If we use the previous example of the "dynamic clock" type
subform, we may want to set one or more alarm times per clock.
4D has implemented the following mechanisms to meet these needs:

Use of the "subform" parameter with the OBJECT Get pointer command
to specify the subform object and the new OBJECT Get name
command.
76 4D v12 Upgrade
Calling of a container object from the subform via the new CALL
SUBFORM CONTAINER command,
Execution of a method in the context of the subform via the new
EXECUTE METHOD IN SUBFORM command.
Object get pointer and In addition to the "Object subform container" selector (see the “Update
Object get name of subform contents”paragraph on page 74), the Object get pointer
commands
command accepts a parameter that indicates in which subform to
search for the object whose name is specified in the second parameter.
This syntax can only be used when the "Object named" selector is
passed.
For example, the following statement:

$ptr:=Object get pointer(Object named;"MyButton";"MySubForm")
... retrieves a pointer to the "MyButton" variable that is located in the

"MySubForm" subform object. This syntax can be used to access from
the parent form any object found in a subform. For a complete
description of this command, refer to the OBJECT Get pointer
command on page 233.
Note Also note the new OBJECT SET STYLED TEXT ATTRIBUTES command
which can be used to retrieve the name of the object that has the
focus.
New CALL SUBFORM The new CALL SUBFORM CONTAINER command lets a subform instance
CONTAINER command send an event to the subform container object, which can then process
it in the context of the parent form. The event is received in the
container object method. It may be at the origin of any event detected
by the subform (click, drag-and-drop, etc.). This mechanism is
illustrated in the following diagram:
Example of execution of the CALL PARENT OBJECT command
Parent form
xxx
Subform object
method Subform
Custom event
CALL PARENT OBJECT (2000)
4D v12 Upgrade 77
The code of the event is unrestricted (for example, 20000 or -100). It

must not, in theory, correspond to any existing form event. It is
recommended to use a negative value to be sure that this code will not
be used by 4D in future versions.
You can also use a code that corresponds to existing events (for
example, 3 for On Validate), but in this case, the event must be allowed
and checked for the subform container.
For a complete description of this command, refer to the “CALL

SUBFORM CONTAINER” paragraph on page 133.
New EXECUTE METHOD This new command lets a form or one of its object request the
IN SUBFORM command execution of a method in the context of the subform instance, which
gives it access to the variables, objects, etc. of the subform. This
method can also receive parameters. This mechanism is illustrated in
the following diagram:
Example of execution of EXECUTE METHOD IN SUBFORM command
Parent form
xxx
EXECUTE METHOD IN
Subform SUBFORM("SF1";"meth";$curtext)
xxx
Note If the subform comes from a component, the method must have the
"Shared by components and host database" property.
For a complete description of this command, refer to the “EXECUTE

METHOD IN SUBFORM” paragraph on page 140.
GOTO OBJECT The GOTO AREA command has been renamed GOTO OBJECT and can
command (formerly now look for the destination object in the parent form even if it is
GOTO AREA)
executed from a subform (see the “GOTO OBJECT” paragraph on
page 132).
Subforms in 4D v12 lets you publish component forms as subforms in the host
components databases. This means that you can, more particularly, develop
components offering graphic objects. Note that the new "widget"
objects provided by 4D are based on the use of subforms in
components (see the “Widgets”paragraph on page 82).
78 4D v12 Upgrade
Publishing a subform On the component side (matrix database), only project subforms can
(component) be specified as published subforms.
For a component form to be selected as a subform in a host database, it

must have been explicitly designated as a "published form" in the
properties dialog box of the form via the new Published as subform in
the host database option:
New option
Note This dialog box can be accessed via the Form Properties... command of
the context menu or from the action menu of the Explorer.
You must manage the interactions between the subform and the
parent forms of the host database using the mechanisms and tools
described in the previous paragraphs.
Using a component On the host database side, it is imperative that subforms coming from
subform (host database) components must be used in page mode: in the form editor, when the
subform object is selected in the parent form, deselect the Output
subform option in the "Sub-Form" theme of the Property list.
4D v12 Upgrade 79
Then, choose <None> in the "Table" menu. The forms published by the
components are then listed in the "Detail Form" menu. Their name is
followed by that of the component in parentheses. You can simply
choose from this list the form to be used in the "Detail Form" list.
Source: None
Deselected option
A new instance of the selected object is then immediately created in

the form.
Preconfigured object library

The preconfigured object library of 4D v12 is a new tool designed to
facilitate adding objects into 4D forms. It offers a collection of
preconfigured objects that can be used in your forms by simple drag-
and-drop or copy-paste.
Library objects This library uses exclusively standard 4D objects (buttons, text areas,
etc.) with certain properties that have been predefined in order to
accelerate and facilitate their implementation. For example, the
"password entry area" object is a text variable associated with a specific
style sheet. The library also offers high-level objects such as the
datepicker and timepicker widgets (see the “Widgets”paragraph on
page 82).
Note Unlike user object libraries, the preconfigured object library of 4D v12
cannot be modified: you cannot add or remove objects from this
library.
Using the library The preconfigured object library appears as a separate window. Objects
can be inserted into the form editor via drag-and-drop.
80 4D v12 Upgrade
Preconfigured object library
To display the preconfigured object library window, simply click on the

last button of the 4D form editor tool bar:
Object library access
The preconfigured object library then appears in a new window. It has

a pop-up menu, a preview area and a comments area:
Object category
selection menu Filtering by platform
Preview and selection of

objects
Description and comments
The objects are classified in different categories (buttons, entry areas,

etc.). To restrict the selection to a category of objects, select it from the
pop-up menu or choose All categories to display all the objects.
4D v12 Upgrade 81
Certain objects are related to a platform (Windows or Macintosh). You

can filter the objects displayed according to platform using the button
located in the top right corner of the window.
The central area displays a preview as well as the name of each object.
You can click on the object to obtain information about it: its
description is shown in the lower part of the window.
Objects can be inserted into a form by simple drag-and-drop or copy-

paste from the central areas of the window onto the form. The object is
inserted with its predefined properties. You can then modify them to
adapt the object to your needs.
Widgets
4D v12 lets you take advantage of predefined compound objects. These
widgets, which can be used with or without programming, give access
to standard functionalities that are very simple to implement. The
following new objects are available:
SearchPicker: search area with standard appearance.
DatePicker: date selector.
TimePicker: time selector.
Note Widgets can also be accessed via the new integrated object library
integrated of 4D (see the “Preconfigured object library”paragraph on
page 80).
SearchPicker With the SearchPicker widget, you can easily create standard search
areas, similar to those found in browsers or tool bars. The appearance
of the area depends on the platform.
Windows Mac OS
82 4D v12 Upgrade
Widgets
The text displayed by default in the area can be controlled by

programming, using a component method described in the
“SearchPicker” paragraph on page 267.
Functioning Besides its appearance, a SearchPicker search area is characterized by the

following elements: grayed out text, an entry area and a deletion icon.
The entry area is where you enter the value to be searched for. This
value is automatically and dynamically assigned to the variable that
you have bound with the area in the Property list (Variable Name
property). You use this variable to provide the value searched for to the
search method.
The grayed out text is an aid indicating to the user the field(s) where
the search will be carried out. It disappears as soon as the area has the
focus. This text can be set via the SearchPicker SET HELP TEXT
command.
The deletion button erases the contents of the area. Its functioning is
automatic.
During execution, you can launch your search method by clicking on
the button or via a form event. The area generates more particularly
the On Data Change and On Losing Focus events. You can provide a
dynamic search that is reevaluated each time the user enters another
character by calling the search method in the On Data Change event.
You can also launch the search when the user hits the Enter key: in this
case, you can simply call the search method in the On Losing Focus
event.
4D v12 Upgrade 83
Creation You can insert a SearchPicker area into a form using the new integrated
object library of 4D (see the “Preconfigured object library” paragraph
on page 80).
You can also create a subform and assign to it the detail form of the a
SearchPicker component, as described in the “Using a component
subform (host database)”paragraph on page 79.
Area displayed in
the form
Choice of SearchPicker
subform
Then specify the name of the variable bound with the subform
(Variable Name property in the Property list). When the form is
executed, this variable will automatically contain the value searched
for by the user. You can then pass this value to your custom search
method.
DatePicker The DatePicker widget is an intuitive, easy-to-use object that you can
use to make the most of any fields that require dates to be entered or
simply represented.
This widget is provided in two forms:

DatePicker Calendar: This object can be used either in a subform, or as
a pull-down calendar displayed by clicking a button.
DateEntry Area: Date area associated with control buttons. This object
can be only be used in a subform.
84 4D v12 Upgrade
Widgets
DatePicker calendar During execution, the user can scroll through the months of the
calendar both forwards and backwards by clicking on the arrow
buttons. They can also use the arrow keys of the keyboard.
When it is inserted into a subform, a DatePicker object can be used

without programming thanks to the mechanism provided by the
bound variable (see below). However, if you want to customize the
functioning of the DatePicker or display it as a pop-up menu, you must
use the set of component methods that is provided. These component
methods are described in the “DatePicker” paragraph on page 258.
Use in a subform
You can insert a DatePicker calendar into a form using the new
integrated object library of 4D (see the “Preconfigured object library”
paragraph on page 80) or by creating a subform area and assigning the
form of the DatePicker component to it, as described in the “Using a
component subform (host database)”paragraph on page 79.
4D v12 Upgrade 85
(Variable Name property in the Property list).
When the form is executed, this date variable automatically contains
the date selected by the user. Conversely, if you modify the value of
this variable by programming, it will be shown automatically in the
subform.
Use in a pop-up
You can use a DatePicker calendar as a pop-up window. To do this,
simply call the DatePicker Display Dialog component method. The
method returns the date selected by the user.
The 4DDatePicker component methods are described in the

“DatePicker” paragraph on page 258.
DateEntry area A DateEntry type area facilitates the entry of a date in the standard
DD/MM/YY form.
The area appears as a date type associated with buttons:
During execution, the buttons located to the right of the entry area are
only displayed when the object has the focus. The user selects each
element of the date (day, month or year) individually by clicking or
hitting the Tab key and can scroll them using the numeric stepper or
the arrow keys of the keyboard. The calendar icon to the right can be
used to select a date from a DatePicker pop-up calendar.
86 4D v12 Upgrade
Widgets
A DateEntry object can be used without programming thanks to the

mechanism provided by the bound variable (see below). However, if
you want to customize the functioning, you can use the set of
component methods that is provided. These methods are the same as
those of the DatePicker object. For more information, refer to the
“DatePicker” paragraph on page 258.
Use in a subform
You can insert a DateEntry area into a form using the new integrated
object library of 4D (see the “Preconfigured object library” paragraph
on page 80). You can also create a subform area and assign the form of
the DateEntry component to it, as described in the “Using a component
subform (host database)”paragraph on page 79.
(Variable Name property in the Property list).
When the form is executed, this variable will automatically contain
the date selected by the user. Conversely, if you modify the value of
this variable by programming, it will automatically be shown in the
subform.
TimePicker The TimePicker widget provides easy-to-use objects that you can use to
make the most of fields where times are to be entered or displayed.
4D v12 Upgrade 87
It can be used either as pop-up menus (single or double), or as a time

entry area in the "hh:mm:ss" format associated with a numeric stepper
that can be used to increase or decrease the value of the hours, minutes
or seconds.
Single pop-up
Double pop-up
Time area (subform)
In addition, each type of TimePicker can display the time in 12-hour

(AM-PM) or 24-hour format.
A TimePicker object can be used without programming thanks to the

mechanism provided by the bound variable (see below). However, if
you want to customize the functioning of TimePicker objects, you
must use the set of component methods that is provided. These
commands are described in the “TimePicker” paragraph on page 267.
Use
A TimePicker area is a subform that you can insert into a form using
the new integrated object library of 4D (see the “Preconfigured object
library” paragraph on page 80). You can also create a subform area and
assign the TimePicker component form to it, as described in the “Using
a component subform (host database)”paragraph on page 79. Then
specify the name of the time variable bound with the subform
(Variable Name property in the Property list). When the form is
executed, this variable will automatically contain the time specified by
the user. Conversely, if you modify the value of this variable by
programming, it will automatically be shown in the subform.
The 4DTimePicker component methods are described in the

“TimePicker” paragraph on page 267.
New form objects

This section lists the new features related to standard objects that can
be used in 4D forms.
88 4D v12 Upgrade
New form objects
New stepper object 4D v12 offers a new form object: the "stepper". This standard object lets
the user scroll through numeric values, durations (times) or dates by
predefined steps by clicking on the arrow buttons:
The functioning of this object is similar to that of the existing ruler

object. The variable associated with the object can be assigned to an
enterable area (field or variable) to store or modify the current value of
the object.
The stepper object is display variant of the ruler object.
To add a stepper to a form, you must draw a ruler object and then
select Numeric stepper in the "Display" menu of the Property list:
"Ruler" object
You can set the Minimum, Maximum and Step properties for steppers.
The other properties, in particular the form events, work the same way
as for all indicator objects.
A stepper can be associated directly with a number, time or date

variable.
4D v12 Upgrade 89
For values of the time type, the Minimum, Maximum and Step
properties represent seconds. For example, to set a stepper from 8:00 to
18:00 with 10-minute steps:
Minimum = 28 800 (8*60*60)
Maximum = 64 800 (18*60*60)
Step = 600 (10*60)
For values of the date type, the value entered in the Step property
represents days. The Minimum and Maximum properties are ignored.
For the stepper to work with a time or date variable, it is imperative to

set its type in the Property list AND to declare it explicitly via the
C_TIME or C_DATE command.
Note It is possible to activate the "Stepper" display using the OBJECT SET
FORMAT command (new name of the SET FORMAT command).
Asynchronous Preliminary note: In 4D v12, for better accuracy and conformity with
progress indicator the interface standards, the "Thermometer" objects have been renamed
"Progress Indicator."
Several variants of progress indicators are now available in 4D v12.

These different variants can be used to display standard interface
objects indicating the current operations such as searching for a
network connection or calculations.
To access these variants, draw a progress indicator in the form. In the

Property list, the new "Indicator type" menu contains the various
possible indicators:
90 4D v12 Upgrade
New form objects
Progress bar: default indicator. This variable corresponds to the

"Thermometer" object in previous versions of 4D. The options of the
"Scale" theme can be set.
Barber shop: indicator bar displaying a continuous "barber shop" type
animation. This variant corresponds to the "Unspecified" option in
previous versions of 4D. When it is selected, the options of the "Scale"
theme are hidden.
Asynchronous progress bar: circular indicator displaying a continuous
animation. When this variant is selected, the options of the "Scale"
theme are hidden.
Note During execution, for an indicator to be animated, the variable

associated with the object just needs to have a value different from 0
(for example, 1). If the variable is set to 0, the animation is stopped.
Note These variants can be specified using the OBJECT SET FORMAT
command (new name of the SET FORMAT command).
New 3D buttons In 4D v12, the 3D buttons group includes four new styles that let you
use native buttons in your interfaces:
Collapse/Expand
Help
OS X Textured
OS X Gradient
4D v12 Upgrade 91
These variants can be access via the Button Style pop-up menu in the
Property list for 3D buttons, 3D checkboxes and 3D radio buttons:
Collapse/Expand This button style can be used to add a standard collapse/expand icon.
These buttons are used natively in hierarchical lists. Under Windows,
the button looks like a [+] or a [-]; under Mac OS, it looks like a triangle
pointing right or down. This style is intended in particular for 3D
checkboxes, where the two states of the button correspond to the
selected/deselected state of the check box:
Windows Mac OS
Help This button style can be used to display a standard help button of the
system. You can use this style to add "system" help buttons in your
forms:
Windows Mac OS
92 4D v12 Upgrade
New form objects
OS X Textured Under Mac OS X, a "Textured" button is a standard system button

displaying a gradation of gray. Its height is predefined: it is not possible
to enlarge or reduce it. This button style can make use of all the 3D
buttons options.
Under Windows, this style is equivalent to a push button, which can,
however, have a pop-up menu and which has the special feature of
being transparent under Vista:
Windows Mac OS
OS X Gradient Under Mac OS X, a "Gradient" button is a two-tone system button. This

button style can make use of all the 3D buttons options.
Under Windows, this style is equivalent to a push button, which can,
however, have a pop-up menu:
Windows Mac OS
Number of states A new property is available for 3D buttons: Number of states.
New property
4D v12 Upgrade 93
This property sets the exact number of states present in the picture
used as the icon for the 3D button. In the source picture, the states
must be stacked vertically:
Source picture State 1
State 2
State 3
State 4...
In general, a button icon includes 4 states: active, clicked, mouse over

and inactive.
Rich text
Overview 4D v12 allows the use of rich text areas with individual style variations.
For example, it is now possible to have words in bold, italics or color
inside a text area:
This new feature applies to fields and variables of the Alpha and Text
type as well as to list box cells. It is supported for page and list forms
both for display and printing.
94 4D v12 Upgrade
Rich text
New options in the Property list can be used to configure rich text
functioning.
The attributes available are font, size, style, text color and (Windows
only) background color. To modify style attributes in a rich text area,
there are two different possibilities:
during execution, use an automatic pop-up menu (the availability
of this menu can be configured in the Property list).
by programming, using the new OBJECT SET STYLED TEXT
ATTRIBUTES command.
In rich text areas, style attributes are stored as standard HTML tags.
When the text area is displayed, these tags are interpreted by 4D. This
means that the developer can specify and modify style attributes in a
text via programming. The tags supported by 4D are described in
appendix B, “Style Tags,” on page 335.
The new OBJECT Get plain text command retrieves raw text without
style tags.
Note You cannot use rich text areas in the following contexts: entry filters,
quick reports and the label editor.
Rich text In the form editor, new properties can be used to activate and
management configure the support of rich text. These properties are available for
properties enterable variables, fields and list box cells of the Alpha or Text type.
Multi-style This option ("Text" theme) enables the possibility of using specific
styles in the selected area. When this option is checked, 4D interprets
any HTML style management tags found in the area.
By default, this option is not checked.
Store with default style This option only appears when the "Multi-style" option has been
tags checked. It is found in the "Text" theme.
When this option is checked, the area will store the style tags with the
text, even if no modification has been made. In this case, the tags
correspond to the default style. When this option is not checked, only
modified style tags are stored.
4D v12 Upgrade 95
For example, here is a text that includes a style modification:
What a beautiful day!

If the "Store with default style tags" option is not checked, the area
only stores the modification. The stored contents are therefore:
What a beautiful day!

If the option is checked, the area stores all the formatting information.
The first generic tag describes the default style then each variation is
the subject of a pair of nested tags. The contents stored in the area are
therefore:
What a beautiful day!
Context menu This option ("Entry" theme) only appears when the "Multi-style"
option has been checked.
It can be used to activate, for the user, the possibility of calling a pop-
up menu during data entry by a right-click in the area. This pop-up
menu offers standard text editing commands (cut, copy, paste) as well
as commands for supported style modifications: font, size, style, color
and (Windows) background color.
96 4D v12 Upgrade
Rich text
When the user modifies a style attribute via this pop-up menu, 4D
generates the On After Edit form event.
Note It is also possible to modify styles via the new OBJECT SET STYLED TEXT
ATTRIBUTES command. Note that in this case, no form event is
generated.
Note The "strikethrough" style is not supported under Mac OS. However, the
corresponding tag can be used by programming.
Processing rich text

Copy paste and drag- The supported style attributes (font, size, style and color) are kept in
and-drop the case of drag-and-drop or copy-paste of styled text between:
different rich text areas within 4D (text variables/fields and list boxes)
a 4D Write area and a 4D rich text area,
an external styled text and a 4D rich text area.
In other cases, the styles will be kept according to the context.
Text object The commands that can be used to manipulate text objects by
management programming do not take any style tags integrated into the text into
commands
account. They act upon displayed text so they function as in previous
versions of 4D. This concerns the following commands:
User Interface theme
HIGHLIGHT TEXT
GET HIGHLIGHT
Note that when you use these commands with commands that
manipulate character strings, it is necessary to filter the formatting
characters using the new OBJECT Get plain text command:
HIGHLIGHT TEXT([Products]Notes;1;Length(OBJECT Get plain
text([Products]Notes))+1)
Object Properties theme
Note The commands of this theme have been renamed in 4D v12 and new
commands have been added. For more information, refer to the
“Object Properties” paragraph on page 155.
4D v12 Upgrade 97
The commands that can be used to modify the style of objects (for
example, OBJECT SET FONT) work as in previous versions of 4D: they
apply to the whole object and not to the selection.
Note that if the object does not have the focus when the command is
executed, the modification is applied simultaneously to the object (the
text area) and to its associated variable. If the object does have the
focus, the modification is carried out on the object but not on the
associated variable. The modification is only applied to the variable
when the object loses the focus. Keep this principle in mind when
programming text areas.
If the "Store with default style tags" option is checked for the object,
the use of these commands will cause a modification of the tags saved
with each object.
Get edited text When it is used with a rich text area, the Get edited text command
command ("Form Events" theme) returns the text of the current area including
any style tags.
To retrieve the "plain" text (text without tags) being edited, you must
use the new OBJECT Get plain text command:
OBJECT Get plain text(Get edited text)
Note For more information about this command, refer to the “OBJECT Get
plain text” paragraph on page 165.
Query and order by Queries and sorts carried out among multi-style objects take into
commands account any style tags saved in the object. If a style modification has
been made within a word, searching for the word will not be
successful.
To be able to carry out valid searches and sorts, you must use the new
OBJECT Get plain text command. For example:
QUERY BY FORMULA([MyTable];Get plain text([MyTable]MyField-
Style)="very well")
98 4D v12 Upgrade
New properties for fields and variables
New commands Several new commands can be used to manipulate the style attributes
of rich text areas: OBJECT SET STYLED TEXT ATTRIBUTES, OBJECT GET
STYLED TEXT ATTRIBUTES and OBJECT Get plain text. These commands
are described in the “Object Properties” paragraph on page 155.
Note The new "Selection always visible" property keeps the text selection
visible in a form even when the object no longer has the focus. This
means that you can build interfaces based on menus or buttons for
style modification. For more information, refer to “Selection always
visible”paragraph on page 103.

New properties are available for fields and variables in the 4D form
editor. This set of new features is meant to provide the 4D developer
with better control over these form objects.
Objects not In previous versions of 4D, the contents of fields and variables that
enterable were declared non-enterable (Enterable option deselected) could not
be selected or copied. Henceforth, new interaction possibilities are
provided via the availability of the Focusable, Tabable and Droppable
properties.
Focusable and Tabable The Focusable and Tabable options are active for objects that are not
enterable:
New options for variables and fields

that are not enterable
4D v12 Upgrade 99
When the Focusable option is checked for the object, the user can
select, copy or even transport via drag-and-drop, the contents of the
area.
The Tabable option is available once the Focusable option is checked.

It allows the object to be selected via the Tab key. Note, however, that
it is still not possible to include the object in the entry order.
Droppable The Droppable property can now be assigned to an object that is not
enterable. This means that the developer can program all types of
action in response to an object being dropped on a field or variable
that is not enterable.
Multiline objects In previous versions of 4D, the display and printing of text in fields
and variables of the form were difficult to control. In objects of the text
type, the display could depend on the size of the area and the
platform.
Note Carriage returns cannot be used in Alpha type objects.
In 4D v12, the display and printing of text areas have been

harmonized between the platforms and a combination of two new
options can be used to control line returns:
Multiline: Option available for variables and fields of the Alpha and
Text type, both enterable and not enterable. It can have three different
values: Yes, No, Automatic.
100 4D v12 Upgrade

Wordwrap: Option only available if the Multiline option is set to Yes. It

can have three different values: Yes, No, Automatic.
These options modify two display parameters for text areas:

Display of words located at the end of the line in single-line areas,
Automatic insertion of line returns in text areas.
Multiline = Automatic In single-line areas, words located at the end of lines are truncated and
there are no line returns.
In multiline areas, 4D carries out automatic line returns:
This functioning corresponds to that of previous versions of 4D.
4D v12 Upgrade 101

Multiline = No In single-line areas, words located at the end of lines are truncated and
there are no line returns.
There are never line returns: the text is always displayed on a single
row. If the Alpha or Text field or variable contains carriage returns, the
text located after the first carriage return is removed as soon as the area
is modified:
Multiline = Yes In this case, an additional option, Wordwrap, must be set.

Wordwrap= Automatic
In single-line areas, the text is displayed up to the first carriage return
or until the last word that can be displayed entirely. 4D inserts line
returns; it is possible to scroll the contents of the area by pressing the
down arrow key.
Wordwrap = Yes
In single-line areas, only the last word that can be displayed entirely is
displayed. 4D inserts line returns; it is possible to scroll the contents of
the area by pressing the down arrow key.
102 4D v12 Upgrade

Wordwrap = No
4D does not do any automatic line returns and the last word that can
be displayed may be truncated. In text type areas, carriage returns are
supported:
Note For these properties to be taken into account correctly, text objects
must not have scroll bars.
Selection always A new property is available for Alpha or Text type fields or variables in
visible forms: Selection always visible:
New option
This property keeps the selection visible within the object after it has
lost the focus. This makes it easier to implement interfaces that allow
the text style to be modified (see the “Rich text”paragraph on page 94).
4D v12 Upgrade 103

List boxes
4D v12 brings several new features relating to list boxes:
The possibility of specifying hierarchical list boxes,
The possibility of printing list boxes,
Access to the data of columns that are added following a SELECT.
Hierarchical list 4D v12 lets you specify and use hierarchical list boxes. A hierarchical
boxes list box is a list box in which the contents of the first column appears
in hierarchical form. This type of representation is adapted to the
presentation of information that includes repeated values and/or
values that are hierarchically dependent (country/region/city and so
on).
Only list boxes of the array type can be hierarchical.
Hierarchical list boxes are a particular way of representing data but

they do not modify the structure of these data (the arrays). Hierarchical
list boxes are managed exactly the same way as regular list boxes. For
more information, refer to the “Functioning of hierarchical list
boxes”paragraph on page 108
To specify a hierarchical list box, there are three different possibilities:

Manually configure hierarchical elements using the Property list of the
form editor. This is described in the “New list box
properties”paragraph on page 104.
Visually generate the hierarchy using the list box management pop-up
menu, in the form editor. This is described in the “Managing hierarchy
with context menu”paragraph on page 107.
Use the new language commands LISTBOX SET HIERARCHY and LISTBOX
GET HIERARCHY. For more information, refer to the “List Box”
paragraph on page 142.
New list box properties New properties can be used to manage hierarchical list boxes. Note
that these properties are automatically modified if you specify the
hierarchy via the pop-up menu of the list box object (see the
“Managing hierarchy with context menu” paragraph on page 107).
104 4D v12 Upgrade

List boxes
Hierarchical list box
To specify a hierarchical list box, you simply need to check the new
Hierarchical list box option. This option is found in the new
"Hierarchy" theme of the Property list, which is available when a list
box object is selected:
List box object selected
New theme
Hierarchical list box option
This option is only present for list boxes whose data source is Arrays.
Variable 1 ... 10
When the Hierarchical list box option is checked, additional enterable

fields are added to the theme: "Variable 1", "Variable 2", etc. Each time
a value is entered in a field, a new row is added. Up to 10 variables can
be specified.
These variables set the hierarchical levels to be displayed in the first

column.
4D v12 Upgrade 105

The first variable always corresponds to the name of the variable for
the first column of the list box (the two values are automatically
bound). This first variable is always visible and enterable. For example:
country.
The second variable is also always visible and enterable; it specifies the
second hierarchical level. For example: regions.
Beginning with the third field, each variable will depends on the one
preceding it. For example: counties, cities, and so on. A maximum of
ten hierarchical levels can be specified.
If you remove a value, the whole hierarchical specified moves up a

level.
The last variable is never hierarchical even if several identical values

exists at this level. For example, referring to the configuration
illustrated above, imagine that arr1 contains the values A A A B B B,
arr2 has the values 1 1 1 2 2 2 and arr3 the values X X Y Y Y Z. In this
case, A, B, 1 and 2 could appear in collapsed form, but not X and Y:
T A
T1
X
X
Y
T B
T2
Y
Y
Z
This principle is not applied when only one variable is specified in the
hierarchy: in this case, identical values may be grouped.
Note If you specify a hierarchy based on the first columns of an existing list
box, you must then remote or hide these columns (except for the first),
otherwise they will appear in duplicate in the list box. If you specify
the hierarchy via the pop-up menu of the editor (see the “Managing
hierarchy with context menu” paragraph on page 107), the
unnecessary columns are automatically removed from the list box.
106 4D v12 Upgrade

List boxes
Modified properties
When the hierarchical mode is enabled ("Hierarchical list box" option

checked), several other properties are disabled or removed:
Number of Static Columns: for hierarchical list boxes, this option is
always at least 1.
Movable Rows: This option is not available for hierarchical list
boxes.
All the properties of the "Display" theme are disabled for the first
column.
Managing hierarchy The context menu of the form editor offers two new commands when
with context menu you click on a list box object: Create hierarchy and Cancel hierarchy.
Create hierarchy
When you select at least one column in addition to the first one in a
list box object (of the array type) in the form editor, the Create
hierarchy command is available in the context menu:
When you choose this command, the following actions are carried out:
The "Hierarchical list box" option is checked for the object (see the
“Hierarchical list box”paragraph on page 105).
The variables of the columns are used to specify the hierarchy (see
the “Variable 1 ... 10”paragraph on page 105). They replace any
variables already specified.
The columns selected no longer appear in the list box (except for
the title of the first one).
4D v12 Upgrade 107

Example: given a list box whose first columns contain Country,

Region, City and Population. When Country, Region and City are
selected (see illustration above), if you choose Create hierarchy in the
context menu, a three-level hierarchy is created in the first column,
columns 2 and 3 are removed and the Population column becomes the
second:
Cancel hierarchy
When the first column is selected and already specified as hierarchical,

you can use the Cancel hierarchy command. When you choose this
command, the following actions are carried out:
The "Hierarchical list box" option is deselected for the object.
The hierarchical levels 2 to X are removed and transformed into
columns added to the list box.
Functioning of When a form containing a hierarchical list box is opened for the first
hierarchical list boxes time, by default all the rows are expanded.
108 4D v12 Upgrade

List boxes
A break row and a hierarchical "node" are automatically added in the

list box when values are repeated in the arrays. For example, imagine a
list box containing four arrays specifying cities, each city being
characterized by a country, a region, a name and a number of
inhabitants:
If this list box is displayed in hierarchical form (the first three arrays
being included in the hierarchy), you will obtain:
Hierarchical Break rows

nodes
The arrays are not sorted before the hierarchy is constructed. If, for
example, an array contains the data AAABBAACC, the hierarchy
obtained will be:
X A
X B
X A
X C
To expand or collapse a hierarchical "node," you can just click on it. If

you Alt+click (Windows) or Option+click (Mac OS) on the node, all its
sub-elements will be expanded or collapsed as well.
Management of A hierarchical list box displays a variable number of rows on screen

selections and positions according to the expanded/collapsed state of the hierarchical nodes.
However, this does not mean that the number of rows of the arrays
vary. Only the display is modified, not the data.
4D v12 Upgrade 109

It is important to understand this principle because programmed

management of hierarchical list boxes is always based on the data of
the arrays, not on the displayed data. In particular, the break rows
added automatically are not taken into account in the display options
arrays (see the “Management of break rows” paragraph on page 112).
Let’s look at the following arrays for example:

France Brittany Brest
France Brittany Quimper
France Brittany Rennes
If these arrays are represented hierarchically, the row "Quimper" will

not be displayed on the second row, but on the fourth, because of the
two break rows that are added:
France
Brittany
Brest
Quimper
Rennes
Regardless of how the data are displayed in the list box (hierarchically
or not), if you want to change the row containing "Quimper" to bold,
you must use the statement Style{2} = bold. Only the position of the
row in the arrays is taken into account.
This principle is implemented for internal arrays that can be used to

manage:
Colors
Background colors
Styles
Hidden rows
Selections.
For example, if you want to select the row containing Rennes, you
must pass:
-> MyListbox{3}:=True
Non-hierarchical representation:
France Brittany Brest
France Brittany Quimper
France Brittany Rennes
110 4D v12 Upgrade

List boxes
Hierarchical representation:
France
Brittany
Brest
Quimper
Rennes
Note If one or more rows are hidden because their parents are collapsed,
they are no longer selected. Only the rows that are visible (either
directly or by scrolling) can be selected. In other words, rows cannot be
both hidden and selected.
As with selections, the LISTBOX GET CELL POSITION command will

return the same values for a hierarchical list box and a non-
hierarchical list box. This means that in both of the examples below,
LISTBOX GET CELL POSITION will return the same position: (3;2)
France Brittany Brest 120000
France Brittany Quimper 80000
France Brittany Rennes 200000
France Normandy Caen 75000
France
Brittany
Brest 120000
Quimper 80000
Rennes 200000
Normandy
Caen 75000
4D v12 Upgrade 111

Management of break If the user selects a break row, LISTBOX GET CELL POSITION returns the
rows first occurrence of the row in the corresponding array. In the following
case:
France
Brittany
Brest 120000
Quimper 80000
Rennes 200000
Normandy
Caen 75000
... LISTBOX GET CELL POSITION returns (2;4). To select a break row by
programming, you must use the new LISTBOX SELECT BREAK command
on page 151.
Break rows are not taken into account in the internal arrays used to
manage the graphic appearance of list boxes (styles and colors). It is
however possible to modify these characteristics for break rows via the
graphic management commands for objects ("Object Properties"
theme). You simply need to execute the appropriate commands on the
arrays that constitute the hierarchy.
Given for example the following list box (the names of the associated
arrays are specified in parentheses):
(T1) (T2) (T3) (T4) (tStyle) (tColor)
France Brittany Brest 120000 Normal 0
France Brittany Quimper 80000 Underline 0
France Brittany Rennes 200000 Normal 0xFF0000
France Normandy Caen 220000 Normal 0
France Normandy Deauville 4000 Normal 0
France
Brittany
Brest 120000
Quimper 80000
Rennes 200000
Normandy
Caen 75000
Deauville 4000
112 4D v12 Upgrade

List boxes
In hierarchical mode, break levels are not taken into account by the
style modification arrays named tStyle and tColors. To modify the color
or style of break levels, you must execute the following statements:
OBJECT SET RGB COLORS(T1;0x0000FF;0xB0B0B0)
OBJECT SET FONT STYLE(T2;Bold)
In this context, only the syntax using the array variable can function
with the object property commands because the arrays do not have
any associated object.
Result:
France
Brittany
Brest 120000
Quimper 80000
Rennes 200000
Normandy
Caen 75000
Deauville 4000
Managing sorts In a list box in hierarchical mode, a standard sort (carried out by
clicking on the header of a list box column) is always constructed as
follows:
In the first place, all the levels of the hierarchical column (first
column) are automatically sorted by ascending order,
The sort is then carried out by ascending or descending order
(according to the user action) on the values of the column that was
clicked.
All the columns are synchronized.
4D v12 Upgrade 113

During subsequent sorts carried out on non-hierarchical columns of

the list box, only the last level of the first column is sorted. It is
possible to modify the sorting of this column by clicking on its header.
Given for example the following list box, in which no specific sort is
specified:
114 4D v12 Upgrade

List boxes
If you click on the "Population" header to sort the populations by

ascending (or alternately descending) order, the data appear as follows:
Click on the header: sorting of the
population (ascending order)
1- Automatic sorting of all

the hierarchical levels by
ascending order
In the case of subsequent

clicks on the Population
header, only the last level 2 - Sorting of the
will be synchronized population by ascending
order within the last level
As for all list boxes, you can disable the standard sort mechanism by
deselecting the "Sortable" option for the list box and managing sorts
using programming.
Display of dates and When values of the date or time type are included in a hierarchical list
times box, they ar displayed in a standard format:
Dates are displayed in the short system format (for example, for May
30, 2009, "05/30/09" on an American system and "30/05/09" on a
European system).
Times are also displayed in the short system format ("12:15:30" or
"12:15" depending on the system parameters).
Hidden rows When all the rows of a sub-hierarchy are hidden, the break line is
automatically hidden. In the above example, if rows 1 to 3 are hidden,
the "Brittany" break row will not appear.
4D v12 Upgrade 115

Scrolling and editing The OBJECT SET SCROLL POSITION (formerly SCROLL LINES) and EDIT
ITEM commands have been adapted for list boxes displayed in
hierarchical mode: if the row aimed at belongs to a collapsed
hierarchical level, this level as well as any parent levels are
automatically expanded for the row to be visible.
Printing list boxes It is now possible to print list boxes in 4D v12. Two printing modes are
available: preview mode, which can be used to print a list box like a
form object and advanced mode, which lets you control the printing
of the list box object itself within the form. A new property specifies
the "Printing" appearance for list box objects.
Preview mode Printing a list box in preview mode consists in directly printing the list
box with the form that contains it using the standard print commands
or the Print menu command. The list box is printed as it is in the form.
This mode does not allow precise control of the printing of the object;
in particular, it does not allow you to print all the rows of a list box
that contains more rows than it can display.
Advanced mode In this mode, the printing of list boxes is carried out by programming,
via the new Print object command. Accordingly, only list boxes found
in project forms can be printed in advanced mode. The new LISTBOX
GET PRINT INFORMATION command is used to control the printing of
the object.
In this mode:
The height of the list box object is automatically reduced when the
number of rows to be printed is less than the original height of the
object (there are no "blank" rows printed). On the other hand, the
height does not automatically increase according to the contents of
the object. The size of the object actually printed can be obtained via
the LISTBOX GET PRINT INFORMATION command.
The list box object is printed "as is", in other words, taking its current
display parameters into account: visibility of headers and gridlines,
hidden and displayed rows, etc.
These parameters also include the first row to be printed: if you call the
OBJECT SET SCROLL POSITION command before launching the
printing, the first row printed in the list box will be the one designated
by the command.
116 4D v12 Upgrade

List boxes
An automatic mechanism facilitates the printing of list boxes that

contain more rows than it is possible to display: successive calls to Print
object prints a new set of rows each time. The LISTBOX GET PRINT
INFORMATION command checks the status of the printing while it is
underway. For more information, refer to the description of these
commands.
Printing property In the Property list, a new platform option is available for list boxes
("Appearance" theme): Printing.
If you select this option, the appearance of the list box is adapted for
printing: headers in black and white, check boxes printed as [x], etc.
The Printing appearance does not depend on the platform where it is
running.
If you do not check this option, the list box will be printed with the
appearance of the current platform.
Note In advanced mode, the scroll bars of list boxes are never printed,
regardless of the appearance chosen.
Access to data of It is now possible to retrieve the contents of columns that are
added SELECT automatically added to a list box by 4D following a SELECT query
columns whose result produces a number of columns greater than that of the
list box.
In previous versions, these added columns were linked to internal

arrays that were inaccessible to the 4D language. In 4D v12, these
columns are bound to variables of the temporary array type. The
duration of these temporary arrays is the same as that of the form. A
temporary variable is also created for each header. When the GET
LISTBOX ARRAYS command is called, the arrColVars parameter contains
pointers to the temporary arrays and the arrHeaderVars parameter
contains pointers to the temporary header variables.
Note that data entry and sorting are now possible for these columns.
4D v12 Upgrade 117

Toolbar button (Mac OS)

Under Mac OS, 4D v12 can display the toolbar management button.
This standard button alternately displays and hides the toolbar of the
window:
Toolbar displayed Toolbar button
Toolbar hidden
The support of this functionality by 4D is carried out at two levels:

A new property can be used to draw the button in the windows,
A new form event is generated when the user clicks on the button.
It is up to the developer of the interface to specify the actions to be

carried out when the button is clicked.
Toolbar property For 4D to display the toolbar management button in your windows,
you have two solutions:
Check the new Toolbar button (Mac OS) property that is available in
the "Appearance" theme of the Property list:
This option is to be used if you create the window with the Open form
window or DIALOG command for example.
118 4D v12 Upgrade

Toolbar button (Mac OS)
Use the new Has toolbar button Mac OS constant. This option is to be
used with the Open window or Open form window command (see the
“Open window” paragraph on page 257).
On Mac toolbar The new On Mac toolbar button form event is generated in the form
button form event method when the user clicks on the tool bar management button of
the window under Mac OS. Of course, the corresponding property
must have been checked in the properties of the form event.
Only the event is generated, 4D does not carry out any other action in
the window. It is up to the developer to modify the size of the window
and to show or hide its interface elements.
4D v12 Upgrade 119

120 4D v12 Upgrade

5 Language
This chapter covers the new features and modifications made to the
programming language of 4D v12.
4D Environment
The new SET DATABASE LOCALIZATION command modifies the current
language of the database and is used in particular for the application
interface (XLIFF architecture). The Version type command accepts new
values that are used to identify a 64-bit 4D Server. Moreover, new
selectors are available for the SET DATABASE PARAMETER and Get
database parameter command.
Get database Get database localization {(languageType)} Æ Text

localization Parameter Type Description
languageType Longint Æ Type of language
Function result Text Å Code of language used

Compatibility Note The Get database localization command was named Get current database
localization in previous versions of 4D.
The Get database localization command now accepts a new parameter

that indicates the type of language to be retrieved. In fact, several
different language configurations can be used simultaneously in the
application.
4D v12 Upgrade 121

Chapter 5 Language
In languageType, pass one of the following constants, found in the "4D

Environment" theme:
languageType (value) Description
Default localization(0) Language set automatically by 4D on startup
according to the Resources folder and the sys-
tem environment (not modifiable)
Current localization(1) Current language of the application: default lan-
guage or language set via the SET DATABASE
LOCALIZATION command
User system localiza- Language set by the current user of the system
tion(2)
Internal 4D localiza- Language used by 4D for sorts and text compar-
tion(3) isons (set in the Preferences of the application)
See Also: SET DATABASE LOCALIZATION
Get table Get table fragmentation (aTable) Æ Real

fragmentation Parameter Type Description
aTable Table Æ Table for which to get the frag-
mentation rate
Function result Real Å Percentage of fragmentation
The new Get table fragmentation command returns the percentage of

logical fragmentation for the records of the table designated by the
aTable parameter.
The rate of logical fragmentation of the records indicates whether the

records are stored in an ordered manner in the data file. If the
fragmentation becomes too high, this can considerably slow down
sorts and sequential searches on the table. A fragmentation percentage
of 0 corresponds to no fragmentation. Beyond a rate of 20%, it may be
useful to compact the data file.
122 4D v12 Upgrade

OPEN 4D PREFERENCES
` This maintenance method lets you request the compacting of the data
file in the case where there is considerable fragmentation in at least
one table of the database:
ToBeCompacted:=False
For ($i ;1;Get last table number)
If(Is table number valid($i))
If(Get table fragmentation(Table($i)->)>20)
ToBeCompacted:=True
End if
End if
End for
If(ToBeCompacted)
// Places a marker requesting compacting
End if
OPEN 4D OPEN 4D PREFERENCES (selector{; access})

PREFERENCES Parameter Type Description
selector String Æ Key designating a theme or a page of
parameters in the Preferences or Settings
dialog box
access Boolean Æ True=Lock the other pages of the dialog
box
False or omitted=Leave the other pages of
the dialog box active
Since the functioning of the Preferences has been remodeled

completely in 4D v12 (see the “Reorganization of Preferences”
paragraph on page 29), the list of keys to pass in the selector parameter
has been modified. In addition, the OPEN 4D PREFERENCES command
now accepts the additional access parameter.
Henceforth, two different dialog boxes can be used to separately

specify the parameters related to the 4D application (Preferences) and
those related to the database that is open (Database settings). The
OPEN 4D PREFERENCES command can be used to access both the dialog
boxes. Note that when these dialog boxes are called via this command,
they are modal.
4D v12 Upgrade 123

Chapter 5 Language
Here is the list of keys that can now be used in the selector parameter.
The first part of the key indicates the dialog box concerned:
/4D
/4D/General
/4D/Structure
/4D/Form editor
/4D/Method editor
/4D/Client-Server
/4D/Shortcuts
/Database
/Database/General
/Database/Mover
/Database/Interface
/Database/Interface/Developer
/Database/Interface/User
/Database/Interface/Shortcuts
/Database/Compiler
/Database/Database
/Database/Database/Data storage
/Database/Database/Memory and cpu
/Database/Database/International
/Database/Backup
/Database/Backup/Scheduler
/Database/Backup/Configuration
/Database/Backup/Backup and restore
/Database/Client-Server
/Database/Client-Server/Network
/Database/Client-Server/IP configuration
/Database/Web
/Database/Web/Config
/Database/Web/Options 1
/Database/Web/Options 2
/Database/Web/Log format
/Database/Web/Log scheduler
/Database/Web/Webservices
/Database/SQL
/Database/php
/Database/Compatibility
/Database/Security
124 4D v12 Upgrade

SET DATABASE LOCALIZATION
If you pass an invalid key or just a slash ("/"), the command displays
the Database Settings dialog box, open to the last page that was
consulted.
Compatibility note The command continues to function with the keys of previous
versions; the correspondence is established automatically by 4D. It is
nevertheless recommended to replace the former calls using the v12
keys.
The new access parameter lets you control user actions in the
Preferences or Database Settings dialog box by locking the other pages.
Typically, you may want for the user to be able to customize certain
parameters while preventing others from being modified. In this case,
passing True in the access parameter means that only the page specified
by the selector parameter will be active and modifiable, while access to
all other pages will be locked (clicking on the buttons in the
navigation bar will have no effect). If you pass False or omit the access
parameter, all the pages of the dialog box will be accessible with no
restriction.
SET DATABASE SET DATABASE LOCALIZATION(language{; *})

LOCALIZATION Parameter Type Description
language Text Æ Language selector
* * Æ Scope of command
The new SET DATABASE LOCALIZATION command modifies the current

language of the database for the current session.
The current language of the database specifies the .lproj folder where
the program will look for the localized elements of the application
(text and pictures). By default, 4D automatically determines the
current language according to the contents of the Resources folder and
the system environment (see the description of the Get database
localization command). SET DATABASE LOCALIZATION modifies the
default current language.
The command does not modify the language of forms that are already
loaded, only elements displayed after the command is called will take
the new configuration into account.
4D v12 Upgrade 125

Chapter 5 Language
Pass the language to be used for the application in language, expressed

in the standard specified by RFC 3066, ISO639 and ISO3166. Typically,
you must pass "fr" for French, "es" for Spanish, "en-us" for American
English, and so on. For more information about this standard, refer to
the Design Reference manual.
By default, the command applies to all the databases and components

that are open, for all the processes. The optional * parameter, if passed,
specifies that the command must only apply to the database that
called it. This parameter can be used more particularly to specify
separately the language of the database and that of a component.
If the command has been executed correctly, the OK system variable is

set to 1; otherwise, it is set to 0.
Note In accordance with the RFC, the command uses the "-" (dash) to
separate the language code and the region code, for example "fr-ca" or
"en-us". On the other hand, the "lproj" folders of the Resources folder
use the "_" (underscore), for example "fr_ca.lproj" or "en_us.lproj".
4D Server With 4D Server, the languages available are those located on the
remote machine that called the command. You must therefore make
sure that the Resources folders are synchronized.
` We want to set French as the interface language:

SET DATABASE LOCALIZATION("fr")
` The interface of your application uses the static string ":xliff:shopping".

The XLIFF files contain more particularly the following information:
FR folder:
<trans-unit id="15" resname="Shopping">
<source>Shopping</source>
<target>Faire les courses</target>
</trans-unit>
126 4D v12 Upgrade

SET DATABASE PARAMETER, Get database parameter
FR_CA folder:
<trans-unit id="15" resname="Shopping">
<source>Shopping</source>
<target>Magasiner</target>
</trans-unit>
SET DATABASE LOCALIZATION("fr")
`the string ":xliff:shopping" displays "Faire les courses"
SET DATABASE LOCALIZATION("fr-ca")
`the string ":xliff:shopping" displays "Magasiner"
See Also: Get database localization
SET DATABASE SET DATABASE PARAMETER ({aTable; }selector; value)

PARAMETER, Get Parameter Type Description
database parameter aTable Table Æ Table for which to set the parameter
selector Longint Æ Code of the database parameter to
modify
value Real | String Æ Value of the parameter
Get database parameter ({aTable; }selector{; stringValue}) Æ Real

Parameter Type Description
aTable Table Æ Table from which to get the para-
meter
selector Longint Æ Code of the database’s parameter
stringValue String Å String value of the parameter
Function result Real Å Value of the parameter

The type of the value parameter and the function result of the Get
database parameter command have been modified: there are now of
the Real type. This modification was necessary to support new spaces
of values used with the 64-bit 4D Server relating to the addressing of
memory (see the “About the 64-bit 4D Server” paragraph on page 321).
Selector 34 (Debug Log Recording) accepts a new value: This selector
now accepts the value 3, which activates the "detailed mode with
values". In this advanced mode, the values of the parameters passed to
the commands, project methods and plug-in commands are also
recorded in the debug file.
4D v12 Upgrade 127

Chapter 5 Language
The following new selectors are available:
Selector = 55 (PHP Interpreter IP address)

Values: Formatted string of the type "nnn.nnn.nnn.nnn" (for
example "127.0.0.1").
Description: IP address used locally by 4D to communicate with the
PHP interpreter via FastCGI. By default, the value is "127.0.0.1".
This address must correspond to the machine where 4D is located.
This parameter can also be set globally for all the machines via the
Database Settings (see the “PHP” paragraph on page 39).
For more information about the PHP interpreter, refer to the
“Executing PHP scripts in 4D” paragraph on page 62.
Selector = 56 (PHP Interpreter port)

Values: Positive long integer type value.
Description: Number of the TCP port used by the PHP interpreter of
4D. By default, the value is 8002.
Selector = 57 (PHP Number of children)

Description: Number of child processes to be created and maintained
locally by the PHP interpreter of 4D. By default, the value is 5.
For optimization reasons, the PHP interpreter creates and uses a set
(pool) of system processes called "child processes" for processing
script execution requests. You can vary the number of child
processes according to the needs of your application.
For more information, refer to the “Architecture” paragraph on
page 63.
Note Under Mac OS, all the child processes share the same port.
Under Windows, each child process uses a specific port number. The
first number is the one set for the PHP interpreter; the other child
processes increment the first one. For example, if the default port is
8002 and you launch 5 child processes, they will use ports 8002 to
8006.
Note This parameter can also be modified globally for all the machines via
the Database Settings (see the “PHP” paragraph on page 39).
128 4D v12 Upgrade

SET DATABASE PARAMETER, Get database parameter
Selector = 58 (PHP Max requests)

Description: Maximum number of requests accepted by the PHP
interpreter. By default, the value is 500. When this maximum
number is reached, the interpreter returns errors of the "server busy"
type. For security or performance reasons, you can modify this
value. For more information about this parameter, refer to the
FastCGI-PHP documentation.
Note On the 4D side, these parameters are applied dynamically; it is not

necessary to exit 4D for them to be taken into account. On the other
hand, if the PHP interpreter is already launched, it will be necessary to
exit and relaunch it for these modifications to be taken into account.
Selector = 60 (PHP Use external interpreter)

Values: 0 = use internal interpreter, 1 = use external interpreter.
Description: Value indicating whether PHP requests in 4D are sent to
the internal interpreter provided by 4D or to an external interpreter.
By default the value is 0 (use of interpreter provided by 4D). If you
want to use your own PHP interpreter, for example to use additional
modules or a specific configuration, pass 1 in value. In this case, 4D
does not launch its internal interpreter in the case of PHP requests.
The custom PHP interpreter must have been compiled in FastCGI
and be located on the same machine as the 4D engine. Note that in
this case, you must manage the interpreter entirely; it will not be
started nor stopped by 4D.
4D v12 Upgrade 129

Chapter 5 Language
Selector = 66 (Cache unload minimum size)

Values: Positive long integer type value > 1.
Description: Minimum size of memory to release from the database
cache when the engine needs to make space in order to allocate an
object to it (value in bytes).
The purpose of this selector is to reduce the number of times that
data is released from the cache in order to obtain better
performance. You can vary this setting according to the size of the
cache and that of the blocks of data being handled in your database.
By default, if this selector is not used, 4D unloads at least 10% of the
cache when space is needed.
Version type Version typeÆ Longint

Function result Longint Å 0 = 32-bit full version

1 = 32-bit demo version
2 = 64-bit version
The Version type command can return an additional value that

distinguishes between the 64-bit 4D Server and the 32-bit version. This
value is available using a new constant found in the "4D Environment"
theme:
Constant Type Value
64 bit Version Longint 2
Backup
RESTORE RESTORE{(archivePath{; destFolderPath})}
archivePath Text Æ Pathname of archive to restore
destFolderPath Text Æ Pathname of destination folder
The RESTORE command now accepts two optional parameters that can
be used to automate the restore process and to update the OK and
document system variables.
130 4D v12 Upgrade

Communications
The archivePath parameter indicates the pathname of the archive file to

be restored. This pathname must be expressed with the system syntax.
You can pass an absolute pathname or a pathname relative to the
database structure file.
In this case (if the destFolderPath parameter is omitted), the standard
restore dialog box appears with the archive pre-selected, so that the
user can designate the destination folder. The functioning of this
command is then identical to that of previous versions of 4D: when
the procedure is completed, a warning dialog box appears and the
folder containing the restored elements is displayed.
You can also pass the destFolderPath parameter with the pathname of
the destination folder of the restored elements. This pathname must be
expressed with the system syntax. You can pass an absolute pathname
or a pathname relative to the database structure file. If you pass this
parameter, a preconfigured restore dialog box appears so that the user
can launch or cancel the restore procedure. When the procedure is
completed, the window is simply reclosed without displaying any
additional information.
Henceforth, the RESTORE command modifies the value of the OK and

Document variables: if the restore was carried out correctly, OK is set to
1 and Document contains the path of the restoration folder.
If the user cancels the restoration dialog box, interrupts the restoration
or if an error occurs, OK is set to 0 and Document contains an empty
string. You can intercept the error using a method installed via the ON
ERR CALL command.
Communications
RECEIVE PACKET RECEIVE PACKET({docRef ;} receiveVar ; stopChar | numBytes)
The RECEIVE PACKET command now supports BOMs (Byte Order Marks)
when receiveVar is a string type variable.
In this case, if the current character set is of the Unicode type (UTF-8,
UTF-16 or UTF-32), 4D attempts to identify a BOM among the first
bytes received. If it is detected, is filtered out of the variable receiving
the data and 4D uses the character set that it defines instead of the
current character set.
4D v12 Upgrade 131

Chapter 5 Language
Drag and Drop

Drop position Drop position {(columnNumber | pictPosX)}Æ Number
columnNum- Longint Å List box column number or -1
ber | pictPosX Or
Position of X coordinate in picture
Function result Number Å • Number (array/list box) or

• Position (hierarchical list) or
• Position in string (text/combo box) of
destination item or -1 if drop occurred
beyond the last array element or list
item or
• Position of Y coordinate in picture
The Drop position command now functions in the context of a drag-

and-drop event that occurs in a picture field or a picture variable.
In this case, the command returns the vertical location of the click
and, in the optional pictPosX parameter, the horizontal location of the
click. The values returned are expressed in pixels and in relation to the
local coordinate system.
See Also: OBJECT GET SCROLL POSITION, OBJECT SET SCROLL POSITION
Entry Control
GOTO OBJECT GOTO OBJECT({*;}object)
Compatibility note The GOTO OBJECT command was named GOTO AREA in previous
versions of 4D.
The GOTO OBJECT command can now be used in the context of a

subform. When it is called from a subform, it first looks for the object in
the subform, then, if the search does not find anything there, it
extends the search to objects of the parent form.
For more information about the new features of subforms in 4D v12,

refer to the “Extension of subform capacities” paragraph on page 71.
132 4D v12 Upgrade

Form Events
Form Events
CALL SUBFORM CALL SUBFORM CONTAINER(event)
CONTAINER Parameter Type Description
event Longint Æ Event to be sent
The new CALL SUBFORM CONTAINER command lets a subform instance

send the event to the subform container object that contains it. The
subform object can then process the event in the context of the parent
form.
This command must be placed in the form method of the subform or

in the object method of one of the subform objects. The event will
only be received in the object method of the subform container.
In event, you can pass any predefined form event of 4D available for a
subform container object (you can use the constants of the "Form
Events" theme) or any value corresponding to a custom event. In the
first case, the event must be checked for the subform container object.
In the case of a custom event, it is recommended to pass a negative
value in event to avoid the risk of interfering with existing or future 4D
event numbers.
Example of execution of the CALL SUBFORM CONTAINER command
Parent form
xxx
Object method of
subform Subform
Custom event
CALL SUBFORM CONTAINER (-20)
For more information about subform mechanisms in 4D v12, refer to

the “Extension of subform capacities” paragraph on page 71.
Forms
To facilitate their use, the commands of this theme have been renamed
and two additional commands have been added.
4D v12 Upgrade 133

Chapter 5 Language
Renamed For harmonization and standardization reasons, several commands of

commands the existing "Forms" theme have been renamed in 4D v12. The "FORM"
prefix has been added systematically. The functioning of these
commands has not changed.
New name in 4D v12 Former name
FORM FIRST PAGE FIRST PAGE
FORM Get current page Current form page
FORM GET OBJECTS GET FORM OBJECTS
FORM GET PARAMETER GET FORM PARAMETER
FORM GET PROPERTIES GET FORM PROPERTIES
FORM GOTO PAGE GOTO PAGE
FORM LAST PAGE LAST PAGE
FORM NEXT PAGE NEXT PAGE
FORM PREVIOUS PAGE PREVIOUS PAGE
FORM SET HORIZONTAL RESIZING SET FORM HORIZONTAL RESIZING
FORM SET INPUT INPUT FORM
FORM SET OUTPUT OUTPUT FORM
FORM SET SIZE SET FORM SIZE
FORM SET VERTICAL RESIZING SET FORM VERTICAL RESIZING
FORM GET FORM GET HORIZONTAL RESIZING (resize{; minWidth{; maxWidth}})

HORIZONTAL Parameter Type Description
RESIZING resize Boolean Å True: Form can be resized horizontally
False: Form cannot be resized horizon-
tally
minWidth Longint Å Smallest form width allowed (pixels)
maxWidth Longint Å Largest form width allowed (pixels)
The new FORM GET HORIZONTAL RESIZING command returns the

horizontal resizing properties of the current form in the resize,
minWidth and maxWidth variables. These properties may have been set
for the form in the Form editor in Design mode or for the current
process via the FORM SET HORIZONTAL RESIZING command.
134 4D v12 Upgrade

FORM GET VERTICAL RESIZING
FORM GET FORM GET VERTICAL RESIZING (resize{; minHeight{; maxHeight}})

VERTICAL RESIZING Parameter Type Description
resize Boolean Å True: Form can be resized vertically
False: Form cannot be resized vertically
minHeight Longint Å Smallest form height allowed (pixels)
maxHeight Longint Å Largest form height allowed (pixels)
The new FORM GET VERTICAL RESIZING command returns the vertical
resizing properties of the current form in the resize, minHeight and
maxHeight variables. These properties may have been set for the form
in the Form editor in Design mode or for the current process via the
FORM SET VERTICAL RESIZING command.
Import and Export

This theme receives the two commands IMPORT ODBC and EXPORT
ODBC. These commands were previously named SQL IMPORT and SQL
EXPORT and located in the Structure Access theme. Their functioning
remains unchanged. The purpose of this reorganization and name
change was to clarify the use of the commands of these two themes.
Interruptions
Four new commands support assertions in the 4D code. These new
tools facilitate the debugging of applications that are in the process of
being developed.
Note Two new system variables can be used to recover the precise location of
programming errors. For more information, refer to the “New system
variables” paragraph on page 254.
4D v12 Upgrade 135

Chapter 5 Language
ASSERT ASSERT(boolExpression {; messageText}})

boolExpression Boolean Æ Boolean expression
messageText String Æ Text of error message
The new ASSERT command places an assertion in the code of a

method.
An assertion is an instruction inserted in the code that is responsible

for detecting any anomalies during its execution. The principle
consists in verifying that an expression is true at a given moment and,
should the opposite occur, to cause an exception.
Assertions are above all used to detect cases that should usually not
ever occur. They are mainly used to detect programming bugs. It is
possible to globally enable or disable all the assertions of an
application (for example according to the type of version) via the new
SET ASSERT ENABLED command.
For more information about assertions in programming, refer to the
article concerning them on Wikipedia:
http://en.wikipedia.org/wiki/Assertion_(computing)
The ASSERT command evaluates the Boolean expression passed as a

parameter. If the expression is true, nothing happens. If it is false, the
command triggers the error -10518 and displays the text of the
assertion preceded by the message "Assert failed:". You can intercept
this error via a method installed using the ON ERR CALL command, for
example, to provide info for a log file.
The command accepts an optional second parameter that you can use
to provide the text that will appear in the error message instead of the
text of the Boolean expression when it is false.
` Before carrying out operations on a record, the developer wants to

make sure that it is actually loaded in read/write mode:
READ WRITE([Table 1])
LOAD RECORD([Table 1])
ASSERT(Not(Locked([Table 1])))
// triggers error -10518 if record is locked
136 4D v12 Upgrade

Asserted
` An assertion allows parameters passed to a project method to be tested

to detect aberrant values. In this example, a custom warning message is
used:
// Method that returns the number of a client according to its name
passed in $1
C_TEXT($1) // Name of client
ASSERT($1 # "";"Search for a blank client name")
// A blank name in this case is an aberrant value
// If the assertion is false, the following will appear in the error dialog box:
// "Assert failed: Search for a blank client name"
See Also: Asserted, SET ASSERT ENABLED
Asserted Asserted (boolExpression {; messageText}})Æ Boolean

boolExpression Boolean Æ Boolean expression
messageText String Æ Text of error message
Function result Boolean Å Result of evaluation of boolExpression
The new Asserted command is similar to that of the ASSERT command,

except that it returns a value which is the result of the evaluation of
the boolExpression parameter. Hence an assertion can be used during
the evaluation of a condition (see the example). For more information
about the operation of assertions and the parameters of this command,
refer to the description of the ASSERT command.
Asserted accepts a Boolean expression as a parameter and returns the

result of the evaluation of this expression. If the expression is false and
if assertions are enabled (see the SET ASSERT ENABLED command), the
error -10518 is generated, just like the ASSERT command. If the
assertions are disabled, Asserted returns the result of the expression
that was passed without triggering an error.
4D v12 Upgrade 137

Chapter 5 Language
` Inserting an assertion in the evaluation of an expression:

READ WRITE([Table 1])
LOAD RECORD([Table 1])
If (Asserted(Not(Locked( [Table 1]))))
// This code triggers the error -10518 if the record is locked
...
End if
See Also: ASSERT, SET ASSERT ENABLED
Get assert enabled Get assert enabled Æ Boolean

Function result Boolean Å True = assertions are enabled

False = assertions are disabled
The new Get assert enabled command returns True or False according to
whether or not assertions are enabled in the database. For more
information about assertions, refer to the description of the ASSERT
command.
By default, assertions are enabled but they may have been disabled
using the SET ASSERT ENABLED command.
See Also: SET ASSERT ENABLED
SET ASSERT SET ASSERT ENABLED(assertions{; *})

ENABLED Parameter Type Description
assertions Boolean Æ True = enable assertions
False = disable assertions
* * Æ If omitted = command applies to all the
processes (existing or created subse-
quently)
If passed= command applies to current
process only
The new SET ASSERT ENABLED command disables or re-enables any

assertions inserted into the 4D code of the application. For more
information about assertions, refer to the description of the ASSERT
command.
138 4D v12 Upgrade

SET ASSERT ENABLED
By default, assertions added in the program are enabled. This

command is useful when you want to disable them since their
evaluation can sometimes be costly in terms of execution time and you
may also want them to be hidden from the final user of the
application. Typically, the SET ASSERT ENABLED command could be
used in the On Startup database method to enable or disable assertions
according to whether the application is in "Test" mode or in
"Production" mode.
By default, the SET ASSERT ENABLED command affects all the processes
of the application. To restrict the effect of the command to the current
process only, you can pass the * parameter.
Note that when assertions are disabled, expressions passed to ASSERT

commands are no longer evaluated. The lines of code that call ASSERT
no longer have any effect on the operation of the application, neither
in terms of behavior, nor in terms of performance.
` Disabling assertions:
SET ASSERT ENABLED(False)
ASSERT(TestMethod) // TestMethod will not be called since assertions are
disabled
See Also: Get assert enabled
Ignore repeated The error window of 4D provides a new shortcut that can be used to
errors in the error ignore an error that occurs repeatedly, for example in a loop.
window
To do so, hold down the Alt (Windows) or Option (Mac OS) key when
you click on the Continue button in the 4D error window. This action
means that the window will no longer be shown if the same error,
triggered by the same method at the same line, occurs again. In this
case, everything continues as if the user was clicking on the Continue
button each time.
4D v12 Upgrade 139

Chapter 5 Language
Language
EXECUTE METHOD EXECUTE METHOD IN SUBFORM(subformObject; methodName{; return{;
IN SUBFORM param;...;paramN}})
subformObject String Æ Name of subform object
methodName String Æ Name of project method to be executed
return Variable | * Å Value returned by method or
* if method does not return a value
param Variable Æ Parameter(s) to pass to method
The new EXECUTE METHOD IN SUBFORM command executes the

methodName project method in the context of the subformObject
subform object.
The project method called can receive from 1 to X parameters in param

and return a value in return. Pass * in the return parameter if the
method does not return parameters.
You can pass the name of any project method that is accessible from
the database or the component executing the command. The
execution context is preserved in the method called, which means that
the current form and current form event remain specified. If the
subform comes from a component, the method must belong to the
component and have the "Shared by components and host database"
property.
This command must be called from the form method of the parent
form (containing the subformObject object).
For more information about subform mechanisms in 4D v12, refer to

the “Advanced inter-form programming” paragraph on page 76.
140 4D v12 Upgrade

EXECUTE METHOD IN SUBFORM
` Given the "ContactDetail" form used as subform in the parent form

"Company". The subform object that contains the ContactDetail form
is named "ContactSubform". Imagine that we want to modify the
appearance of certain elements of the subform according to the value
of the field(s) of the company (for example, "contactname" must
switch to red when [Company]City="New York" and to blue when
[Company]City="San Diego"). This mechanism is implemented via the
SetToColor method. To be able to get this result, the SetToColor method
cannot be called directly from the process of the "On Load" form event
of the Company parent form because the "contactname" object does
not belong to the current form, but to the form displayed in the
"ContactSubform" subform object. The method must therefore be
executed using the EXECUTE METHOD IN SUBFORM command to
function correctly.
Case of
: (Form event= On Load)
Case of
: ([Company]City = "New York")
$Color:=$Red
: ([Company]City = "San Diego")
$Color:=$Blue
Else
$Color:=$Black
End case
EXECUTE METHOD IN SUBFORM("ContactSubform";"SetToCol-
or";*;$Color)
End case
` You are developing a database that will be used as a component. It

includes a shared project form (named, for instance, Calendar) that
contains Dynamic variables as well as a public project method that
adjusts the calendar: SetCalendarDate(varDate).
4D v12 Upgrade 141

Chapter 5 Language
If this method was used directly in the Calendar form method, you
could call it directly in the "On Load" event: SetCalendarDate(Current
date). But, in the context of the host database, imagine that a project
form contains two "Calendar" subforms, in subform objects called
"Cal1" and "Cal2". You must set the date of Cal1 to 01/01/10 and the
date of Cal2 to 05/05/10. You cannot call SetCalendarDate directly
because the method will not "know" which forms and variables it
should apply. Therefore, you must call it via the following code:
EXECUTE METHOD IN SUBFORM("Cal1";
"SetCalendarDate";*;!01/01/10!)
EXECUTE METHOD IN SUBFORM("Cal2";
"SetCalendarDate";*;!05/05/10!)
` Advanced example: in the same context as before, this example

provides a generic method:
// Contents of the SetCalendarDate method
C_DATE($1)
C_TEXT($2)
Case of
: (Count parameters=1)
// Standard execution of method (as if it was executed from
// the form itself) or specifically for a context (see case 2)
: (Count parameters=2)
// External call, needs a context
// Recursive call with only one parameter
EXECUTE METHOD IN SUBFORM($2;"SetCalendarDate";*;$1)
End case
List Box
Several modifications have been made to the List Box theme of 4D
v12:
Four new commands are dedicated to the management of hierarchical
list boxes (for more information about hierarchical list boxes, refer to
“List boxes” paragraph on page 104),
The new LISTBOX GET PRINT INFORMATION command controls the
printing of list boxes,
142 4D v12 Upgrade

LISTBOX COLLAPSE
New parameters for the LISTBOX SET COLUMN WIDTH and LISTBOX Get
column width commands can be used to control the resizing of
columns.
To facilitate their use via autocomple functions, all the commands
have been prefixed LISTBOX.
LISTBOX COLLAPSE LISTBOX COLLAPSE ({*; }object{;recursive{; selector{; row; column}

| {level}}}})
* Æ If specified, object is an object name
(string)
If omitted, object is a variable
object Form object Æ Object name (if * is specified) or
Variable (if * is omitted)
recursive Boolean Æ True = collapse sublevels
False = do not collapse sublevels
selector Longint Æ Part of list box to collapse
row Longint Æ Number of break row to collapse
column Longint Æ Number of break column to collapse
level Longint Æ Number of list box level to collapse
The LISTBOX COLLAPSE command collapses the break rows of the list
box object designated by the object and * parameters.
If you pass the optional * parameter, you indicate that the object
parameter is an object name (string). If you do not pass this parameter,
you indicate that the object is a variable. In this case, you pass a
variable reference instead of a string.
If the list box is not configured in hierarchical mode, the command

does nothing. For more information about hierarchical list boxes, refer
to “List boxes” paragraph on page 104.
The optional recursive parameter configures the collapsing of the

hierarchical sublevels of the list box. Pass True or omit this parameter
for the command to collapse all the levels and all the sublevels. If you
pass False, only the first level will be collapsed.
4D v12 Upgrade 143

Chapter 5 Language
The optional selector parameter specifies the scope of the command.

You can pass one of the following constants in this parameter:
Listbox All (default value, used if parameter is omitted): collapses all
sub-levels.
Listbox Selection: collapses selected sub-levels.
Listbox Break row: collapses sub-level to which the "cell" designated
by the row and column parameters belongs. Note that these
parameters represent the row and column numbers in the list box
in standard mode and not in its hierarchical representation.
Listbox Level: collapses all the break rows corresponding to the level
column. This parameter designates a column number in the list box
in standard mode and not in its hierarchical representation.
If the selection or list box does not contain a break row or if all the
break rows are already collapsed, the command does nothing.
` This example collapses the first level of the break rows of the selection
in the list box:
LISTBOX COLLAPSE (*;"MyListbox";False;Listbox selection)
See Also: LISTBOX EXPAND
LISTBOX EXPAND LISTBOX EXPAND ({*; }object{;recursive{; selector{; row; column}

| {level}}}})
(string)
recursive Boolean Æ True = expand sublevels
False = do not expand sublevels
selector Longint Æ Part of list box to expand
row Longint Æ Number of break row to expand
column Longint Æ Number of break column to expand
level Longint Æ Number of list box level to expand
The LISTBOX EXPAND command expands the break rows of the list box
object designated by the object and * parameters.
144 4D v12 Upgrade

LISTBOX EXPAND
If the list box is not configured in hierarchical mode, the command

does nothing. For more information about hierarchical list boxes, refer
to “List boxes” paragraph on page 104.
The optional recursive parameter configures the expanding of the

hierarchical sublevels of the list box. Pass True or omit this parameter
for the command to expand all the levels and all the sublevels. If you
pass False, only the first level specified will be expanded.
The optional selector parameter specifies the scope of the command.

You can pass one of the following constants in this parameter:
Listbox all (default value, used if parameter is omitted): expands all
sub-levels.
Listbox selection: expands selected sub-levels.
Listbox break row: expands sub-level to which the "cell" designated
by the row and column parameters belongs. Note that these
parameters represent the row and column numbers in the list box
in standard mode and not in its hierarchical representation. In this
case, if the row and column parameters are omitted, the command
does nothing.
Listbox level: expands all the break rows corresponding to the level
column. This parameter designates a column number in the list box
in standard mode and not in its hierarchical representation. In this
case, if the level parameter is omitted, the command does nothing.
The command does not select break rows.
If the selection or list box does not contain a break row or if all the
break rows are already expanded, the command does nothing.
4D v12 Upgrade 145

Chapter 5 Language
` This example illustrates different ways of using the command. Given

the following arrays shown in a list box:
France Normandy Deauville 4000
France Normandy Cherbourg 41000
Belgium Wallonia Namur 111000
Belgium Wallonia Liege 200000
Belgium Flanders Antwerp 472000
Belgium Flanders Louvain 95000
// Expand all the break rows and subrows of the list box
LISTBOX EXPAND(*;"MyListbox")
V France
V Brittany
Brest 120000
Quimper 80000
Rennes 200000
V Normandy
Caen 220000
Deauville 4000
Cherbourg 41000
V Belgium
V Wallonia
Namur 111000
Liege 200000
V Flanders
Antwerp 472000
Louvain 95000
// Expand the first level of break rows of the selection

LISTBOX EXPAND (*;"MyListbox";False;Listbox selection)
// If the "Belgium" row was selected
> France
V Belgium
> Wallonia
> Flanders
146 4D v12 Upgrade

LISTBOX Get column width
// Expand the Brittany break row with recursion

LISTBOX EXPAND (*;"MyListbox";False;Listbox break row;1;2)
V France
V Brittany
Brest 120000
Quimper 80000
Rennes 200000
> Normandy
> Belgium
// Expand all the first columns (countries) without recursion

LISTBOX EXPAND (*;"MyListbox";False;Listbox level;1)
V France
> Brittany
> Normandy
V Belgium
> Wallonia
> Flanders
See Also: LISTBOX COLLAPSE
LISTBOX Get column LISTBOX Get column width({*; }object{; minWidth{; maxWidth}}) Æ Longint
width Parameter Type Description
(string)
minWidth Longint Å Minimum column width (in pixels)
maxWidth Longint Å Maximum column width (in pixels)
Function result Longint Å Column width (in pixels)
The LISTBOX Get column width command can now return the resizing
limits of the column in the minWidth and maxWidth parameters.
These limits can be specified via the LISTBOX SET COLUMN WIDTH
command.
4D v12 Upgrade 147

Chapter 5 Language
If no minimum and/or maximum value has been set for the column,
the corresponding parameter returns 0.
See Also: LISTBOX SET COLUMN WIDTH
LISTBOX GET LISTBOX GET HIERARCHY ({*; }object; hierarchical{; hierarchy})

HIERARCHY Parameter Type Description
(string)
hierarchical Boolean Å True = hierarchical list box
False = non-hierarchical list box
hierarchy Array Å Array of pointers
The new LISTBOX GET HIERARCHY command lets you find out the
hierarchical properties of the list box object designated by the object
and * parameters.
The Boolean hierarchical parameter indicates whether or not the list

box is in hierarchical mode:
If it returns True, the list box is in hierarchical mode,
If it returns False, the list box is in non-hierarchical mode (standard

array mode).
If the list box is in hierarchical mode, the command fills the hierarchy
array with pointers to the arrays of the list box used to set the
hierarchy.
Note If the list box is in non-hierarchical mode, the command returns, in

the first element of the hierarchical array, a pointer to the array of the
first column of the list box.
See Also: LISTBOX SET HIERARCHY
148 4D v12 Upgrade

LISTBOX GET PRINT INFORMATION
LISTBOX GET PRINT LISTBOX GET PRINT INFORMATION ({*; }object; selector; info)
INFORMATION Parameter Type Description
(string)
selector Longint Æ Information to get
info Longint | Å Current value
Boolean
The new LISTBOX GET PRINT INFORMATION command returns the

current information relative to the printing of the list box object
designated by the object and * parameters. This command can be used
to control the printing of the list box contents.
This command must be called in the context of the printing of a list

box via the Print object command. Outside of this context, it will not
return significant values.
Pass a value indicating the information you want to find out in selector
and a variable of the number or BLOB type in info. In selector, you can
pass one of the following constants, found in the "List box" theme:
selector Value returned in info
Listbox Last printed Returns in info the number of the last row printed.
row number (0) Lets you find out the number of the next row to
be printed.
The number returned may be greater than the
number of rows actually printed if the list box
contains invisible rows or if the OBJECT SET
SCROLL POSITION command has been called.
For example, if rows 1, 18 and 20 have been
printed, info is 20.
4D v12 Upgrade 149

Chapter 5 Language
Listbox Printed Returns in info the number of rows actually

rows(1) printed during the last call to the Print object
command. This number includes any break rows
added in the case of a hierarchical list box.
For example, info is 10 if the list box contains 20
rows and the odd-numbered rows were hidden.
Listbox Printing is Returns in info a Boolean indicating whether the
over (2) last (visible) row of the list box has actually been
printed. True = row has been printed; Otherwise,
False.
Listbox Printed height Returns in info the height in pixels of the object
(3) actually printed (including headers, lines, etc.).
Remember that if the number of rows to print is
less than the "capacity" of the list box, its height is
automatically reduced.
For more information about the principles of printing list boxes, refer
to the “Printing list boxes” paragraph on page 116.
` Printing until all the rows have been printed:

OPEN PRINTING JOB
OPEN PRINTING FORM("SalesForm")
…
$Over:=False
Repeat
PRINT OBJECT (*;"mylistbox")
LISTBOX GET PRINT INFORMATION(*;"mylistbox";
Listbox Printing is over;$Over)
Until ($Over)
…
CLOSE PRINTING JOB
` Printing at least 500 rows of the list box, knowing that certain rows are
hidden:
$GlobalPrinted:=0
Repeat
PRINT OBJECT (*;"mylistbox")
LISTBOX GET PRINT INFORMATION(*;"mylistbox";
Listbox Printed rows;$Printed)
$GlobalPrinted:=$GlobalPrinted+$Printed
PAGE BREAK
Until ($GlobalPrinted>=500)
150 4D v12 Upgrade

LISTBOX SELECT BREAK
LISTBOX SELECT LISTBOX SELECT BREAK({*; }object; row; column{; action})

BREAK Parameter Type Description
(string)
row Longint Æ Number of break row
column Longint Æ Number of break column
action Longint Æ Selection action
The new LISTBOX SELECT BREAK command selects break rows in the list
box object designated by the object and * parameters. The list box must
be displayed in hierarchical mode.
Break rows are added to represent the hierarchy but they do not
correspond to existing rows in the array. To designate a break row to be
selected, in the row and column parameters, you must pass the row and
column number corresponding to the first occurrence in the
corresponding array. These values are returned by the LISTBOX GET
CELL POSITION command when the user has selected a break row. This
principle is described in the “Management of selections and positions”
The action parameter, if it is passed, can set the selection action to be

carried out when a selection of break rows already exists in the list box.
You can pass a value or one of the following constants, found in the
"List box" theme:
Replace listbox selection (0): The selected break row becomes the new
break row selection and replaces the existing selection. The command
produces the same effect as a user click on a break row. This action is
carried out by default (when the action parameter is not passed).
Add to listbox selection (1): The selected break row is added to the
existing selection. If the break row designated already belongs to the
existing selection, the command does nothing.
4D v12 Upgrade 151

Chapter 5 Language
Remove from listbox selection (2): The selected break row is removed
from the existing selection. If the break row designated does not
belong to the existing selection, the command does nothing.
` Given the following arrays shown in a list box:

(T1) (T2) (T3) (T4)
France Normandy Deauville 4000
France Normandy Cherbourg 41000
Belgium Wallonia Namur 111000
Belgium Wallonia Liege 200000
Belgium Flanders Antwerp 472000
Belgium Flanders Louvain 95000
We want to select the "Normandy" break row:

$row:=Find in array(T2;"Normandy")
$column:=2
LISTBOX COLLAPSE (*;"MyListbox") `collapsing of all levels
LISTBOX SELECT BREAK(*;"MyListbox";$row;$column)
Here is the result:
V France
> Brittany
> Normandy
> Belgium
See Also: LISTBOX GET CELL POSITION, LISTBOX EXPAND
152 4D v12 Upgrade

LISTBOX SET COLUMN WIDTH
LISTBOX SET LISTBOX SET COLUMN WIDTH({*; }object; width{; minWidth{; maxWidth}})
COLUMN WIDTH Parameter Type Description
(string)
width Longint Æ Column width (in pixels)
minWidth Longint Æ Minimum column width (in pixels)
maxWidth Longint Æ Maximum column width (in pixels)
The LISTBOX SET COLUMN WIDTH command now accepts two

additional optional parameters that can be used to set limits for the
manual resizing of the column.
You can pass, respectively, the minimum and maximum width

expressed in pixels in the minWidth and maxWidth parameters.
If you want users to be unable to resize the column, you can pass the
same value in width, minWidth and maxWidth.
See Also: LISTBOX Get column width
LISTBOX SET LISTBOX SET HIERARCHY({*; }object; hierarchical{; hierarchy})

HIERARCHY Parameter Type Description
(string)
hierarchical Boolean Æ True = hierarchical list box
False = non-hierarchical list box
hierarchy Array Æ Array of pointers
The new LISTBOX SET HIERARCHY command lets you configure the list
box object designated by the object and * parameters in hierarchical or
non-hierarchical mode.
Note This command only functions with list boxes based on arrays. When
this command is used with a list box based on selections, it does
nothing.
4D v12 Upgrade 153

Chapter 5 Language
The Boolean hierarchical parameter lets you specify the list box mode:
If you pass True, the list box is displayed in hierarchical mode,
If you pass False, the list box is displayed in non-hierarchical mode

(standard array mode).
When you pass a list box in hierarchical mode, certain properties are
automatically restricted. For more information, refer to the “Modified
properties” paragraph on page 107.
The hierarchy parameter designates the arrays of the list box to be used
to build the hierarchy.
If you omit this parameter:
If the list box is already in hierarchical mode, the command does
nothing.
If the list box is in non-hierarchical mode and has never been
declared hierarchical, the first array is used as the hierarchy by
default.
If the list box is in non-hierarchical mode but has previously been
declared hierarchical, the last hierarchy is re-established.
` Definition of the aCountry, aRegion and aCity arrays as the hierarchy of

a list box:
ARRAY POINTER($ArrHierarch;3)
$ArrHierarch{1}:=->aCountry `First break level
$ArrHierarch{2}:=->aRegion `Second break level
$ArrHierarch{3}:=->aCity `Third break level
LISTBOX SET HIERARCHY(*;"mylistbox";True;$ArrHierarch)
See Also: LISTBOX GET HIERARCHY
Insertion or deletion The existing LISTBOX INSERT COLUMN, LISTBOX INSERT COLUMN
commands FORMULA and LISTBOX DELETE COLUMN commands do not have any
effect when they are applied to the first column of a list box displayed
in hierarchical mode.
Note These commands are renamed in 4D v12 (see the paragraph below).
154 4D v12 Upgrade

Object Properties
Renamed For reasons of harmonization and standardization, the existing

commands commands of the "Listbox" theme have been renamed in 4D v12. The
"LISTBOX" prefix has been added systematically. The functioning of
these commands has not changed.
LISTBOX DELETE COLUMN DELETE LISTBOX COLUMN
LISTBOX DELETE ROW DELETE LISTBOX ROW
LISTBOX GET ARRAYS GET LISTBOX ARRAYS
LISTBOX GET CELL POSITION GET LISTBOX CELL POSITION
LISTBOX Get column width Get listbox column width
LISTBOX Get information Get listbox information
LISTBOX Get number of columns Get number of listbox columns
LISTBOX Get number of rows Get number of listbox rows
LISTBOX Get rows height Get listbox rows height
LISTBOX GET TABLE SOURCE GET LISTBOX TABLE SOURCE
LISTBOX INSERT COLUMN INSERT LISTBOX COLUMN
LISTBOX INSERT COLUMN FOR- INSERT LISTBOX COLUMN FORMULA
MULA
LISTBOX INSERT ROW INSERT LISTBOX ROW
LISTBOX MOVED COLUMN NUM- MOVED LISTBOX COLUMN NUMBER
BER
LISTBOX MOVED ROW NUMBER MOVED LISTBOX ROW NUMBER
LISTBOX SELECT ROW SELECT LISTBOX ROW
LISTBOX SET COLUMN WIDTH SET LISTBOX COLUMN WIDTH
LISTBOX SET GRID COLOR SET LISTBOX GRID COLOR
LISTBOX SET ROWS HEIGHT SET LISTBOX ROWS HEIGHT
LISTBOX SET TABLE SOURCE SET LISTBOX TABLE SOURCE
LISTBOX SHOW GRID SHOW LISTBOX GRID
LISTBOX SORT COLUMNS SORT LISTBOX COLUMNS
Object Properties
The commands of this theme have undergone numerous
modifications in 4D v12:
New properties can be accessed via new commands.
For greater ease of use, existing commands have been prefixed,

renamed and completed if necessary by "read" and/or "write"
commands of the symmetrical properties.
4D v12 Upgrade 155

Chapter 5 Language
ENABLE BUTTON, The ENABLE BUTTON and DISABLE BUTTON commands are declared
DISABLE BUTTON obsolete in 4D v12. They are kept for compatibility reasons only. Their
overall scope, including all the instances of the designated variable and
not only those of the current form, does not correspond to that of the
commands of the "Object Properties" theme.
In 4D v12, ENABLE BUTTON and DISABLE BUTTON are favorably replaced
by the new OBJECT SET ENABLED and OBJECT Get enabled commands.
OBJECT DUPLICATE OBJECT DUPLICATE ({*; }object{;newName{;newVar{; boundTo{; moveH{;

moveV{; resizeH{; resizeV}}}}}}}{; *})
* * Æ If specified, object is an object name
(string)
If omitted, object is a variable or a field
Variable or field (if * is omitted)
newName Text Æ Name of new object
newVar Pointer Æ Pointer to variable of new object
boundTo Text Æ Name of previous enterable object (or
radio button)
moveH Longint Æ Horizontal shift of new object
(>0 = to the right, <0 = to the left)
moveV Longint Æ Vertical shift of new object
(>0 = downwards, <0 = upwards)
resizeH Longint Æ Horizontal resize of new object
resizeV Longint Æ Vertical resize of new object
* * Æ If specified= absolute coordinates
If omitted= relative coordinates
The new OBJECT DUPLICATE command creates a copy of the object

designated by the object parameter. The copy is generated in the
context of the form being executed (Application mode). The source
form, generated in Design mode, is not modified.
By default, all the options specified in the Property list for the source
object are applied to the copy (size, resizing options, color, etc.),
including any associated object method.
156 4D v12 Upgrade

OBJECT DUPLICATE
However, the following exceptions should be noted:

Default button: there can only be one default button in a form. When
you duplicate a button having the "Default button" property, this
property is assigned to the copy and is removed from the source object.
Keyboard equivalents: the keyboard shortcut associated with a source
object is not duplicated. This property is left blank in the copy.
Object names: there cannot be several objects with the same name in a
form. If you do not pass the newName parameter, the name of the
source object is automatically incremented in the new object (see
below).
you indicate that the object is a field or a variable. In this case, you pass
a field or variable reference (object field or variable only) instead of a
string.
If you pass a field or variable reference and if the form contains several
objects that use the same reference, the first occurrence found will be
used. In this case, to avoid any ambiguity, it is recommended to work
with object names, that are unique.
Pass the name assigned to the copy of the object in the newName
parameter. This name must be in keeping with the rules for naming
objects and be unique in the form. If it is not valid or already used by
another object, the command does nothing and the OK variable
returns 0.
If you omit this parameter or pass an empty string, the new name is
automatically generated by incrementation of the source object name
(if this name is not already used). For example:
Source name Name of copy
Button Button1
Button20 Button21
Button21 Button23 if Button22 already exists
4D v12 Upgrade 157

Chapter 5 Language
Pass a pointer to the variable to be associated with the new object in

newVar. As a rule, you must point to a variable of the same type as the
that of the source object but certain kinds of "retyping" are possible.
The command provides automatic functions to facilitate writing
generic code:
Usually, all "enterable" variables can be retyped; for example, an object
displaying a Date or Longint can be duplicated and used with a
variable of the Text type. Any compatible properties will be kept. The
command also permits changing types between Text objects and
Picture objects. Note that a text object that is duplicated and associated
with a Boolean variable or field will automatically appear as a check
box.
It is usually possible to dynamically transform a variable into a field
and vice versa.
On the other hand, graphic objects (buttons, check boxes, and so on)
cannot be transformed into other types of controls.
If the variable type is not compatible with the object, the command
does nothing and the OK variable is set to 0.
If you omit this parameter, the variable is created dynamically by 4D
(see the “Dynamic variables” paragraph on page 255).
If you duplicate a static object (lines, rectangle, static picture, etc.), this
parameter is ignored. Pass a Nil pointer (->[]) if you want to be able to
use the other parameters.
You use the boundTo parameter in two cases:

Update of entry order: in this case, in boundTo, pass the name of the
enterable object located just before the duplicated object. If you want
for the new object to become the first object in the entry order of the
page, pass the new Object First in entry order constant (see the OBJECT
Get pointer command on page 233).
Association with a group of radio buttons: radio buttons function in a
coordinated fashion when they are grouped. If the duplicated object is
a radio button, in boundTo pass the name of a radio button of the
group to which you want to attach the new object.
If you omit this parameter or pass an empty string, the new object
becomes the last enterable object of the form page. In the case of a
radio button, the object is attached to the group of the source button.
158 4D v12 Upgrade

OBJECT DUPLICATE
The new object can be moved and resized via the moveH, moveV,
resizeH and resizeV parameters. As with the OBJECT MOVE command,
the direction of the move or the resizing is specified by the sign of the
values passed in the moveH and moveV parameters:
If the value is positive, the move or resizing is carried out, respectively,
to the right or downwards.
If the value is negative, the move or resizing is carried out, respectively,
to the left or upwards.
By default, the values of moveH, moveV, resizeH and resizeV modify the
coordinates of the object in relation to its previous position. If you
want for these parameters to specify absolute coordinates, pass the
optional final * parameter.
If you omit these parameters, the new object is superimposed on top of

the source object.
This command must be used in the context of the display of a form. It

will generally be called in the On Load form event or following a user
action (On Clicked event).
Note If the On Load form event is associated with the source object, it is
generated for the duplicated object when the command is executed.
This allows, for example, the value of the object to be initialized.
For technical and logical reasons, OBJECT DUPLICATE cannot be called

within the certain form events, in particular:
On Load event generated in an object method
On Unload event
Event related to printing context (On Header, On Printing Detail,
etc.). To print an object several times, you must use the new Print
object command).
When the command is called in a context that is not supported, the

object is not duplicated and the OK variable is set to 0. If it is called in
a printing context, the error -10601 is generated as well.
If the command was executed correctly, the OK variable is set to 1.

Otherwise, it is set to 0.
4D v12 Upgrade 159

Chapter 5 Language
` Creation of a new button named "CancelButton" on top of the existing

"OKButton" object and association with the vCancel variable:
OBJECT DUPLICATE(*;"OKButton";"CancelButton";vCancel)
` Creation of a new radio button "bRadio6" based on the existing radio

button "bRadio5". This button will be associated with the variable
<>r6, integrated with the group of the "bRadio5" button and placed 20
pixels above it:
OBJECT DUPLICATE(*;"bRadio5";"bRadio6";<>r6;"bRadio5";0;20)
OBJECT Get choice OBJECT Get choice list name ({*; }object) Æ String
list name Parameter Type Description
(string)
If omitted, object is a variable or a
field
Function result String Å Name of choice list (specified in

Design mode)
The new OBJECT Get choice list name command returns the name of
the choice list associated with the object or group of objects designated
by object.
string.
See Also: OBJECT SET CHOICE LIST NAME
160 4D v12 Upgrade

OBJECT Get enabled
OBJECT Get enabled OBJECT Get enabled ({*; }object) Æ Boolean

(string)
Function result Boolean Å True = object(s) enabled; Otherwise,

false
The new OBJECT Get enabled command returns True if the object or
group of objects designated by object is enabled in the form and False if
it is not enabled.
An enabled object reacts to mouse clicks and to keyboard shortcuts.
variable reference (object variable only) instead of a string.
This command can be applied to the following types of objects:

Button, Default button, 3D button, Invisible button, Highlight button
Radio button, 3D radio button, Picture button
Check Box, 3D Check Box
Pop-up menu, Drop-down List, Combo Box, Menu/Drop-down List
Thermometer, Ruler
See Also: OBJECT SET ENABLED
4D v12 Upgrade 161

Chapter 5 Language
OBJECT Get OBJECT Get enterable ({*; }object) Æ Boolean

enterable Parameter Type Description
(string)
Function result Boolean Å True = object(s) enterable; Otherwise,

false
The new OBJECT Get enterable command returns True if the object or
group of objects designated by object has the enterable attribute;
otherwise, it returns False.
string.
See Also: OBJECT SET ENTERABLE
OBJECT Get filter OBJECT Get filter ({*; }object) Æ String

(string)
Function result String Å Name of filter
The new OBJECT Get filter command returns the name of any filter
associated with the object or group of objects designated by object.
string.
See Also: OBJECT SET FILTER
162 4D v12 Upgrade

OBJECT Get font
OBJECT Get font OBJECT Get font ({*; }object) Æ String

(string)
Function result String Å Name of font
The new OBJECT Get font command returns the name of the character
font used by the form object(s) designated by object.
string.
See Also: OBJECT SET FONT
OBJECT Get font size OBJECT Get font size ({*; }object) Æ Longint
(string)
Function result Longint Å Size of font in points
The new OBJECT Get font size command returns the size (in points) of
the character font used by the form object(s) designated by object.
string.
See Also: OBJECT SET FONT SIZE
4D v12 Upgrade 163

Chapter 5 Language
OBJECT Get font OBJECT Get font style ({*; }object) Æ Longint
style Parameter Type Description
(string)
Function result Longint Å Font style
The new OBJECT Get font style command returns the current style of
the character font used by the form object(s) designated by object.
string.
You can compare the value returned with the value of one or more of
the following predefined constants, placed in the "Font Styles" theme:
Constant Type Value
Plain Longint 0
Bold Longint 1
Italic Longint 2
Underline Longint 4
See Also: OBJECT SET FONT STYLE
164 4D v12 Upgrade

OBJECT Get plain text
OBJECT Get plain OBJECT Get plain text({*; }object) Æ Text

text Parameter Type Description
* * Æ If specified, object is an object
name (string)
field
Function result Text Å Text without tags
The new OBJECT Get plain text command removes any style tags from
the text variable or field designated by the * and object parameters and
returns the plain text.
a field or variable reference instead of a string.
` You are looking for the text "very nice" among the values of a multi-
style text field. The value was stored in the following form: "The
weather is very nice today".
QUERY BY FORMULA([Comments];
OBJECT Get plain text([Comments]Weather)="@very nice@")
Note In this context, the following statement will not give the desired result
because the text is saved with style tags:
QUERY([Comments];[Comments]Weather="@very nice@")
4D v12 Upgrade 165

Chapter 5 Language
OBJECT GET RGB OBJECT GET RGB COLORS({*; }object; foregroundColor{; background-
COLORS Color{; altBackgrndColor}})
name (string)
field
foregroundColor Longint Å RGB color value for foreground
backgroundColor Longint Å RGB color value for background
altBackgrndColor Longint Å RGB color value for alternating
background
The new OBJECT GET RGB COLORS command returns the foreground
and background colors of the object or group of objects designated by
object.
string.
When the command is applied to a List box type object, the

alternating background color for the rows can be returned in the
altBackgrndColor parameter. In this case, the value of backgroundColor is
used for the background of odd-numbered rows only.
The RGB color values returned in the foregroundColor, backgroundColor

and altBackgrndColor parameters are 4-byte longints of the format
(0x00RRGGBB). For more information about this format, refer to the
description of the OBJECT SET RGB COLORS command.
See Also: OBJECT SET RGB COLORS
166 4D v12 Upgrade

OBJECT GET SCROLLBAR
OBJECT GET OBJECT GET SCROLLBAR({*; }object; horizontal; vertical)

SCROLLBAR Parameter Type Description
name (string)
field
horizontal Boolean Å True=displayed, False=hidden
vertical Boolean Å True=displayed, False=hidden
The new OBJECT GET SCROLLBAR command is used to find out the
displayed/hidden status of the horizontal and vertical scrollbars of the
object or group of objects designated by object.
string.
This command can be used with the following form objects:

list boxes,
scrollable areas,
hierarchical lists,
subforms.
4D v12 Upgrade 167

Chapter 5 Language
OBJECT GET SCROLL OBJECT GET SCROLL POSITION({*; }object; vPosition{; hPosition})
POSITION Parameter Type Description
(string)
If omitted, object is a variable, a field or a
table
Variable or field or table (if * is omitted)
vPosition Longint Å Number of first line displayed or
Vertical scrolling in pixels (pictures)
hPosition Longint Å Number of first column displayed or
Horizontal scrolling in pixels (pictures)
The new OBJECT GET SCROLL POSITION returns, in the vPosition and
hPosition parameters, information related to the position of the scroll
bars of the form object designated by the * and object parameters.
parameter is the name of an object of the subform, hierarchical list,
scrollable area, list box or picture type (in this case, pass a string in
object). If you do not pass this parameter, you indicate that the object is
a table (list form or subform table) or a variable (ListRef of hierarchical
list, picture or list box variable) or a field.
If object designates a list type object (subform, list form, hierarchical
list, scrollable area or list box), vPosition returns the number of the first
line displayed in the object. hPosition (list box only) returns the
number of the first column that is completely visible in the left part of
the list box. With other types of objects, this parameter returns 0.
If object designates a picture (variable or field), vPosition returns the
vertical movement and hPosition the horizontal movement of the
picture. These values are expressed in pixels with respect to the origin
of the picture in the local coordinate system.
See Also: OBJECT SET SCROLL POSITION
168 4D v12 Upgrade

OBJECT Get styled text
OBJECT Get styled OBJECT Get styled text({*; }object{; startSel{; endSel}}) Æ Text
text Parameter Type Description
(string)
startSel Longint Æ Start of selection
endSel Longint Æ End of selection
Function result Text Å Text including style tags
The new OBJECT Get styled text command returns the styled text found
in the multi-style text field or variable designated by the object
parameter.
The command returns the text with any style tags that are associated
with it, which means, for example, that you can copy and paste text
while keeping its style.
The optional startSel and endSel parameters let you designate a

selection of text in object. The startSel and endSel values give a selection
of plain text, without taking any style tags found in the text into
account.
If you omit startSel and endSel, OBJECT Get styled text returns all the
text contained in object,
If you pass startSel and endSel, OBJECT Get styled text returns the
selection of text set by these limits.
If the values of startSel and endSel are equal or if startSel is greater than
endSel, an error is returned.
See Also: OBJECT SET STYLED TEXT, OBJECT Get plain text
4D v12 Upgrade 169

Chapter 5 Language
OBJECT GET STYLED OBJECT GET STYLED TEXT ATTRIBUTES({*; }object; startSel; endSel; attr-
TEXT ATTRIBUTES Name; attrValue{; attrName2; attrValue2;...;attrNameN; attrValueN})
(string)
startSel Number Æ Start of text selection
endSel Number Æ End of text selection
attrName Longint Æ Attribute to get
attrValue Variable Å Current value of attribute
The new OBJECT GET STYLED TEXT ATTRIBUTES command recovers the
current value of a style attribute in a selection of text of the form
object(s) designated by object.
The startSel and endSel parameters designate the text selection of the
object from which the style attribute is to be read. Pass the position of
the first character of the selection in startSel and the position plus one
of the last character of the selection in endSel.
The startSel and endSel values do not take any style tags already present
in the area into account. They are evaluated on the basis of raw text
(text from which style tags have been filtered).
Pass the name of the attribute to read in the attrName parameter. To do

this, you must use one of the constants of the "Multistyle text
attributes" theme. For more information, refer to the description of the
OBJECT SET STYLED TEXT ATTRIBUTES command on page 177. Pass a
variable which must recover the current value of the attribute in the
attrValue parameter.
You can pass as many attribute/value pairs as you want.
170 4D v12 Upgrade

OBJECT Get title
If the value of the attrName attribute is the same for all of the selection,
it is returned in attrValue. If this value is different or if object does not
contain SPAN tags, the following values are returned:
attrValue if attribute heterogenous in
attrName
selection or no SPAN tags
Attribute font name "" (empty string)
Attribute text size 2
Attribute text color FFFFFFFF
Attribute background color FFFFFFFF
Attribute bold style 2
Attribute italic style 2
Attribute underline style 2
Attribute strikethrough 2
style
OBJECT Get title OBJECT Get title ({*; }object) Æ String

(string)
objet Form object Æ Object name (if * is specified) or
Function result String Å Title of button
The new OBJECT Get title command returns the title (label) of the form
object(s) designated by object. This command can only be used with
objects of the ’button’ type displaying text: buttons, check boxes and
radio buttons.
string.
See Also: OBJECT SET TITLE
4D v12 Upgrade 171

Chapter 5 Language
OBJECT Get visible OBJECT Get visible ({*; }object) Æ Boolean

(string)
Function result Boolean Å True = object(s) visible; Otherwise,

False
The new OBJECT Get visible command returns True if the object or
group of objects designated by object has the visible attribute and False
otherwise.
string.
See Also: OBJECT SET VISIBLE
OBJECT SET OBJECT SET ENABLED({*; }object; active)

ENABLED Parameter Type Description
(string)
active Boolean Æ True = object(s) enabled; otherwise, False
The new OBJECT SET ENABLED command enables or disables the object
or group of objects specified by object in the current form.
An enabled object reacts to mouse clicks and to keyboard shortcuts.
variable reference (object variable only) instead of a string.
This command can be applied to the following types of objects:
172 4D v12 Upgrade

OBJECT SET FORMAT
Button, Default button, 3D button, Invisible button, Highlight button
Radio button, 3D radio button, Picture button
Check Box, 3D Check Box
Pop-up menu, Drop-down List, Combo Box, Menu/Drop-down List
Thermometer, Ruler
Note This command has no effect with an object to which a standard action
has been assigned (4D looks after modifying the state of this object
when necessary), except in the case of the Validate and Cancel actions.
See Also: OBJECT Get enabled, ENABLE BUTTON, DISABLE BUTTON
OBJECT SET OBJECT SET FORMAT({*; }object; displayFormat)

FORMAT
Note The OBJECT SET FORMAT command was named SET FORMAT in
previous versions of 4D.
In the case of thermometers and rulers, a new subparameter is

available in the series of displayFormat subparameters:
min;max;unit;step;flags{;format{;display}}
For rulers, this subparameter can have the following values:
display = 0 (or is omitted): displays a standard ruler.
display = 1: activates "Stepper" mode. For more information, refer to
the “New stepper object” paragraph on page 89.
For thermometers (progress indicators), this subparameter is only
taken into account if the flags subparameter is 128 (undetermined). In
this case:
display = 0 (or is omitted): displays a thermometer in continuous
animation of the "barber shop" type.
display = 1: activates the "Asynchronous progress" mode. For more
information, refer to the “Asynchronous progress indicator”
4D v12 Upgrade 173

Chapter 5 Language
OBJECT SET SCROLL OBJECT SET SCROLL POSITION({*; }object{; vPosition{; hPosition}}{; *})
POSITION Parameter Type Description
(string)
If omitted, object is a variable, a field or a
table
Variable or field or table (if * is omitted)
vPosition Longint Æ Line number to display or
Vertical scrolling in pixels (pictures)
hPosition Longint Æ Column number to display (list box) or
Horizontal scrolling in pixels (pictures)
* * Æ Display of line (and column if the hPosition
parameter is passed) in first position after
scroll
Note The OBJECT SET SCROLL POSITION command was named SCROLL LINES
and was found in the "User Interface" theme in previous versions of 4D.
The scope of the OBJECT SET SCROLL POSITION command has been
extended in 4D v12. In addition to vertical scrolling of subforms, list
forms and list boxes, this command can also cause horizontal scrolling
of list boxes and both vertical and horizontal scrolling of pictures.
Horizontal scrolling of a list box: if object designates a list box, you can
pass a column number in the hPosition parameter. In this case,
executing the command causes horizontal scrolling of the list box so
that this column will be shown. If the column is already visible, the
command does nothing.
As with vertical scrolling, if you pass the second optional * parameter,
the column made visible by the command (if the list box is actually
scrolled) will be placed in the first position.
Note Keep in mind that this command is always based on the "standard"
representation (non-hierarchical) of a list box, even if it is displayed in
hierarchical mode. Consequently, the result of a OBJECT SET SCROLL
POSITION statement may be different depending on whether the list
box is displayed in standard mode or in hierarchical mode.
174 4D v12 Upgrade

OBJECT SET SCROLL POSITION
Scrolling of pictures: if object designates a picture displayed in the

form, you can scroll its contents using the OBJECT SET SCROLL
POSITION command. The picture must be displayed in the "Truncated
(non-centered)" format. In vPosition and hPosition, you can pass,
respectively, the vertical and horizontal scrolling to be applied to the
picture. Pass 0 in vPosition if you do not want to scroll the picture
vertically. The values must be expressed in pixels in relation to the
origin of the picture in its local context.
Note Scrolling an object by programming remains possible even when the

scrollbars have been hidden in the form.
` This example illustrates the difference in the way the command

functions depending on whether the list box is displayed in standard
or hierarchical mode:
OBJECT SET SCROLL POSITION(*;"mylistbox";4;2;*)
// displays 4th row of 2nd column of list box in the first position
If this statement is applied to a list box displayed in standard mode:

France Brittany Brest 120000 ...
France Brittany Quimper 80000 ...
France Brittany Rennes 200000 ...
France Normandy Caen 220000 ...
France Normandy Deauville 4000 ...
France Normandy Cherbourg 41000 ...
... ... ... ... ...
... the rows and columns of the list box actually scroll:
Normandy Caen 220000 ... ...
Normandy Deauville 4000 ... ...
Normandy Cherbourg 41000 ... ...
... ... ... ... ...
... ... ... ... ...
... ... ... ... ...
... ... ... ... ...
4D v12 Upgrade 175

Chapter 5 Language
On the other hand, if the same statement is applied to a list box

displayed in hierarchical mode, the rows scroll but not the columns
because the 2nd column is part of the hierarchy:
V Normandy
Caen 220000
Deauville 4000
Cherbourg 41000
...
See Also: OBJECT GET SCROLL POSITION, OBJECT SET FORMAT
OBJECT SET STYLED OBJECT SET STYLED TEXT({*; }object; newText{; startSel{; endSel}})
TEXT Parameter Type Description
(string)
newText String Æ Text to insert
startSel Longint Æ Start of selection
endSel Longint Æ End of selection
The new OBJECT SET STYLED TEXT command inserts the text passed in
the newText parameter into the multi-style text field or variable
designated by the object parameter. This command only applies to the
plain text of the object parameter, without modifying any style tags
that it contains. You can use it to modify, by programming, styled text
displayed on screen.
In newText, pass the text to be inserted.
176 4D v12 Upgrade

OBJECT SET STYLED TEXT ATTRIBUTES
The optional startSel and endSel parameters let you designate a

selection of text in object. The startSel and endSel values give a selection
of plain text, without taking any style tags found in the text into
account. The action of the command varies according to the optional
startSel and endSel parameters:
If you omit startSel and endSel, OBJECT SET STYLED TEXT replaces all the
text of the object by newText,
If you only pass startSel, OBJECT SET STYLED TEXT inserts the newText
text into object beginning at startSel,
If you pass both startSel and endSel, OBJECT SET STYLED TEXT replaces
the plain text set by these limits with the newText text.
` You want to replace the styled text selected by the user with the
contents of the vtemp variable:
GET HIGHLIGHT([Products]Notes;vStart;vEnd)
OBJECT SET STYLED TEXT([Products]Notes;vtemp;vStart;vEnd)
See Also: OBJECT Get styled text, OBJECT Get plain text
OBJECT SET STYLED OBJECT SET STYLED TEXT ATTRIBUTES({*; }object; startSel; endSel; attr-
TEXT ATTRIBUTES Name; attrValue{; attrName2; attrValue2;...;attrNameN; attrValueN})
(string)
startSel Number Æ Start of new text selection
endSel Number Æ End of new text selection
attrName Longint Æ Attribute to set
attrValue String | Æ New value of attribute
Number
The new OBJECT SET STYLED TEXT ATTRIBUTES command modifies one
or more style attributes in the form object(s) designated by object.
4D v12 Upgrade 177

Chapter 5 Language
The definition of an attribute is carried out via the insertion or

modification of HTML style tags within the text (see the “Rich text
management properties” paragraph on page 95). Note that OBJECT SET
STYLED TEXT ATTRIBUTES inserts style tags in all cases, even if the object
designates text objects of the form that do not have the Multi-style
property.
Note Adding tags increases the size of the string. If you modify the style
attributes of Alpha fields, make sure that the length of the resulting
string does not exceed the maximum field size. Otherwise, the data
will be truncated.
The startSel and endSel parameters designate the selection of text to

which to apply the style modification(s) within the object. Pass the
position of the first character to modified in startSel and the position of
the last character to be modified in endSel.
If the startSel and endSel values are equal or if startSel is greater than
endSel, an error is returned. If the value of endSel is greater than the
number of characters in the object, all the characters between startSel
and the end of the text will be modified.
The startSel and endSel values do not take any style tags already present
in the area into account. They are evaluated on the basis of raw text
(text where style tags have been filtered).
In attrName and attrValue, pass the name and the value, respectively, of
the attribute to be modified. You can pass as many attribute/value pairs
as you want.
To specify the attrName parameter, use the predefined constants placed

in the "Multistyle text attributes" theme. The value passed in the
attrValue parameter depends on the attrName parameter:
attrName attrValue
Attribute bold style(1) 0 = remove bold attribute from selection
1= apply bold attribute to selection
Attribute italic style(2) 0 = remove italic attribute from selection
1= apply italic attribute to selection
178 4D v12 Upgrade

OBJECT SET STYLED TEXT ATTRIBUTES
Attribute strikethrough 0 = remove strikethrough attribute from

style(3) selection
1= apply strikethrough attribute to selec-
tion
Attribute underline style (4) 0 = remove underline attribute from selec-
tion
1= apply underline attribute to selection
Attribute font name(5) Font name (string)
Attribute text size(6) Number of points (number)
Attribute text color(7) Hexadecimal values or HTML color names
(see the "Colors" paragraph)
Attribute background (Windows only) Hexadecimal values or
color(8) HTML color names (see the "Colors" para-
graph)
Colors
If you pass the Attribute text color or Attribute background color
constants in attrName, you must pass a string containing either an
HTML color name or a hexadecimal color value in attrValue:
HTML color name Hexa value
Aqua #00FFFF
Black #000000
Blue #0000FF
Fuchsia #FF00FF
Gray #808080
Green #008000
Lime #00FF00
Maroon #800000
Navy #000080
Olive #808000
Purple #800080
Red #FF0000
Silver #C0C0C0
Teal #008080
White #FFFFFF
Yellow #FFFF00
The attrValue parameter can be of the Text, Boolean, Integer, Real, Date
or Time type. If you pass invalid attributes or values, 4D returns an
error.
4D v12 Upgrade 179

Chapter 5 Language
` In this example, we modify the size and color of the text as well as the
bold and underline attributes of the characters 2 to 5 of the field:
OBJECT SET STYLED TEXT ATTRIBUTES([MyTable]MyField;2;5;
Attribute font name;"Arial";Attribute text size; 10;
Attribute underline style; 1; Attribute bold style;
1;Attribute text color;"Blue")
Reorganization of For reasons of harmonization and standardization, several existing

theme commands of the "Object Properties" theme have been renamed in 4D
v12 (in particular the "OBJECT" prefix has been added systematically).
The functioning of these commands has not changed.
In addition, new commands have been added to provide a more
symmetrical set of "read" and "write" property commands.
All these modifications are listed in the following table. The new
commands are described afterwards:
New name in 4D v12 Former 4D name
OBJECT Get alignment Get alignment
OBJECT GET BEST SIZE BEST OBJECT SIZE
OBJECT GET COORDINATES GET OBJECT RECT
OBJECT Get format Get format
OBJECT MOVE MOVE OBJECT
OBJECT SET ALIGNMENT SET ALIGNMENT
OBJECT SET CHOICE LIST NAME SET CHOICE LIST
OBJECT SET COLOR SET COLOR
OBJECT SET ENTERABLE SET ENTERABLE
OBJECT SET FILTER SET FILTER
OBJECT SET FONT FONT
OBJECT SET FONT SIZE FONT SIZE
OBJECT SET FONT STYLE FONT STYLE
OBJECT SET FORMAT SET FORMAT
OBJECT SET RBG COLORS SET RGB COLORS
OBJECT SET SCROLLBAR SET SCROLLBAR VISIBLE
OBJECT SET TITLE BUTTON TEXT
OBJECT SET VISIBLE SET VISIBLE
180 4D v12 Upgrade

Pasteboard
New commands in 4D v12

OBJECT DUPLICATE
OBJECT Get choice list name
OBJECT Get enabled
OBJECT Get enterable
OBJECT Get filter
OBJECT Get font
OBJECT Get font size
OBJECT Get font style
OBJECT GET RGB COLORS
OBJECT GET SCROLLBAR
OBJECT GET SCROLL POSITION
OBJECT Get title
OBJECT Get visible
OBJECT SET ENABLED
Pasteboard
SET FILE TO SET FILE TO PASTEBOARD(file{; *})
PASTEBOARD Parameter Type Description
file Text Å File name or
Complete pathname of file
* * Æ If passed = add
If omitted = replace
For greater flexibility, you can now pass a file name directly to the SET
FILE TO PASTEBOARD command (without a complete pathname).
In addition, the command also accepts the star * as an optional

parameter. By default, when this parameter is omitted, the command
replaces the contents of the pasteboard by the last pathname specified
by file (previous functioning of command).
If you pass this parameter, the command adds the file to the
pasteboard. This way it can contain a "stack" of file pathnames.
In both cases, if data other than pathnames was present in the

pasteboard, it is erased.
4D v12 Upgrade 181

Chapter 5 Language
PHP
This new theme groups together commands dedicated to the execution
of PHP scripts in 4D (see the “Executing PHP scripts in 4D” paragraph
on page 62).
PHP Execute PHP Execute (scriptPath{; functionName{; * | result{; param}{; param2; … ;

paramN}}}) Æ Boolean
scriptPath String Æ Pathname to PHP script or
"" to execute a PHP function
functionName String Æ PHP function to be executed
* | result * | Variable Å Result of PHP function execution or * to
| Field not receive any result
param1...N Æ Parameter(s) of PHP function
Function result Boolean Å True = execution correct

False = execution error
The PHP Execute command executes a PHP script or function.
Pass the pathname of the PHP script to be executed in the scriptPath

parameter. This can be a relative pathname if the file is located next to
the database structure or a complete path. The pathname can be
expressed in either the system syntax or POSIX syntax.
If you want to execute a standard PHP function directly, pass an empty
string ("") in scriptPath. The function name must be passed in the
second parameter.
Pass a PHP function name in the functionName parameter if you want

to execute a specific function in the scriptPath script.
If you pass an empty string or omit this parameter, the script is entirely
executed.
Note PHP is case sensitive for function names. Do not use parentheses, just
enter the function name only.
The result parameter receives the result of the execution of the PHP
function. You can pass either:
a variable, an array or a field to receive the result,
the * character if the function does not return any result or if you do
not want to retrieve it.
182 4D v12 Upgrade

PHP Execute
You can pass a variable, an array or a field of the Text, Longint, Real,
Boolean, or Date type as well as (except for arrays) a field of the BLOB
or Time type. 4D will carry out the conversion of the data and any
adjustments needed (for example, for a Real value, the separator will be
chosen according to the system).
If the value returned does not correspond to the type of the result
parameter, 4D will convert it if possible. For example, if you pass a
result variable of the Boolean type and receive a number, result will be
True unless the number is equal to 0. On the other hand, if you pass a
result variable of the number type (Longint or Real) and receive True or
False, result is set to 1 or 0.
If the result is placed in a variable or a field of the Text type, by default

it does not contain the headers returned by the PHP interpreter. If you
also want to retrieve the headers as text, use the PHP Raw result
constant with the PHP SET OPTION command. Note that if the result
returned is not exploitable as text, 4D encodes it in Base64.
Note - If the result is placed in a BLOB, the headers are always kept.
- If the result is placed in a Date, the PHP script must return a date in
the DATE_ATOM format (type "YYYY-MM-DDTHH:MM:SS") and not a
custom or localized format.
If the PHP function called expects arguments, use the param1...N

parameters to pass one or more values. The values must be separated
by semi-colons. You can pass values of the Alpha, Text, Boolean, Real,
Integer, Longint, Date or Time type. Pictures and BLOBs are not
accepted. You can pass the values of an array by using a pointer to this
array (see the example). The command accepts all types of arrays
except for pointer, picture and 2D arrays.
Notes - When you pass a date, it is automatically converted to UTC text by

4D. For example, April 23, 2010 is sent as "2010-04-23T00:00:00Z".
Similarly, times are automatically converted to text in the HH:MM:SS
format. For example, 1:05 a.m. is sent as "01:05:00".
You can use a custom string if you want to change the format. In
particular, since there is no "datetime" type in the 4D language, you
can build a string representing an ISO format such as "2008-12-
10T19:12:28+02:00".
- For technical reasons, the size of parameters passed via the FastCGI
protocol must not exceed 64 KB. You need to take this limitation into
account if you use parameters of the Text type.
4D v12 Upgrade 183

Chapter 5 Language
The command returns True if the execution has been carried out
correctly on the 4D side, in other words, if the launching of the
execution environment, the opening of the script and the establishing
of the communication with the PHP interpreter were successful.
Otherwise, an error is generated, which you can intercept with the ON
ERR CALL command and analyze with GET LAST ERROR STACK.
In addition, the script itself may generate PHP errors. In this case, you
must use the PHP GET FULL RESPONSE command to analyze the source
of the error (see example 4).
Note PHP can be used to configure error management. For more

information, refer, for example, to the following page:
http://www.php.net/manual/en/errorfunc.configuration.php#ini.error-
reporting.
Using environment You can use the SET ENVIRONMENT VARIABLE command to specify the
variables environment variables used by the script. Warning: after calling
LAUNCH EXTERNAL PROCESS or PHP Execute, the set of environment
variables is erased.
Special functions 4D provides the following special functions:

quit_4d_php: quits the PHP interpreter and all its child processes. If at
least one child process is executing a script, the interpreter does not
quit and the PHP Execute command returns False.
relaunch_4d_php: relaunches the PHP interpreter.
Note that the interpreter is relaunched automatically when the first
request is sent by PHP Execute.
Examples
` Example 1: Calling the "myPhpFile.php" script without any function.
Here are the contents of the script:
<?php
echo 'Current PHP version: ' . phpversion();
?>
184 4D v12 Upgrade

PHP Execute
The following 4D code:

C_TEXT($result)
C_BOOLEAN($isOK)
$isOK:=PHP Execute("C:\\php\\myPhpFile.php"; "";$result)
ALERT ($Result)
... will display "Current PHP version: 5.3"
` Example 2: Calling the myPhpFunction function in the

"myNewScript.php" script with parameters. Here are the contents of
the script:
<?php
// . . . PHP code. . .
function myPhpFunction($p1, $p2) {
return $p1 . ' '. $p2;
}
// . . . PHP code. . .
?>
Calling with function:
C_TEXT($result)
C_TEXT($param1)
C_TEXT($param2)
C_BOOLEAN($isOk)
$param1:= "Hello"
$param2:= "4D world!"
$isOk:=PHP Execute("C:\\MyFolder\\myNewScript.php";"myPhpFunc-
tion";$result;$param1;$param2)
ALERT($result) // Displays "Hello 4D world!"
` Example 3: Quitting the PHP interpreter

$ifOk:=PHP Execute ("";"quit_4d_php")
` Example 4: Error management

// Installing the error-management method
phpCommError:="" // Modified by PHPErrorHandler
$T_saveErrorHandler:=Method called on error
ON ERR CALL("PHPErrorHandler")
4D v12 Upgrade 185

Chapter 5 Language
// Executing script
C_TEXT($T_result)
If(PHP Execute("C:\\MyScripts\\MiscInfos.php";"";$T_result))
// No error, $T_Result contains the result
Else
// An error is detected, managed by PHPErrorHandler
If(phpCommError="")
... // PHP error, use PHP GET FULL RESPONSE
Else
ALERT(phpCommError)
End if
End if
// Uninstalling method
ON ERR CALL ($T_saveErrorHandler)
The PHP_errHandler method is as follows:

phpCommError:=""
GET LAST ERROR STACK(arrCodes; arrComps; arrLabels)
For ($i;1;Size of array(arrCodes))
phpCommError:=phpCommError+arrCodes{$i}+" "+arrComps{$i}+" "+
arrLabels{$i}+Char(Carriage return)
End for
` Example 5: Dynamic creation by 4D of a script before its execution.

DOCUMENT TO BLOB("C:\\Scripts\\MyScript.php";$blobDoc)
If (OK=1)
$strDoc:=BLOB to text($blobDoc;UTF8 text without length)
$strPosition:=Position("function2Rename";$strDoc)
$strDoc:=Insert string($strDoc;"_v2";Length("function2Rename")
+$strPosition)
TEXT TO BLOB($strDoc;$blobDoc;UTF8 text without length)

BLOB TO DOCUMENT("C:\\Scripts\\MyScript.php";$blobDoc)
If (OK#1)
ALERT("Error on script creation")
End if
End if
186 4D v12 Upgrade

PHP Execute
The script is then executed:

$err:=PHP Execute("C:\\Scripts\\MyScript.php";
"function2Rename_v2";*)
` Example 6: Direct retrieval of a Date and Time type value. Here are the
contents of the script:
<?php
// . . . code php. . .
echo date(DATE_ATOM, mktime(1, 2, 3, 4, 5, 2009));
// . . . code php. . .
?>
Receiving the date on the 4D side:
C_DATE($phpResult_date)
$result:=PHP Execute("C:\php_scripts\ReturnDate.php";"";
$phpResult_date)
//$phpResult_date is !05/04/2009 !
C_TIME($phpResult_time)
$result:=PHP Execute("C:\php_scripts\ReturnDate.php";"";
$phpResult_time)
//$phpResult_time is ?01 :02 :03 ?
` Example 7: Distributing the data into arrays:

ARRAY TEXT($arText ;0)
ARRAY LONGINT($arLong ;0)
$p1:=","
$p2:= "11,22,33,44,55"
$phpok:=PHP Execute("" ;"explode";$arText;$p1;$p2)
$phpok:=PHP Execute("" ;"explode";$arLong;$p1;$p2)
// $arText contains the Alpha values "11", "22", "33", etc.

// $arLong contains the numbers, 11, 22, 33, etc.
` Example 8: Initializing an array:

ARRAY TEXT($arText ;0)
$phpok:=PHP Execute("";"array_pad";$arText;->$arText;50;"undefined")
// Execute in PHP: $arrTest = array_pad($arrTest, 50, ’undefined’);
// Fills the $arText array with 50 "undefined" elements
4D v12 Upgrade 187

Chapter 5 Language
` Example 9: Passing of parameters via an array:

ARRAY INTEGER($arInt;0)
$phpok:=PHP Execute("";"json_decode";$arInt;"[13,51,69,42,7]")
// Execute in PHP: $arInt = json_decode(’[13,51,69,42,7]’);
// Fills the array with the initial values
PHP GET FULL PHP GET FULL RESPONSE (stdOut{; errLabels; errValues}{; httpHeader-
RESPONSE Fields{; httpHeaderValues}})
stdOut Text/BLOB Å Contents of stdOut buffer
Variable
errLabels Text array Å Labels of errors
errValues Text array Å Values of errors
httpHeaderFields Text array Å Names of HTTP headers
httpHeaderValues Text array Å Values of HTTP headers
The PHP GET FULL RESPONSE command lets you obtain additional
information about the response returned by the PHP interpreter. This
command is particularly useful in the case of an error occurring during
execution of the script.
The PHP script can write data in the stdOut buffer (echo, print, etc.).
This data can be recovered in the stdOut variable.
The synchronized errLabels and errValues text arrays are filled when the
execution of the PHP scripts causes errors. These arrays provide
information in particular on the error origin, script and line. These two
arrays are inseparable: if errLabels is passed, errValues must be passed as
well.
Since exchanges between 4D and the PHP interpreter are carried out
via FastCGI, the PHP interpreter functions as if it were called by an
HTTP server and therefore sends HTTP headers. You can recover these
headers and their values in the httpHeaderFields and httpHeaderValues
arrays.
188 4D v12 Upgrade

PHP GET OPTION
PHP GET OPTION PHP GET OPTION (option; value)

option Longint Æ Option to get
value String | Å Current value of option
Boolean
The PHP GET OPTION command can be used to find out the current
value of an option relating to the execution of PHP scripts.
Pass a constant from the "PHP" theme in the option parameter to

designate the option to be gotten. The command returns the current
value of the option in the value parameter. You can pass one of the
following constants:
PHP Privileges: returns the current user account (password is not
returned).
PHP Raw result: returns processing mode of HTTP headers.
For more information about these options, refer to the description of

the PHP SET OPTION command.
` We want to find out the current user account:

C_TEXT($userAccount)
C_BLOB($isOK)
$isOK:=PHP GET OPTION (PHP Privileges;$userAccount)
If($isOK)
ALERT($userAccount)
End if
See Also: PHP SET OPTION
PHP SET OPTION PHP SET OPTION (option; value{; *})

option Longint Æ Option to be set
value String | Æ New value of option
Boolean
* * Æ If passed: modification only applied to
next call
The PHP SET OPTION command sets specific options before calling the
PHP Execute command. The scope of this command is the current
process.
4D v12 Upgrade 189

Chapter 5 Language
Pass a constant from the "PHP" theme in the option parameter to

designate the option to be modified and pass the new value for the
option in the value parameter. Here is a description of the options:
Option Description Value(s)
PHP Privileges Definition of specific user privi-String in the form
leges relating to the execution of"User:Password".
the script For example:
"root:jd51254d"
PHP Raw result Definition of processing mode for Boolean
HTTP headers returned by PHP in False (default
the execution result when this value): remove
result is of the Text type (when HTTP headers from
the result is of the BLOB type, result.
headers are always kept). True: keep HTTP
headers
By default, PHP SET OPTION sets the option for all subsequent calls to
PHP Execute of the process. If you want to set it for the next call only,
pass the star (*) parameter.
` Execute the "myAdminScript.php" script with Admin access rights:

PHP SET OPTION(PHP Privileges; "admin:mypwd"; *)
`Since we pass the *, the admin privileges will only be used once
C_TEXT($result)
C_BOOLEAN($isOK)
$isOK:=PHP Execute("myAdminScript.php";$result)
If($isOK)
ALERT($result)
End if
See Also: PHP GET OPTION
Pictures
This theme contains several new commands used to test picture files (Is
picture file) and work with metadata (SET PICTURE METADATA and GET
PICTURE METADATA). The CONVERT PICTURE and PICTURE CODEC LIST
commands accept additional parameters and three obsolete commands
have been renamed.
190 4D v12 Upgrade

Pictures
New APIs for 4D v12 uses new native APIs to encode and decode pictures (fields and
encoding and variables) under Windows and Mac OS. These implementations
decoding pictures provide access to additional native formats, including the RAW format,
which is currently used for digital cameras.
Under Windows, 4D now uses WIC (Windows Imaging Component).
WIC natively supports the following formats: BMP, PNG, ICO
(decoding only), JPEG, GIF, TIFF and WDP (Microsoft Windows Digital
Photo).
It is possible to use additional formats such as JPEG-2000 by installing
third-party WIC codecs.
Under Mac OS, 4D now uses ImageIO. All the available ImageIO codecs
are therefore supported natively for decoding (reading) as well as
encoding (writing):
Decoding Encoding
public.jpeg public.jpeg
com.compuserve.gif com.compuserve.gif
public.png public.png
public.jpeg-2000 public.jpeg-2000
com.nikon.raw-image public.tiff
com.pentax.raw-image com.adobe.photoshop.image
com.sony.arw-raw-image com.adobe.pdf
com.adobe.raw-image com.microsoft.bmp
public.tiff com.canon.crw-raw-image com.truevision.tga-image
com.canon.cr2-raw-image com.sgi.sgi-image
com.canon.tif-raw-image com.apple.pict
com.sony.raw.image com.ilm.openexr-image
com.olympus.raw-image
com.konicaminolta.raw-image
com.panasonic.raw-image
com.fuji.raw-image
com.adobe.photoshop-image
com.adobe.illustrator.ai-image
com.adobe.pdf
com.microsoft.ico
com.microsoft.bmp
com.truevision.tga-image
com.sgi.sgi-image
com.apple.quicktime-image
com.apple.icns
com.apple.pict
4D v12 Upgrade 191

Chapter 5 Language
com.apple.macpaint-image
com.kodak.flashpix-image
public.xbitmap-image
com.ilm.openexr-image
public.radiance
Under Windows as under Mac OS, the formats supported will vary
according to the operating system and the custom Codecs installed on
the machines. To find out which Codecs are available, you will need to
use the PICTURE CODEC LIST command.
Note that WIC and ImageIO allow the use of metadata in pictures. Two
new commands, SET PICTURE METADATA and GET PICTURE METADATA
have been added so that you can benefit from metadata in your
development projects.
CONVERT PICTURE CONVERT PICTURE (picture; codec{; compression})

picture Picture Æ Picture to be converted
Å Converted picture
codec String Æ Picture Codec ID
compression Real Æ Quality of compression
The CONVERT PICTURE command accepts a new optional compression

parameter that specifies the compression quality to be applied to the
resulting picture when a compatible Codec is used.
Pass a value between 0 and 1 in compression to specify the quality of the

compression, where 0 is the most mediocre quality (high compression)
and 1 the best quality (low compression). This parameter is only taken
into account when the Codec supports compression (for example JPEG
or HDPhoto) and is supported by the WIC and ImageIO APIs.
Consequently, it cannot be used with Codecs that are managed by
QuickTime only.
Note For more information about picture management APIs in 4D v12, refer
to the “New APIs for encoding and decoding pictures” paragraph on
page 191.
By default, if you omit this parameter, the best quality is applied

(compression =1).
192 4D v12 Upgrade

GET PICTURE METADATA
` Conversion of a picture with 60% quality:

CONVERT PICTURE (vPicture;".JPG";0.6)
GET PICTURE GET PICTURE METADATA (picture; metaName1; contents1{ ;...; metaNa-
METADATA meN; contentsN})
picture Picture Æ Picture whose metadata you want to
get
metaName1...N Text Æ Name or path of block to get
contents1...N Variable Å Metadata contents
The new GET PICTURE METADATA command reads the contents of the
metadata (or meta-tags) found in picture (4D picture field or variable).
For more information about metadata, refer to the description of the
SET PICTURE METADATA command.
In the metaName parameter, pass a string specifying the type of

metadata to retrieve. You can pass:
a constant from the new "Picture metadata names" theme,
containing a tag path,
the name of a complete block of metadata ("TIFF", "EXIF", "GPS" or
"IPTC"),
an empty string ("").
Pass the variable intended to receive the metadata in the contents

parameter:
If you passed a tag path in metaName, the contents parameter will
directly contain the value to get. The value will be converted to the
type of the variable. Variables of the Text type will be formatted in
XML (XMP standard). Pass an empty string ("") to erase any existing
metadata. You can pass an array when the metadata contains more
than one value (this is the case, more particularly, for the IPTC
Keywords tags.
4D v12 Upgrade 193

Chapter 5 Language
If you passed a block name or an empty string in metaName, the

contents parameter must be a valid XML DOM element reference. In
this case, the contents of the designated block (or all the blocks if
you passed an empty string in metaName) is recopied into the
element referenced.
Note Since they are numerous, the constants of the new "Picture metadata
names" and "Picture metadata values" themes are described in the
appendix C, “Metadata Constants,” on page 337.
The OK system variable returns 1 if the retrieval of the metadata has

proceeded correctly and 0 if an error occurs or if at least one of the tags
is not found. In all cases, the any values that can be read are returned.
` Using DOM tree structures:

$xml:=DOM Create XML Ref ("Root") \\Creation of an XML DOM tree
\\Reception of TIFF metadata

$_Xml_TIFF:=DOM Create XML element ($xml;"/Root/TIFF")
GET PICTURE METADATA(vPicture;"TIFF";$_Xml_TIFF)
\\Reception of GPS metadata

$_Xml_GPS:=DOM Create XML element($xml;"/Root/GPS")
GET PICTURE METADATA(vPicture;"GPS";$_Xml_GPS)
` Using variables:
C_DATE($dateAsDate)
GET PICTURE METADATA("TIFF/DateTime";$dateAsDate)
//only returns the date since $dateAsDate is of the Date type
C_TEXT($dateAsText)
GET PICTURE METADATA("TIFF/DateTime";$dateAsText)
//only returns the date but in XML format
C_INTEGER($urgency)
GET PICTURE METADATA(vPicture;"IPTC/Urgency";$urgency)
194 4D v12 Upgrade

Is picture file
` Reception of tags with multiple values in arrays:

ARRAY TEXT($tTkeywords;0)
GET PICTURE METADATA(vPicture;"IPTC/Keywords";$tTkeywords)
After execution of the command, arrTkeywords contains for example:

$arrTkeywords{1} = "France"
$arrTkeywords{2} = "Europe"
` Reception of tags with multiple values in a Text variable:

C_TEXT($vTwords;0)
GET PICTURE METADATA(vPicture;"IPTC/Keywords";$vTwords)
After execution of the command, vTwords contains for example

"France;Europe".
See Also: SET PICTURE METADATA
Is picture file Is picture file (filePath{;* })Æ Boolean

filePath Texte Æ File pathname
* * Æ Validate data
Function result Boolean Å True = filePath designates a picture

file; otherwise, False
The new Is picture file command tests the file designated by the filePath
parameter and returns True if it is a valid picture file. The command
returns False if the file is not of the picture type or if it is not found.
Pass the pathname of the picture file to be tested in the filePath

parameter. The path must be expressed with the system syntax. You
can pass an absolute pathname or a pathname relative to the database
structure file. If you pass an empty string (""), the command returns
False.
4D v12 Upgrade 195

Chapter 5 Language
If you do not pass the * parameter, the command tests the file by
looking for its extension among the list of available codecs. If you want
to be able to test files without extensions or to carry out a more
thorough verification, pass the * parameter. In this case, the command
makes additional tests: it loads and inspects the file header and queries
the codecs in order to validate the picture. This syntax slows command
execution.
Note The command returns True for PDF files under Windows and EMF files
under Mac OS.
PICTURE CODEC PICTURE CODEC LIST (codecArray{; namesArray}{; *})

LIST Parameter Type Description
codecArray String array Å IDs of available picture Codecs
namesArray String array Å Names of picture Codecs
* * Æ Return list of reading (decoding) Codecs
The PICTURE CODEC LIST command now allows you to recover the list
of Codecs used to decode (read) pictures. To do this, simply pass the
new optional * parameter. By default, when this parameter is omitted,
the command returns the Codecs that can be used to encode (write)
pictures.
The two lists are not exclusive, certain reading and writing Codecs are
identical. Codecs intended for encoding pictures may usually be used
for decoding. On the other hand, decoding Codecs cannot necessarily
be used for encoding. For example, the ".jpg" Codec will be found in
both lists, whereas the ".xbmp" Codec will only be found in the list of
reading (decoding) Codecs.
196 4D v12 Upgrade

SET PICTURE METADATA
SET PICTURE SET PICTURE METADATA (picture; metaName1; contents1{ ;...; metaNa-
METADATA meN; contentsN})
picture Picture Æ Picture whose metadata you want to
set
metaName1...N Text Æ Name or path of block to set
contents1...N Variable Æ Metadata contents
The new SET PICTURE METADATA command sets or modifies the

contents of the metadata (or meta-tags) found in the picture (4D
picture field or variable).
Metadata are additional information inserted into pictures. 4D lets you

handle four types of standard metadata: EXIF, GPS, IPTC and TIFF.
Note For a detailed description of these metadata types, you can consult the
following documents:
http://www.iptc.org/std/IIM/4.1/specification/IIMV4.1.pdf (IPTC) and
http://exif.org/Exif2-2.PDF (TIFF, EXIF and GPS).
In the metaName parameter, pass a string specifying the type of

metadata to set or modify. You can pass:
one of the constants from the new "Picture metadata names" theme.
This theme groups together all the tags supported by 4D. Each
constant contains a tag path (for example, "TIFF/DateTime"),
the name of a complete block of metadata ("TIFF", "EXIF", "GPS" or
"IPTC"),
an empty string ("").
Pass the new values of the metadata in the contents parameter:

If you passed a tag path constant in metaName, in the contents
parameter you can pass the value to set directly or one of the
appropriate constants from the new "Picture metadata values"
theme. The value can be of the Text, Longint, Real, Date or Time
type, according to the metadata specified. You can use an array if
the metadata contains more than one value. If you pass a string, it
must be formatted in XML (XMP standard). You can pass an empty
string ("") to erase any existing metadata.
4D v12 Upgrade 197

Chapter 5 Language
If you passed a block name or an empty string in metaName, in the

contents parameter you can pass the XML DOM reference of the
element containing the metadata to set. In the case of an empty
string, all the metadata will be modified.
Note Since they are numerous, the constants of the new "Picture metadata
names" and "Picture metadata values" themes are described in
appendix C, “Metadata Constants,” on page 337.
Under Windows, if an error occurs during command execution, the OK

variable is set to 0.
Note that under Mac OS, for technical reasons, metadata writing errors
are not detected. Therefore this command does not modify the OK
variable under Mac OS.
` Setting several values of the "Keywords" metadata via arrays:

ARRAY TEXT($arrTkeywords;2)
$arrTkeywords{1}:="France"
$arrTkeywords{2}:="Europe"
SET PICTURE METADATA(vPicture;"IPTC Keywords";$arrTkeywords)
` Setting of GPS block via a DOM reference:

C_TEXT($domMetas)
$domMetas:=DOM Parse XML source("metas.xml")
C_TEXT($gpsRef)
$gpsRef:=DOM Find XML element ($domMetas;"Metadatas/GPS")
If (OK=1)
SET PICTURE METADATA(vImage;"GPS";$refGPS)
//here $gpsRef actually points to the GPS element
...
End if
DOM CLOSE XML($domMetas)
Note When all the metadata are handled via a DOM element reference, the
tags are stored as attributes attached to an element (a child of the
referenced element) whose name is the block name (TIFF, IPTC, etc.).
When a specific metadata block is manipulated, the block tags are
stored as attributes that are directly attached to the element referenced
by the command.
See Also: GET PICTURE METADATA
198 4D v12 Upgrade

WRITE PICTURE FILE
WRITE PICTURE FILE WRITE PICTURE FILE (fileName ; picture {; codec})

The functioning of the WRITE PICTURE FILE command has been
modified to facilitate the handling and storage of pictures in native
format.
From now on, if you omit the codec parameter, the command will
attempt to determine the codec based on the extension of the file
name passed in the fileName parameter. For example, if you pass the
statement:
WRITE PICTURE FILE ("c:\folder\photo.jpg";myphoto)
... the command will use the JPEG codec to store the picture.
If the extension used does not correspond to any available codec, the
file is not saved and the OK system variable is set to 0. If you do not
pass a codec or a file extension, the picture file is saved in PICT format.
Renamed In 4D v12, three command of the "Pictures" theme have been prefixed
commands with "QT" to indicate that they are based on the Apple QuickTime
extension and are obsolete:
QT COMPRESS PICTURE COMPRESS PICTURE
QT LOAD COMPRESS PICTURE FROM LOAD COMPRESS PICTURE FROM
FILE FILE
QT COMPRESS PICTURE FILE COMPRESS PICTURE FILE
These command must no longer be used in 4D v12. They are kept for
compatibility reasons only.
Printing
The printing function has been strengthened along two main lines in
4D v12:
For more customization, the new OPEN PRINTING FORM and Print
object command complete the set of tools that manage the printing of
form objects,
The integration of the OpenSource PDFCreator driver and its support
via the SET PRINT OPTION and GET PRINT OPTION commands
facilitates the PDF printing under Windows.
4D v12 Upgrade 199

Chapter 5 Language
OPEN PRINTING OPEN PRINTING FORM(form)

FORM Parameter Type Description
form String Æ Name of project form to open for prin-
ting or
Empty string to close current project
form
The new OPEN PRINTING FORM command loads the project form form
for printing. Once loaded, this form becomes the current printing
form. All the object management commands, and in particular the
new Print object command, work with this form.
If a printing form has already been loaded beforehand (via a previous

call to the OPEN PRINTING FORM command), it is closed and replaced
by form. You can open and close several project forms in the same print
session. Changing the printing form via the OPEN PRINTING FORM
command does not generate page breaks. It is up to the developer to
manage page breaks. If you pass an empty string in form, the current
printing project form is closed.
Only the "On Load" form event is executed during the opening of the
project form. The other form events are ignored. The "On Unload"
form event is executed at the end of printing.
To preserve the graphic consistency of forms, it is recommended to

apply the "Printing" appearance property regardless of the platform.
The current printing form is automatically closed when the CLOSE

PRINTING JOB command is called.
See Also: Print object
200 4D v12 Upgrade

Print object
Print object Print object({*;}object{;posX{;posY{;width{;height}}}}) Æ Boolean

(string)
posX Longint Æ Horizontal location of object
posY Longint Æ Vertical location of object
width Longint Æ Width of object (pixels)
height Longint Æ Height of object (pixels)
Function result Boolean Å True = object entirely printed; other-

wise False
The new Print object command prints the form object(s) designated by
the object and * parameters, at the location set by the posX and posY
parameters.
The Print object command can only print project form objects. Before
calling this command, you must designate the project form containing
the objects to be printed using the new OPEN PRINTING FORM
command.
parameter is an object name (character string). If you do not pass the *
parameter, you indicate that object is a variable. In this case, you pass a
variable reference (object type only) instead of a string.
The posX and posY parameters specify the starting point for printing
the object(s). These values must be expressed in pixels. If these
parameters are omitted, the object will be printed according to its
location in the form.
The width and height parameters specify the width and height of the
form object. The Print object command does not manage objects of
variable size. You must use the OBJECT GET BEST SIZE command to
manage the size of objects. You can also use the OBJECT GET BEST SIZE
command to find out the most appropriate size for objects containing
text. Similarly, Print object will not cause automatic page breaks. You
must manage them according to your needs.
4D v12 Upgrade 201

Chapter 5 Language
You can use 4D commands to modify object properties (color, size,

etc.) on the fly.
The command returns True if the object has been completely printed
and False if this is not the case, in other words if it was not able to print
all the data associated with the object within the set framework.
Typically, the command returns False when printing a list box if all the
rows of the list box could not be printed. In this case, you can simply
call the Print object command repeatedly until it returns True: a specific
mechanism automatically causes the contents of the object to scroll
after each call.
Notes - In the current version of 4D v12, only list box type objects have this
mechanism (the command always returns True for any other type of
object). In forthcoming versions of 4D, this functioning will be
extended to other objects with variable contents.
- The LISTBOX GET PRINT INFORMATION command lets you check the
status of the printing during the operation. For more information, refer
to the “Printing list boxes” paragraph on page 116.
The Print object command can only be used in the context of a print
job opened beforehand with the OPEN PRINTING JOB command. If it is
not called in this context, the command does nothing. Several Print
object commands can be called in the same print job.
Note Hierarchical lists and Web areas cannot be printed.
` Example for printing ten objects in a form:

PRINT SETTINGS
If (OK=1)
OPEN PRINTING JOB
If (OK=1)
OPEN PRINTING FORM("PrintForm")
x:=100
y:=50
GET PRINTABLE AREA(hpaper;wpaper)
202 4D v12 Upgrade

Print object
For ($i;1;10)
OBJECT GET BEST SIZE(*;"Obj"+String($i);bestwidth;bestheight)
$end:=Print object(*;"Obj"+String($i))
y:=y+bestheight+15
If (y>hpaper)
PAGE BREAK(>)
y:=50
End if
End for
End if
CLOSE PRINTING JOB
End if
` Example of printing a complete list box:

Repeat
$end:=Print object(*;"mylistbox")
Until ($end)
See Also: OPEN PRINTING FORM
Integration of The support of PDF printing under Windows has been extended in 4D
PDFCreator driver v12. The program relies on the PDFCreator driver to offer simple and
under Windows functional PDF printing functions. The SET PRINT OPTION and GET
PRINT OPTION commands have been modified to be able to use this
driver.
PDFCreator is a free driver (OpenSource) governed by the AFPL

(Aladdin Free Public License). For more information about this license,
refer to the following address: http://en.pdfforge.org/content/license
Note Under Mac OS, PDF printing is supported natively by the system.
To use the PDFCreator driver, you must download the appropriate

version and install it in your environment. (It is not installed by
default by 4D.) Note that the PDFCreator driver version certified for 4D
v12 is version 0.9.9. You can download this version, for example, at the
following location: http://filehippo.com/download_pdfcreator/6821/
You must have Administrator access rights in order to install the driver.
During installation, a new virtual printer named "PDFCreator" by

default is installed in your system. You can change this name if desired.
4D v12 Upgrade 203

Chapter 5 Language
GET PRINT OPTION GET PRINT OPTION (option; value1{; value2})

option Longint | String Æ Option number or PDF
option code
value1 Longint | String Å Value 1 of the option
value2 Longint Å Value 2 of the option
The GET PRINT OPTION command now accepts a string in the option
parameter. This modification allows the command to manage the
PDFCreator driver options. For more information about this new
features, refer to the description of the SET PRINT OPTION command.
SET CURRENT SET CURRENT PRINTER (printerName)

PRINTER
The SET CURRENT PRINTER command designates the virtual printer
installed by the PDFCreator driver as the printing destination. 4D v12
relies on the PDFCreator driver to facilitate the printing of PDF
documents under Windows (see the “Integration of PDFCreator driver
under Windows” paragraph on page 203).
To print a PDF document, in the printerName parameter, pass the name

of the virtual printer that was installed by the PDFCreator driver.
By default, the name of the virtual printer is "PDFCreator". However,

this name may have been modified when the driver was installed. In
order for 4D to automatically look for and use the name of the virtual
printer, even if it has been customized, pass the new PDFCreator Printer
name constant in printerName. This constant is found in the "Print
options" theme.
204 4D v12 Upgrade

SET PRINT OPTION
SET PRINT OPTION SET PRINT OPTION (option; value1{; value2})

option Longint | String Æ Option number or PDF option
code
value1 Longint | String Æ Value 1 of the option
value2 Longint | String Æ Value 2 of the option
The SET PRINT OPTION command has been modified so as to take

advantage of the PDFCreator driver under Windows. In order to use
these new features, you must have installed this driver in your 4D
environment (for more information, refer to the “Integration of
PDFCreator driver under Windows” paragraph on page 203).
The option parameter now accepts a Text type value in which you can
pass a PDF option code. The option code consists of two parts:
OptionType and OptionName, combined as "OptionType:OptionName".
Here is the description of this code:
OptionType: Indicates whether you are specifying a native PDFCreator
option or a 4D PDF administration option. Two values are accepted:
PDFOptions = native option
PDFInfo = internal option.
OptionName: Specifies the option to be set (depending on the
OptionType value).
If OptionType = PDFOptions, you can pass one of several PDFCreator
native options in OptionName. For example, the UseAutosave
option affects the automatic backup. To be able to modify this
option, pass "PDFOptions:UseAutosave" in the option parameter and
the value to be used in the value1 parameter. For a complete
description of the PDFCreator native options, refer to the
documentation provided with the PDFCreator driver.
If OptionType = PDFInfo, you can pass one of the following specific
selectors in OptionName:
- Reset print: resets the internal waiting status in order, more
particularly, to exit from an infinite loop.
In this case, value1 is not used.
- Reset standard options: resets all the PDFCreator options to their
default values. If printing is in progress, the default settings are
applied after its completion. In this case, value1 is not used.
4D v12 Upgrade 205

Chapter 5 Language
- Start: starts or stops the PDFCreator spooler. Pass 0 in value1 to

stop it and 1 to start it.
- Reset options: resets all the options modified since the beginning
of the session using the SET PRINT OPTION command and the
PDFOptions selector.
- Version: reads the current version number of the PDFCreator
driver. This selector can only be used with the GET PRINT OPTION
command. The number is returned in the value1 parameter.
- Last error: reads the last error returned by the PDFCreator driver.
This selector can only be used with the GET PRINT OPTION
command. The error number is returned in the value1 parameter.
- Print in progress: finds out if 4D is waiting for printing by
PDFCreator. This selector can only be used with the GET PRINT
OPTION command. The value1 parameter returns 1 if 4D is waiting
for PDFCreator and 0 otherwise.
- Job count: finds out the number of jobs waiting in the printing
queue. This selector can only be used with the GET PRINT OPTION
command. The number of jobs is returned in the value1 parameter.
- Synchronous Mode: sets the synchronization mode between
printing requests sent by 4D and the PDFCreator driver. Since 4D
cannot get information about the current status of a print job that
is in the printing queue, this option can be used to better control
the execution of the jobs by only sending them when the status of
the PDFCreator driver is "free". In this case, 4D is synchronized with
the driver. Pass 0 in value1 for 4D to send print requests
immediately (default value) and 1 in order for 4D to be
synchronized and to wait for the driver to have finished the job in
progress before sending another one.
Note After each printing, 4D automatically re-establishes the previous

settings of the PDFCreator driver to avoid any interference with other
programs using PDFCreator.
206 4D v12 Upgrade

SQL
` The following method configures the PDF driver to print all the
records of the table in the C:\test\Test_PDF_X file where X is the
sequence number of the record:
SET CURRENT PRINTER(PDFCreator Printer name)
// Use the virtual printer installed by PDFCreator
SET PRINT OPTION ("PDFOptions:UseAutosave";1)
SET PRINT OPTION("PDFOptions:UseAutosaveDirectory";1)
SET PRINT OPTION("PDFOptions:AutosaveDirectory";"C:\\test\\")
ALL RECORDS([Table_1])
For ($i;1;Records in selection([Table_1]))
SET PRINT OPTION("PDFOptions:AutosaveFilename";
"Test_PDF_"+String($i))
PRINT RECORD([Table_1];*)
NEXT RECORD([Table_1])
End for
SET PRINT OPTION("PDFInfo:Reset standard options";0)
// Resetting the PDFCreator driver options
SQL
Three new SQL commands can be used to export the data of the 4D
database and to execute SQL scripts.
Note that the new features relating to the SQL engine of 4D are
described in Chapter 6, “SQL,” on page 295.
4D v12 Upgrade 207

Chapter 5 Language
SQL EXECUTE SQL EXECUTE SCRIPT(scriptPath; errorAction{; attrName1; attrValue1;...;

SCRIPT attrNameN; attrValueN})
scriptPath String Æ Complete pathname of file containing
SQL script to execute
errorAction Longint Æ Action to carry out in case of error
during script execution
attrName1...N String Æ Name of attribute to use
attrValue1...N String Æ Value of attribute
The new SQL EXECUTE SCRIPT command executes a series of SQL

statements placed in the script file designated by scriptPath. SQL
EXECUTE SCRIPT can only be executed on a local machine (local 4D or
stored procedure on 4D Server).
Note This command cannot be used with an external connection that is

opened directly or via ODBC.
Pass the complete pathname of the text file containing the SQL
statements to be executed in the scriptPath parameter. The pathname
must be expressed using the syntax of the current system. If you pass
an empty string ("") in scriptPath, a standard Open document dialog
box appears and the user can select the script file to be executed.
Note The new SQL EXPORT DATABASE and SQL EXPORT SELECTION
commands automatically generate this script file.
The errorAction parameter configures the functioning of the command

when an error occurs during script execution. You can pass one of the
three following constants, placed in the "SQL" theme:
Constant Type Value
SQL On error abort Longint 1
SQL On error confirm Longint 2
SQL On error continue Longint 3
SQL On error abort: in the event of an error, 4D immediately stops
script execution.
SQL On error confirm: in the event of an error, 4D displays a dialog box
describing the error and allowing the user to interrupt or continue
script execution.
208 4D v12 Upgrade

SQL EXECUTE SCRIPT
SQL On error continue: in the event of an error, 4D ignores it and

continues script execution.
The attrName and attrValue parameters must be passed in pairs. These

parameters are intended to specify specific attributes for the script
execution. In the current version of 4D, a single attribute can be passed
in attrName, available via the following constant, placed in the "SQL"
theme:
Constant Type Value
SQL Use Access Rights String SQL_Use_Access_Rights
SQL Use Access Rights: restricts the access rights to be applied during
execution of the SQL commands of the script. When you use this
attribute, you must pass 0 or 1 in attrValue:
attrValue = 1: 4D uses the access rights of the current 4D user.
attrValue = 0 (or attribute not specified): 4D does not restrict access,
the Designer rights are used.
If the 4D log file is activated (via the selectors 28 or 45 of the SET

DATABASE PARAMETER command), each SQL command executed will
generate an entry with the following information:
Type of SQL command
Number of records affected by the command
Duration of command execution
For each error encountered:
- The error code
- The error text if available.
If the script is executed correctly (no error occurs), the OK system

variable is set to 1.
In the event of an error, the OK system variable is set to 0 or not
according to the errorAction parameter:
If errorAction is "SQL On error abort" (value 1), OK is set to 0.
If errorAction is "SQL On error confirm" (value 2), the OK variable is
set to 0 if the user chooses to stop the operation and 1 if they
choose to continue.
4D v12 Upgrade 209

Chapter 5 Language
If errorAction is "SQL On error continue" (value 3), the OK variable is

always 1.
Note If you use this command to execute memory-consuming actions such

as massive data imports, you can consider calling the new SQL ALTER
DATABASE command to temporarily disable the SQL options.
SQL EXPORT SQL EXPORT DATABASE(folderPath{; numFiles{; fileLimitSize}})

DATABASE Parameter Type Description
folderPath String Æ Pathname of export folder or "" to dis-
play folder selection dialog box
numFiles Number Æ Maximum number of files per folder
fileLimitSize Number Æ Size limit value of export files (in KB)
The new SQL EXPORT DATABASE command exports in SQL format all
the records of all the tables in the open database. In SQL, this global
export operation is called "Dump".
Note This command cannot be used with an external connection that has
been opened directly or via ODBC.
The command generates a text file containing the SQL statements

needed for importing data into another database. This file can be used
directly by the new SQL EXECUTE SCRIPT to import data into another
4D database.
The export files will be placed in a folder named "SQLExport" that is

created in the destination folder designated by the folderPath
parameter. Note that if an "SQLExport" folder already exists at the
location specified, the command will replace it without any warning
message being shown.
If you pass an empty string in this parameter, 4D displays a standard
dialog box which lets the user designate the destination folder. By
default, the dialog box displays the current folder of the user that
opened the session ("My Documents" under Windows or "Documents"
under Mac OS).
For each exported table, the command carries out the following
actions:
A subfolder with the table name is created in the destination folder.
210 4D v12 Upgrade

SQL EXPORT DATABASE
A text file named "Export.sql" is created in the subfolder. This file is

encoded in UTF-8 with a BOM (byte-order mark).
It contains SQL INSERT orders corresponding to the exported data.
The field values are separated by colons. There may be fewer values
than there are fields in the table. In this case, the remaining fields
are considered NULL.
If the table contains BLOB, picture or text fields (texts stored
externally, in other words, outside of records), an additional
subfolder named "BLOBS" is created next to the "Export.sql" file.
Inside this subfolder are created as many subfolders named
"BlobsX” as necessary. These subfolders will store as separate files
the contents of all the BLOB, picture or external text fields of the
table records. The BLOB files are named "BlobXXXXX.BLOB" (where
XXXXX is a unique number generated by the application). The
picture files are named PICTXXXXX.ZZZZ (where XXXXX is a
unique number generated by the application and ZZZZ is the
extension). When possible, pictures are exported in their original
native format with the extension corresponding to the picture type
(.jpg, .png, etc.). If the export is not possible in the native format,
the pictures are exported in the internal 4D format 4D with the
.4PCT extension.
If you pass the numFiles parameter, the command will create as many
"BlobsX" subfolders as necessary so that each one of them does not
contain more than numFiles BLOB, picture or external text files. By
default, if the numFiles parameter is omitted, the command limits the
number of files to 200. If you pass 0, each subfolder will contain at
least one file.
The fileLimitSize parameter sets a size limit (in bytes) for each
"Export.sql" created on disk. Once the size of the export file being
created reaches the value set in fileLimitSize, 4D stops writing records,
closes the file and creates a new file named "ExportX.sql" (where X
represents the sequence number) next to the previous one. Note that
with this mechanism, the actual size of the "ExportX.sql" files exceeds
the value set by fileLimitSize because the file is only closed after the
record that was being exported when the limit was reached has been
completely written. The minimum size accepted is 100 KB and the
maximum size is 10 MB.
4D v12 Upgrade 211

Chapter 5 Language
In the export file, there may be fewer values than there are fields in the
table. In this case, the empty fields will be considered as NULL. You
can also pass the NULL value in a field.
If the export has been carried out correctly, the OK variable is set to 1.
See Also: SQL EXPORT SELECTION
SQL EXPORT SQL EXPORT SELECTION(aTable; folderPath{; numFiles{; fileLimitSize}})

SELECTION Parameter Type Description
aTable Table Æ Table from which to export selection
folderPath String Æ Pathname of export folder or "" to dis-
play folder selection dialog box
numFiles Number Æ Maximum number of files per folder
fileLimitSize Number Æ Size limit value of export files (in KB)
The new SQL EXPORT SELECTION command exports in SQL format the
records of the current selection of the 4D table designated by the
aTable parameter.
Note This command cannot be used with an external connection that has
been opened directly or via ODBC.
This command is nearly identical to the SQL EXPORT DATABASE

command. The main difference between these two commands is that
SQL EXPORT SELECTION only exports the current selection of aTable
whereas SQL EXPORT DATABASE exports the entire database. Also,
unlike the SQL EXPORT DATABASE command, the SQL EXPORT
SELECTION command does not work with external SQL databases (see
the “Using external databases” paragraph on page 306). It can only be
used with the main database.
Refer to the description of the SQL EXPORT DATABASE command for a

detailed description of the functioning and parameters of these
commands.
If the current selection is empty, the command does nothing. Note

that in this case, the destination folder is not emptied.
If the export is carried out correctly, the OK variable is set to 1.
See Also: SQL EXPORT DATABASE
212 4D v12 Upgrade

String
String
Convert to text Convert to text(BLOB ; charSet) Æ Text
The Convert to text command now supports BOMs (Byte Order Marks).
If the character set specified is of the Unicode type (UTF-8, UTF-16 or

UTF-32), 4D attempts to identify a BOM among the first bytes received.
If it is detected, it is filtered out of the result and 4D uses the character
set that it defines instead of the one specified.
Structure Access
Two new utility commands have been added to this theme, which
allow the recovery of any "phantom" data of the database.
GET MISSING TABLE GET MISSING TABLE NAMES(missingTables)

NAMES Parameter Type Description
missingTables Text array Å Names of missing tables in the data-
base
The new GET MISSING TABLE NAMES command returns the names of
all the missing tables of the current database in the missingTables array.
Missing tables are tables whose data are present in the data file but that
do not exist at the level of the current structure. This can happen when
a data file is opened with different versions of the structure.
Typically, the scenario is as follows:

The developer provides a structure containing tables A, B and C,
The user adds the custom tables D and E, using, for example, the
integrated SQL commands of 4D, and stores data in these tables,
The developer provides a new version of the structure. It does not
contain tables D and E.
In this case, the user version of the database still contains data from
tables D and E, but it cannot be accessed. The GET MISSING TABLE
NAMES command will return the names "D" and "E".
4D v12 Upgrade 213

Chapter 5 Language
Once you have identified the missing tables of the database, you can
reactivate them via the new REGENERATE MISSING TABLE command.
Note The data of missing tables are erased when the data file is compacted
(if the tables have not been regenerated).
REGENERATE REGENERATE MISSING TABLE (tableName)

MISSING TABLE Parameter Type Description
tableName Text Æ Name of missing table to be regene-
rated
The new REGENERATE MISSING TABLE command rebuilds the missing

table whose name is passed in the tableName parameter. When a
missing table is rebuilt, it becomes visible in the Structure editor and
its data can once again be accessed.
Missing tables are tables whose data are present in the data file but that
do not exist at the structure level. You can identify any missing tables
that may be present in the application by using the new GET MISSING
TABLE NAMES command.
If the table designated by the tableName parameter is not a missing

table of the database, the command does nothing.
` This method regenerates all the missing tables that may be present in
the database:
ARRAY TEXT($arrMissingTables;0)
GET MISSING TABLE NAMES($arrMissingTables)
$SizeArray:=Size of array($arrMissingTables)
If ($SizeArray#0)
// Fills the array with the names of all the tables in the database
ARRAY TEXT(arrTables;Get last table number)
If (Get last table number>0) //If there are actually tables
For ($vlTables;Size of array(arrTables);1;-1)
If (Is table number valid($vlTables))
arrTables{$vlTables}:=Table name($vlTables)
Else
DELETE FROM ARRAY(arrTables;$vlTables)
End if
End for
End if
214 4D v12 Upgrade

SVG
For ($i;1;$SizeArray)
If (Find in array(arrTables;$arrMissingTables{$i})=-1)
CONFIRM("Regenerate the table"+$arrMissingTables{$i}+"?")
If (OK=1)
REGENERATE MISSING TABLE($arrMissingTables{$i})
End if
Else
ALERT("Impossible to regenerate table "+$arrMissingTables{$i}+
" because there is already a table with this name in the database.")
End if
End for
Else
ALERT("No tables to regenerate.")
End if
See Also: GET MISSING TABLE NAMES
SVG
The new "SVG" theme groups together all the SVG commands of 4D
v12. In previous versions of 4D, these commands were placed in the
"XML Utilities" theme.
Four new SVG commands make their appearance in 4D v12: SVG SET
ATTRIBUTE, SVG GET ATTRIBUTE, SVG Find element ID by rect, SVG SHOW
ELEMENT.
Note on the SVG The SVG rendering engine has been updated in 4D v12. In addition to
rendering engine the new commands described below, many new elements and
attributes of elements are now supported, such as "pattern" or
"CoreText". The SVG component of 4D takes advantage of these new
features.
4D v12 Upgrade 215

Chapter 5 Language
SVG Find element ID SVG Find element ID by rect ({*; }pictureObject; x; y; width; height; arrIDs)
by rect Æ Boolean
* * Æ If specified, pictureObject is an
object name (string)
If omitted, pictureObject is a varia-
ble
pictureObject Picture Æ Object name (if * specified) or
Field or variable (if * omitted)
x Longint Æ Horizontal coordinate of top left
corner of selection rectangle
y Longint Æ Vertical coordinate of top left cor-
ner of selection rectangle
width Longint Æ Width of selection rectangle
height Longint Æ Height of selection rectangle
arrIDs String array Å IDs of elements whose bounding
rectangle intersects with the selec-
tion rectangle
Function result Boolean Å True = at least one element is found
The new SVG Find element ID by rect command fills the Text or Alpha
arrIDs array with the IDs ("id" or "xml:id" attribute) of the XML
elements whose bounding rectangle intersects with the selection
rectangle at the location specified by the x and y parameters.
The command returns True if at least one element is found (in other
words if the arrIDs array is not empty), and False otherwise.
This command can be used in particular to manage interactive graphic

interfaces.
If you pass the optional * parameter, you indicate that the pictureObject
you indicate that the pictureObject is a field or a variable. In this case,
you pass a field or variable reference (object field or variable only)
instead of a string.
216 4D v12 Upgrade

SVG GET ATTRIBUTE
The coordinates passed in the x and y parameters must be expressed in

pixels in relation to the top left corner of the picture (0,0). You can use
the values returned by the MouseX and MouseY system variables. These
variables are updated in the On Clicked, On Double Clicked form events
as well as the On Mouse Enter and On Mouse Move form events.
Note In the system of picture coordinates, [x;y] always specifies the same
point, regardless of the picture display format, apart from the
"Replicated" format.
All elements whose bounding rectangle are included in the selection

rectangle are taken into account, even those that are under other
elements.
SVG GET ATTRIBUTE SVG GET ATTRIBUTE({*; }pictureObject; element_ID; attrName; attrValue)
ble
Variable (if * omitted)
element_ID String Æ ID of element whose attribute value
you want to get
attrName String Æ Attribute whose value you want to
get
attrValue String | Value Å Current value of attribute
The new SVG GET ATTRIBUTE command retrieves the current value of
the attrName attribute in an object or an SVG picture.
parameter is an object name (string). In this case, the command
returns the value of the attribute for the rendered image attached to
the object. This value may have been modified by SVG SET ATTRIBUTE
for example.
4D v12 Upgrade 217

Chapter 5 Language
If you do not pass the * parameter, you indicate that the pictureObject
parameter is a variable. Therefore, you pass a variable reference (object
variable only) instead of a string. In this case, the command returns
the value of the attribute for the initial rendered image (corresponding
to the data source of the variable).
Note This principle also applies to the existing SVG Find element ID by
coordinates command.
For more information about SVG attributes, refer to the description of

the SVG SET ATTRIBUTE command. Here is a list of 4D attributes
reserved and dedicated to animation:
Attributes Access Comments
4D-text read/ Replaces/reads the contents of the text
write node. Can be used with 'text' 'tspan' and
'textArea' elements
4D-bringToFront write If 'true', move node in front of sibling
nodes. Can only be used with the SVG
SET ATTRIBUTE command
4D-isOfClass- read Returns 'true' if inherited class attribute
{IDENT of node contains all class name(s); other-
[[S|COMMA] wise, returns 'false'
IDENT]*} Returns for example true for "4D-isOf-
Class-land" if the inherited class of the
node is "land department01"
218 4D v12 Upgrade

SVG SET ATTRIBUTE
SVG SET ATTRIBUTE SVG SET ATTRIBUTE({*; }pictureObject; element_ID; attrName; attrValue{;
attrName2; attrValue2; ...; attrNameN; attrValueN})
ble
Variable or Field (if * omitted)
element_ID String Æ ID of element where one or more
attributes are set
attrName String Æ Attribute to be specified
attrValue String | Value Æ New value of attribute
The new SVG SET ATTRIBUTE command modifies the value of an

existing attribute in the SVG rendering tree of a displayed picture.
The modifications made by this command apply to the representation

of the picture; they are not stored and are lost when the picture is
erased by programming or when the form is closed.
applies to the parameters of the rendered image attached to the object
(note that the parameters and therefore the rendered image of the
object are only created if the SVG SET ATTRIBUTE command is called at
least once).
If you do not pass the * parameter, you indicate that the pictureObject
parameter is a variable or a field. Therefore, you pass a variable (object
variable only) or field reference instead of a string. In this case, the
command applies to the rendered images of all the objects that use the
variable (but not to the initial rendered image).
In the attrName and attrValue parameters, pass, respectively, the

attribute to set and its value (as variables, fields or literal values). You
can pass as many attribute/value pairs as you want.
4D v12 Upgrade 219

Chapter 5 Language
The SVG SET ATTRIBUTE command is used to modify (but not to add or
delete) most of the SVG attributes, such as, for instance, 'fill', 'opacity',
'font-family', and so on. For a complete definition of the SVG
attributes, refer to the reference documents available on the Internet,
for example http://www.w3.org/TR/SVG11/attindex.html. The rendered
image is updated immediately; the modifications are transferred on to
the child elements for inherited styles.
Note that for technical reasons, the attributes of certain elements as

well as certain attributes cannot be modified. The following table lists
the elements that can be modified, and those that cannot, as well as
the attributes that cannot be modified:
Elements whose attributes can be modified
svg Restrictions:
- "width" and "height" cannot be modified(1)
- "viewBox" can only be modified if "width" and
"height" are specified in the original document
g
defs
use
filter Restriction: fe_xxx child elements cannot be modi-
fied
circle
ellipse
line
polyline
polygon
path
rect
text The specific "4d-text" attribute modifies the text of a
tspan "text", "tspan" or "textArea" element (see the exam-
textArea ple)
Image
220 4D v12 Upgrade

SVG SET ATTRIBUTE
Elements whose attributes cannot be modified

linearGradient This group designates all the elements that can be
radialGradient referenced or contained in an element that can be
Stop referenced. This means that it is not possible, for
solidColor example, to redefine the attributes of a gradient (but
marker it is possible to change the gradient used). Similarly,
symbol to change a black color marker to a red marker, it is
necessary to define both markers in the SVG docu-
clipPath
ment (one black and one red) and to select one of
filter and elements
them. It is not possible either for example to modify
beginning with fe
the color of a rectangle if its parent is a symbol or
style marker element
pattern
Attributes that cannot be modified

id or xml:id
lang or xml:lang
class or xml:class
width Concerns the attributes of the 'svg' element only(1)
height
(1) These attributes cannot be modified because they define and
structure the resulting image. The width and height attributes of the svg
element define the initial dimensions of the picture in 4D. These
dimensions must remain constant after the picture is created (however
it is possible to modify the dimensions of the resulting picture with the
4D TRANSFORM PICTURE command).
If you attempt to modify the attribute of an element that is not

supported or one of its child elements, the command does nothing
and no error is generated.
` Modifying the contents of a Text type element:

SVG SET ATTRIBUTE (*;picture_object_name;text_element_ID;"4d-
text";"This is a text")
Note There is no namespace so that the attribute could be used in a CSS style
sheet without risk of conflict.
4D v12 Upgrade 221

Chapter 5 Language
SVG SHOW SVG SHOW ELEMENT ({*; }pictureObject; id{;margin})

ELEMENT Parameter Type Description
ble
Variable or field (if * omitted)
id String Æ ID attribute of element to display
margin Longint Æ Margin of visibility (in pixels by
default)
The new SVG SHOW ELEMENT command moves the pictureObject SVG
document in order to show the element whose "id" attribute is
specified by the id parameter.
applies to the rendered picture attached to the object. If you do not
pass this parameter, you indicate that pictureObject is a field or a
variable and you pass a variable (object variable only) or a field
reference instead of a string. In this case, the command applies to the
rendered pictures of all the objects that use the variable (but not the
initial rendered picture).
The command moves the SVG document so that all of the object,
whose limits are defined by its bounding rectangle, is visible. The
margin parameter configures the amplitude of the movement by
specifying the distance that must separate the object displayed from
the borders of the document. In other words, the bounding rectangle
will be increased by margin pixels in width and in height. By default,
the movement value is 4 pixels.
This command only takes effect in "top left" display mode (with
scrollbars).
222 4D v12 Upgrade

System Documents
System Documents
The management of documents within a multi-language interface
based on XLIFF architecture has been extended in 4D v12. A new
command can be used to retrieve the pathname of any document
integrated in this architecture according to the current language. In
addition, two new commands facilitate the conversion of system and
POSIX pathnames. A new parameter has been added to the Select folder
command in order to benefit from additional options.
Note It is now possible to specify the current language of the database using
the new SET DATABASE LOCALIZATION command, located in the "4D
Environment" theme.
Convert path POSIX Convert path POSIX to system(posixPath{; *}) Æ Text

to system Parameter Type Description
posixPath Text Æ POSIX pathname
* * Æ Encoding option
Function result Text Å Pathname expressed in system syntax
The new Convert path POSIX to system command converts a pathname

expressed with the POSIX (Unix) syntax into a pathname expressed
with the system syntax.
Pass the complete pathname of a file or folder in the posixPath

parameter, expressed with the POSIX syntax. This path must be
absolute (it must begin with the "/" character). You must pass a disk
path; it is not possible to pass a network path (beginning, for example,
with ftp://ftp.mysite.fr).
The command returns the complete pathname of the file or folder

expressed in the current system syntax.
The optional * parameters indicates whether the posixPath parameter is

encoded. If this is the case, you must pass this parameter, otherwise the
conversion will not be valid. The command returns the pathname
without encoding.
4D v12 Upgrade 223

Chapter 5 Language
` Examples under Mac OS:

$path:=Convert path POSIX to system("/Volumes/machd/
file 2.txt")
`returns "machd:file 2.txt"
$path:=Convert path POSIX to system("/Volumes/machd/
file%202.txt";*)
`returns "machd:file 2.txt"
$path:=Convert path POSIX to system("/file 2.txt")
`returns "machd:file 2.txt" if machd is the startup disk
` Examples under Windows:
$path:=Convert path POSIX to system("c:/docs/file 2.txt")
`returns "c:\docs\truc 2.txt"
$path:=Convert path POSIX to system("c:/docs/file%202.txt";*)
`returns "c:\docs\truc 2.txt"
See Also: Convert path system to POSIX
Convert path system Convert path system to POSIX(systemPath{; *}) Æ Text

to POSIX Parameter Type Description
systemPath Text Æ Relative or absolute pathname
expressed in system syntax
* * Æ Encoding option
Function result Text Å Absolute pathname expressed in POSIX

syntax
The new Convert path system to POSIX command converts a pathname

expressed with the system syntax as a pathname expressed with the
POSIX (Unix) syntax.
Pass the pathname for a file or folder in the systemPath parameter,

expressed with the system syntax (Mac OS or Windows). This path
may be absolute or relative to the database folder (folder containing
the database structure file). It is not mandatory that the elements of
the path actually exist on the disk at the time the command is
executed (the command does not test the validity of the pathname).
The command returns the complete pathname of the file or folder

expressed in the POSIX syntax. The command always returns an
absolute pathname, regardless of the type of path passed in systemPath.
224 4D v12 Upgrade

Get localized document path
If you passed a relative pathname in systemPath, 4D completes the

value returned by adding the pathname of the database folder.
The optional * parameter specifies the encoding of the POSIX path. By

default, Convert path system to POSIX does not encode the special
characters of the POSIX path. If you pass the * parameter, the special
characters are translated (for example, "My folder" becomes
"My%20folder").
` Example under Mac OS

$path:=Convert path system to POSIX("machd:file 2.txt")
`returns "/Volumes/machd/file 2.txt" (even if machd is the startup disk)
$path:=Convert path system to POSIX("machd:file 2.txt";*)
`returns "/Volumes/machd/file%202.txt"
$path:=Convert path system to POSIX("resources:images")
`returns "/Volumes/machd/bases/basevideo/resources/images"
` Example under Windows
$path:=Convert path system to POSIX("c:\docs\file 2.txt")
`returns "c:/docs/file 2.txt"
$path:=Convert path system to POSIX("\\srv\tempo\file.txt")
`returns "//srv/tempo/file.txt"
See Also: Convert path POSIX to system
Get localized Get localized document path (relativePath) Æ Text

document path Parameter Type Description
relativePath Text Æ Relative pathname of document for
which we want to obtain localized ver-
sion
Function result Text Å Absolute pathname of localized docu-

ment
The Get localized document path command returns the complete

(absolute) pathname of a document designated by relativePath and
located in a xxx.lproj folder.
4D v12 Upgrade 225

Chapter 5 Language
This command must be used within a multi-language application

architecture based on the presence of a Resources folder and xxx.lproj
subfolders (where xxx represents a language). With this architecture,
4D automatically supports localized files of the .xliff type as well as
pictures, but you may need to use the same mechanism for other types
of files.
Pass the relative pathname of the document to be searched for in

relativePath. The path entered must be relative to the first level of the
"xxx.lproj" folder of the database. The command will return a complete
pathname using the "xxx.lproj" folder corresponding to the current
language of the database.
Note The current language is either set automatically by 4D according to the

contents of the Resources folder (see the Get database localization
command), or via the new SET DATABASE LOCALIZATION command.
You can express the contents of the relativePath parameter using a

system or a POSIX syntax. For example:
xsl/log.xsl (POSIX syntax: can be used under Mac OS or Windows)
xsl\log.xsl (Windows only)
xsl:log.xsl (Mac OS only)
The absolute pathname returned by the command is always expressed

in the system syntax.
4D Server In remote mode, the command returns the path of the Resources folder
on the client machine if the command is called from a client process.
4D looks for the file while respecting a sequence that allows all the
cases of multi-language applications to be processed. At each step, 4D
checks for the presence of relativePath in the folder corresponding to
the language and returns the complete path when it succeeds. If
relativePath is not found or if the folder does not exist, 4D passes to the
next step. Here are the folders for each of the different search stages:
Current language (e.g.: fr-ca)
Current language without region (e.g.: fr)
Language loaded by default on startup (e.g.: es-ga)
Language loaded by default on startup without region (e.g.: es)
First .lproj folder found (e.g.: en.lproj)
First level of Resources folder
226 4D v12 Upgrade

Get localized document path
If relativePath is not found in any of these locations, the command

returns an empty string.
` For the purpose of transforming an XML or HTML file, you want to use
a "log.xsl" transformation file. This file differs depending on the
current language. You therefore want to know which "log.xsl" file path
to use.
Here are the contents of the Resources folder:
To use a .xsl file adapted to the current language, you simply need to
pass:
$myxsl:=Get localized document path ("xsl/log.xsl")
If the current language is, for example, French Canadian (fr-ca), the
command returns:
Under Windows:
C:\users\…\…\…\resources\fr_ca.lproj\xsl\log.xsl"
Under Mac OS:
"HardDisk:users:…:…:…:resources:fr_ca.lproj:xsl:log.xsl"
4D v12 Upgrade 227

Chapter 5 Language
Select folder Select folder{(message{; defaultPath{; options}})} Æ Text

message Text Æ Title of the window
defaultPath Text | Longint Æ Pathname or
Number of memorized pathname
options Longint Æ Selection option(s)
Function result Text Å Access path to the selected folder
The Select folder command now accepts the options parameter. This
parameter lets you benefit from additional functions under Mac OS.
In options, you can pass one of the following predefined constants,
located in the "System Documents" theme:
Package open (2): Allows the opening of packages as folders and thus
the display/selection of their contents. By default, if this constant is
not used, the command does not allow the opening of packages.
Use Sheet Window (16): Displays the selection dialog box as a sheet
window. Sheet windows are specific to the Mac OS X interface and
benefit more particularly from a graphic animation. By default, if this
constant is not used, the command displays a standard dialog box.
You can pass a single constant or a combination of both.
These options are only taken into account under Mac OS. Under
Windows, the options parameters is ignored if it is passed.
Tools
Several modifications have been made in the "Tools" theme of 4D v12:
A new command has been added that generates UUID identifiers,
The ENCODE and DECODE commands have been renamed BASE64

ENCODE and BASE64 DECODE and can now return a text.
228 4D v12 Upgrade

BASE64 DECODE
BASE64 DECODE BASE64 DECODE ({encodedText; } blob)

encodedText Text Æ Text containing BLOB encoded in Base64 format
blob BLOB Æ BLOB encoded in Base64 format (if encoded-
Text is omitted)
Å Decoded BLOB
Compatibility note The BASE64 DECODE command was named DECODE in previous
versions of 4D.
The BASE64 DECODE command accepts a new optional parameter:

encodedText. If you pass this parameter, the command decodes its
contents and returns it in the blob parameter. It must contain a BLOB
encoded in Base64 format. In this case, the initial contents of the blob
parameter are ignored by the command.
This modification allows the command to be used in a way that is

more in keeping with XML specifications (see the “Note on use of XML
BLOBs in 4D v12” paragraph on page 235).
If you omit the encodedText parameter, the command functions as in

previous versions of 4D.
` This example lets you transfer a picture via a BLOB:

C_BLOB($sourceBlob)
C_PICTURE($mypicture)
$mypicture:=[people]photo
PICTURE TO BLOB($mypicture;$sourceBlob;".JPG")
C_TEXT($base64Text)
BASE64 ENCODE($sourceBlob;$base64Text) //Encoding of text
// the binary is now available as character strings in $base64Text
C_TEXT($base64Text)
C_BLOB($targetBlob)
BASE64 DECODE($base64Text;$targetBlob) //Decoding of text
// the binary encoded in base 64 is now available as a BLOB in $blobTarget
4D v12 Upgrade 229

Chapter 5 Language
BASE64 ENCODE BASE64 ENCODE (blob{; encodedText})

blob BLOB Æ BLOB to encode in Base64 format
Å BLOB encoded in Base64 format (if encoded-
Text is omitted)
encodedText Text Å Result of BLOB encoded in Base64 format
Compatibility note The BASE64 ENCODE command was named ENCODE in previous
versions of 4D.
The BASE64 ENCODE command accepts a new optional parameter:

encodedText. If you pass this parameter, it receives the contents of the
encoded blob at the end of command execution. In this case, the blob
parameter itself is not modified by the command.
This modification allows the command to be used in a way that is

more in keeping with XML specifications (see the “Note on use of XML
BLOBs in 4D v12” paragraph on page 235).
If you omit the encodedText parameter, the command functions as in

previous versions.
Generate UUID Generate UUID Æ Alpha

This command does not require any parameters
Function result Alpha Å New UUID as non-canonical text

(32 characters)
The Generate UUID returns a new 32-character UUID identifier in non-

canonical form.
For more information about UUID identifiers, refer to the “Using

Universally Unique Identifiers (UUIDs)” paragraph on page 19.
` Generation of a UUID in a variable:

C_TEXT(MyUUID)
MyUUID:=Generate UUID
SET ENVIRONMENT The SET ENVIRONMENT VARIABLE command now functions with the
VARIABLE PHP Execute command.
230 4D v12 Upgrade

User Interface
User Interface
This theme receives the new OBJECT Get name and OBJECT Get pointer
commands. The HIGHLIGHT TEXT and GET HIGHLIGHT commands now
accept an "object" syntax. The SCROLL LINES command has been
renamed OBJECT SET SCROLL POSITION and transferred to the "Object
Properties" theme.
GET HIGHLIGHT GET HIGHLIGHT({*; }object; startSel; endSel)

* * Æ If specified, object is an object name (string)
If omitted, object is a field or variable
Field of variable (if * is omitted)
startSel Number Å Current text selection starting position
endSel Number Å Current text selection ending position
The GET HIGHLIGHT command now accepts an "object" type syntax, in

other words, designating a form object by its name and not by its
variable reference.
parameter, you indicate that object is a field or variable. In this case,
you pass the field or variable reference (form fields or variables only)
` This new syntax facilitates the use of the new OBJECT SET STYLED TEXT
ATTRIBUTES command:
GET HIGHLIGHT(*;"myText";$startsel,$endsel)
OBJECT SET STYLED TEXT ATTRIBUTE(*;"myText";$startsel,$endsel;
Attribute underline style; 1; Attribute bold style;1)
4D v12 Upgrade 231

Chapter 5 Language
HIGHLIGHT TEXT HIGHLIGHT TEXT({*; }object; startSel; endSel)

* * Æ If specified, object is an object name (string)
If omitted, object is a field or variable
Field of variable (if * is omitted)
startSel Number Æ New text selection starting position
endSel Number Æ New text selection ending position
The HIGHLIGHT TEXT command now accepts an "object" type syntax,

in other words, designating a form object by its name and not by its
variable reference.
parameter, you indicate that object is a field or variable. In this case,
you pass the field or variable reference (form fields or variables only)
OBJECT Get name OBJECT Get name{(selector)} Æ Text

selector Longint Æ Object category
Function result Text Å Name of object
The new OBJECT Get name command returns the name of a form
object.
The command designates two types of objects according to the value

of the selector parameter. In this parameter, you can pass one of the
following constants (placed in the new "Form objects" theme):
Object current or selector omitted: If you pass this selector or omit
the selector parameter, the command returns the name of the object
from which it was called (object method or submethod called by
the object method). In this case, the command must be called in
the context of a form object, otherwise it returns an empty string.
Object with focus: If you pass this selector, the command returns the
name of the object that has the focus in the form.
` Object method for "bValidateForm" button:

$btnName:=OBJECT Get name(Object current)
232 4D v12 Upgrade

OBJECT Get pointer
After the execution of this object method, the $btnName variable

contains the "bValidateForm" value.
See Also: OBJECT Get pointer
OBJECT Get pointer OBJECT Get pointer {(selector{; objectName{; subformName}})} Æ Pointer
selector Longint Æ Object category
objectName Text Æ Object name
subformName Text Æ Subform object name
Function result Å Pointer to object variable
The OBJECT Get pointer command returns a pointer to the variable of a

form object.
This command designates different objects according to the value of

the selector parameter. You can pass one of the constants of the new
"Form objects" theme in this parameter:
Object current or selector omitted: If you omit the selector parameter
or pass this selector, the command returns a pointer to the variable
associated with the current object (object whose form method is
executing).
Note This is strictly equivalent to the previous functioning of the Self

command. The Self command is nevertheless kept for compatibility
reasons.
Object with focus: If you pass this selector, the command returns a
pointer to the variable associated with the object that has the focus
in the form. The last two optional parameters are ignored if they are
passed.
Note This is strictly equivalent to the functioning of the Focus object

command. The Focus object command is now obsolete in 4D v12.
4D v12 Upgrade 233

Chapter 5 Language
Object subform container: If you pass this selector, the command

returns a pointer to the variable bound with the subform container.
The last two optional parameters are ignored if they are passed. This
selector can therefore only be used in the context of a form used as
a subform, so as to access the variable bound with the container
object. For more information, refer to “Update of subform
contents” paragraph on page 74.
Object named: If you pass this selector, you must also pass the
second parameter, objectName. In this case, the command returns a
pointer to the variable associated with the object whose name was
passed in this parameter.
If objectName corresponds to a subform and the "Output subform"
option is checked, the command returns a pointer to the table of
the subform if a source table is specified; otherwise it returns Nil.
The optional subformName parameter retrieves a pointer to an

objectName object that does not belong to the current context, i.e. in
the parent form. To use this parameter, you must pass the Object
named selector.
When the subformName parameter is passed, the OBJECT Get pointer
command first looks for the subform object named subformName in
the current form, then looks inside this subform for an object named
objectName. If this object is found, it returns a pointer to the variable of
this object.
` Given a form "SF" used twice as a subform in the same parent form.
The subform objects are named "SF1" and "SF2". The "SF" form contains
an object named CurrentValue. In the "On Load" form event of the form
method of the parent form, we want to initialize the CurrentValue
object of SF1 to "January" and that of SF2 to "February":
C_POINTER($Ptr)
$Ptr:=OBJECT Get pointer(Object named;"CurrentValue";"SF1")
$Ptr->:="January"
$Ptr:=OBJECT Get pointer(Object named;"CurrentValue";"SF2")
$Ptr->:="February"
See Also: OBJECT Get name
234 4D v12 Upgrade

Web Server
Web Server
PROCESS HTML The PROCESS HTML TAGS command is optimized in 4D v12. The
TAGS processing performed by this command is now completely decoupled
from the Web server settings. In particular, when you use BLOB type
parameters, the command no longer takes the character set specified
for the Web server into account. For the sake of compatibility, it
considers that the character set used for BLOBs is MacRoman.
For better efficiency, it is not strongly recommended to use Text type
parameters. In this case, processing will automatically be carried out in
Unicode.
XML
Note The "XML" theme replaces the "XML Utilities" theme of previous
versions of 4D. It now groups together the generic XML commands
that apply to both DOM and SAX commands, as well as the XSLT and
SVG commands.
The integrated XML commands have been modified in 4D v12 and

new commands have been added. The conversion mechanisms of data
types between 4D and XML have been strengthened.
Note on use of XML XML structures are based on data of the Text type. However, the 4D
BLOBs in 4D v12 XML commands (for example DOM Parse XML variable) usually accept
parameters of the BLOB type for handling XML data, regardless of their
original type. This possibility was necessary in previous versions of 4D
where the size of Text type variables was limited to 32 KB.
Beginning with 4D v11, variables and fields of the Text type can
contain up to 2 GB of data. It is now highly inadvisable to store texts
in BLOBs. The use of BLOBs should be reserved for processing binary
data. For better conformity with XML specifications, in 4D v12 binary
data are automatically encoded in Base64, even if the BLOB contains
text.
Note The ENCODE and DECODE commands (renamed The SET
ENVIRONMENT VARIABLE command now functions with the PHP Execute
command. and BASE64 DECODE) can now handle Text type parameters.
These commands are useful in the framework of encoding XML data.
These commands are included in the "Tools" theme (see the “Tools”
4D v12 Upgrade 235

Chapter 5 Language
XML DECODE XML DECODE (xmlValue; object)

xmlValue Text Æ Text type value coming from an XML
structure
object Field | Å 4D variable or field receiving the con-
Variable verted XML value
The XML DECODE command converts a value stored as an XML string

into a 4D typed value. The conversion is carried out automatically
according to the following rules:
Conversion on English
Value Examples
system
number <Price>8,5</Price> Real: 8.5
<Price>8.5</Price>
Boolean <Double>1</Double> Boolean: True/False
<Double>0</Double> or
<Double>true</Double>
<Double>false</Double>
BLOB Base64 decoding
Picture Base64 decoding + BLOB to
picture command
Date 2009-10- Deletion of time part as well as
25T01:03:20+01:00 time zone: !10/25/2009!
Time 2009-10- Deletion of date part as well as
25T01:03:20+01:00 time zone: ?01:03:20?
` Importing data from an XML document in which values are stored as

attributes.
Example of XML document:
<CD Date="2003-01-01T00:00:00Z" Description="This double CD reissued
by EMI in 1995 combines 4 Stabat mater hymns. One by Rossini interpreted
by the Berlin Symphony Orchestra, directed by Karl Forster. Followed by a
work of Verdi, by the Philharmonic Orchestra, directed by Carlo Maria
Giulini. On the second CD, you will find Francis Poulenc interpreted by
Régine Crespin. This compilation ends with a little-known version, that of
the Polish composer Karol Szymanowski. Polish National Radio Symphony
Orchestra directed by Antoni Wit" Double="true" Duration="7246"
Type="Sacred music" CD_ID="5" Performer="Various" Price="8.5" Title="4
Stabat mater"/>
236 4D v12 Upgrade

XML DECODE
Repeat
MyEvent:=SAX Get XML node(DocRef)
Case of
: (MyEvent=XML Start Element)
ARRAY TEXT(arrAttribNames;0)
ARRAY TEXT(arrAttribValues;0)
SAX GET XML ELEMENT (DocRef;vName;vPrefix;arrAttribNames;ar-
rAttribValues)
If (vName="CD")
CREATE RECORD([CD])
For ($i;1;Size of array(arrAttribNames))
$attrName:=arrAttribNames{$i}
Case of
: ($attrName="CD_ID")
XML DECODE(arrAttribValues{$i};[CD]CD_ID)
: ($attrName="Title")
[CD]Work:=arrAttribValues{$i}
: ($attrName="Price")
XML DECODE(arrAttribValues{$i};[CD]Price)
: ($attrName="Date")
XML DECODE(arrAttribValues{$i};[CD]Date entered)
: ($attrName="Duration")
XML DECODE(arrAttribValues{$i};[CD]Total_duration)
: ($attrName="Double")
XML DECODE(arrAttribValues{$i};[CD]Double_CD)
End case
End for
End if
...
End case
Until (MyEvent=XML Start Document)
4D v12 Upgrade 237

Chapter 5 Language
XML GET OPTIONS XML GET OPTIONS(elementRef | document; selector; value{; selector2;
value2;...;selectorN; valueN})
elementRef | String | Æ XML root element reference or
document DocRef Reference of open document
selector1...N Integer Æ Option to get
value1...N Integer Å Current value of option
The new XML GET OPTIONS command retrieves the current value of
one or more XML parameters for the current session and the current
user.
In selector, pass a constant of the "XML" theme indicating the option to

get. The current value of the option is returned in the value parameter.
For more information about the options to pass in the selector

parameter and the values returned, refer to the description of the XML
SET OPTIONS command.
See Also: XML SET OPTIONS
XML SET OPTIONS XML SET OPTIONS(elementRef | document; selector; value{; selector2;
value2;...;selectorN; valueN})
elementRef | String | Æ XML root element reference or
document DocRef Reference of open document
selector1...N Integer Æ Option to set
value1...N Integer Æ Value of option
The new XML SET OPTIONS command modifies the value of one or
more XML parameters for the current session and current user.
This command applies the XML structures of the "tree" type (DOM) or
of the "document" type (SAX). In the first parameter, you can pass
either a root element reference (elementRef), or the reference of an open
SAX document (document).
The options set by this command are only used in the direction 4D to
XML (it has no effect on the reading of XML values in 4D. The
following commands use these options:
DOM SET XML ELEMENT VALUE
238 4D v12 Upgrade

XML SET OPTIONS
DOM SET XML ATTRIBUTE

SAX ADD XML ELEMENT VALUE
Pass the option to be modified in selector and the new value of the
option in value. You can pass as many selector/value pairs as you want.
You must use the constants described below, placed in the "XML"
theme:
selector = XML String encoding(1)
This selector specifies the way 4D strings are converted to element
values. It does not concern the conversion to attributes for which XML
imposes the use of escape characters.
value = XML With escaping(1) (default value): conversion of 4D
strings to XML element values with replacement of characters. The
Text type data are automatically parsed so that forbidden characters
(<&>’) are replaced by XML entities (&<> '").
value = XML Raw data(2): 4D strings are sent as raw data; 4D does
not carry out encoding or parsing. 4D values are converted if
possible to XML fragments and inserted as a child of the target
element. If a value cannot be considered as an XML fragment, it is
inserted as raw data into a new CDATA node.
selector = XML Date encoding(2)
This selector specifies the way 4D dates will be converted. For example,
!01/01/2003! in the Paris time zone.
value = XML ISO (1) (default value): uses the format xs:datetime
without indication of time zone. Result: "2003-01-01". The time
part, if it is present in the 4D value (via SQL) is lost.
value = XML Local (2): uses the format xs:date with indication of
time zone. Result: "2003-01-01 +01:00". The time part, if it is present
in the 4D value (via SQL) is lost.
value = XML Datetime local (3): uses the format xs:dateTime (ISO
8601). Indication of time zone. This format allows the time part to
be kept, if it is present in the 4D value (via SQL). Result:
"<Date>2003-01-01T00:00:00 +01:00</Date>".
value = XML UTC (4): uses the format xs:date. Result: "2003-01-01Z".
The time part, if it is present in the 4D value (via SQL) is lost.
4D v12 Upgrade 239

Chapter 5 Language
value = XML Datetime UTC (5): uses the format xs:dateTime (ISO
8601). This format allows the time part to be kept, if it is present in
the 4D value (via SQL). Result: "<Date>2003-01-
01T00:00:00Z</Date>".
Note The XML Local and XML Datetime local values do not provide dates
expressed in UTC (Universal Time Coordinated); they are converted
without modification but indicating the time difference. These formats
are useful in the case of successive and reciprocal conversions (round
tripping).
The XML UTC and XML Datetime UTC values are equivalent to the
previous ones from the formatting viewpoint, but they are expressed in
UTC. These formats should be given priority to ensure interoperability.
The values are not modified.
selector = XML Time encoding(3)

This selector specifies the way 4D times are converted. For example,
?02/00/46? (Paris time). The encoding differs depending on whether
you want to express a time or a duration.
For time type values:
value = XML Datetime UTC (5): time expressed in UTC (Universal
Time Coordinated). Note that conversion to UTC is automatic.
Result: "<Duration>0000-00-00T01:00:46Z</Duration>".
value = XML Datetime local (3): time expressed with the time
difference of the machine of the 4D engine. Result:
"<Duration>0000-00-00T02:00:46+01:00</Duration>".
value = XML Datetime local absolute (1) (default value): time
expressed without indication of time zone. No modification of the
value. Result: "<Duration>0000-00-00T02:00:46</Duration>".
For duration type values:
value = XML Seconds (4): number of seconds since midnight; no
modification of the value since it expresses a duration. Result:
"<Duration>7246</Duration>".
value = XML Duration (2): duration expressed in compliance with
XML Schema Part 2: Datatypes Second Edition. No modification of
the value since it expresses a duration. Result:
"<Duration>PT02H00M46S</Duration>".
240 4D v12 Upgrade

XML SET OPTIONS
selector = XML Binary encoding(5)

This selector specifies the way binary data will be converted.
XML Base64 (1) (default value): binary data are simply converted to
Base64.
XML Data URI scheme (2): binary data are converted to Base64 and
the "data:;base64" header is added. This format mainly allows a
browser to automatically decode a picture, and is also required for
the insertion of SVG pictures. For more information, see
http://en.wikipedia.org/wiki/Data_URI_scheme.
selector = XML Picture encoding(6)
This selector specifies the way pictures must be converted (before
encoding in Base64).
XML Convert to PNG (1) (default value): pictures are converted to
PNG before being encoded in Base64.
XML Native codec(2): pictures are converted in their first native
storage CODEC before being encoded in Base64. You must use these
options to encode SVG pictures (see example 1).
selector = XML Indentation (4)
This selector specifies the indentation of the XML document.
XML With indentation (1) (default value): the document is indented.
XML No indentation (2): the document is not indented; its contents
are placed in a single line.
` Example 1: Inserting an SVG picture

XML SET OPTIONS ($pictElemRef;XML Binary encoding;
XML Data URI scheme)
XML SET OPTIONS ($pictElemRef;XML Picture encoding;
XML Native codec)
DOM SET XML ATTRIBUTE ($pictElemRef;"xlink:href";PictVar)
See Also: XML GET OPTIONS
4D v12 Upgrade 241

Chapter 5 Language
XML DOM
Several new commands have been added to the XML DOM theme:
DOM Create XML element arrays, DOM REMOVE XML ATTRIBUTE, DOM
Insert XML element, DOM Append XML element, DOM Append XML child
node, DOM GET XML CHILD NODES, DOM Get XML document ref.
Furthermore, due to the implementation of the XML SET OPTIONS and
XML GET OPTIONS commands, the existing DOM SET XML OPTIONS
command has been renamed DOM SET XML DECLARATION and its
functioning has been adapted.
DOM Append XML DOM Append XML child node (elementRef; childType; childValue) Æ
child node String
elementRef String Æ XML element reference
childType Longint Æ Type of child to append
childValue String | BLOB Æ Text or variable (Text or BLOB) whose
value must be inserted as child node
Function result String Å Reference of child XML element
The new DOM Append XML child node command appends the
childValue value to the XML node designated by elementRef.
The type of node created is specified by the childType parameter. In this

parameter you can pass one of the following constants, located in the
"XML" theme:
Type of child node Constant (value)
Text XML DATA (6)
Processing instruction XML Processing Instruction (3)
Comment XML Comment (2)
CDATA XML CDATA (7)
DOCTYPE XML DOCTYPE (10)
Element XML ELEMENT (11)
242 4D v12 Upgrade

DOM Append XML child node
In childValue, pass the data to be inserted. You can pass a string or a 4D

variable (string or BLOB). The contents of this parameter will always be
converted into text.
Note If the elementRef parameter designates the Document node (top level
node), the command inserts a "Doctype" node before any other node.
The same goes for processing instructions and comments, which are
always inserted before the root node (but after the Doctype node).
` Adding a text type node:

Reference:= DOM Create XML element (elementRef;"myElement")
DOM SET XML ELEMENT VALUE(Reference ; "Hello")
temp:= DOM Create XML element (Reference ; "br")
temp:= DOM Append XML child node (Reference ; XML DATA; "New")
temp:= DOM Create XML element (Reference ; "br")
temp:= DOM Append XML child node(Reference ; XML DATA; "York")
Result:
<myElement>Hello New York</myElement>
` Adding a processing instruction type node:
$Txt_instruction:="xml-stylesheet type = \"text/xsl\" href=\"style.xsl\""
Reference:= DOM Append XML child node(elementRef;XML Processing
Instruction ; $Txt_instruction )
Result (inserted before first element):

<?xml-stylesheet type="text/xsl" href="style.xsl"?>
` Adding a comment type node:
Reference:= DOM Append XML child node (elementRef;XML Comment;
"Hello world")
Result:

` Adding a CDATA type node:
Reference:= DOM Append XML child node (elementRef; XML CDATA;
"12 < 18")
Result:
<element><![CDATA[12 < 18]]></element>
4D v12 Upgrade 243

Chapter 5 Language
` Adding or replacing a Doctype declaration type node:

Reference:=DOM Append XML child node(elementRef;XML DOCTYPE;
"Books SYSTEM \"Book.DTD\"")
Result (inserted before first element):

<!DOCTYPE Books SYSTEM "Book.DTD">
` Adding or replacing an Element type node.
If the childValue parameter is an XML fragment, it is inserted as
child nodes:
Reference:=DOM Append XML child node(elementRef;XML ELEMENT;
"<child>simon</child><child>eva</child>")
Result:
<parent>
<child>simon</child>
<child>eva</child>
</parent>
Otherwise, a new blank child element is appended:

Reference:=DOM Append XML child node (elementRef;XML ELEMENT;
"tbreak")
Result:
<parent>
<tbreak/>
</parent>
If the contents of childValue are not valid, an error is returned.
See Also: DOM GET XML CHILD NODES
244 4D v12 Upgrade

DOM Append XML element
DOM Append XML DOM Append XML element (targetElementRef; sourceElementRef) Æ

element String
targetElementRef String Æ Reference of XML parent element
sourceElementRef String Æ Reference of XML element to append
Function result String Å Reference of new XML element
The new DOM Append XML element command adds a new XML
element to the children of the XML element whose reference is passed
in the targetElementRef parameter.
Pass the element to be added in sourceElementRef. This element must be

passed as the reference of an existing XML element in a DOM tree. It is
added after the last existing child element of targetElementRef.
` See the example of the DOM Insert XML element command.
See Also: DOM Insert XML element
DOM Create XML DOM Create XML element arrays (elementRef; xPath{; attrNamesArray;
element arrays attrValuesArray}{; attrNamesArray2; attrValuesArray2; ...; attrNamesArrayN;
attrValuesArrayN}) Æ String
elementRef String Æ XML root element reference
xPath Text Æ XPath path of the XML element to
create
attrNamesArray Array Æ Array of attribute names
attrValuesArray Array Æ Array of attribute values
Function result String Å Reference of created XML element
The new DOM Create XML element arrays command adds a new
element in the elementRef XML element, as well as, optionally,
attributes and their values in the form of arrays.
Apart from supporting arrays (see below), this command is identical to

DOM Create XML element. Refer to the description of this command for
the details of its functioning.
4D v12 Upgrade 245

Chapter 5 Language
Optionally, the DOM Create XML element arrays command can be used
to pass several pairs of attributes and attribute values as arrays in the
attrNamesArray and attrValuesArray parameters. In attrValuesArray, you
can pass arrays of the text, date, number, and picture type. 4D
automatically carries out the necessary conversions; you can modify
these conversions using the new XML SET OPTIONS command.
The arrays must have been created beforehand and function by pairs.
You can pass as many pairs of arrays and as many elements in each pair
as you want.
` We want to create the following element:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<RootElement>
<Elem1>
<Elem2>
<Elem3 Font="Verdana" Size="10" Style="Bold"></Elem3>
</Elem2>
</Elem1>
</RootElement>
For this, you can simply write:
ARRAY TEXT(arrAttribNames;3)
ARRAY TEXT(arrAttribValues;3)
arrAttribNames{1}:="Font"
arrAttribValues{1}:="Verdana"
arrAttribNames{2}:="Style"
arrAttribValues{2}:="10"
arrAttribNames{3}:="Style"
arrAttribValues{3}:="Bold"
vRootRef:=DOM Create XML ref("RootElement")
vxPath:="/RootElement/Elem1/Elem2/Elem3"
vElementRef:=DOM Create XML element arrays(vRootRef;
vxPath;arrAttribNames;arrAttribValues)
See Also: DOM Create XML element
246 4D v12 Upgrade

DOM GET XML CHILD NODES
DOM GET XML DOM GET XML CHILD NODES(elementRef; childTypesArr; nodeRefsArr)
CHILD NODES Parameter Type Description
childTypesArr Longint array Å Types of child nodes
nodeRefsArr Text array Å References or Values of child
nodes
The new DOM GET XML CHILD NODES command returns the types and
references or values of all the child nodes of the XML element
designated by elementRef.
The types of child nodes are returned in the childTypesArr array. You
can compare the values returned by the command with the following
constants, found in the "XML" theme:
Constant Type Value
XML Comment Longint 2
XML Processing Instruction Longint 3
XML DATA Longint 6
XML CDATA Longint 7
XML DOCTYPE Longint 10
XML ELEMENT Longint 11
For more information, refer to the description of the DOM Append

XML child node command.
The nodeRefsArr array receives the values or references of the elements

according to their nature (contents or instructions).
` Given the following XML structure:

<myElement>Hello New York</myElement>
After executing these instructions:
elementRef:=DOM Find XML element ($root;"myElement")
DOM GET XML CHILD NODES(elementRef;$typeArr;$textArr)
4D v12 Upgrade 247

Chapter 5 Language
... the $typeArr and $textArr arrays will contain the following values:
$typeArr{1}=6 $textArr{1} = "Hello"
$typeArr{2}=11 $textArr{2} = "AEF1233456878977" (element reference
 )
$typeArr{3}=6 $textArr{3} = "New"
$typeArr{4}=11 $textArr{4} = "AEF1237897734568" (element reference
 )
$typeArr{5}=6 $textArr{5} = "York"
See Also: DOM Append XML child node
DOM Get XML DOM Get XML document ref (elementRef) Æ String
document ref Parameter Type Description
elementRef String Æ Reference of existing element in
DOM tree
Function result String Å Reference of first element of a DOM

tree (document node)
The new DOM Get XML document ref command recovers the reference
of the "document" element of the DOM tree whose reference you have
passed in elementRef. The document element is the first element of a
DOM tree; it is the parent of the root element.
The reference of the document element lets you handle the "Doctype"
and "Processing Instruction" nodes. It can only be used with the DOM
Append XML child node and DOM GET XML CHILD NODES commands.
At this level, you can only append processing instructions and
comments or replace the Doctype node. You cannot create CDATA or
Text nodes there.
248 4D v12 Upgrade

DOM GET XML ELEMENT VALUE
` In this example, we want to find the DTD declaration of the XML

document:
C_TEXT($rootRef)
$rootRef:=DOM Parse XML source("")
If (OK=1)
C_TEXT($documentRef)
// we are looking for the document node, since it is the node to which
// the DOCTYPE node is attached before the root node
$documentRef:=DOM Get XML document ref($rootRef)
ARRAY TEXT($typeArr;0)
ARRAY TEXT($valueArr;0)
// on this node we look for the DOCTYPE type node among the
// child nodes
DOM GET XML CHILD NODES($refDocument;$typeArr;$valueArr)
C_TEXT($text)
$text:=""
$pos:=Find in array($typeArr;XML DOCTYPE)
If ($pos>-1)
// We retrieve the DTD declaration in $text
$text:=$text+"Doctype: "+$valueArr{$pos}+Char(Carriage return)
End if
DOM CLOSE XML($rootRef)
End if
See Also: DOM GET XML CHILD NODES, DOM Append XML child node
DOM GET XML DOM GET XML ELEMENT VALUE(elementRef; elementValue{; cDATA})
ELEMENT VALUE
Henceforth, if the object received in elementRef is a BLOB, the
command will automatically attempt to decode it into Base64. In fact,
if the BLOB was created by the DOM SET XML ELEMENT VALUE
command, it was automatically encoded in Base64. It is no longer
necessary to call the BASE64 DECODE command.
See Also: SAX GET XML ELEMENT VALUE
4D v12 Upgrade 249

Chapter 5 Language
DOM Insert XML DOM Insert XML element (targetElementRef; sourceElementRef; childIn-
element dex) Æ String
targetElementRef String Æ Parent XML element reference
sourceElementRef String Æ XML element reference to insert
childIndex Longint Æ Index of child of target element
above which the new element must
be inserted
Function result String Å Reference of new XML element
The new DOM Insert XML element command inserts a new XML
element among the child elements of the XML element whose
reference is passed in the targetElementRef parameter.
Pass the element to be inserted in sourceElementRef. This element must

be passed as the reference of an existing XML element in a DOM tree.
The childIndex parameter designates the child of the parent element

before which the new element must be inserted. Pass an index number
in this parameter. If the value is not valid (for example, there is no
child element having this index), the new element will be added
before the first child of the parent element.
The command returns the reference of the XML element obtained.
` In the following structure, we would like to invert the first and second
book:
<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<NewBooks>
<Book>
<Title>Open Source Web Services</Title>
<Author>Collective</Author>
<Date>2003</Date>
<ISBN>2-7440-1507-5</ISBN>
<Publisher>Wrox</Publisher>
</Book>
<Book>
250 4D v12 Upgrade

DOM REMOVE XML ATTRIBUTE
<Title>Building XML Web services</Title>

<Author>Scott Short</Author>
<Date>2002</Date>
<ISBN>2-10-006476-2</ISBN>
<Publisher>Microsoft Press</Publisher>
</Book>
</NewBooks>
To do this, simply execute the following code:
C_TEXT($rootRef)
$rootRef:=DOM Parse XML source ("") `selection of XML document
If (OK=1)
C_TEXT($newStruct)
$newStruct:=DOM Create XML Ref ("NewBooks")
$bookRef:=DOM Find XML element ($rootRef;"/BookCata-

logue/Book[1]")
$newElementRef:=DOM Append XML element ($newStruct;$bookRef)
$bookRef:=DOM Find XML element ($rootRef;"/BookCata-

logue/Book[2]")
C_TEXT($newElementRef)
$newElementRef:=DOM Insert XML element ($newStruct;$bookRef;1)
DOM CLOSE XML($newStruct)

DOM CLOSE XML($rootRef)
End if
See Also: DOM Append XML element
DOM REMOVE XML DOM REMOVE XML ATTRIBUTE (elementRef; attrName)

ATTRIBUTE Parameter Type Description
attrName String Æ Attribute to be removed
The new DOM REMOVE XML ATTRIBUTE command removes the

attribute designated by attrName, if it exists, from the XML element
whose reference is passed in the elementRef parameter.
If the attribute has been correctly removed, the OK system variable is

set to 1. If no attribute named attrName exists in elementRef, an error is
returned and the OK system variable is set to 0.
4D v12 Upgrade 251

Chapter 5 Language
` Given the following structure:
The following code removes the first attribute "N=1":

C_BLOB(myBlobVar)
C_STRING(16;$xml_Parent_Ref;$xml_Child_Ref)
C_LONGINT($LineNum)
$xml_Parent_Ref:=DOM Parse XML variable (myBlobVar)

$xml_Child_Ref:=DOM Get first child XML element ($xml_Parent_Ref)
DOM REMOVE XML ATTRIBUTE($xml_Child_Ref;"N")
See Also: DOM GET XML ATTRIBUTE BY INDEX, DOM GET XML ATTRIBUTE
BY NAME
DOM SET XML DOM SET XML DECLARATION (elementRef; encoding{; standalone{; inden-
DECLARATION tation}}))
encoding String Æ XML document character set (UTF-8 by
default)
standalone Boolean Æ True= document is standalone,
False (default)=document is not standa-
lone
indentation Boolean Æ Obsolete, do not use
Compatibility notes • The DOM SET XML DECLARATION command was named DOM SET
XML OPTIONS in previous versions of 4D.
• The DOM options no longer depend on SAX options.
The indentation parameter is kept for reasons of compatibility with

previous versions of 4D but we do not recommend its use in 4D v12.
From now on, to specify the indentation of the document, it is
strongly recommended to use the new XML SET OPTIONS command.
252 4D v12 Upgrade

XML SAX
XML SAX
Three commands of the XML SAX theme have been modified. Due to
the implementation of the XML SET OPTIONS and XML GET OPTIONS
commands, the existing SAX SET XML OPTIONS command has been
renamed SAX SET XML DECLARATION and its functioning has been
adapted.
SAX GET XML SAX GET XML ELEMENT VALUE(document; value)

ELEMENT VALUE
Just like the DOM GET XML ELEMENT VALUE command, 4D attempts to
convert the value obtained to the type of the variable passed as
parameter. If the type is BLOB, the command automatically attempts
to decode it into Base64.
See Also: DOM GET XML ELEMENT VALUE
SAX OPEN XML SAX OPEN XML ELEMENT ARRAYS (document; tab{; attrNamesArray; attr-
ELEMENT ARRAYS ValuesArray}{; attrNamesArray2; attrValuesArray2; ...; attrNamesArrayN;
attrValuesArrayN})
Besides text type arrays, the SAX OPEN XML ELEMENT ARRAYS
command now accepts date, number, Boolean and picture arrays as
attrValuesArray parameter(s). 4D automatically carries out the necessary
conversions; you can modify these conversions using the new XML SET
OPTIONS command.
4D v12 Upgrade 253

Chapter 5 Language
SAX SET XML SAX SET XML DECLARATION (document; encoding{; standalone{; indenta-
DECLARATION tion}})
document DocRef Æ Reference of open document
encoding String Æ XML document character set (UTF-8 by
default)
standalone Boolean Æ True= document is standalone,
False (default)=document is not standa-
lone
indentation Boolean Æ Obsolete, do not use
Compatibility notes • The SAX SET XML DECLARATION command was named SAX SET XML
OPTIONS in previous versions of 4D.
• The SAX options are now valid only for the open document and are
no longer kept after closing this document.
The indentation parameter is kept for reasons of compatibility with

previous versions of 4D but its use is not recommended in 4D v12.
From now on, to specify the indentation of the document, it is
strongly recommended to use the new XML SET OPTIONS command.
New system variables

Two new system variables are available in 4D v12. Used in the
framework of an on-error method, these variables can be used to
precisely determine the error source:
Error method: Text type system variable. This variable contains the full
name of the method that triggered the error.
Error line: Longint type system variable. This variable contains the line
number at the origin of the error in the method that triggered the
error.
Following the example of the existing Error variable, these two

variables can only be used during the execution of an error-catching
method installed by the ON ERR CALL command.
If you would like to be able to access these variables in the method that
caused the error, you will need to copy their value into your own
process variable.
254 4D v12 Upgrade

Dynamic variables
Dynamic variables
You can now leave it to 4D to create variables associated with your
form objects (buttons, enterable variables, check boxes, etc.)
dynamically and according to your needs. To do this, simply leave the
"Variable Name" field blank in the Property list for the object:
Variable Name left blank
When a variable is not named, when the form is loaded, 4D creates a

new variable for the object, with a calculated name that is unique in
the space of the process variables of the interpreter (which means that
this mechanism can be used even in compiled mode). This temporary
variable will be destroyed when the form is closed.
For this principle to work in compiled mode, it is imperative that

dynamic variables are explicitly typed using the "Variable Type" menu
of the Property list. If you specify a dynamic variable (variable that is
not named) and select the value None in the "Variable Type" menu, a
typing error will be returned by the compiler.
Note As in previous versions of 4D, when the variable is named, the

"Variable Type" menu does not actually type the variable but simply
allows the options of the Property list to be updated (except for picture
variables). To type a named variable, it is necessary to use the language.
In 4D code, dynamic variables can be accessed via a pointer that is

obtained using the OBJECT Get pointer command. For example:
// assign the time 12:00:00 to the variable of the "hstart" object
$p: = Object Get pointer(Object named;"hstart")
$p->: = ?12:00:00?
4D v12 Upgrade 255

Chapter 5 Language
The advantage of this new mechanism is twofold:

On the one hand, it allows the development of "subform" type
components that can be used several times in the same host form. Let
us take as an example the case of a datepicker subform that is inserted
twice in a host form to set a start date and an end date. This subform
will use objects for choosing the date of the month and the year. It will
be necessary for these objects to work with different variables for the
start date and the end date. Letting 4D create their variable with a
unique name is a way of resolving this difficulty.
On the other hand, it can be used to limit memory usage. In fact, form
objects only work with process or inter-process variables. However, in
compiled mode, an instance of each process variable is created in all
the processes, including the server processes. This instance takes up
memory, even when the form is not used during the session.
Therefore, letting 4D create variables dynamically when loading the
forms can economize memory.
Notes • When there is no variable name, the object name is shown in

quotation marks in the form editor.
• This mechanism is available for all the objects associated with a
variable name except for list boxes.
Constants
Additional functionalities can be accessed via new constants described
in this section.
Form Events Two new form events have been added in the "Form Events" theme:
Constant Type Value Description
On bound variable Longint 54 Generated when the variable
change bound to a subform is modified.
See the “Management of the
bound variable” paragraph on
page 74.
On Mac toolbar Longint 55 Generated when the user clicks
button on the toolbar management
button under Mac OS. See the
“Toolbar button (Mac OS)”
256 4D v12 Upgrade

4D Widgets
Open window The new Has toolbar button Mac OS constant displays a toolbar
management button in a window created under Mac OS (see the
“Toolbar button (Mac OS)” paragraph on page 118).
The Metal Look constant has been renamed Texture appearance, in
conformity with the evolution of the Mac OS interface (the "Metal
Look" option of the Form editor Property List has also been renamed
"Textured (under Mac OS)").
Constant Type Value
Has toolbar button Mac OS Longint 8192
Texture appearance Longint 2048
` Example of use:
$NewWin:=Open window(10;10;1010;810;Plain window+Has toolbar
button Mac OS)
Note The Has toolbar button Mac OS constant can also be used with the
Open form window command.
System Documents A new constant has been added to the "System Documents" theme:
Folder separator. This constant has a different value depending on the
operating system from which it is called:
Constant Type Value
Folder separator String \ (Windows) or
: (Mac OS)
This constant can be used to build valid pathnames without taking the
operating platform into account.
4D Widgets
4D v12 integrates high-level form objects that are provided via a new
component called 4D Widgets. These objects are described in the
“Widgets” paragraph on page 82.
4D v12 Upgrade 257

Chapter 5 Language
This component can be configured using specific project methods

listed on the Methods page of the Explorer:
This section describes the syntax of these methods.
DatePicker The DatePicker component provides intuitive graphic interface objects

for entering and displaying dates in forms. For more information, refer
to the “DatePicker” paragraph on page 84.
Component methods can be used to customize the functioning of

these objects. The DatePicker Display Dialog command is used to display
a DatePicker calendar object in the form of a pop-up menu.
DatePicker APPLY DatePicker APPLY DEFAULT VALUES(objectName)

DEFAULT VALUES
objectName Text Æ Name of subform object
The DatePicker APPLY DEFAULT VALUES command resets all the

DatePicker parameters to their default values for the objectName
subform object.
258 4D v12 Upgrade

4D Widgets
These default values may be the factory settings but may also have
been modified via the SET DEFAULT commands of the component.
The action of this command is immediate: the default values of
objectName are instantly modified. Note that the variable associated
with the object could also be modified in order to take the new values
into account. For example, if the new default values set the minimum
date to 01/01/2000 and the variable associated with objectName was
05/05/1995, its value is automatically returned to 01/01/2000
The DatePicker parameters include:

minimum or maximum enterable dates
the first day of the week
weekly and yearly "days off" as well as specific holidays
` This example resets the parameters of the Date1 object to their default
settings:
DatePicker APPLY DEFAULT VALUES ("Date1")
DatePicker Display DatePicker Display Dialog {(top; left)} Æ Date

Dialog
top Longint Æ Location for top of window
left Longint Æ Location for left side of window
Function result Date Å Date selected by user
The DatePicker Display Dialog command opens a DatePicker calendar in

a pop-up window (a pop-up type window is automatically closed when
the user clicks outside the window or hits the Enter or Esc key).
The two optional parameters specify the location of the top left corner
of the window to be opened. These two parameters must be passed
together; if only one is passed, it is ignored.
If these parameters are omitted, the window is opened at the location
of the click.
The function returns the date selected by the user in the DatePicker
calendar. If the window is closed without a date being selected, the
command returns a blank date.
4D v12 Upgrade 259

Chapter 5 Language
` This example displays a DatePicker calendar when a button is clicked:

OBJECT GET COORDINATES (*;"MyCalendarButton";$x1;$y1;$x2;$y2)
$MyLocalDate:=DatePicker Display Dialog ($x1;$y1)
If($MyLocalDate #!00/00/00!)
[Event]DateRV:=$MyLocalDate
End if
DatePicker RESET DatePicker RESET DEFAULT VALUES

DEFAULT VALUES
The DatePicker RESET DEFAULT VALUES command resets the parameters

of the DatePicker component to their "factory settings". After
executing this command:
the minimum or maximum enterable dates are 00/00/00 (meaning
there are no limits)
the first day of the week is 2 (Monday)
the weekly "days off" are Saturday and Sunday
no yearly "days off" or specific holidays are set.
Note that this setting is only taken into account for calendars created
subsequently and is not applied to any existing calendars. If you want
to apply it to existing calendars, you must use the DatePicker APPLY
DEFAULT VALUES command.
DatePicker SET DAYS DatePicker SET DAYS OFF (objectName; dayType; ptrHolidaysArray)
OFF
dayType Longint Æ Types of days off
ptrDaysOffArray Pointer Æ Pointer to date or Boolean array of
days off
The DatePicker SET DAYS OFF command sets the days off to be shown in
the DatePicker calendar. These days appear in bold and italic and
remain selectable for the user.
The objectName parameter specifies the instance of the subform to

which the command must be applied. In this parameter, you must pass
the name of a subform object displayed in the current form.
260 4D v12 Upgrade

4D Widgets
This command can be used to set either recurrent weekly or yearly days
off as well as occasional holidays. You specify the type of days off set
via the dayType parameter:
0 = Days off occurring weekly (by default, Saturday and Sunday)
1 = Days off that occur every year (such as January 1st or December
25th)
2= Occasional holidays, set for a single year.
You set the holidays by creating a array and by passing a pointer to this
array as the ptrDaysOffArray parameter. The type of array depends on
the value passed in dayType:
If you pass 0 in dayType (weekly days off), in ptrDaysOffArray you
must pass a pointer to a Boolean array made up of 7 elements. Each
element set to True indicates a weekly day off.
If you pass 1 or 2 in dayType (yearly or occasional days off), in
ptrDaysOffArray you must pass a pointer to a Date array. In this
array, each element must contain a valid date, indicating a day off.
The dates must be expressed in the default format corresponding to
the system language. If you passed 1 in dayType (recurrent days), the
year is ignored; you can pass any value.
` Designation of Friday as the weekly day off (instead of Saturday and

Sunday by default):
ARRAY BOOLEAN ($arrbDaysOff;7)
//By default, all the elements of a Boolean array are False; thus it is
//not necessary to add initialization code
$arrbDaysOff{Friday }:=True
DatePicker SET DAYS OFF ("mycalendar";0;->$arrbDaysOff)
4D v12 Upgrade 261

Chapter 5 Language
` Designating occasional holidays:

ARRAY DATE($arrdUniqueDays;0)
//The year is taken into account
APPEND TO ARRAY($arrdUniqueDays;!02/15/2008!)
DatePicker SET DAYS OFF (1;->$arrdUniqueDays)
See Also: DatePicker SET WEEK FIRST DAY, DatePicker SET DEFAULT DAYS
OFF
DatePicker SET DEFAULT DatePicker SET DEFAULT 1ST DAY(dayNum)

1ST DAY
dayNum Longint Æ First day of the week
The DatePicker SET DEFAULT 1ST DAY command sets the first day of the
week to be displayed by default in the left part of all DatePicker
calendars.
Note that this parameter is only taken into account for calendars
created subsequently and does not apply to any existing calendars. If
you want to apply it to existing calendars, you must use the DatePicker
APPLY DEFAULT VALUES command.
See Also: DatePicker SET MAX DATE, DatePicker SET DEFAULT MIN DATE
DatePicker SET DEFAULT DatePicker SET DEFAULT DAYS OFF (dayType; ptrDaysOffArray)
DAYS OFF
dayType Longint Æ Types of days off
ptrDaysOffArray Pointer Æ Pointer to date or Boolean array of
days off
The DatePicker SET DEFAULT DAYS OFF command sets the days off that
will appear in all the calendars of the DatePicker component. These
days appear in bold and italic and remain selectable for the user.
Note that this setting is only taken into account for calendars that are
you want to apply it to the existing calendars, you will need to use the
DatePicker APPLY DEFAULT VALUES command.
262 4D v12 Upgrade

4D Widgets
The command can be used to set recurrent weekly or yearly days off as
well as occasional holidays. You specify the type of days off set by the
method via the dayType parameter:
0 = Days off occurring weekly (by default, Saturday and Sunday)
1 = Days off that occur every year (such as January 1st or December
25th)
2 = Occasional holidays, set for a single year
You set the holidays by creating a array and by passing a pointer to this
array as the ptrDaysOffArray parameter. The type of array depends on
the value passed in dayType:
If you pass 0 in dayType (weekly days off), in ptrDaysOffArray you
must pass a pointer to a Boolean array made up of 7 elements. Each
element set to True indicates a weekly day off.
If you pass 1 or 2 in dayType (yearly or occasional days off), in
ptrDaysOffArray you must pass a pointer to a Date array. In this
array, each element must contain a valid date, indicating a day off.
The dates must be expressed in the default format corresponding to
the system language. If you passed 1 in dayType (recurrent days), the
year is ignored; you can pass any value.
` Designating recurrent holidays (example valid for the USA):

ARRAY DATE($arrdRepeatedDays;0)
//The year is ignored; we use 2000 by default
APPEND TO ARRAY($arrdRepeatedDays;!01/01/2000!)
DatePicker SET DEFAULT DAYS OFF (1;->$arrdRepeatedDays)
See Also: DatePicker SET DAYS OFF
4D v12 Upgrade 263

Chapter 5 Language
DatePicker SET DEFAULT DatePicker SET DEFAULT MAX DATE (maxDate)

MAX DATE
maxDate Date Æ Upper limit of enterable date
The DatePicker SET DEFAULT MAX DATE command sets the maximum
enterable day for all the calendars of the DatePicker component.
See Also: DatePicker SET MAX DATE, DatePicker SET DEFAULT MIN DATE
DatePicker SET DEFAULT DatePicker SET DEFAULT MIN DATE (minDate)

MIN DATE
minDate Date Æ Lower limit of enterable date
The DatePicker SET DEFAULT MIN DATE command sets the minimum
enterable day for all the calendars of the DatePicker component.
` Designating the minimum date as January 1, 2000:

DatePicker SET DEFAULT MIN DATE (!01/01/2000!)
See Also: DatePicker SET MIN DATE, DatePicker SET DEFAULT MAX DATE
DatePicker SET MAX DatePicker SET MAX DATE (objectName; maxDate)

DATE
maxDate Date Æ Upper limit of enterable date
The DatePicker SET MAX DATE command specifies the maximum

enterable date in the DatePicker calendar (the days located after this
maximum date appear grayed out in the calendar).
264 4D v12 Upgrade

4D Widgets
The objectName specifies the instance of the subform to which the

command must be applied. In this parameter, you must pass the name
of a subform object displayed in the current form.
The maxDate date must be expressed in the default entry format

corresponding to the system language. If you pass a blank date
(!00/00/00!), all the dates that follow the current date are enterable.
Note If the maximum enterable date is earlier than the minimum enterable
date (see DatePicker SET MIN DATE), no date will be enterable.
` Disabling all dates after December 31, 2009 in the object named
"ReturnDate":
DatePicker SET MAX DATE("ReturnDate";!12/31/2009!)
See Also: DatePicker SET MIN DATE
DatePicker SET MIN DatePicker SET MIN DATE (objectName; minDate)

DATE
minDate Date Æ Lower limit of enterable date
The DatePicker SET MIN DATE command sets the minimum enterable
date in a DatePicker calendar (the days located before this minimum
date appear grayed out in the calendar).

The minDate date must be expressed in the default entry format

corresponding to the system language. If you pass a blank date
(!00/00/00!), all the dates preceding the current date are enterable.
Note If the minimum enterable date is later than the maximum enterable
date (see DatePicker SET MAX DATE), no date will be enterable.
4D v12 Upgrade 265

Chapter 5 Language
` The current form contains two DatePicker calendars located in two

subform objects named "DP1" and "DP2".
//Disabling all dates before January 1, 2009 in the first calendar
DatePicker SET MIN DATE("DP1";!01/01/2009!)
//Disabling all dates before March 1st, 2009 in the second calendar
DatePicker SET MIN DATE("DP2";!03/01/2009!)
See Also: DatePicker SET MAX DATE
DatePicker SET WEEK DatePicker SET WEEK FIRST DAY (objectName; dayNum)
FIRST DAY
dayNum Longint Æ Number of first day to display
The DatePicker SET WEEK FIRST DAY command sets the first day of the
week to display in the left part of a DatePicker calendar. By default, the
first day is Monday.

Pass a 4D constant from the "Days and Months" theme in the dayNum
parameter.
` Setting first day to Sunday:

DatePicker SET WEEK FIRST DAY("mycalendar";Sunday)
266 4D v12 Upgrade

4D Widgets
` Setting first day to Thursday:

DatePicker SET WEEK FIRST DAY("mycalendar";Thursday)
See Also: DatePicker SET DAYS OFF
SearchPicker The SearchPicker component is used to insert standard search areas in

your forms. For more information, refer to the “SearchPicker”
The method of this component sets the help text of the area.
SearchPicker SET HELP SearchPicker SET HELP TEXT (helpText)

TEXT
helpText Text Æ Text to display
The SearchPicker SET HELP TEXT command displays a non-enterable

grayed-out text in the background of the search area specified by
objectName. This text disappears when the user clicks in the area.
` Displays the word "Country" in the area, indicating that the search will
concern this variable:
C_TEXT(vCountry)
SearchPicker SET HELP TEXT("vSearch";"Country")
TimePicker The TimePicker component provides graphic objects for the entry and
display of times in forms. For more information, refer to the
“TimePicker” paragraph on page 87.
The methods of this component are used to customize the functioning

of these objects.
4D v12 Upgrade 267

Chapter 5 Language
TimePicker APPLY TimePicker APPLY DEFAULT VALUES (objectName)

DEFAULT VALUES
The TimePicker APPLY DEFAULT VALUES command resets all the

TimePicker parameters to their current default values for the
objectName subform object.
These default values may be the factory settings but may also have
been modified via the SET DEFAULT commands of the component.
The action of this command is immediate: the default values of
objectName are instantly modified. Note that the bound variable of the
object could also be modified in order to take the new values into
account. For example, if the new default values set the minimum time
to 07:00:00 and the value of the variable bound with objectName was
06:00:00, its value is automatically returned to 07:00:00.
The TimePicker parameters include:

minimum or maximum enterable times,
the AM and PM labels,
the steps in minutes.
See Also: TimePicker RESET DEFAULT VALUES
TimePicker RESET TimePicker RESET DEFAULT VALUES

DEFAULT VALUES
The TimePicker RESET DEFAULT VALUES command resets the parameters

of the TimePicker component to their "factory settings". After
execution of this command:
the minimum enterable time is 08:00:00
the maximum enterable time is 20:00:00
the AM and PM labels are the system labels
the steps in minutes is 00:15:00
Note that this parameter is only taken into account for TimePicker
objects created subsequently and does not apply to any existing
objects. If you want to apply it to existing objects, you must use the
TimePicker APPLY DEFAULT VALUES command.
268 4D v12 Upgrade

4D Widgets
TimePicker SET DEFAULT TimePicker SET DEFAULT LABEL AM (label)

LABEL AM
label Text Æ Label to use for AM
The TimePicker SET DEFAULT LABEL AM command modifies the default

"AM" label in all the TimePicker objects displaying the AM/PM format.
This setting is only taken into account for objects created subsequently
and does not apply to any existing objects. If you want to apply it to
existing objects, you must use the TimePicker APPLY DEFAULT VALUES
command.
See Also: TimePicker SET LABEL AM
TimePicker SET DEFAULT TimePicker SET DEFAULT LABEL PM (label)

LABEL PM
label Text Æ Label to use for PM
The TimePicker SET LABEL PM command modifies the default "PM" label
in all the TimePicker objects displaying the AM/PM format.
command.
See Also: TimePicker SET LABEL PM
TimePicker SET DEFAULT TimePicker SET DEFAULT MAX TIME (maxTime)

MAX TIME
maxTime Time Æ Upper limit of enterable time
The TimePicker SET DEFAULT MAX TIME command specifies the

maximum enterable time that will be allowed by default for all the
TimePicker objects.
4D v12 Upgrade 269

Chapter 5 Language
command.
See Also: TimePicker SET MIN TIME
TimePicker SET DEFAULT TimePicker SET DEFAULT MIN TIME (minTime)

MIN TIME
minTime Time Æ Lower limit of enterable time
The TimePicker SET DEFAULT MIN TIME command specifies the

minimum enterable time that will be allowed by default for all the
TimePicker objects.
command.
See Also: TimePicker SET MAX TIME
TimePicker SET DEFAULT TimePicker SET DEFAULT STEP (step)

STEP
step Time Æ Interval between two time values
The TimePicker SET DEFAULT STEP command sets the step between time
values for all the TimePicker objects.
command.
See Also: TimePicker SET STEP
270 4D v12 Upgrade

4D Widgets
TimePicker SET LABEL TimePicker SET LABEL AM (objectName; label)

AM
label Text Æ Label to use for AM
The TimePicker SET LABEL AM command modifies the "AM" label in

TimePicker objects displaying the AM/PM format. The command
applies to the object designated by objectName. By default, the system
am/pm labels are used.
` Using "in the morning" by default instead of the system label for AM:
TimePicker SET LABEL AM("clock"; "in the morning")
See Also: TimePicker SET LABEL PM
TimePicker SET LABEL TimePicker SET LABEL PM (objectName; label})

PM
label Text Æ Label to use for PM
The TimePicker SET LABEL PM command modifies the "PM" label in

TimePicker objects displaying the AM/PM format. The command
applies to the object designated by objectName. By default, the system
am/pm labels are used.
` Using "in the evening" by default instead of the system label for PM:
TimePicker SET LABEL PM("clock"; "in the evening")
See Also: TimePicker SET LABEL AM
TimePicker SET MAX TimePicker SET MAX TIME (objectName; maxTime)

TIME
maxTime Time Æ Upper limit of enterable time
The TimePicker SET MAX TIME command sets the maximum enterable
time that will be accepted by the object designated by objectName. If a
higher time value is entered, it will not be accepted.
See Also: TimePicker SET MIN TIME
4D v12 Upgrade 271

Chapter 5 Language
TimePicker SET MIN TimePicker SET MIN TIME (objectName; minTime)

TIME
minTime Time Æ Lower limit of enterable time
The TimePicker SET MIN TIME command sets the minimum enterable
time that will be accepted by the object designated by objectName. If a
lower time value is entered, it will not be accepted.
See Also: TimePicker SET MAX TIME
TimePicker SET STEP TimePicker SET STEP (objectName; step)

step Time Æ Interval between two time values
The TimePicker SET STEP command sets the step between time values
available for the object designated by objectName. This parameter only
applies to TimePickers displayed as pop-up menus.
The step value must be included between 1 minute and 1 hour and
must be shown as whole divisions of 60 minutes. In practice, only the
values 1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30 and 60 min are possible. Any
other value will automatically be rounded off in order to correspond to
this principle.
` Configuration of the TimePicker in the form of a pop-up menu named

"time1", limitation of enterable times from 8:30 to 16:30 with 10-
minute steps:
TimePicker SET MIN TIME ("time1";?08:30:00?)
TimePicker SET MAX TIME ("time1";?16:30:00?)
TimePicker SET STEP ("time1";?00:10:00?)
272 4D v12 Upgrade

4D SVG
4D SVG
Version 12 of the 4D SVG component includes several new commands
as well as a few modified commands. All these commands will be
covered in the following paragraphs.
Attributes
SVG_SET_CLASS SVG_SET_CLASS (svgObject; class)
svgObject SVG_Ref Æ Reference of SVG element
class Text Æ Name of class
The SVG_SET_CLASS command sets the class for the object passed in
svgObject. An error is generated if svgObject is not a valid reference.
` Refer to the example for the SVG_Define_style command.
See Also: http://www.w3.org/TR/SVG/styling.html#ClassAttribute
SVG_SET_CLIP_PATH SVG_SET_CLIP_PATH (svgObject; clipPathID)

clipPathID Text Æ Name of clip path
The SVG_SET_CLIP_PATH command sets the clip path named clipPathID

for the object passed in svgObject. An error is generated if svgObject is
not a valid reference or if the clip path is not defined.
` Defining a circular clip path that will then be assigned to an image.

//Defining a circular clip path
$Dom_clipPath:=SVG_Define_clip_path ($Dom_SVG;"theClip")
$Dom_circle:=SVG_New_circle ($Dom_clipPath;150;100;100)
//Creating a group
$Dom_g:=SVG_New_group ($Dom_SVG)
//Inserting an image
$Txt_path:= Get 4D folder(6)+"logo.svg"
READ PICTURE FILE($Txt_path;$Pic_buffer)
$Dom_picture:=SVG_New_embedded_image ($Dom_g;$Pic_buffer)
SVG_SET_ID ($Dom_picture;"MyPicture")
4D v12 Upgrade 273

Chapter 5 Language
//Applying clip path to group

SVG_SET_CLIP_PATH ($Dom_g;"theClip")
` The same image with a rectangular clip path with rounded corners:
//Defining a rectangular clip path
$Dom_clipPath:=SVG_Define_clip_path ($Dom_SVG;"theClip")
$Dom_rect:=SVG_New_rect ($Dom_clipPath;5;10;320;240;10;10)
//Creating a group
//Inserting an image
$Txt_path:= Get 4D folder(6)+"logo.svg"
READ PICTURE FILE($Txt_path;$Pic_buffer)
$Dom_picture:=SVG_New_embedded_image ($Dom_g;$Pic_buffer)
SVG_SET_ID ($Dom_picture;"MyPicture")
//Applying clip path to group

SVG_SET_CLIP_PATH ($Dom_g;"theClip")
See Also: http://www.w3.org/TR/2001/REC-SVG-20010904/mas-

king.html#EstablishingANewClippingPath
274 4D v12 Upgrade

4D SVG
SVG_SET_FILL_RULE SVG_SET_FILL_RULE (svgObject; fillRule)

fillRule Text Æ Mode for filling object
The SVG_SET_FILL_RULE command specifies the fill rule for the SVG
object designated by svgObject. An error is generated if svgObject is not a
valid reference.
The fillRule parameter must contain one of the following values:

"nonzero", "evenodd" or "inherit". Otherwise, an error is generated.
` Illustration of filling modes:

//Creating a path with the 'evenodd' fill rule
$Dom_path:=SVG_New_path ($Dom_SVG;250;75)
SVG_PATH_LINE_TO ($Dom_path;323;301;131;161;369;161;177;301)
SVG_PATH_CLOSE ($Dom_path)
SVG_SET_FILL_BRUSH ($Dom_path;"red")
SVG_SET_STROKE_WIDTH ($Dom_path;3)
SVG_SET_FILL_RULE ($Dom_path;"evenodd")
//Creating a similar object with the 'nonzero' fill rule

$Dom_path:=SVG_New_path ($Dom_SVG;250;75)
SVG_PATH_LINE_TO ($Dom_path;323;301;131;161;369;161;177;301)
SVG_SET_STROKE_WIDTH ($Dom_path;3)
SVG_SET_FILL_RULE ($Dom_path;"nonzero")
//Horizontal movement
SVG_SET_TRANSFORM_TRANSLATE ($Dom_path;300)
See Also: http://www.w3.org/TR/SVG/painting.html#FillRuleProperty
4D v12 Upgrade 275

Chapter 5 Language
SVG_SET_SHAPE_RENDER SVG_SET_SHAPE_RENDERING (svgObject; rendering)

ING
rendering Text Æ Type of rendering
The SVG_SET_SHAPE_RENDERING command is used to set which

tradeoffs should be made regarding the rendering of graphic elements
for the object designated by svgObject. If svgObject is not an SVG object,
an error is generated.
The rendering parameter must contain one of the following values:

"auto", "optimizeSpeed", "crispEdges", "geometricPrecision" or "inherit".
Otherwise, an error is generated.
See Also: http://www.w3.org/TR/2001/REC-SVG-20010904/pain-

ting.html#ShapeRenderingProperty
SVG_SET_STROKE_DASH SVG_SET_STROKE_DASHARRAY (svgObject; dash ;value1{ ;...; valueN})

ARRAY
dash Real Æ Length of first dash
value1...N Longint Æ Length of spaces and dashes
The SVG_SET_STROKE_DASHARRAY command sets the pattern of dashes

and gaps used to outline the path of the SVG object passed in svgObject.
If svgObject is not a valid SVG reference, an error is generated.
The whole value of the dash parameter indicates the length of the first
dash of the dotted pattern. If the value1 to valueN parameters are
omitted, the dotted line will consists of a series of dashes and gaps of
the same length.
The decimal value of the dash parameter, if it is not null, indicates the
distance into the pattern from which the dashes will start.
If dash is 0, the dotted pattern is removed.
The value1 to valueN parameters alternately specify the lengths of the

gaps and dashes that follow the first dash. If an odd number of values
is given (including the first dash), the list of values is repeated until it
produces an even number of values.
276 4D v12 Upgrade

4D SVG
` Illustrations of a dotted line path:

//Line
$Dom_line:=SVG_New_line ($Dom_SVG;10;10;500;500)
SVG_SET_STROKE_WIDTH ($Dom_line;10)
SVG_SET_STROKE_DASHARRAY ($Dom_line;8,099)
SVG_SET_STROKE_BRUSH ($Dom_line;"red")
//Rectangle
$Dom_rect:=SVG_New_rect ($Dom_SVG;25;30;320;240;10;10;"red";
"yellow:30")
SVG_SET_STROKE_WIDTH ($Dom_rect;5)
SVG_SET_STROKE_DASHARRAY ($Dom_rect;2)
//Circle
$Dom_circle:=SVG_New_circle ($Dom_SVG;350;400;100;"blue";"none")
SVG_SET_STROKE_DASHARRAY ($Dom_circle;2;4;6;8)
See Also: http://www.w3.org/TR/SVG/painting.html#StrokeProperties
SVG_SET_STROKE_MITER SVG_SET_STROKE_MITERLIMIT (svgObject; join)

LIMIT
join Longint Æ Value of join
The SVG_SET_STROKE_MITERLIMIT command sets the limit for the

length of the miter join between the path and the outline of the SVG
object designated by svgObject. If svgObject is not a valid SVG reference,
4D v12 Upgrade 277

Chapter 5 Language
If the join parameter is -1, the value will be the default value (4). If the
join parameter is 0, then the definition of the attribute is removed. Any
other value < 0 will cause an error.
See Also: http://www.w3.org/TR/SVG/painting.html#StrokeProperties
Colors and
Gradients
SVG_Color_RGB_from_ SVG_Color_RGB_from_CMYK (cyan ; magenta ; yellow ; black {; format} )

CMYK
Æ Function result
cyan Longint Æ Cyan value
magenta Longint Æ Magenta value
yellow Longint Æ Yellow value
black Longint Æ Black value
format Longint Æ Color format
Function result Text Å Color string
The SVG_Color_RGB_from_CMYK command returns a string expressing

the color corresponding to the four color parameters, cyan, magenta,
yellow and black, passed as arguments. The string returned is in the
form "RGB(red,greeen,blue)" by default, the syntax recognized by SVG
rendering engines.
cyan, magenta, yellow and black are longints included between 0 and
100%.
The optional format parameter specifies the desired format for the color
string returned. The values are:
Vakue Format
1 (default) rgb(r,g,b)
2 #rgb
3 #rrggbb
4 rgb(r%, g%, b%)
278 4D v12 Upgrade

4D SVG
SVG_Color_RGB_from_ SVG_Color_RGB_from_HLS (hue ; luminosity ; saturation {; format} ) Æ

HLS
Function result
hue Longint Æ Hue value
luminosity Longint Æ Luminosity value
saturation Longint Æ Saturation value
format Longint Æ Color format
Function result Text Å Color string
The SVG_Color_RGB_from_HLS command returns a string expressing

the color corresponding to the hue, luminosity and saturation
parameters passed as arguments. The string returned is in the form
"RGB(red,green,blue)" by default, the syntax recognized by SVG
rendering engines.
hue is a longint included between 0 and 360°.
luminosity and saturation are longints included between 0 and 100%.
The optional format parameter specifies the desired format for the color
string returned. The values are:
Value Format
1 (default) rgb(r,g,b)
2 #rgb
3 #rrggbb
4 rgb(r%, g%, b%)
SVG_GET_COLORS_ARRAY SVG_GET_COLORS_ARRAY (colorNamesArrayPointer)

colorNamesArrayPointer Pointer Æ Pointer to array receiving color
names
The SVG_GET_COLORS_ARRAY command fills in the array pointed to by

the colorNamesArrayPointer parameter with the names of colors
recognized by SVG.
See Also: http://www.w3.org/TR/SVG/types.html#ColorKeywords
4D v12 Upgrade 279

Chapter 5 Language
Drawing
SVG_Add_object SVG_Add_object (targetSVGObject ; sourceSVGObject )Æ Function result

targetSVGObject SVG_Ref Æ Reference of parent element
sourceSVGObject SVG_Ref Æ Reference of object to be added
Function result SVG_Ref Å Reference of SVG object
The SVG_Add_object command places an SVG object designated by

sourceSVGObject in the SVG container designated by targetSVGObject
and return its reference. The SVG container can be the root of the
document or any other reference to an SVG object that is able to
contain this type of element.
Structure and
Definitions
SVG_Define_clip_path SVG_Define_clip_path (parentSVGObject; clipPathID) Æ Function result

parentSVGObject SVG_Ref Æ Reference of parent element
clipPathID Text Æ Name of clip path
Function result SVG_Ref Å Reference of clip path
The SVG_Define_clip_path command specifies a new clip path in the

SVG container designated by parentSVGObject and returns its reference.
If parentSVGObject is not (or does not belong to) an SVG document, an
error is generated.
The clipPathID parameter designates the name of the clip path. This
name will be used to associate a clip path with an object. If an element
with the same name already exists in the document, an error is
generated.
` Refer to the example of the SVG_SET_CLIP_PATH command.
See Also: http://www.w3.org/TR/2001/REC-SVG-20010904/mas-

king.html#EstablishingANewClippingPath
280 4D v12 Upgrade

4D SVG
SVG_Define_pattern SVG_Define_pattern (parentSVGObject; patternID{; width {; height {; x {; y

{; unit {; viewBox}}}}}}) Æ Function result
patternID Text Æ Name of pattern
width Longint Æ Width of pattern
height Longint Æ Height of pattern
x Longint Æ Position X of pattern
y Longint Æ Position Y of pattern
unit Text Æ Unit of lengths and positions
viewBox Text Æ Viewbox
Function result SVG_Ref Å Reference of pattern
The SVG_Define_pattern command sets a new custom pattern in the

SVG container designated by parentSVGObject and returns its reference.
If parentSVGObject is not (or does not belong to) an SVG document, an
error is generated.
The patternID parameter specifies the name of the pattern. This name
will be used to associate the pattern with an object. If an element with
the same name already exists, an error is generated.
The optional width, height, x, y, unit and viewBox parameters define the
reference rectangle of the pattern, in other words, the way the pattern
tiles will be placed and spaced.
The pattern will be associated as fill or stroke paint by passing the

"url(#id)" string as the value when a color expression is expected.
` Setting a pattern and using it to fill an ellipse:

//Definition of pattern
$Dom_pattern:=SVG_Define_pattern ($Dom_SVG;"MyPattern";100;100;
0;0;"";"0 0 10 10")
$Dom_path:=SVG_New_path ($Dom_pattern;0;0)
SVG_PATH_MOVE_TO ($Dom_path;0;0)
SVG_PATH_LINE_TO ($Dom_path;7;0)
SVG_PATH_LINE_TO ($Dom_path;3,5;7)
SVG_SET_STROKE_BRUSH ($Dom_path;"blue")
4D v12 Upgrade 281

Chapter 5 Language
//Drawing an ellipse filled with the pattern

$Dom_ellipse:=SVG_New_ellipse($Dom_SVG;400;200;350;150;"black";
"url(#MyPattern)";5)
` Setting a pattern and using it to fill and stroke the outline of an ellipse:
//Definition of pattern
$Dom_pattern:=SVG_Define_pattern ($Dom_SVG;"MyPattern ";80;80;0;
0;"";"0 0 20 20")
$Dom_rect:=SVG_New_rect ($Dom_pattern;0;0;20;20;0;0;"white";"red")
//Drawing an ellipse
$Dom_ellipse:=SVG_New_ellipse ($Dom_SVG;400;200;350;150)
//Using pattern for filling and outline

SVG_SET_FILL_BRUSH ($Dom_ellipse;"url(#MyPattern)")
SVG_SET_STROKE_BRUSH ($Dom_ellipse;"url(#MyPattern)")
See Also: http://www.w3.org/TR/SVG/pservers.html#Patterns
282 4D v12 Upgrade

4D SVG
SVG_Define_style SVG_Define_style (parentSVGObject ; style { ; type {; media}}) Æ Function

result
style Text Æ Definition of style OR
Pathname of file to use
type Text Æ Type of content
media Text Æ Media descriptor
Function result SVG_Ref Å Reference of style
The SVG_Define_style command sets a new style sheet in the SVG

container designated by parentSVGObject and returns its reference. If
parentSVGObject is not (or does not belong to) an SVG document, an
error is generated.
The style parameter embeds style sheets directly within SVG content:
If the style parameter contains a valid pathname to a CSS file, the style
definition is done using a mechanism referencing external style sheets.
The path, if it begins with the # character or by the string "file:",
expresses a relative path whose root is the "Resources" folder of the
database.
The style parameter can also be an URL of the "http://… " type; in this
case, the style sheet will be referenced as an external resource.
The optional type parameter specifies the language of the style sheet for
the contents of the element. The default value is "text/css".
The optional media parameter specifies the intended destination media

for the style information. If you omit this parameter, the default value
used is "all". If the value is not included in the list of media types
recognized by CSS2, an error is generated.
4D v12 Upgrade 283

Chapter 5 Language
` Setting an embedded style and overlay of one of the elements:

//Definition of style
$Txt_style:=".colored {fill: yellow; fill-opacity: 0.6; stroke: red;
stroke-width:8; stroke-opacity: 0.6}"
SVG_Define_style ($Dom_SVG;$Txt_style)
//Creating a group and assigning a default style

SVG_SET_CLASS ($Dom_g;"colored")
//Drawing a rectangle
$Dom_rect:=SVG_New_rect ($Dom_g;25;30;320;240;10;10;"";"")
//Drawing a circle and style overlay with a custom outline color

$Dom_circle:=SVG_New_circle ($Dom_g;300;250;100;"";"")
SVG_SET_STROKE_BRUSH ($Dom_circle;"blue")
` Referencing the "mystyle.css" file placed in the "dev" folder of the

"Resources" folder:
//Definition of style
SVG_Define_style ($Dom_svg;"#dev/monstyle.css")
//Creating a group and assigning a default style

SVG_SET_CLASS ($Dom_g;"colored")
//Drawing a rectangle
$Dom_rect:=SVG_New_rect ($Dom_g;25;30;320;240;10;10;"";"")
284 4D v12 Upgrade

4D SVG
mystyle.css file:
.colored {fill: red; fill-opacity: 0.6; stroke: blue; stroke-width:8; stroke-opa-
city: 0.6}
See Also: http://www.w3.org/TR/SVG/styling.html#StyleElement
SVG_DELETE_OBJECT SVG_DELETE_OBJECT (svgObject)

svgObject SVG_Ref Æ Reference of SVG element to be
deleted
The SVG_DELETE_OBJECT command deletes the SVG object designated

by svgObject from the document to which it belongs. An error is
generated when svgObject is not a valid reference.
SVG_Get_default_encod SVG_Get_default_encoding Æ Function result

ing
Function result Text Å Character set
The SVG_Get_default_encoding command returns the encoding used

when a new document is created.
SVG_SET_DEFAULT_EN SVG_SET_DEFAULT_ENCODING {(encoding)}

CODING
encoding Text Æ Character set
The SVG_SET_DEFAULT_ENCODING command sets the encoding that

will be used when subsequent documents are created.
If the encoding parameter is omitted, the command reestablishes the

default character set: "UTF-8".
4D v12 Upgrade 285

Chapter 5 Language
SVG_SET_PATTERN_CON SVG_SET_PATTERN_CONTENT_UNITS (patternObject; sysCoord)

TENT_UNITS
patternObject SVG_Ref Æ Reference of pattern to modify
sysCoord Text Æ System of coordinates to be used
The SVG_SET_PATTERN_CONTENT_UNITS command sets the system of

coordinates for the contents of the pattern designated by patternObject.
If patternObject is not a pattern, an error is generated.
The sysCoord parameter specifies the name of the system to be used. It

must be set to "userSpaceOnUse" or "objectBoundingBox", otherwise
SVG_SET_PATTERN_UNITS SVG_SET_PATTERN_UNITS (patternObject; sysCoord)

patternObject SVG_Ref Æ Reference of pattern to modify
sysCoord Text Æ System of coordinates to be used
The SVG_SET_PATTERN_UNITS command sets the system coordinates

for the x, y, width and height attributes of the pattern designated by
patternObject. If patternObject is not a pattern, an error is generated.
The sysCoord parameter specifies the name of the system to be used. It

must be set to "userSpaceOnUse" or "objectBoundingBox", otherwise
Text
SVG_APPEND_TEXT_TO SVG_APPEND_TEXT_TO_TEXTAREA (svgObject; addedText)

_TEXTAREA
svgObject SVG_Ref Æ Reference of text element
addedText Text Æ Text to be added
The SVG_APPEND_TEXT_TO_TEXTAREA command appends text to the

textual content of the text object designated by svgObject. If svgObject is
not a "textArea" object, an error is generated.
286 4D v12 Upgrade

4D SVG
Line return characters are automatically replaced by "<tbreak/>"

elements.
` Adding text
//Display outlines using 'rect' element
$Dom_rect:=SVG_New_rect ( $Dom_SVG;10;10;500;200;0;0;"blue:50";
"none")
//Creating the text

$Dom_text:=SVG_New_textArea ($Dom_SVG;"It is today, ";10;30;500;200;
"'Arial'";36;0;3)
//Adding the date and 2 CR

SVG_APPEND_TEXT_TO_TEXTAREA ($Dom_text; String(Current date)+
"\r\r")
//Lastly, adding the current time

SVG_APPEND_TEXT_TO_TEXTAREA ($Dom_text;"and it was exactly "+
String(Current time))
SVG_Get_text SVG_Get_text (svgObject) Æ Function result

Paramètre Type Description
Function result Text Å Text contents
The SVG_Get_text command returns the textual content of the element

designated by svgObject. If svgObject is not a text object reference ('text',
'textArea' or 'tspan'), an error is generated.
In the case of a textArea object, <tbreak/> elements are converted to

CRs.
4D v12 Upgrade 287

Chapter 5 Language
SVG_SET_TEXT_KERNING SVG_SET_TEXT_KERNING (svgObject; kerning {; unit })

kerning Real Æ Kerning
unit Text Æ Unit of value
The SVG_Get_text command modifies the kerning for the text object
designated by svgObject. If svgObject is not an SVG text object, an error
is generated.
The optional unit parameter specifies the unit of the kerning value. The
default value is "%".
If kerning is -1, the kerning value is set to 'auto'.
Note Under Windows, the implementation is limited to text from left to

right and top to bottom (disabled for right to left text) and to the 'text'
and 'tspan' elements; under Mac OS, support is not limited.
` Examples of kerning variations:

//Reference
$Dom_text:=SVG_New_text ($Dom_SVG;"Hello world !";20;40;"";36)

SVG_SET_TEXT_KERNING ($Dom_text;0,5)
SVG_SET_TEXT_KERNING ($Dom_text;1)
288 4D v12 Upgrade

4D SVG
See Also: http://www.w3.org/TR/SVG/text.html#KerningProperty
SVG_SET_TEXT_LETTER_ SVG_SET_TEXT_LETTER_SPACING (svgObject; spacing {; unit})

SPACING
spacing Real Æ Letter spacing
unit Text Æ Unit of value
The SVG_SET_TEXT_LETTER_SPACING command modifies the letter

spacing for the text object designated by svgObject in addition to the
spacing due to the 'kerning' property. If svgObject is not an SVG text
object, an error is generated.
The optional unit parameter specifies the unit of the spacing value. The
default value is "%".
If spacing is -1, the spacing value is set to 'normal'.
` Examples of spacing variations:

//Reference

SVG_SET_TEXT_LETTER_SPACING ($Dom_text;1)
SVG_SET_TEXT_LETTER_SPACING ($Dom_text;1;"em")
SVG_SET_TEXT_LETTER_SPACING ($Dom_text;1;"px")
SVG_SET_TEXT_LETTER_SPACING ($Dom_text;1;"pt")
SVG_SET_TEXT_LETTER_SPACING ($Dom_text;1;"pc")
4D v12 Upgrade 289

Chapter 5 Language

SVG_SET_TEXT_LETTER_SPACING ($Dom_text;1;"mm")
SVG_SET_TEXT_LETTER_SPACING ($Dom_text;1;"cm")
SVG_SET_TEXT_LETTER_SPACING ($Dom_text;1;"in")
See Also: http://www.w3.org/TR/SVG/text.html#LetterSpacingProperty
SVG_SET_TEXT_RENDER SVG_SET_TEXT_RENDERING (svgObject; rendering)

ING
rendering Text Æ Value of rendering
The SVG_SET_TEXT_RENDERING command defines the tradeoffs to

make regarding the rendering of text for the text object designated by
svgObject. If svgObject is not an SVG text object, an error is generated.
The rendering parameter can have one of the following values: "auto",
"optimizeSpeed", "optimizeLegibility", "geometricPrecision" or
"inherit". Otherwise, an error is generated.
See Also: http://www.w3.org/TR/2001/REC-SVG-20010904/pain-

ting.html#TextRenderingProperty
SVG_SET_TEXT_WRITING SVG_SET_TEXT_WRITING_MODE (svgObject; writingMode)

_MODE
writingMode Text Æ Direction of writing
The SVG_SET_TEXT_WRITING_MODE command sets whether the

writing direction for the text object designated by svgObject will be left
to right, right to left or bottom to top. If svgObject is not an SVG text
object, an error is generated.
290 4D v12 Upgrade

4D SVG
The writingMode parameter can have one of the following values: "lr-
tb", "rl-tb", "tb-rl", "lr", "rl", "tb" or "inherit ". Otherwise, an error is
generated.
` Writing from right to left:

//Frame
SVG_New_rect ($Dom_SVG;5;5;210;310;0;0;"blue";"none")
//Text
$Dom_text:=SVG_New_textArea ($Dom_SVG;$Txt_sample;10;10;200;
300;"Baghdad 'Arial Unicode MS'";25)
SVG_SET_TEXT_WRITING_MODE($Dom_text;"rl")
SVG_SET_TEXTAREA_ SVG_SET_TEXTAREA_TEXT (svgObject ; theText)

TEXT
theText Text Æ Text to set
The SVG_SET_TEXTAREA_TEXT command sets/replaces the textual

content of the text object designated by svgObject. If svgObject is not a
"textArea" object, an error is generated.
The line return characters are automatically replaced by "<tbreak/>"

elements.
4D v12 Upgrade 291

Chapter 5 Language
Modified commands
SVG_New_textArea The SVG_New_textArea command now replaces line returns by

<tbreak/> elements.
See Also: http://www.w3.org/TR/SVGTiny12/text.html#tbreakElement
SVG_SET_FONT_FAMILY SVG_SET_FONT_FAMILY (svgObject; font1{ ;...; fontN})

font1...N String Æ Font name(s)
The SVG_SET_FONT_FAMILY command now accepts more than one

font name. When several names are passed, it automatically builds the
list of font family names and/or generic family names.
` Passing several font names:

SVG_SET_FONT_FAMILY(svgObject ; "Lucida grande" ; "Sans-serif")
// will build the following list: " 'Lucida grande' 'Sans-serif'"
Utilities
SVG_ABOUT SVG_ABOUT
The SVG_ABOUT command displays a dialog with the 4D SVG logo

indicating the version number of the component:
292 4D v12 Upgrade

4D SVG
SVGTool_SET_VIEWER_ SVGTool_SET_VIEWER_CALLBACK (methodName)

CALLBACK
methodName Text Æ Name of 4D method
The SVGTool_SET_VIEWER_CALLBACK command installs methodName as

the project method that will be called when the On Clicked and On
Mouse Move events occur on the image displayed by the
SVGTool_SHOW_IN_VIEWER command.
This method receives a text parameter that is the ID of the element

being clicked or over which the mouse is moving as provided by the
4D SVG Find element ID by coordinates command. This parameter must
be declared in the methodName project method of the host database by
inserting it into the line C_TEXT($1).
You must assign the "Shared by components and host database"

property to the methodName method.
If the method does not exist or is not shared, the error -10508 is
generated by 4D.
Modified commands
SVG_References_array SVG_References_array (refsArrayPointer) Æ Function result

refsArrayPointer Pointer Æ Alpha array of document references
Function result Longint Å Number of references
The SVG_References_array command now returns the number of

references found.
` Loop on number of elements:

ARRAY TEXT (MyArray ; 0 )
For ($i ; 1 ; SVG_References_array ( ->MyArray ))
…
End for
4D v12 Upgrade 293

Chapter 5 Language
294 4D v12 Upgrade

6 SQL
This section covers the new features and modifications made to the
SQL engine of 4D v12:
New function for replicating database via SQL
Direct definition of a primary key
Support of outer joins
Use of external databases
Support of UUID fields
New commands and modified commands
Note The use of new SQL statements in the code editor is facilitated via
specific macro commands. To be able to take advantage of them, you
will need to update your "Macros.xml" file. For more information
about this point, refer to the “Updating the Macros.xml file” paragraph
on page 17.
Replication via SQL

4D v12 provides a new mechanism that allows data to be synchronized
between two or more 4D databases via SQL. This mechanism can be
used to set up one or more mirror databases, guaranteeing permanent
availability of data.
The principle is as follows: a target database replicates the data of a

remote source database locally. Updates are carried out periodically by
the local database which retrieves the data from the remote database.
Replication is carried out at the table level: you replicate the data of a
remote database table into a table in the local database.
4D v12 Upgrade 295

Chapter 6 SQL
This is made possible by the addition of stamps and new SQL

commands.
A new table property enables the replication mechanism in the remote
and local database. On the local side, the new SQL REPLICATE
command retrieves data from a table in the remote database and then
integrates this data into a table of the local database. Lastly, the new
SQL SYNCHRONIZE command can be used to synchronize two tables.
New virtual fields Each table of the 4D database can be assigned three new "virtual" fields:
__ROW_ID, __ROW_STAMP and __ROW_ACTION. These fields are
called "virtual" to differentiate them from "standard" fields because
they have specific properties: they are automatically filled in, can be
read but not modified by the users, and do not appear in the system
tables of the database. The following table describes these fields as well
as their mode of use:
Virtual field Type Content Use
__ROW_ID Int32 ID of record In any SQL state-
ment except for
REPLICATE or SYN-
CHRONIZE
__ROW_STAMP Int64 Record replication infor- In any SQL state-
mation ment
__ROW_ACTION Int16 Type of action carried out Only with the
on the record: REPLICATE or SYN-
1 = Addition or modifica- CHRONIZE com-
tion mand
2 = Deletion
When the replication mechanisms are enabled, as soon as a record is

created, modified or deleted, the corresponding information is
automatically updated in the virtual fields of this record.
Enabling replication By default the mechanisms that allow replication are not enabled. You
must explicitly enable them in both the remote and local database for
each table to be used in the replication or synchronization.
Note that enabling the mechanism does not trigger the replication
itself; in order for the data to actually be replicated in a local or
synchronized database, you must use the new REPLICATE or
SYNCHRONIZE commands.
296 4D v12 Upgrade

Replication via SQL
To enable the internal replication mechanism for each table (on the
remote and local database), you must use the new Enable Replication
table property that is found in the table Inspector:
Enabling of replication
For the replication mechanism to be able to function, you must specify

a primary key for the tables implicated in the remote and local data-
bases. You can create this key via the structure editor (see the “Setting
the primary key” paragraph on page 23) or via SQL commands (see the
“Specifying a primary key when creating columns” paragraph on
page 298).
When this option is checked, 4D generates the information necessary

for replicating the records of the table (based more particularly on the
primary key of the table). This information is stored in the virtual
__ROW_STAMP and __ROW_ACTION fields.
Note It is possible to enable and disable the generation of replication

information via the SQL CREATE TABLE and ALTER TABLE commands. To
do this, the new ENABLE REPLICATE and DISABLE REPLICATE keywords
are available. For more information, refer to the description of these
commands in the “Modified SQL commands” paragraph on page 319.
Update on local Once the replication mechanism is enabled in the each table of each
database side database, you can use it from the local database via the new SQL
REPLICATE command. This command is described in the “New SQL
commands” paragraph on page 308
4D v12 Upgrade 297

Chapter 6 SQL
Specifying a primary key when creating columns

You can now specify a primary key (PRIMARY KEY) directly when
creating a table (via the CREATE TABLE command) or when adding a
column (via ALTER TABLE). In previous versions of 4D, it was necessary
to use the ALTER TABLE command with an existing column.
The syntaxes of these commands have therefore been modified; the

PRIMARY KEY key word is now accepted when creating a column.
For more information, refer to the description of these commands in

the following paragraph.
Note 4D also allows you to manage primary keys directly in the structure
editor. For more information, refer to the “Setting the primary key”
Support of joins
The SQL engine of 4D v12 extends the support of joins and more
particularly allows outer joins to be carried out.
Join operations may be inner or outer, implicit or explicit. Implicit

inner joins, carried out using the SELECT command, were already
supported by 4D v11 SQL (see below). 4D v12 now allows explicit
inner and outer joins to be generated using the SQL JOIN keyword.
Note The current implementation of joins in the 4D SQL engine does not
include:
- natural joins.
- the USING construct on inner joins.
Overview Join operations make connections between the records of two or more
tables and combine the result in a new table, called a join.
You generate joins via SELECT statements that specify the join
conditions. With explicit joins, these conditions can be complex but
they must always be based on an equality comparison between the
columns included in the join. For example, it is not possible to use the
>= operator in an explicit join condition.
Any type of comparison can be used in an implicit join.
298 4D v12 Upgrade

Support of joins
Internally, equality comparisons are carried out directly by the 4D

engine, which ensures rapid execution.
Note Usually, in the database engine, the table order is determined by the
order specified during the search. However, when you use joins, the
order of the tables is determined by the list of tables. In the following
example:
SELECT * FROM T1 RIGHT OUTER JOIN T2 ON T2.depID = T1.depID;
... the order of the tables is T1 then T2 (as they appear in the list of
tables) and not T2 then T1 (as they appear in the join condition).
Explicit inner joins An inner join is based on a comparison to find matches between two
columns. For example, if we consider the three following tables:
Employees
name depID cityID
Alan 10 30
Anne 11 39
Bernard 10 33
Mark 12 35
Martin 15 30
Philip NULL 33
Thomas 10 NULL
Departments
depID depName
10 Program
11 Engineering
NULL Marketing
12 Development
13 Quality
Cities
cityID cityName
30 Paris
33 New York
NULL Berlin
Note The example structure above will be used throughout this section.
4D v12 Upgrade 299

Chapter 6 SQL
As a reminder, here is an example of an implicit inner join (already

supported in 4D v11 SQL):
SELECT *
FROM employees, departments
WHERE employees.DepID = departments.DepID;
In 4D v12, you can now use the JOIN keyword to specify an explicit
inner join:
SELECT *
FROM employees
INNER JOIN departments
ON employees.DepID = departments.DepID;
You can insert this query into 4D code as follows:

ARRAY TEXT (aName;0)
ARRAY TEXT (aDepName;0)
ARRAY INTEGER (aEmpDepID;0
ARRAY INTEGER (aDepID;0)
Begin SQL
SELECT *
FROM employees
INNER JOIN departments
ON employees.depID = departments.depID
INTO :aName, :aEmpDepID, :aDepID, :aDepName;
End SQL
Here are the results of this join:

aName aEmpDepID aDepID aDepName
Alan 10 10 Program
Anne 11 11 Engineering
Bernard 10 10 Program
Mark 12 12 Development
Thomas 10 10 Program
Note that neither the employees named Philip or Martin nor the
Marketing or Quality departments appear in the resulting join because:
Philip does not have a department associated with his name (NULL
value),
The department ID associated with Martin’s name does not exist in
the Departments table,
300 4D v12 Upgrade

Support of joins
There is no employee associated with the Quality department (ID

13),
The Marketing department does not have an ID associated with it
(NULL value).
Cross joins A cross or Cartesian join is an inner join for which no WHERE nor ON
clauses have been specified. It consists in associating each row of one
table with each row of another table.
The result of a cross join is the Cartesian product of the tables,
containing a x b rows, where a is the number of rows in the first table
and b is the number of rows in the second table. This product
represents every possible combination formed by the concatenation of
the rows of both tables.
Each of the following syntaxes are equivalent:

SELECT * FROM T1 INNER JOIN T2
SELECT * FROM T1, T2
SELECT * FROM T1 CROSS JOIN T2;
Here is an example of 4D code with a cross join:

Begin SQL
SELECT *
FROM employees CROSS JOIN departments
End SQL
Here is the result of this join with our example database:

Alan 10 10 Program
Anne 11 10 Program
Mark 12 10 Program
Martin 15 10 Program
Philip NULL 10 Program
Alan 10 11 Engineering
Bernard 10 11 Engineering
Mark 12 11 Engineering
4D v12 Upgrade 301

Chapter 6 SQL
Martin 15 11 Engineering
Philip NULL 11 Engineering
Thomas 10 11 Engineering
Alan 10 NULL Marketing
Anne 11 NULL Marketing
Bernard 10 NULL Marketing
Mark 12 NULL Marketing
Martin 15 NULL Marketing
Philip NULL NULL Marketing
Thomas 10 NULL Marketing
Alan 10 12 Development
Anne 11 12 Development
Bernard 10 12 Development
Martin 15 12 Development
Philip NULL 12 Development
Thomas 10 12 Development
Alan 10 13 Quality
Anne 11 13 Quality
Bernard 10 13 Quality
Mark 12 13 Quality
Martin 15 13 Quality
Philip NULL 13 Quality
Thomas 10 13 Quality
Note For performance reasons, cross joins should be used with precaution.
Outer joins You can now generate outer joins with 4D v12. With outer joins, it is
not necessary for there to be a match between the rows of joined
tables. The resulting table contains all the rows of the tables (or of at
least one of the joined tables) even if there are no matching rows. This
means that all the information of a table can be used, even if the rows
are not completely filled in between the different joined tables.
There are three types of outer joins, specified using the LEFT, RIGHT
and FULL keywords. LEFT and RIGHT are used to indicate the table
(located to the left or right of the JOIN keyword) where all the data
must be processed. FULL indicates a bilateral outer join.
Note Only explicit outer joins are supported by 4D v12.
302 4D v12 Upgrade

Support of joins
Left outer joins The result of a left outer join (or left join) always contains all the
records for the table located to the left of keyword even if the join
condition does not find a matching record in the table located to the
right. This means that for each row in the left table where the search
does not find any matching row in the right table, the join will still
contain this row but it will have NULL values in each column of the
right table. In other words, a left outer join returns all the rows of the
left table plus any of those of the right table that match the join
condition (or NULL if none match). Note that if the right table
contains more than one row that matches the join predicate for a
single row of the left table, the values of the left table will be repeated
for each distinct row of the right table.
Here is an example of 4D code with a left outer join:

Begin SQL
SELECT *
FROM employees
LEFT OUTER JOIN departments
End SQL
Here is the result of this join with our example database (additional
rows shown in red):
Alan 10 10 Program
Martin 15 NULL NULL
Philip NULL NULL NULL
Right outer joins A right outer join is the exact opposite of a left outer join (see previous
paragraph). Its result always contains all the records of the table
located to the right of the JOIN keyword even if the join condition
does not find any matching record in the left table.
4D v12 Upgrade 303

Chapter 6 SQL
Here is an example of 4D code with a right outer join:

Begin SQL
SELECT *
FROM employees
RIGHT OUTER JOIN departments
End SQL
rows shown in red):
Alan 10 10 Program
NULL NULL NULL Marketing
NULL NULL 13 Quality
Full outer joins A full outer join simply combines together the results of a left outer
join and a right outer join. The resulting join table contains all the
records of the left and right tables; it fills in the missing fields on each
side with NULL values.
Here is an example of 4D code with a full outer join:

Begin SQL
SELECT *
FROM employees
FULL OUTER JOIN departments
End SQL
304 4D v12 Upgrade

Support of joins
rows shown in red):
Alan 10 10 Program
Martin 15 NULL NULL
Philip NULL NULL NULL
NULL NULL NULL Marketing
NULL NULL 13 Quality
Multiple joins in a single It is possible to combine several joins in the same SELECT statement. It
statement is also possible to mix implicit or explicit inner joins and explicit outer
joins.
Here is an example of 4D code with multiple joins:

ARRAY TEXT (aCityName;0)
ARRAY INTEGER (aEmpCityID;0)
ARRAY INTEGER (aCityID;0)
Begin SQL
SELECT *
FROM employees
FULL OUTER JOIN departments
FROM (employees RIGHT OUTER JOIN departments
ON employees.depID = departments.depID)
LEFT OUTER JOIN cities
ON employees.cityID = cities.cityID
INTO :aName, :aEmpDepID, :aEmpCityID, :aDepID, :aDepName;
:aCityID, :aCityName;
End SQL
4D v12 Upgrade 305

Chapter 6 SQL
Here is the result of this join with our example database:

aName aEmpDepID aEmpCityID aDepID aDepName aCityID aCityName
Alan 10 30 10 Program 30 Paris
Anne 11 39 11 Engineering 0
Bernard 10 33 10 Program 33 New York
Mark 12 35 12 Development 0
Thomas 10 NULL 10 Program 0
Using external databases

4D v12 can be used to create, modify and use "external databases" via
SQL.
An external database is a 4D database that is independent from the

main 4D database, but that you can work with from the main 4D
database. Using an external database means temporarily designating
this database as the current database, in other words, as the target
database for the SQL queries executed by 4D. By default, the main
database is the current database.
You can create an external database directly from the main database
with the new SQL CREATE DATABASE command. The database is stored
on disk in standard files (.4db and .4dd files). You can create as many
external databases as you want from the main 4D database.
Once created, an external database can be designated as the current
database using the new SQL USE DATABASE command. It can then be
modified via standard SQL commands (CREATE TABLE, ALTER TABLE,
etc.) and you can store data in it. The new DATABASE_PATH function
can be used to find out the current database at any time.
306 4D v12 Upgrade

The main interest of external databases resides in the fact that they can
be created and worked with via 4D components. This new feature
allows the development of components that are capable of creating
tables and fields according to their needs.
Note An external database is a standard 4D database. It can be opened and

worked with as the main database by a 4D or 4D Server application.
Conversely, any standard 4D database can be used as an external
database. However, it is imperative that you do not activate the access
management system (by assigning a password to the Designer) in an
external database, otherwise you will no longer be able to have access
to it via the SQL USE DATABASE command.

4D v12 lets you generate and store UUID numbers (see the “Using
Universally Unique Identifiers (UUIDs)” paragraph on page 19).
Creating a UUID In the structure editor, a UUID field is specified by assigning a specific
field property to an Alpha field (see the “UUID format” paragraph on
page 21).
On the 4D SQL side, a UUID field is identified via a new data type:
UUID. This data type can be used with the commands that create or
modify fields. For example:
Begin SQL
CREATE TABLE ACTORS_FAN
(ID UUID,
Name VARCHAR(30));
End SQL
Or:
Begin SQL
(Name VARCHAR(30));
ALTER TABLE ACTORS_FAN
ADD ID UUID;
End SQL
4D v12 Upgrade 307

Chapter 6 SQL
Generating UUIDs In 4D, it is possible to generate UUID numbers automatically in the

automatically records of a UUID field using the "Auto UUID" property (see the “Auto
UUID” paragraph on page 21).
On the 4D SQL side, this property is supported via a new keyword:
AUTO_GENERATE. This keyword can be used with the commands that
create or modify fields. For example:
Begin SQL
(ID UUID AUTO_GENERATE,
Name VARCHAR(30));
End SQL
New SQL commands

Several new SQL commands are available in 4D v12:
Commands related to the management of external databases: CREATE
DATABASE, USE DATABASE,
Commands related to the new implementations: ALTER DATABASE,
REPLICATE and SYNCHRONIZE.
CREATE DATABASE CREATE DATABASE [IF NOT EXISTS] DATAFILE<Complete pathname>
The new CREATE DATABASE command creates a new external database

(.4db and .4dd files) at a specific location (see the “Using external
databases” paragraph on page 306).
If the IF NOT EXISTS constraint is passed, the database is not created

and no error is generated if a database with the same name already
exists at the location specified.
If the IF NOT EXISTS constraint is not passed, the database is not
created and the "Database already exists. Failed to execute CREATE
DATABASE command." error message is shown if a database with the
same name already exists at the location specified.
308 4D v12 Upgrade

CREATE DATABASE
You use the DATAFILE clause to specify the complete name (complete
pathname + name) of the new external database. You must pass the
name of the structure file. The program automatically adds the ".4db"
extension to the file if it is not already specified and creates the data
file. The pathname can be expressed either in POSIX syntax or in the
system syntax. It can be absolute or relative to the structure file of the
main 4D database.
POSIX syntax (URL type): folder names are separated by a slash ("/"),
regardless of the platform that you use, for example:
.../extdatabases/myDB.4db
system syntax: pathname respecting the syntax of the current
platform, for example:
- (Mac OS) Disk:Applications:myserv:extdatabases:myDB.4db
- (Windows) C:\Applications\myserv\extdatabases\myDB.4db
After successful execution of the CREATE DATABASE command, the new

database created does not automatically become the current database.
To do this, you must explicitly declare it as the current database using
the new USE DATABASE command.
` Creation of ExternalDB.4DB and ExternalDB.4DD external database files

at the location C:/MyDatabase/:
Begin SQL
CREATE DATABASE IF NOT EXISTS DATAFILE 'C:/MyDatabase/ExternalDB';
End SQL
` Creation of TestDB.4DB and TestDB.4DD external database files next to

the structure file of the main database:
Begin SQL
CREATE DATABASE IF NOT EXISTS DATAFILE 'TestDB';
End SQL
` Creation of External.4DB and External.4DD external database files at

the location specified by the user:
C_TEXT($path)
$path:=Select folder("Destination folder of external database:")
$path:= $path+"External"
Begin SQL
CREATE DATABASE DATAFILE <<$path>>;
End SQL
See Also: USE DATABASE
4D v12 Upgrade 309

Chapter 6 SQL
USE DATABASE USE [LOCAL | REMOTE] DATABASE

{DATAFILE <Complete pathname> | SQL_INTERNAL | DEFAULT}
[AUTO_CLOSE]
The new USE DATABASE command designates an external database (see

the “Support of joins” paragraph on page 298), as the current database,
in other words, the database to which the next SQL queries in the
current process will be sent. All types of SQL queries are concerned:
queries included in the Begin SQL/End SQL structure, SQL EXECUTE or
SQL EXECUTE SCRIPT commands, etc.
If you are working in a single-user configuration, the external database

must be located on the same machine as your 4D.
If you are working in remote mode, the external database can be
located on the local machine or on the 4D Server machine.
If you are using 4D in remote mode, the REMOTE keyword can be used
to designate an external database located on 4D Server.
For security reasons, this mechanism only works with native remote
connections, in other words, in the context of a remote 4D database
connected with 4D Server. Connections via ODBC or pass-through
connections are not allowed.
If no keyword is specified, the LOCAL option is used by default. If you
are using 4D in local mode, the REMOTE and LOCAL keywords are
ignored: connections are always local.
To designate an external database to be used, pass its complete

pathname (access path + name) in the DATAFILE clause. The path can
be expressed either in the POSIX syntax, or in the system syntax. It can
be absolute or relative to the structure file of the main 4D database.
In remote mode, if the REMOTE keyword is passed, this parameter
designates the database path from the server machine. If it is omitted
or if the LOCAL keyword is passed, this parameter designates the
database path on the local 4D machine.
You must designate a valid external database, and one where access
control has not been activated (by assigning a password to the
Designer). Otherwise, an error is generated.
To reset the main database as the current database, execute the

command while passing the SQL_INTERNAL or DEFAULT keyword.
310 4D v12 Upgrade

ALTER DATABASE
Pass AUTO_CLOSE if you want to physically close the external database

after its use; in other words, when you change the current database. In
fact, since opening an external database is an operation that requires
some time, for optimization reasons 4D keeps information stored in
memory concerning external databases opened during the user
session. This information is kept as long as the 4D application remains
launched. Subsequent opening of the same external database is
therefore faster. However, this prevents the sharing of external
databases among several 4D applications because the external database
remains open in read/write for the first application that uses it. If
several 4D applications must be able to use the same external database
simultaneously, pass the AUTO_CLOSE keyword to physically release
the external database after its use.
This restriction does not apply to processes of the same application:

different processes of an application can always access the same
external database in read/write without it being necessary to force it to
close.
Note that when several processes use the same external database, it is
physically released only when the last process that uses it is closed,
even when the AUTO_CLOSE option has been passed. You should take
this functioning into account for operations that involve inter-
application sharing or deletion of external databases.
` Use of an external database for a request then return to the main

database:
Begin SQL
USE DATABASE DATAFILE 'C:/MyDatabase/Names'
SELECT Name FROM emp INTO :tNames1
USE DATABASE SQL_INTERNAL
End SQL
See Also: CREATE DATABASE, DATABASE_PATH
ALTER DATABASE ALTER DATABASE {ENABLE | DISABLE} {INDEXES | CONSTRAINTS}
The new ALTER DATABASE command enables or disables SQL options of

the current database for the current session.
4D v12 Upgrade 311

Chapter 6 SQL
This command is intended to allow you to temporarily disable SQL

options in order to accelerate certain operations that take up a lot of
resources. For example, disabling indexes and constraints before
beginning the import of a large quantity of data can significantly
reduce the duration of the import. Note that constraints include
primary keys and foreign keys as well as unique and null attributes.
Warning: this command must be used with precaution since the

disabling of triggers during an import may render the data incoherent
or corrupt them. You must take this risk into account and implement
strategies to preserve data integrity when necessary.
ALTER DATABASE applies to the entire database. In other words, if a user

disables an option, it will be disabled for all the users of the database.
` Example of an import with temporary disabling of all SQL options:

Begin SQL
ALTER DATABASE DISABLE INDEXES;
ALTER DATABASE DISABLE CONSTRAINTS;
End SQL
SQL EXECUTE SCRIPT ("C:\Exported_data\Export.sql"; SQL On error con-
tinue)
Begin SQL
ALTER DATABASE ENABLE INDEXES;
ALTER DATABASE ENABLE CONSTRAINTS;
End SQL
312 4D v12 Upgrade

REPLICATE
REPLICATE REPLICATE replicated_list

FROM table_reference
[WHERE search_condition]
[LIMIT {int_number | 4d_language_reference}]
[OFFSET {int_number | 4d_language_reference}]
FOR REMOTE [STAMP] {int_number | 4d_language_reference}
[, LOCAL [STAMP] {int_number | 4d_language_reference}]
[{REMOTE OVER LOCAL | LOCAL OVER REMOTE}]
[LATEST REMOTE [STAMP] 4d_language_reference
[, LATEST LOCAL [STAMP] 4d_language_reference]]
INTO {target_list | table_reference(sql_name_1;...;sql_name_N)};
The new REPLICATE command replicates the data of a table of database

A into that of a table of database B. By convention, the database where
the command is executed is called the "local database" and the
database from which the data are replicated is called the "remote
database."
You can only use this command in the framework of a database

replication system. For the system to work, replication must have been
enabled on the local database and the remote database side and each
table implicated must have a primary key. For more information about
this system, refer to the “Replication via SQL” paragraph on page 295.
Note If you would like to implement a complete synchronization system,

refer to the description of the new SYNCHRONIZE command.
Pass a list of fields (virtual or standard) separated by commas in

replicated_list. The fields must belong to the table_reference table of the
remote database.
The FROM clause must be followed by an argument of the

table_reference type which designates the table of the remote database
from which to replicate the data of the replicated_list fields.
Note The virtual fields of the remote table can only be stored in the arrays of
the local database.
4D v12 Upgrade 313

Chapter 6 SQL
Remote database side The optional WHERE clause can be used to apply a preliminary filter to
the records of the table in the remote database so that only those
records that satisfy the search_condition will be taken into account by
the command.
4D then recovers the values of the replicated_list fields for all the
records designated by the FOR REMOTE STAMP clause. The value passed
in this clause can be either:
a value of the type longint > 0: In this case, records where the value
of __ROW_STAMP is greater than or equal to this value are
recovered.
0: In this case, all the records where the value of __ROW_STAMP is
different from 0 are recovered. Note that any records that existed
before the enabling of replication will therefore not be taken into
account (the value of their __ROW_STAMP = 0).
-1: In this case, all the records of the remote table are recovered; in
other words, all the records where the value of __ROW_STAMP >= 0.
Unlike the previous case, all the records of the table, including any
that existed before replication was enabled, will be taken into
account.
-2: In this case, all the records deleted from the remote table (after
enabling of replication) are recovered; in other words, all the
records where the value of __ROW_ACTION = 2.
Finally, you can apply the optional OFFSET and/or LIMIT clauses to the
selection obtained:
When it is passed, the OFFSET clause ignores the first X records of
the selection (where X is the value passed to the clause).
When it is passed, the LIMIT clause restricts the result selection to
the first Y records (where Y is the value passed to the clause). If the
OFFSET clause is also passed, the LIMIT clause is applied to the
selection obtained after the execution of OFFSET).
Once both clauses have been applied, the resulting selection is sent to
the local database.
314 4D v12 Upgrade

REPLICATE
Local database side The values recovered are directly written into the target_list of the local
database or in the standard fields specified by sql_name of the
table_reference table of the local database. The target_list argument can
contain either a list of standard fields or a list of arrays of the same type
as the remote fields (but not a combination of both). If the destination
of the command is a list of fields, the target records will be
automatically created, modified or deleted according to the action
stored in the virtual __ROW_ACTION field.
Conflicts (identical primary keys) are resolved using conflict

management clauses (REMOTE OVER LOCAL or LOCAL OVER REMOTE
option):
If you pass the REMOTE OVER LOCAL option or omit the conflict
management clause, in the case of a conflict, the source record (remote
database) always replaces the target record (local database). Note that if
you use this option, it is pointless to pass a LOCAL STAMP clause
because in this case, it is ignored.
If you pass the LOCAL OVER REMOTE option, in the case of a conflict,
the target record (local database) is not modified. The command takes
the LOCAL STAMP into account. When it is used, the LOCAL STAMP
clause limits the replication in the local table to the conflict records
where the value of the stamp is less than or equal to the one passed.
You use this clause to reduce the selection of conflict records that will
be replicated in the local table.
If you pass the LATEST REMOTE STAMP and/or LATEST LOCAL STAMP
clauses, 4D returns the values of the last stamps of the remote and
local tables in the corresponding 4d_language_reference variables. This
information is useful when you want to customize the handling of the
synchronization procedure. These values correspond to the value of
the stamps just after the replication operation was completed: if you
use them in a subsequent REPLICATE or SYNCHRONIZE statement, you
do not need to increment them because they were automatically
incremented before being returned by the REPLICATE command.
4D v12 Upgrade 315

Chapter 6 SQL
If the replication operation is carried out correctly, the OK system

variable is set to 1. You can check this value from a 4D method.
If errors occur during the replication operation, the operation is
stopped at the first error that occurs. The last source variable (if it has
been specified) is valorized with the stamp of the record in which the
error occurred. The OK system variable is set to 0. The error generated
can be intercepted by an error-handling method installed by the ON
ERR CALL command.
Note Operations carried out by the REPLICATE command do not take data
integrity constraints into account. This means, for instance, that the
rules governing foreign keys, uniqueness, and so on, are not checked.
If the data received could undermine data integrity, you must check
the data after the replication operation is finished. The simplest way is
to lock, using SQL or the 4D language, the records that have to be
modified.
SYNCHRONIZE SYNCHRONIZE
[LOCAL] TABLE table_reference (sql_name_1;...;sql_name_N)
WITH
[REMOTE] TABLE table_reference (sql_name_1;...;sql_name_N)
FOR REMOTE [STAMP] {int_number | 4d_language_reference}
LOCAL [STAMP] {int_number | 4d_language_reference}
{REMOTE OVER LOCAL | LOCAL OVER REMOTE}
LATEST REMOTE [STAMP] 4d_language_reference
LATEST LOCAL [STAMP] 4d_language_reference;
The new SYNCHRONIZE command synchronizes two tables located on

two different 4D SQL servers. Any change made to one of the tables is
also carried out in the other. The 4D SQL server that executes the
command is called the local server and the other server is called the
remote server.
316 4D v12 Upgrade

SYNCHRONIZE
Note The SYNCHRONIZE command is a combination of two internal calls to

the REPLICATE command. The first call replicates the data from the
remote server to the local server and the second carries out the
opposite operation: replication of local server data to the remote
server. The tables to be synchronized must therefore be configured for
replication:
- They must have a primary key,
- The "Enable Replication" option must be checked in the Inspector
window of each table.
For more information, refer to the description of the REPLICATE
command.
The SYNCHRONIZE command accepts four stamps as "parameters": two

input stamps and two output stamps (last modification). The input
stamps indicate the moment of the last synchronization on each
server. This moment is expressed as coded information, with no
duration. The output stamps return the value of the modification
stamps on each server right after the last modification. Thanks to this
principle, when the SYNCHRONIZE command is called regularly, it is
possible to use the output stamps of the last synchronization as input
stamps for the next one.
Note Input and output stamps are expressed as number values and not as
timestamps. For more information about these stamps, refer to the
description of the REPLICATE command.
In the event of an error, the output stamp of the server concerned

contains the stamp of the record at the origin of the error. If the error
stems from a cause other than the synchronization (network problems
for example), the stamp will contain 0.
There are two different error codes, one to indicate a synchronization
error on the local site and another for a synchronization error on the
remote site.
When an error occurs, the state of the data will depend on that of the
transaction on the local server. On the remove server, the
synchronization is always carried out within a transaction, so the data
cannot be altered by the operation. However, on the local server, the
synchronization process is placed under the control of the developer. It
will be carried out outside of any transaction if the Auto-commit
Transactions preference is not selected, (otherwise, a transaction
context is automatically created).
4D v12 Upgrade 317

Chapter 6 SQL
The developer can decide to start a transaction and it is up to the

developer to validate or cancel this transaction after data
synchronization.
Conflicts are resolved using the REMOTE OVER LOCAL and LOCAL OVER
REMOTE clauses, that clearly indicate which server will have priority if
the same record has been modified on both sides. For more
information about the implementation mechanisms, refer to the
description of the REPLICATE command.
Note Operations carried out by the SYNCHRONIZE command do not take

data integrity constraints into account. This means, for instance, that
the rules governing foreign keys, uniqueness, and so on, are not
checked. If the data received could undermine data integrity, you must
check the data after the synchronization operation. The simplest way
is to lock, using SQL or the 4D language, the records that must be
modified.
New function
DATABASE_PATH DATABASE_PATH()
The DATABASE_PATH function returns the complete pathname of the

current database. The current database can be modified using the SQL
USE DATABASE command. By default, the current database is the main
4D database.
` Let us suppose that the current external database is named

TestBase.4DB and is located in the "C:\MyDatabases" folder. After
execution of the following code:
C_TEXT(vCrtDatabasePath)
Begin SQL
SELECT DATABASE_PATH()
INTO :vCrtDatabasePath;
End SQL
...the vCrtDatabasePath variable will contain

"C:\MyDatabases\TestBase.4DB”.
See Also: CREATE DATABASE, USE DATABASE
318 4D v12 Upgrade

Modified SQL commands
Modified SQL commands

This section presents the modifications made to the existing SQL
commands of 4D. These modifications appear in italic.
CREATE TABLE CREATE TABLE [IF NOT EXISTS] {sql_name.}sql_name({column_definition

|table_constraint} [PRIMARY KEY], ... , {column_definition
|table_constraint} [PRIMARY KEY]) [{ENABLE | DISABLE} REPLICATE]
The CREATE TABLE command accepts two new keywords:

PRIMARY KEY: specifies the primary key when the table is created (see
the “Specifying a primary key when creating columns” paragraph on
page 298).
Note The PRIMARY KEY keyword is accepted since version 11.4 of 4D.
{ENABLE | DISABLE} REPLICATE: enables or disables the mechanism

allowing replication of the table (see the “Enabling replication”
ALTER TABLE ALTER TABLE sql_name

{ADD column_definition [PRIMARY KEY]|
DROP sql_name |
ADD primary_key_definition |
DROP PRIMARY KEY |
ADD foreign_key_definition |
DROP CONSTRAINT sql_name |
[{ENABLE | DISABLE} REPLICATE] |
SET SCHEMA sql_name}
The ALTER TABLE command accepts two new keywords:

PRIMARY KEY: specifies the primary key when a column is added (see
the “Specifying a primary key when creating columns” paragraph on
page 298).
Note The PRIMARY KEY keyword is accepted since version 11.4 of 4D.
{ENABLE | DISABLE} REPLICATE: enables or disables the mechanism

allowing replication of the table (see the “Enabling replication”
4D v12 Upgrade 319

Chapter 6 SQL
320 4D v12 Upgrade

7 4D Server Administration
About the 64-bit 4D Server

4D Server v12 for Windows is available in 32-bit (standard) version and
64-bit version. The 64-bit version is intended for use on 64-bit
Windows operating systems.
The 64-bit version of 4D Server is now in the process of being finalized

and is the subject of a beta test program. You can currently evaluate
this version by connecting to the 4D Web site (http://www.4d.com/). It
will be soon be available in a final public version.
For technical information about the 64-bit version of 4D Server, refer

to the 64-bit 4D Server manual, available on the 4D documentation site
(http://doc.4d.com/).
4D Server administration window

New memory The Monitor page of the 4D Server administration window provides
information access to additional information concerning the memory used by the
application.
4D v12 Upgrade 321

Chapter 7 4D Server Administration
This new information is available in the menu located in the center of

the window:
This menu includes the following new items:

Physical memory: Indicates the quantity of RAM memory installed on
the machine that is used by 4D Server. This option was found under
the name "Memory" in previous versions of 4D Server.
Virtual memory: Displays in the graph area the quantity of virtual
memory used by the 4D Server application. This memory is allocated
by the system according to the application needs. The value found at
the bottom right of the area indicates the quantity of memory
currently being used. The value found at the top left indicates the
maximum quantity of usable virtual memory. The maximum value is
calculated dynamically according to the general memory settings of
the application.
Cache: Displays in the graph area the quantity of cache memory used
by the 4D Server application. The value found at the bottom right of
the area indicates the quantity of memory currently being used. The
value found at the top left indicates the total size of the cache memory,
as set via the Database Settings.
Note that when this option is selected, the graph area scrolling is
slowed down since an efficient analysis of the cache is generally carried
out over a fairly long observation period.
322 4D v12 Upgrade

4D Server administration window
Removal of In previous versions of 4D Server, a user was automatically added to

"technical" users the list of users once at least one stored procedure was launched on the
server and a client was connected. The same mechanism was
implemented when at least one Web process was launched. Of course,
this type of user, created for technical reasons, was not counted in the
licenses used by the application. Nevertheless, its presence could
sometimes be a source of confusion.
For better transparency, "technical" users no longer appear in the

administration window of 4D Server v12. Note that this modification
has no consequence on the functioning of 4D Server.
4D v12 Upgrade 323

Chapter 7 4D Server Administration
324 4D v12 Upgrade

A PHP Modules
This appendix details the implementation of PHP modules in 4D v12.

The following subjects are covered:
List of standard PHP modules provided by default with the PHP
interpreter of 4D
List of standard PHP modules not retained by 4D,
Installation instructions for additional modules.
Modules provided by default

The following table details the PHP modules provided by default with
4D v12.
Generic modules
Name Web site Description
BCMath http://php.net/bc Binary calculator handling numbers of any size and
precision represented as strings.
Example:
// Returns the result of ($myValue*$myValue*$myValue)
PHP Execute("";"bcpow";$result;String($myValue);"3";)
Calendar http://php.net/calendar Set of functions simplifying conversion between dif-
ferent calendar formats. Based on Julian Day Count.
Example:
PHP Execute("";"cal_days_in_month";Number of days in Febrary;1;2;Year())
4D v12 Upgrade 325

Appendix

Ctype http://php.net/ctype Functions that check whether a character or a string
belongs to a certain character class, depending on
the current local configuration
Example:
// Check that all the characters of the string provided are punctuation marks
PHP Execute("";"ctype_punct";isPunct;$myString)
Date and Time http://php.net/datetime Recovery of the date and time from the server
where the PHP script is executed
Example:
// Calculation of time of sunrise in Lisbon, Portugal, Latitude: 38.4 North, Longi-
tude: 9 West, Zenith ~= 90, Time-lag: +1 GMT
PHP Execute("";"eval";$resultType;"SUNFUNCS_RET_STRING")
PHP Execute("";"date_sunrise";SunriseTime;$timestamp;$resultType;38.4l;-9; 90;
1)
DOM (Document http://php.net/dom Use of XML documents via the DOM API in PHP 5
Object Model)
Exif http://php.net/exif Work with image metadata.
Fileinfo(*) http://php.net/fileinfo Detection of type of contents and encoding of a

file.
Filter http://php.net/filter Validate and filter data from a non-secure source,

like user entries.
Example:
PHP Execute("";"filter_id";$filterId;"FILTER_VALIDATE_EMAIL")
ON ERR CALL("notValidEmail")
validEmail:=$emailToValidate
$ok:=PHP Execute("";"filter_var";$test;$filterId;$emailToValidate;$resultType)
ON ERR CALL("")
FTP (File Transfer http://php.net/ftp Detailed access to a FTP server
Protocol)
Hash http://php.net/hash Message Digest engine. Allows direct or incremen-
tal processing of arbitrary length messages using a
variety of hashing algorithms
Example:
PHP Execute("";"hash";$md5Result;"md5";$myString)
GD (Graphics http://php.net/gd Working with images
Draw) Library
Iconv http://php.net/iconv Conversion of files between various character sets
326 4D v12 Upgrade


JSON (JavaScript http://php.net/json Implementation of JSON data exchange format
Object Notation)
LDAP http://php.net/ldap LDAP is an access protocol to "folder servers" that
store information in the form of a tree diagram
LibXML http://php.net/libxml Library of XML functions and constants
Multibyte String http://php.net/mbstring Set of functions for working with strings that can be
used to handle multi-byte character encodings or to
convert character strings.
OpenSSL http://php.net/openssl Use of OpenSSL functions to generate and verify

signatures, to seal (encode) and open (decode)
data.
PCRE (Perl Com- http://php.net/pcre Set of functions that implement rational expressions
patible Regular using the same syntax and semantics Perl 5
Expressions) Example:
// This example removes unnecessary spaces from a string.
$myString:="foo o bar"
PHP Execute("";"preg_replace";$myString;"/\\s\\s+/";" ";$myString)
// $myString is now "foo o bar" without repeated spaces
PDO (PHP Data http://php.net/pdo Interface for accessing a database. Requires a data-
Objects) base-specific PDO driver.
PDO_SQLITE http://php.net/pdo_sqlite Driver that implements the PHP Data Objects

(PDO) interface to allow PHP access to SQLite 3
databases.
Reflection http://php.net/reflection Complete reflection API that lets you reverse-engi-

neer classes, interfaces, functions and methods as
well as extensions.
Phar (PHP Archive) http://php.net/phar Allows a complete PHP application to be included

in a unique file named "phar" (PHP Archive) to facili-
tate its installation and configuration
4D v12 Upgrade 327

Appendix

Session http://php.net/session Support of PHP sessions
Example:
Sessions are used in Web applications to preserve the context between each re-
quest. When you call PHP Execute in 4D, the PHP script can start a session and
store anything that is useful to be kept as context in the associated $_SESSION ar-
ray.
If a PHP script uses sessions, you must obtain the session ID returned by PHP using
the PHP GET FULL RESPONSE command and specify it before each call to PHP Exe-
cute using the SET ENVIRONMENT VARIABLE command.
// "PHP Execute with context" method
If (<>PHP_Session # "")
SET ENVIRONMENT VARIABLE ("HTTP_COOKIE";<>PHP_Session)
End if
If (PHP Execute($1))
PHP GET FULL RESPONSE ($0;$errorInfos;$errorValues;$headerFields;
$headerValues)
$idx:=Find in array($headerFields; "Set-Cookie")
If ($idx>0)
<>PHP_Session:=$headerValues{$idx}
End if
End if
SimpleXML http://php.net/simpleXML Very simple and easy-to-use tools to be used to con-
vert XML to an object that can be processed with its
properties and array iterators.
Sockets http://php.net/sockets Implementation of a low-level interface to the

socket communication functions based on BSD
sockets and providing the possibility to act as both
a socket server as well as a client.
SPL (Standard PHP http://php.net/spl Collection of interfaces and classes that are meant
Library) to solve standard problems.
SQLite http://php.net/sqlite Extension for the SQLite database engine. This

engine is embeddable.
SQLite3 http://php.net/sqlite3 Support for SQLite version 3 databases.
328 4D v12 Upgrade


Tokenizer http://php.net/tokenizer Functions that let you write your own PHP analysis
tools or modification tools without having to deal
with the language specification at the lexical level.
XML (eXtensible http://php.net/xml Parsing of XML documents.

Markup Lan-
guage)
XMLreader http://php.net/xmlreader XML Pull parser
XMLwriter http://php.net/xmlwriter Generation of XML format streams or files.
Zlib http://php.net/zlib Reading and writing of gzip (.gz) compressed files.

Example:
GET HTTP HEADER($names;$values)
$pos:=Find in array($names;"Accept-Encoding")
If($pos>0)
Case of
:(Position($values{$pos};"gzip")>0)
SET HTTP HEADER("Content-Encoding: gzip")
PHP Execute("";"gzencode";$html;$html)
:(Position($values{$pos};"deflate")>0)
SET HTTP HEADER("Content-Encoding: deflate")
PHP Execute("";"gzdeflate";$html;$html)
End case
End if
SEND HTML TEXT($html)
Zip http://php.net/zip Reading and writing of ZIP compressed archives
and the files inside them
(*) Not available under Windows in the current version of 4D v12.
4D v12 Upgrade 329

Appendix
Modules only For structural reasons, the following PHP modules are only available
available under on the Windows platform.
Windows
COM & .NET http://php.net/com COM (Component Object Model) is one of the
main ways for applications and components to
communicate on Windows platforms.
In addition, 4D supports the instantiation and cre-
ation of .Net assemblies via the COM layer.
ODBC (Open http://php.net/odbc In addition to standard ODBC support, the Unified

DataBase Connec- ODBC functions in PHP gives you access to several
tivity) databases that have borrowed the semantics of the
ODBC API to implement their own API.
WDDX (Web Dis- http://php.net/wddx Facilitates data exchanges between Web applica-
tributed Data tions over the Web, regardless of the platform.
eXchange)
Disabled modules
The following PHP modules have not been implemented in 4D v12.
The rightmost column gives the reason they were not implemented:
Name Web site Cause - Alternative solution
Mimetype http://php.net/mime-magic Obsolete (Deprecated) - Use Fileinfo
POSIX (Portable http://php.net/posix
Operating System Obsolete (Deprecated)
Interface)
Regular Expression http://php.net/regex
Obsolete (Deprecated) - Use PCRE
(POSIX Extended)
Crack http://php.net/crack Restrictive license
ffmpeg http://ffmpeg-php.source- Restrictive license - Use ffmpeg in command line
forge.net/ with LAUNCH EXTERNAL PROCESS
Image Magick http://php.net/man- Restrictive license - Use GD 2
ual/book.imagick.php
IMAP (Internet http://php.net/imap Restrictive license - Use the 4D Internet Commands
Message Access integrated plugin
Protocol)
PDF (Portable Doc- http://php.net/pdf Restrictive license - Use Haru PDF
ument Format)
330 4D v12 Upgrade

Installation of additional modules
Name Web site Cause - Alternative solution

Mysqlnd (MySQL http://dev.mysql.com/down Not pertinent in the 4D environment
Native Driver) loads/connector/php-
mysqlnd/

The PHP interpreter leaves you the possibility of installing additional
modules. This gives you access to specific functionalities that are not
present by default.
You can install several types of extensions:

PECL (PHP Extension Community Library) extensions
Extensions of the PEAR (PHP Extension and Application Repository)

framework
Extensions of the Zend framework
Extensions of the Symphony framework
Extensions of the JELIX framework
eZ components
Installation information for each type of extension are provided below.
Note The characteristics of the PHP version provided with 4D v12 are as
follows:
- version 5.3.2
- 32-bit compilation under Windows and Mac OS
- compilation in "thread-safe" mode under Windows and Mac OS.
PECL extensions Web Site: http://pecl.php.net

X To add PECL extensions:
1 Download and build the PECL extension desired.
OR
Take the extension already built from a PHP 5.3 VC9 Non Thread Safe
Windows binary package
(http://www.windows.php.net/download/#php-5.3-nts-VC9-x86)
2 Add the extension into the extension folder.
4D v12 Upgrade 331

Appendix
3 Activate the extension in the php.ini file.

Warning: if the extensions available on the PECL Web site are under
PHP license which is not restrictive, certain may require libraries which
may themselves have a more restrictive license.
PHP extensions are available on other Web sites, but in this case they
do not have the security guarantee provided by the validation of the
PHP Group.
PEAR extensions Web Site: http://pear.php.net
PEAR is a framework that is entirely object oriented.

X To add PEAR extensions:
1 Download (http://pear.php.net/package/PEAR/download) and
uncompact the PEAR package into a folder named "pear".
2 Add this "pear" folder in the "include_path" specified in the "php.ini"
file.
3 Download and uncompact any PEAR packages into this folder.
Zend extensions
1 Download (http://framework.zend.com/download/latest) and
uncompact the Zend framework into a folder named "zend".
2 Add this "zend" folder in the "include_path" specified in the "php.ini"
file.
3 Read the documentation for Zend framework components:
http://framework.zend.com/manual/en
Symphony Web Site: http://www.symfony-project.org

extensions
The Symphony framework is structured so as to be used as a Web
application accompanied by its Web controller.
1 Download and uncompact the source framework as well as the
sandbox from the following address: http://www.symfony-
project.org/installation/1_2.
332 4D v12 Upgrade

JELIX extensions
1 Download (http://jelix.org/articles/en/download/stable) and uncompact
the JELIX framework.
2 Add the resulting "jelix" folder in the "include_path" specified in the
"php.ini" file.
3 Read the documentation for JELIX framework components:
http://jelix.org/articles/en/manual-1.1/components
eZ components
1 Download (http://www.ezcomponents.org/download) and uncompact
the eZ components into a "ez" folder.
2 Add the "ez" folder in the "include_path" specified in the "php.ini" file.
3 Read the documentation for eZ components:
http://www.ezcomponents.org/docs/api/latest
4D v12 Upgrade 333

Appendix
334 4D v12 Upgrade

B Style Tags
This appendix lists the style tags supported by 4D v12 in text areas
having the "Multi-style" attribute. For a description of this attribute,
refer to the “Rich text” paragraph on page 94.
You can use these tags to set up custom style management. Only the
tags listed below are supported by 4D for style variations.
Font name ... 
Font size ... 
Font style
Bold
 ... 
Italic or normal
 ... 

 ... 
Underline
 ... 
Strikethrough
...
Note The "strikethrough" style is not supported under Mac OS. However, the
corresponding tag can be used by programming.
4D v12 Upgrade 335

Appendix
Font colors ... 
or
...
Background colors ... 

(Windows only)
or
...
Note Under Mac OS, this attribute is ignored. It is removed if the object is
modified.
Color values For the font color and background color attributes, the color value can
be either the hexadecimal code of RGB colors or the name of one of
the 16 HTML colors specified for the CSS standard by the W3C:
336 4D v12 Upgrade

C Metadata Constants
This appendix shows the constants found in the new "Picture metadata
names" and "Picture metadata values" themes of 4D v12. For more
information about the use of these constants, refer to the description
of the SET PICTURE METADATA and GET PICTURE METADATA commands.
Picture metadata names

EXIF
Types of possible values or
Constants of the "Picture
associated constants of the
metadata names" theme Value
"Picture metadata values"
(metaName parameter)
theme (contents parameter)
EXIF Aperture Value EXIF/ApertureValue Real (APEX value)
EXIF Brightness Value EXIF/BrightnessValue Real (APEX value)
EXIF Color Space EXIF/ColorSpace EXIF Adobe RGB
EXIF s RGB
EXIF Uncalibrated
EXIF Components Configuration EXIF/ComponentsConfiguration EXIF B
EXIF Cb
EXIF Cr
EXIF G
EXIF R
EXIF Unused
EXIF Y
EXIF Compressed Bits Per Pixel EXIF/CompressedBitsPerPixel Real
EXIF Contrast EXIF/Contrast EXIF High
EXIF Low
EXIF Normal
EXIF Custom Rendered EXIF/CustomRendered EXIF Normal
EXIF Custom
EXIF Date Time Digitized EXIF/DateTimeDigitized Date or Text (XML Datetime)
4D v12 Upgrade 337

Appendix
EXIF Date Time Original EXIF/DateTimeOriginal Date or Text (XML Datetime)

EXIF Digital Zoom Ratio EXIF/DigitalZoomRatio Real
EXIF Exif Version EXIF/ExifVersion Integer array (4 values)
EXIF Exposure Bias Value EXIF/ExposureBiasValue Real
EXIF Exposure Index EXIF/ExposureIndex Real
EXIF Exposure Mode EXIF/ExposureMode EXIF Auto
EXIF Auto Bracket
EXIF Manual
EXIF Exposure Program EXIF/ExposureProgram EXIF Manual
EXIF Action
EXIF Aperture Priority AE
EXIF Creative
EXIF Landscape
EXIF Exposure Portrait
EXIF Program AE
EXIF Shutter Speed Priority AE
EXIF Exposure Time EXIF/ExposureTime Real
EXIF File Source EXIF/FileSource EXIF Digital Camera
EXIF Film Scanner
EXIF Reflection Print Scanner
EXIF Flash EXIF/Flash EXIF Auto Mode
EXIF Compulsory Flash Firing
EXIF Compulsory Flash Suppres-
sion
EXIF Unknown
EXIF Detected
EXIF No Detection Function
EXIF Not Detected
EXIF Reserved
EXIF Flash Energy EXIF/FlashEnergy Real
EXIF Flash Pix Version EXIF/FlashPixVersion Integer array (4 values)
EXIF Flash Fired EXIF/Flash/Fired Boolean
EXIF Flash Function Present EXIF/Flash/FunctionPresent Boolean
EXIF Flash Mode EXIF/Flash/Mode EXIF Auto Mode
EXIF Compulsory Flash Firing
EXIF Compulsory Flash Suppres-
sion
EXIF Unknown
EXIF Flash Red Eye Reduction EXIF/Flash/RedEyeReduction Boolean
EXIF Flash Return Light EXIF/Flash/ReturnLight EXIF Detected
EXIF No Detection Function
EXIF Not Detected
EXIF Reserved
EXIF F Number EXIF/FNumber Real
EXIF Focal Len In 35 mm Film EXIF/FocalLenIn35mmFilm Longint
338 4D v12 Upgrade

EXIF Focal Length EXIF/FocalLength Real

EXIF Focal Plane Resolution Unit EXIF/FocalPlaneResolutionUnit Longint
EXIF Focal Plane X Resolution EXIF/FocalPlaneXResolution Real
EXIF Focal Plane Y Resolution EXIF/FocalPlaneYResolution Real
EXIF Gain Control EXIF/GainControl EXIF High Gain Down
EXIF High Gain Up
EXIF Low Gain Down
EXIF Low Gain Up
EXIF None
EXIF Gamma EXIF/Gamma Real
EXIF Image Unique ID EXIF/ImageUniqueID Text
EXIF ISO Speed Ratings EXIF/ISOSpeedRatings Longint or Longint array
EXIF Light Source EXIF/LightSource EXIF Unknown
EXIF Cloudy
EXIF Cool White Fluorescent
EXIF D50
EXIF D55
EXIF D65
EXIF D75
EXIF Daylight
EXIF Daylight Fluorescent
EXIF Day White Fluorescent
EXIF Fine Weather
EXIF Flash
EXIF Light Fluorescent
EXIF ISOStudio Tungsten
EXIF Other
EXIF Shade
EXIF Standard Light A
EXIF Standard Light B
EXIF Standard Light C
EXIF Tungsten
EXIF White Fluorescent
EXIF Maker Note EXIF/MakerNote Text
EXIF Max Aperture Value EXIF/MaxApertureValue Real
EXIF Metering Mode EXIF/MeteringMode EXIF Other
EXIF Average
EXIF Center Weighted Average
EXIF Multi Segment
EXIF Multi Spot
EXIF Partial
EXIF Spot
EXIF Pixel X Dimension EXIF/PixelXDimension Longint
EXIF Pixel Y Dimension EXIF/PixelYDimension Longint
EXIF Related Sound File EXIF/RelatedSoundFile Text
4D v12 Upgrade 339

Appendix
EXIF Saturation EXIF/Saturation EXIF High

EXIF Low
EXIF Normal
EXIF Scene Capture Type EXIF/SceneCaptureType EXIF Scene Landscape
EXIF Night
EXIF Scene Portrait
EXIF Standard
EXIF Scene Type EXIF/SceneType Longint
EXIF Sensing Method EXIF/SensingMethod EXIF Color Sequential Area
EXIF Color Sequential Linear
EXIF Not Defined
EXIF One Chip Color Area
EXIF Three Chip Color Area
EXIF Trilinear
EXIF Two Chip Color Area
EXIF Sharpness EXIF/Sharpness EXIF High
EXIF Low
EXIF Normal
EXIF Shutter Speed Value EXIF/ShutterSpeedValue Real
EXIF Spectral Sensitivity EXIF/SpectralSensitivity Text
EXIF Subject Area EXIF/SubjectArea Longint array (2, 3 or 4 values)
EXIF Subject Dist Range EXIF/SubjectDistRange EXIF Unknown
EXIF Close
EXIF Distant
EXIF Macro
EXIF Subject Distance EXIF/SubjectDistance Real
EXIF Subject Location EXIF/SubjectLocation Longint array (2 values)
EXIF User Comment EXIF/UserComment Text
EXIF White Balance EXIF/WhiteBalance EXIF Auto
EXIF Manual
GPS
GPS Altitude GPS/Altitude GPS Above Sea Level
GPS Below Sea Level
GPS Altitude Ref GPS/AltitudeRef GPS Above Sea Level
GPS Below Sea Level
GPS Area Information GPS/AreaInformation Text
GPS Date Time GPS/DateTime Date or Text (XML Datetime)
GPS Dest Bearing GPS/DestBearing Text (1 character)
GPS Dest Bearing Ref GPS/DestBearingRef Text (1 character)
340 4D v12 Upgrade

GPS Dest Distance GPS/DestDistance Text (1 character)

GPS Dest Distance Ref GPS/DestDistanceRef Text (1 character)
GPS Dest Latitude GPS/DestLatitude Text
GPS Dest Latitude Deg GPS/DestLatitude/Deg Real
GPS Dest Latitude Dir GPS/DestLatitude/Dir Text (1 character)
GPS Dest Latitude Min GPS/DestLatitude/Min Real
GPS Dest Latitude Sec GPS/DestLatitude/Sec Real
GPS Dest Longitude GPS/DestLongitude Text
GPS Dest Longitude Deg GPS/DestLongitude/Deg Real
GPS Dest Longitude Dir GPS/DestLongitude/Dir Text (1 character)
GPS Dest Longitude Min GPS/DestLongitude/Min Real
GPS Dest Longitude Sec GPS/DestLongitude/Sec Real
GPS Differential GPS/Differential GPS Correction Applied
GPS Correction Not Applied
GPS DOP GPS/DOP Real
GPS Img Direction GPS/ImgDirection GPS Magnetic north
GPS True north
GPS Img Direction Ref GPS/ImgDirectionRef GPS Magnetic north
GPS True north
GPS Latitude GPS/Latitude GPS North
GPS South
GPS Latitude Deg GPS/Latitude/Deg Real
GPS Latitude Dir GPS/Latitude/Dir GPS North
GPS South
GPS Latitude Min GPS/Latitude/Min Real
GPS Latitude Sec GPS/Latitude/Sec Real
GPS Longitude GPS/Longitude GPS West
GPS East
GPS Longitude Deg GPS/Longitude/Deg Real
GPS Longitude Dir GPS/Longitude/Dir GPS West
GPS East
GPS Longitude Min GPS/Longitude/Min Real
GPS Longitude Sec GPS/Longitude/Sec Real
GPS Map Datum GPS/MapDatum Text
GPS Measure Mode GPS/MeasureMode GPS 2D
GPS 3D
GPS Processing Method GPS/ProcessingMethod Text
GPS Satellites GPS/Satellites Text
GPS Speed GPS/Speed GPS km h
GPS miles h
GPS knots h
GPS Speed Ref GPS/SpeedRef GPS km h
GPS miles h
GPS knots h
GPS Status GPS/Status GPS Measurement in progress
4D v12 Upgrade 341

Appendix
GPS Measurement Interoperabi-

lity
GPS Track GPS/Track Real (0.00..359.99)
GPS Track Ref GPS/TrackRef Text (1 character)
GPS Version ID GPS/VersionID Longint array (4 characters)
IPTC
IPTC Byline IPTC/Byline Text or Text array
IPTC Byline Title IPTC/BylineTitle Text or Text array
IPTC Caption Abstract IPTC/CaptionAbstract Text
IPTC Category IPTC/Category Text
IPTC City IPTC/City Text
IPTC Contact IPTC/Contact Text or Text array
IPTC Content Location Code IPTC/ContentLocationCode Text or Text array
IPTC Content Location Name IPTC/ContentLocationName Text or Text array
IPTC Copyright Notice IPTC/CopyrightNotice Text
IPTC Country Primary Location IPTC/CountryPrimaryLocation- Text
Code Code
IPTC Country Primary Location IPTC/CountryPrimaryLocation- Text
Name Name
IPTC Credit IPTC/Credit Text
IPTC Date Time Created IPTC/DateTimeCreated Date or Text (XML Datetime)
IPTC Digital Creation Date Time IPTC/DigitalCreationDateTime Date or Text (XML Datetime)
IPTC Edit Status IPTC/EditStatus Text
IPTC Expiration Date Time IPTC/ExpirationDateTime Date or Text (XML Datetime)
IPTC Fixture Identifier IPTC/FixtureIdentifier Text
IPTC Headline IPTC/Headline Text
IPTC Image Orientation IPTC/ImageOrientation Text
IPTC Image Type IPTC/ImageType Text
IPTC Keywords IPTC/Keywords Text or Text array
IPTC Language Identifier IPTC/LanguageIdentifier Text
IPTC Object Attribute Reference IPTC/ObjectAttributeReference Text
IPTC Object Cycle IPTC/ObjectCycle Text
IPTC Object Name IPTC/ObjectName Text
IPTC Original Transmission Refe- IPTC/OriginalTransmissionRefe- Text
rence rence
IPTC Originating Program IPTC/OriginatingProgram Text
IPTC Program Version IPTC/ProgramVersion Text
IPTC Province State IPTC/ProvinceState Text
IPTC Release Date Time IPTC/ReleaseDateTime Date or Text (XML Datetime)
342 4D v12 Upgrade

IPTC Scene IPTC/Scene IPTC Action

IPTC Aerial View
IPTC Close Up
IPTC Couple
IPTC Exterior View
IPTC Full Length
IPTC General View
IPTC Group
IPTC Half Length
IPTC Headshot
IPTC Interior View
IPTC Movie Scene
IPTC Night Scene
IPTC Off Beat
IPTC Panoramic View
IPTC Performing
IPTC Posing
IPTC Profile
IPTC Rear View
IPTC Satellite
IPTC Single
IPTC Symbolic
IPTC Two
IPTC Under Water
IPTC Source IPTC/Source Text
IPTC Special Instructions IPTC/SpecialInstructions Text
IPTC Star Rating IPTC/StarRating Longint
IPTC Sub Location IPTC/SubLocation Text
IPTC Subject Reference IPTC/SubjectReference Longint or Longint array
IPTC Supplemental Category IPTC/SupplementalCategory Text or Text array
IPTC Urgency IPTC/Urgency Longint
IPTC Writer Editor IPTC/WriterEditor Text or Text array
4D v12 Upgrade 343

Appendix
TIFF
TIFF Artist TIFF/Artist Text
TIFF Compression TIFF/Compression TIFF Adobe Deflate
TIFF CCIRLEW
TIFF CCITT1D
TIFF DCS
TIFF Deflate
TIFF Epson ERF
TIFF IT8BL
TIFF IT8CTPAD
TIFF IT8LW
TIFF IT8MP
TIFF JBIG
TIFF JBIGB&W
TIFF JBIGColor
TIFF JPEG
TIFF JPEG2000
TIFF JPEGThumbs Only
TIFF Kodak262
TIFF Kodak DCR
TIFF Kodak KDC
TIFF LZW
TIFF MDIBinary Level Codec
TIFF MDIProgressive Transform
Codec
TIFF MDIVector
TIFF Next
TIFF Nikon NEF
TIFF Pack Bits
TIFF Pentax PEF
TIFF Pixar Film
TIFF Pixar Log
TIFF SGILog
TIFF SGILog24
TIFF Sony ARW
TIFF T4Group3Fax
TIFF T6Group4Fax
TIFF Thunderscan
TIFF Uncompressed
TIFF Copyright TIFF/Copyright Text
344 4D v12 Upgrade

TIFF Date Time TIFF/DateTime Date or Text (XML Datetime)

TIFF Document Name TIFF/DocumentName Text
TIFF Host Computer TIFF/HostComputer Text
TIFF Image Description TIFF/ImageDescription Text
TIFF Make TIFF/Make Text
TIFF Model TIFF/Model Text
TIFF Orientation TIFF/Orientation TIFF Horizontal
TIFF Mirror Horizontal
TIFF Mirror Horizontal And
Rotate270CW
TIFF Mirror Horizontal And
Rotate90CW
TIFF Mirror Vertical
TIFF Rotate180
TIFF Rotate270CW
TIFF Rotate90CW
TIFF Photometric Interpretation TIFF/PhotometricInterpretation TIFF Black Is Zero
TIFF CIELab
TIFF CMYK
TIFF Color Filter Array
TIFF ICCLab
TIFF ITULab
TIFF Linear Raw
TIFF Pixar Log L
TIFF Pixar Log Luv
TIFF RGB
TIFF RGBPalette
TIFF Transparency Mask
TIFF White Is Zero
TIFF YCb Cr
TIFF Resolution Unit TIFF/ResolutionUnit TIFF CM
TIFF Inches
TIFF MM
TIFF None
TIFF UM
TIFF Software TIFF/Software Text
TIFF XResolution TIFF/XResolution Real
TIFF YResolution TIFF/YResolution Real
4D v12 Upgrade 345

Appendix
Picture metadata values

This list shows the constants of the "Picture metadata values" theme as
well as their values. These constants can be used in the contents
parameter of the SET PICTURE METADATA and GET PICTURE METADATA
commands, according to the metaName parameter:
Constant Type Value
EXIF Adobe RGB Longint 2
EXIF s RGB Longint 1
EXIF Uncalibrated Longint -1
EXIF B Longint 6
EXIF Cb Longint 2
EXIF Cr Longint 3
EXIF G Longint 5
EXIF R Longint 4
EXIF Unused Longint 0
EXIF Y Longint 1
EXIF High Longint 2
EXIF Low Longint 1
EXIF Normal Longint 0
EXIF Custom Longint 1
EXIF Auto Longint 0
EXIF Auto Bracket Longint 2
EXIF Manual Longint 1
EXIF Action Longint 6
EXIF Aperture Priority AE Longint 3
EXIF Creative Longint 5
EXIF Landscape Longint 8
EXIF Exposure Portrait Longint 7
EXIF Program AE Longint 2
EXIF Shutter Speed Priority AE Longint 4
EXIF Digital Camera Longint 3
EXIF Film Scanner Longint 1
EXIF Reflection Print Scanner Longint 2
EXIF Auto Mode Longint 3
EXIF Compulsory Flash Firing Longint 1
EXIF Compulsory Flash Suppression Longint 2
EXIF Unknown Longint 0
EXIF Detected Longint 3
EXIF No Detection Function Longint 0
EXIF Not Detected Longint 2
EXIF Reserved Longint 1
346 4D v12 Upgrade

EXIF Auto Mode Longint 3

EXIF Compulsory Flash Firing Longint 1
EXIF Compulsory Flash Suppression Longint 2
EXIF Detected Longint 3
EXIF No Detection Function Longint 0
EXIF Not Detected Longint 2
EXIF Reserved Longint 1
EXIF High Gain Down Longint 4
EXIF High Gain Up Longint 2
EXIF Low Gain Down Longint 3
EXIF Low Gain Up Longint 1
EXIF None Longint 0
EXIF Cloudy Longint 10
EXIF Cool White Fluorescent Longint 14
EXIF D50 Longint 23
EXIF D55 Longint 20
EXIF D65 Longint 21
EXIF D75 Longint 22
EXIF Daylight Longint 1
EXIF Daylight Fluorescent Longint 12
EXIF Day White Fluorescent Longint 13
EXIF Fine Weather Longint 9
EXIF Flash Longint 4
EXIF Light Fluorescent Longint 2
EXIF ISOStudio Tungsten Longint 24
EXIF Other Longint 255
EXIF Shade Longint 11
EXIF Standard Light A Longint 17
EXIF Standard Light B Longint 18
EXIF Standard Light C Longint 19
EXIF Tungsten Longint 3
EXIF White Fluorescent Longint 15
EXIF Other Longint 255
EXIF Average Longint 1
EXIF Center Weighted Average Longint 2
EXIF Multi Segment Longint 5
EXIF Multi Spot Longint 4
EXIF Partial Longint 6
EXIF Spot Longint 3
EXIF High Longint 2
EXIF Low Longint 1
EXIF Scene Landscape Longint 1
4D v12 Upgrade 347

Appendix
EXIF Night Longint 3

EXIF Scene Portrait Longint 2
EXIF Standard Longint 0
EXIF Color Sequential Area Longint 5
EXIF Color Sequential Linear Longint 8
EXIF Not Defined Longint 1
EXIF One Chip Color Area Longint 2
EXIF Three Chip Color Area Longint 4
EXIF Trilinear Longint 7
EXIF Two Chip Color Area Longint 3
EXIF High Longint 2
EXIF Low Longint 1
EXIF Close Longint 2
EXIF Distant Longint 3
EXIF Macro Longint 1
EXIF Auto Longint 0
GPS Above Sea Level Longint 0

GPS Below Sea Level Longint 1
GPS Above Sea Level Longint 0
GPS Below Sea Level Longint 1
GPS Correction Applied Longint 1
GPS Correction Not Applied Longint 0
GPS Magnetic north Text M
GPS True north Text T
GPS Magnetic north Text M
GPS True north Text T
GPS North Text N
GPS South Text S
GPS North Text N
GPS South Text S
GPS West Text W
GPS East Text E
GPS West Text W
GPS East Text E
GPS 2D Longint 2
GPS 3D Longint 3
GPS km h Text K
GPS miles h Text M
GPS knots h Text K
GPS km h Text K
GPS miles h Text M
348 4D v12 Upgrade

GPS knots h Text K

GPS Measurement in progress Text A
GPS Measurement Interoperability Text V
IPTC Action Longint 11900

IPTC Aerial View Longint 11200
IPTC Close Up Longint 11800
IPTC Couple Longint 10700
IPTC Exterior View Longint 11600
IPTC Full Length Longint 10300
IPTC General View Longint 11000
IPTC Group Longint 10900
IPTC Half Length Longint 10200
IPTC Headshot Longint 10100
IPTC Interior View Longint 11700
IPTC Movie Scene Longint 12400
IPTC Night Scene Longint 11400
IPTC Off Beat Longint 12300
IPTC Panoramic View Longint 11100
IPTC Performing Longint 12000
IPTC Posing Longint 12100
IPTC Profile Longint 10400
IPTC Rear View Longint 10500
IPTC Satellite Longint 11500
IPTC Single Longint 10600
IPTC Symbolic Longint 12200
IPTC Two Longint 10800
IPTC Under Water Longint 11300
TIFF Adobe Deflate Longint 8

TIFF CCIRLEW Longint 32771
TIFF CCITT1D Longint 2
TIFF DCS Longint 32947
TIFF Deflate Longint 32946
TIFF Epson ERF Longint 32769
TIFF IT8BL Longint 32898
TIFF IT8CTPAD Longint 32895
TIFF IT8LW Longint 32896
TIFF IT8MP Longint 32897
TIFF JBIG Longint 34661
TIFF JBIGB&W Longint 9
TIFF JBIGColor Longint 10
TIFF JPEG Longint 7
TIFF JPEG2000 Longint 34712
TIFF JPEGThumbs Only Longint 6
4D v12 Upgrade 349

Appendix
TIFF Kodak262 Longint 262

TIFF Kodak DCR Longint 65000
TIFF Kodak KDC Longint 32867
TIFF LZW Longint 5
TIFF MDIBinary Level Codec Longint 34718
TIFF MDIProgressive Transform Codec Longint 34719
TIFF MDIVector Longint 34720
TIFF Next Longint 32766
TIFF Nikon NEF Longint 34713
TIFF Pack Bits Longint 32773
TIFF Pentax PEF Longint 65535
TIFF Pixar Film Longint 32908
TIFF Pixar Log Longint 32909
TIFF SGILog Longint 34676
TIFF SGILog24 Longint 34677
TIFF Sony ARW Longint 32767
TIFF T4Group3Fax Longint 3
TIFF T6Group4Fax Longint 4
TIFF Thunderscan Longint 32809
TIFF Uncompressed Longint 1
TIFF Horizontal Longint 1
TIFF Mirror Horizontal Longint 2
TIFF Mirror Horizontal And Rotate270CW Longint 5
TIFF Mirror Horizontal And Rotate90CW Longint 7
TIFF Mirror Vertical Longint 4
TIFF Rotate180 Longint 3
TIFF Rotate270CW Longint 8
TIFF Rotate90CW Longint 6
TIFF Black Is Zero Longint 1
TIFF CIELab Longint 8
TIFF CMYK Longint 5
TIFF Color Filter Array Longint 32803
TIFF ICCLab Longint 9
TIFF ITULab Longint 10
TIFF Linear Raw Longint 34892
TIFF Pixar Log L Longint 32844
TIFF Pixar Log Luv Longint 32845
TIFF RGB Longint 2
TIFF RGBPalette Longint 3
TIFF Transparency Mask Longint 4
TIFF White Is Zero Longint 0
TIFF YCb Cr Longint 6
TIFF CM Longint 3
TIFF Inches Longint 2
TIFF MM Longint 4
350 4D v12 Upgrade

TIFF None Longint 1

TIFF UM Longint 5
4D v12 Upgrade 351

Appendix
352 4D v12 Upgrade

4D v12 Upgrade

Hochgeladen von

Dokumentinformationen

Originalbeschreibung:

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

4D v12 Upgrade

Hochgeladen von

Copyright:

Verfügbare Formate

4D v12

IMPORTANT LICENSE INFORMATION

Chapter 2 Architecture and Database . . . . . . . . . . . . . . . . . . . 19

Chapter 3 Development Workshop . . . . . . . . . . . . . . . . . . . . . 29

Chapter 4 Forms and Objects . . . . . . . . . . . . . . . . . . . . . . . . . .71

Chapter 5 Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

SET ASSERT ENABLED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

PHP GET OPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

User Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Chapter 6 SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .295

Chapter 7 4D Server Administration . . . . . . . . . . . . . . . . . . . .321

Appendix A PHP Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

Appendix B Style Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

Appendix C Metadata Constants . . . . . . . . . . . . . . . . . . . . . . . 337

Welcome to 4D v12. Totally open towards the most widespread

Numerous functions that were much in demand by the 4D developer

The new possibility for installing components in the 4D application

Printing functions are enhanced with the new PRINT OBJECT

Finally, the 4D SQL language provides powerful new functions, such as

The new features are detailed in the following chapters:

 Forms and Objects

Conversion of earlier databases

To convert a earlier database to the new version, select it in the

4D v11 SQL r6 Preferences

In version 12 of 4D, there are new macro commands available to

Phasing out obsolete functions

Several new 4D v12 features are related to the architecture of 4D

 New option for data replication via SQL

 New import and export options

 Installation of components at the 4D application level.

Using Universally Unique Identifiers (UUIDs)

Overview A UUID is a type of unique identifier, originally standardized by the

A UUID is a 16-byte number (128 bits). It contains 32 hexadecimal

In 4D v12, UUID numbers are stored in a special format,

4D v12 lets you:

 automatically generate UUIDs in fields with the UUID format via a

Querying and sorting fields with style tags

New property for ignoring styles

This option is related to a new function in 4D v12 to apply different

In the 4D database structure, a new Enable Replication property lets

In SQL, a primary key identifies the column(s) (field(s)) used for

The fields included in the primary key appear as underlined in the

X To remove a primary key from a table:

A confirmation dialog box appears. Click OK to remove the primary

Importing and exporting data

 Integration of Byte Order Mark (export),

 New XML export options.

New export option

This additional information facilitates the text interpretation by the

This option is enabled by default but it is only taken into account

 Encode binary fields in Base64: This option adds the "data:;base64,"

Components installed in the 4D application

In version 12 of 4D, just like plug-ins, you can install 4D components

If the same component is installed in both locations, 4D only loads the

This section outlines the new features and modifications in the

 New functions in the structure editor

 New code editor

 PHP code execution

 New function for recovering data in the MSC.

Options found in the Preferences dialog box for the previous 4D

Note The Language of text comparison option is found both in the

This menu option is available even when there is no open database.

Forms and Objects

New option for data replication via SQL

New import and export options

Installation of components at the 4D application level.

automatically generate UUIDs in fields with the UUID format via a

Integration of Byte Order Mark (export),

New XML export options.

Encode binary fields in Base64: This option adds the "data:;base64,"

New functions in the structure editor

New code editor

PHP code execution

New function for recovering data in the MSC.

Matching parentheses: This option modifies the graphic signaling of

Highlight the line running: Highlights the line that is currently

Automatic opening of window for:

Editing area background: Background color of Method editor

Interpreter address and port number

Restart the interpreter after X requests: This sets the maximum

in the context menu of the editor (click on a table or a relation)

Text: In this case, 4D looks for a character string throughout the

Language expression: Used to search for any valid 4D expression.

is today: Period beginning at midnight (00:00 h) of the current day.

is this week: Period beginning on Monday of the current week.

List all variables in the database:

If a method or form concerned by a "replace in content" operation is

Autocompletion features are extended to variables as well as table and

Uppercase / Lowercase: Switch the selected characters to uppercase or

Collapse / Expand Selection: collapses or expands all the code

field: displays the properties of the field in the inspector of the

form: displays the form in the Form editor,

variable (local, process, interprocess or $n parameter): displays the line

Goto Next / Goto Previous: Enables browsing among bookmarks in the

Ln: Line number

Col: Column number, i.e., the level in the hierarchy of

Handling of ZIP files

COM access (control of MS Office documents)...