SCULPTOR CUMULATIVE NEW FEATURES - 28 November 2006
For a list of bug fixes, see the file bugfixes.txt.
For a list of upward compatibility issues, see the file compat.txt.
For a list of known issues that are not bugs, see the file issues.txt.
--------------------------------------------------------------------
Before upgrading from Sculptor 5.0 or earlier to Sculptor 5.1 or later,
please read the Sculptor 5.1 notes about the security features added to
kfserver in Sculptor 5.1.
Most new features use new code in the interpreters. A program that uses a
new feature will not work with an earlier version of Sculptor. An attempt
to run such a program will produce the message "Program code is damaged".
Programs that are compiled with the latest version of scc but which do not
use new features will work with an earlier run-time system.
The Sculptor servers kfserver and kfservnt support connections from
earlier client versions of Sculptor. Always upgrade the server first.
SCULPTOR 5.7.1
1. The following environment variables, which have the main Sculptor version
number appended, take precedence over the non-version equivalents:
SCULPTOR5
SCDATA5
SAGEDATA5
SCLOGDIR5
A Sculptor 2 update that supports this feature is available. This makes it
easier to run Sculptor 2 and Sculptor 5 on the same system.
SCULPTOR 5.7.0
1. The EV_CHANGE event that is sent when a window is being resized has been
improved by adding a fifth argument that describes the resize event in
more detail. The arguments are now:
EventFunc(EV_CHANGE, win_id, drag_width, drag_height, event_detail)
event_detail is one of:
EV_CHANGE_NEW_SIZE
The window has been resized.
If "Show window contents while dragging" is checked in the user's display
effects, this is an interim event that is sent each time the window has a
new size during a drag opeation.
If "Show window contents while dragging" is unchecked, this event is sent
only once when the user has finished resizing the window because in this
case the user is resizing only the border rectangle.
This event provides the option to show new content in the window in
accordance with the user's preferences.
If the programmer needs to scroll a window that is being resized, this must
be done in the EV_CHANGE_SIZING event and/or the EV_CHANGE_END_SIZE event.
The window must not be scrolled during its EV_CHANGE_NEW_SIZE event.
EV_CHANGE_SIZING
The window has been resized. This is an interim event that is sent
whether or not "Show window contents while dragging" is checked. The
user is still dragging the window border.
EV_CHANGE_END_SIZE
The window has been resized and the user has released the left mouse
button. This event is sent whether or not "Show window contents while
dragging" is checked.
Note that EV_CHANGE events are not default events. They must be enabled.
SCULPTOR 5.6.2
There are two backward compatibility issues in this release.
Please read compat.txt for details.
1. New function: setlocale(category, locale)
Sets the required locale or returns the current locale.
category: Use LC_ALL for all categories. See sculptor.h for other values.
locale: The required locale. This can be a full locale string that
specifies the language, country and code page required, e.g.
"French_France.1252" or just the language, e.g. "French", in which case
the default full string for the specified language is used.
Returns the full name of the new locale. If the supplied value of locale
is NULL or "", returns the full name of the current locale.
See example program: \sculptor\examples\setlocale.r
2. There are two new edit modes for use with editable tables:
EM_NO_HIGHLIGHT
The current line is never highlighted. Only a cell can be focused.
There is still a current line and the is_selected() and set_selected()
functions work as before.
EM_CELL_SELECT_NO_HIGHLIGHT
The current line is not highlighted when a cell has focus. A line
can be highlighted by clicking on a non-editable cell.
3. The do_drag_drop() function now has three optional parameters.
do_drag_drop(object[, format[, width, height]])
If width and height are specified, these define the size of the dragged
rectangle in pixels.
4. There is a new Sculptor debug tool called scdebug.exe. Please see the
reference manual for usage information. Programmers who have beta
versions of this program should remove their existing sculptor\debug
directory completely and replace it with the one in this release. Also,
use Task Manager to check for and end any sagewcd or srepwcd processes
that are running before using scdebug. If a source file does not display
correctly in the debug program, run it through the Sculptor cvteol
program. Note that several features have not yet been implemented in
the debugger and there is no need to report features that simply don't
work yet.
5. Various bug fixes and enhancements have been made to ddeditor, proggen
and file manager. There is a new command line syntax for proggen. See
the reference manual for details.
6. Sculptor can keep an ODBC database automatically synchronised with a
Sculptor database. Read commands work from the Sculptor database, which
is deemed to be the master. Update commands (insert, write and delete)
are applied automatically to both databases.
The Sculptor database can be an explicitly defined +|-database of type
DBT_SCULPTOR, with its own set of !file declarations, or the default
Sculptor database, which contains all independent !file declarations.
The ODBC database must be declared using a -database declaration with
type DBT_ODBC. This is a template database. It should not be opened and
should not contain any !file declarations. It must have a valid source
clause defined at compile time or set dynamically at run-time before
being used. Other database properties such as flags and riu_timeout can
also be specified but riu_timeout should normally be 0, otherwise there
is the risk that an update to the SQL database will be missed simply
because the server is busy.
Any valid source string is acceptable. Examples:
source = "DSN=mydatasource"
source = "DRIVER=SQL Server;SERVER=myserver;DATABASE=master;\
UID=username;PWD=password"
To use this mirroring feature, a program must first call the
set_mirror_source() function to define the Sculptor and ODBC databases:
set_mirror_source(sculptor_db, template_db, logfile, options, callback)
sculptor_db An explicitly declared database of type DBT_SCULPTOR
or NULL for the default Sculptor database that contains
all files declared outside a database declaration.
template_db The template ODBC database. If NULL, any existing
mirror operation stops.
logfile The full pathname to a logfile or "" if a logfile
is not required. Errors in the mirror operation are
logged to this file. Example:
"myserver:/home/sculptor/log/mirror.log"
options Zero or one or more flags combined using |.
Only one flag is currently implemented:
MIRROR_RECREATE_LOGFILE
Forces a new, empty logfile. If not set, error messages
are appended to an existing logfile and a new logfile is
created only if one does not already exist.
callback NULL or the name of a user written !function. If a
function name is supplied and Sculptor later loses
the connection to the SQL database, this function is
called once so that the program knows an error has
occurred and the mirror operation has stopped. The
function is called with a single argument - the id
of the template_db.
After calling set_mirror_source(), use the mirror command to specify the
Sculptor files whose updates are to be mirrored to the ODBC database:
mirror file_id1, file_id2, file_id3, ...
Any number of mirror commands can be executed. It is not necessary to
specify all the files in one command but updates to a file will not be
mirrored until that file has been specified in a mirror command.
Every time a record is updated in the Sculptor database, Sculptor applies
the same update to the ODBC database. Sculptor also automatically inserts
records and creates tables that are missing in the ODBC database.
7. spd now has a settings option to specify whether or not a blank line
is required between controls.
SCULPTOR 5.6.1
1. The function set_thread_execution_state(state) has been withdrawn in
this version as it is not supported by Windows NT4.
SCULPTOR 5.6.0
In the beta versions of 5.6.0, the directories ddeditor, manager and
proggen each had a "Files" sub-directory. These sub-dictories are no
longer used and should be deleted.
The debug programs sagewcd.exe and srepwcd.exe are not supplied with
Sculptor 5.6.0. A new debug tool is being prepared and will be
supplied in a future upgrade.
The Sculptor ODBC interface has been improved and performance is
significantly better, especially with SQL Server. Some compatibility
issues between SQL databases and Sculptor keyed files have been removed.
There are also some useful new features. Existing ODBC based applications
should be re-tested before using this release.
Early beta versions of the new program design tool were named scIDE.exe.
This program is now spd.exe (Sculptor Program Designer). If you have
been working with scIDE.exe, remove the following files before updating
to this release:
In \SCULPTOR\default, remove all user sub-directories (Administrator and
any other login names). These will be recreated with default settings
when you start spd.exe. It will be necessary to redefine any projects
you had created, so you may wish to run scIDE.exe and make a note of
existing project settings before doing this.
descw.exe has been replaced by ddeditor.bat, which runs the Sculptor
program \SCULPTOR\ddeditor\ddeditor.q
spg.bat has been replaced by proggen.bat, which runs the Sculptor
program \SCULPTOR\proggen\proggen.q
The batch file \SCULPTOR\runme.bat removes obsolete files and moves
obsolescent files (such as descw.exe) to \SCULPTOR\obsolete.
New features in Sculptor 5.6.0 are listed below. Full documentation
for these can be found in the Sculptor Reference Manual.
1. table_set_key(table_id, topline, row)
For use with tables whose source_object is a Sculptor Keyed File. Scrolls
the table so that the record whose key matches the current values in the
file's default record buffer is displayed on the specified row of the
table (1 to table_id->rows). If the source_object is an index, the key
values for that index must be set in the record buffer before calling this
function. If a record with the specified key does not exist, the table
is scrolled to the record with the next higher key. The topline argument
determines the position of the vertical scroll bar. If this is not known
a reasonable estimate should be provided or the nextkey command used to
count this key's position from the start of the file.
One use for this function is to restore a table to a previously saved
position. Since the table_get_key() function only returns the values for
the main key fields, code similar to the following must be used to save
the current position when the source_object is an index:
!record save_fileid = fileid
!temp save_topline,,i4
table_get_key(table_id, 1) /* Get key for current top line */
readu fileid nsr=IGNORE /* (if source_object is an index) */
save_fileid = fileid /* Save the current values */
save_topline = table_id->topline /* Save the current top line */
...
fileid = save_fileid
table_set_key(table_id, save_topline, 1)
2. table_check_input(table_id, option)
Checks a table for unsaved input in a textbox cell. Options:
TABLE_TEST_INPUT Returns TRUE if there is unsaved input in a cell,
otherwise FALSE. Does not save the input.
TABLE_SAVE_INPUT If there is unsaved input in a cell, attempts to save
it and returns:
0 There is no input to save.
1 Input saved.
-1 There is invalid input that cannot be saved.
A typical use for this function is during a right mouse event where it
might not be safe to open a popup menu if a cell contains unsaved input.
3. A cell in an editable table can now be a checkbox. Define the cell type
as TCT_CHECKBOX. The box is ticked when the corresponding field in the
source object is non-zero. If the user ticks or unticks the box, an
EV_VALIDATE event is sent. The new value is Arg5 in the event function.
4. spw.exe has been replaced by spd.exe (Sculptor Program Designer). Early
beta versions were called scIDE.exe. This and $SCULPTOR\text\scide.eng
should be deleted. Any projects that exist in $SCULPTOR\default\username
for scIDE should be deleted and recreated using File->New Project and
then Options->Settings in spd.
5. bin\descw.exe has been replaced by ddeditor\ddeditor.q. If $SCULPTOR\bin
is in the search path, this can be started from a DOS prompt by typing
"ddeditor" or "ddeditor ".
6. bin\spg.g has been replaced by proggen\proggen.q. If $SCULPTOR\bin
is in the search path, this can be started from a DOS prompt by typing
"proggen" or "proggen ".
7. There is a new tool manager\kfman.q. This is the Sculptor File Manager.
If $SCULPTOR\bin is in the search path, this can be started from a DOS
prompt by typing "kfman".
8. The file $SCULPTOR\runme.bat deletes obsolete files and moves obsolescent
files such as bin\descw.exe and default\spw.cfg to corresponding
sub-directories in $SCULPTOR\obsolescent. To continue using one of these
files, move it back to its normal place.
9. There is a new printer property called PP_DEFAULTSOURCE. This is the
user selected print bin and is returned by SelectPrinter(). See
printer.h for a list of values (PR_DMBIN_...). Call SetPrintProperty()
to select this bin.
10. New command: writekl (write keep lock). This is identical to the write
command except that the record remains locked. On some SQL databases,
using writekl instead of write can substantially improve performance.
See the notes on improving performance with SQL databases for details.
11. New command: closefile file_id[,file_id]...
Closes the specified files, resets the file positions and releases
other information about the files currently cached on the server. The
closefile command is preferred to the generic close command, which
for historical reasons closes the system file handles but retains the
file position and other information cached on the server.
12. The sql command now has an optional err=label clause. This traps an
error in the sql statement and passes control to the label instead of
generating an ODBC debug message. The err= clause must be the last
clause in the statement. When the err= trap occurs, Sculptor returns
error information in the following system variables:
sys.Error The native database error code (i4).
sys.SQLState The SQL state code (a5).
For SQLState codes, see the Microsoft ODBC documentation. For sql
commands that have no select or parameter variables, the statement is
executed using the ODBC function SQLExecDirect(), otherwise the
statement is prepared using SQLPrepare() and then executed using
SQLExecute().
13. New function: sql_set_stmt_attr(cursor_id, attr_id, value)
Sets a statement attribute for an ODBC cursor. Some useful attribute
id's are defined in sculptor.h (SQL_ATTR_). Associated values are
defined below these. This function is for advanced use with the sql
command. See the Microsoft ODBC documentation for SQLSetStmtAttr()
for further details.
14. nph-srep now supports the execute() function.
15. The Sculptor interpreter now traps a GPF, issues a message and exits
gracefully.
16. The function table_focus_cell() has an optional fourth parameter:
table_focus_cell(table_id, row, col[, view_row])
view_row is a visible row number in the range 1 to table_id->rows
If possible, the line that contains the focused cell is positioned
on view_row. For example, if the table has 5 rows and view_row=3,
the selected row will be the middle row.
17. The EV_RIGHT_MOUSE_UP and EV_RIGHT_MOUSE_DOWN events are now sent
for a static text control if enabled.
18. Windows and groups can have an options= clause. Valid options, which
are defined in sculptor.h, can be combined using the | operator:
OPT_NOCOLOURED Valid for a tab window. The tab does not inherit the
background colour of the tab window. This makes it
possible to have a set of tab windows, each with a
different background colour, but with their tabs
having the same, default window background colour.
OPT_TABOUT Can be set for a group. If a control in the group
has focus and the user presses the tab key, focus
moves the first control outside the group instead
of to the next control in the group.
19. The data type of a field can be retrieved at run-time using:
field_id->datatype
The data type of b4, i4, n4 and u4 fields can be interchanged:
field_id->datatype = new_datatype
The following changes are valid:
b4 (DT_BINARY) to DT_INTEGER, DT_UNSIGNED or DT_NUMBER
i4 (DT_INTEGER) to DT_BINARY, DT_UNSIGNED or DT_NUMBER
n4 (DT_NUMBER) to DT_BINARY, DT_INTEGER, DT_UNSIGNED
u4 (DT_UNSIGEND) to DT_BINARY, DT_INTEGER or DT_NUMBER
All other changes are ignored. No attempt is made to convert
the value in the field.
When a datatype is changed, the number of implied decimal
places is reset to zero. For n4 fields only, the number of
implied decimal places can then be set using:
field_id->impdp = number
One use of the above features would be to define an i4 field in
a data dictionary and then change it at run-time to a type not
supported in the .d file, such as n4.1 or n4.3.
20. The "name=" clause in an openfile command can contain a SQL database
connection string as an alternative to a pathname. Examples:
openfile FILE1 \
name="DBID=db1;DRIVER=SQL Server;SERVER=myserver;DATABASE=master;" create
openfile FILE2 \
name="DBID=db1;DRIVER=;...;UID=username;PWD=password;" update
The first field=value pair must be "DBID=database_id;" where database_id
is a database declared in the Sculptor program. This informs Sculptor
that the table is to be attached to that database. All other field=value
pairs are standard. If a value parameter contains non-alphanumeric
characters, it should be enclosed in {}. Example:
openfile FILEID name="DBID=db1;...;SERVER={myserver-001};...;" update
The table name is taken from the !file declaration. Sculptor ignores any
path information and extracts only the base filename for use with ODBC.
For a complete definition of an ODBC connection string, see the MSDN
documentation for the function SQLDriverConnect().
You don't need UID and PWD if you are using Windows Authentication and
a trusted connection but you need them if you are using SQL Server
authentication.
There is no need to define an ODBC data source. The following database
definition is sufficient:
-database db1 {
type = DBT_ODBC
flags = DBFL_CASE_SENSITIVE /* This clause is optional */
!file FILE1 "file1"
!file FILE2 "file2"
}
-database must be used because the database can't be opened until the
first openfile command has supplied the connection information.
When this type of openfile command is used, the files can be declared
inside the database structure as above or outside as below:
-database db1 {
type = DBT_ODBC
flags = DBFL_CASE_SENSITIVE /* This clause is optional */
}
!file FILE1 "mydata/file1"
!file FILE2 "mydata/file2"
21. Because SQL Server waits on a locked record and does not return a record
in use status, a timeout option has been introduced in the database
structure. If a timeout occurs, it triggers the riu trap:
-database mydb {
riu_timeout = 5 /* Value in seconds */
}
The riu_timeout value can be changed at run-time:
mydb->riu_timeout = 0
A value of zero means no timeout and SQL Server will wait indefinitely
for a locked record.
22. Sculptor keyed files sort positive integer key values first, followed
by negative key values. SQL databases sort negative values first. The
Sculptor sequence is historical but some applications rely on it. If the
SQL database supports binary fields, it's possible to sort one or more
key fields in the same way as Sculptor. To do this, the SQL database
must be created in Sculptor with one or more flags set. Once the table
has been created, the sort sequence is fixed, so the flags are not
needed when opening an existing table.
To make a specific i2 or i4 key field sort positive values first, set
its "U" flag at run-time before creating the table:
fldname->flags = "U" (the U must be upper case)
To make all main index key fields sort positive values first, set the
following database flag before creating the table:
flags = DBFL_UNSIGNED_KEYS
DBFL_UNSIGNED_KEYS has no effect on secondary index key fields, so the
"U" flag must be set for these if required.
When Sculptor creates the table, it makes the i2 or i4 field a binary(4)
field in the SQL data dictionary. Sculptor then handles all translations
between integer and binary automatically.
To make it easy to use a non-Sculptor reporting tool, Sculptor creates
a second, computed SQL field for each such binary field (but only if
the SQL database supports computed fields). These fields are given the
same name as their corresponding Sculptor fields but have the prefix
"int_". When these fields are retrieved in a reporting tool, their
values are returned as normal integers. Computed fields are read-only
and cannot be updated.
23. The Microsoft Access ODBC driver is not multi-user safe and we advise
using Access in single user mode only. If it is essential to work with
Access in multi-user mode, set the following flag in the database
declaration:
flags = DBFL_ACCESS_MULTIUSER
This tells Sculptor to perform updates to an Access database in a slower
but more reliable way. This technique has proved reliable in tests but
safe multi-user operation cannot be guaranteed. This flag must also be
set if you are using an Access data dictionary that contains a key field
of type AutoNumber.
24. New command: sync_indexes file_id[, file_id]...
Synchronises the current file position of all secondary indexes for the
specified file to the current main index file position. Otherwise, each
index maintains its own file position. The sync_indexes command affects a
subsequent next[u], nextkey, prev[u] or prevkey command on a secondary
index. Note that if the user defined key for a secondary index is not
unique, the read[u] and readkey commands on that index always return the
first record that has the supplied secondary index key - the current
values in the main key fields are not taken into account.
25. To obtain maximum database compatibility, the batch_read flag is now
OFF by default for both Sculptor and ODBC files. Setting this flag can
improve performance substantially. Setting this flag is recommended in
most circumstances. See the Reference Manual for guidelines.
26. New function: set_thread_execution_state(state)
Sets the execution state of the current program. Some power save settings
cause the execution of a background process to pause until the user moves
the mouse or presses a key. This function can be called to inform Windows
that this program must be kept running. Normal, interactive programs do
not need to call this function. For details, please see the documentation
for the function SetThreadExecutionState() in the Windows API. States are
defined in sculptor.h beginning ES_. The return value is the previous
state (i4).
SCULPTOR 5.5.4
See bugfixes.txt.
SCULPTOR 5.5.3
1. The directory name in the dir() function can be on a server and can
contain environment variables.
2. array_to_text(start_element, count)
Extracts characters from an array starting at the specified element.
Continues across element boundaries until 'count' characters have been
extracted or the end of the array is reached. The array can have multiple
dimensions. Returns a long text string.
!temp LongText,,a200[10],,p
!temp TextArray,,a100[20,1000]
LongText = array_to_text(TextArray[10,1], 2000)
3. text_to_array(start_element, count, text)
Copies characters from a text string, which can be long text, to an array
starting at the specified element. Continues across element boundaries until
'count' characters have been copied or the end of the array is reached. The
array can have multiple dimensions.
text_to_array(TextArray[10,1], 2000, LongText)
4. The style WS_THEMED has been introduced for static text. This style should
be set for static text that is used as a control label. When the program is
running in a themed environment, Sculptor draws the text using the theme
style and colour. It is not possible to override the foreground colour of
themed text. If a foreground colour is specified, it is ignored in a themed
environment and used only in a classic environment. If a background colour
is specified, it is used in both environments but specifying a background
colour for themed text is not recommended as it may clash with the selected
theme. Also, in a themed environment, Windows draws standard control labels
two pixels left of the position it draws them in a classic environment. For
this reason, programs that use themed text are best designed on a themed
platform, especially if themed text needs to be aligned with standard
control labels. To compensate for this difference, Sculptor positions
themed text two pixels right of its defined x coordinate when the program
is running on a classic Windows platform.
5. If the user clicks a window's close button while a textbox has focus and
in the EV_CLOSE event the program exits, then by default any value typed
into the textbox is not saved. This allows a program to be closed even
though invalid data has been typed into the textbox. If the program
requires the value to be saved, subject to validation, then it can now
execute the save_text command in the EV_CLOSE event.
SCULPTOR 5.5.1 and 5.5.2
See bugfixes.txt.
SCULPTOR 5.5.0
1. In a program compiled with scc 5.5 or later, a menu defined in a child
window with style WS_OWNED now appears in the child window instead of the
parent. If an existing program relies on this behaviour, the menu should
be moved to the parent window before recompiling the program. If this is
inconvenient, add or uncomment the line "!compat childmenu=4" in the
standard header file $SCULPTOR/include/local.h.
2. The quality of scaled images has been improved.
3. Buttons are now supported as headings for table columns. The following
fields have been added to the cell_properties record for a table:
heading_type,,u1[numcols]
This can be 0 (for the standard, text heading) or TCT_BUTTON (for a
push button).
heading_event,,p[numcols]
This defines the event function for the heading control. For TCT_BUTTON,
the only event sent is EV_BUTTON_CLICKED but the event code should be
checked because new events may be added in the future. Note that this
is a pointer field. The following syntax should be used to set the
required event function:
heading_event[col] = &EventFunc
The event sent is:
EventFunc(EventCode, Object, Line, Col)
Object is the table id, Line is 0, Col is the column number.
4. An EV_MOUSE_OVER event can be enabled for a window or control:
event_enable = EV_DEFAULT | EV_MOUSE_OVER
If enabled, the object receives a stream of EV_MOUSE_OVER events as the
mouse passes over it. These events are only received if the program is
in a dialog. The event function is called as follows:
Tables:
func(event_code, table_id, line, column, xctl, yctl, xwin, ywin, virtkey)
line The line number clicked (0=headings, -1=below last line)
column The column number clicked (0=left of first, -1=right of last)
Other arguments as for other controls below.
func(event_code, object_id, xctl, yctl, xwin, ywin, virtkey)
xctl X position in pixels relative to the control.
yctl Y position in pixels relative to the control.
xwin X position relative to the control's effective, parent window.
In pixels or characters depending on the program grid.
ywin Y position relative to the control's effective, parent window.
In pixels or characters depending on the program grid.
virtkey A virtual key code that indicates the state of mouse buttons, the
shift key and the control key. See the defines prefixed MK_ in
SCULPTOR\include\sculptor.h for bit values that can be tested
using the & operator.
The effective parent is the highest window in the parent window chain that
has no further parent or has style WS_OWNED.
5. A browse_for_folder() function has been introduced. This creates a browse
dialog that uses a tree view control and returns a selected folder name.
It can also be used to select a filename.
browse_for_folder(window_id, parameter_record)
window_id The dialog is opened relative to this window.
parameter_record
The name of a !record structure defined as follows:
!record {
Title,,a80
DisplayName,,a80
Flags,,i4
RootIDL,,i4
RootPath,,a255
}
Fields that are not required can be omitted, in which case their value, if
required, is taken to be zero or blank.
Title A text string that is displayed above the tree view control in the
dialog window. Can be used to provide instructions such as
"Please select a folder to save this document."
The a80 size is arbitrary. The field can be larger or smaller.
DisplayName
Receives the name of the selected file or folder without path
information. Blank if the user cancels the dialog. The a80 size
is arbitrary but the field needs to be large enough to receive
the name of any object that can be selected.
Flags Zero for default options, otherwise one or more of the !define
flags prefixed BIF_ in SCULPTOR\include\files.h, combined using
the | operator. If the BIF_BROWSEINCLUDEFILES flag is set, the
dialog allows files as well as folders to be selected but the
program must then determine the type of the returned object. The
Sculptor function fileinfo() can be used for this purpose.
RootIDL An integer value that identifies the root folder for the dialog.
If zero, the root folder specified in RootPath is used, otherwise
this should be one of the !define values prefixed CSIDL_ in
SCULPTOR\include\files.h identifying a standard, Windows folder.
If the standard folder does not exist on the system, the default
root path (the desktop) is used.
RootPath
If RootIDl is 0, the pathname to be used as the root folder. Either
'/' or '\' can be used as a directory separator but note that in a
string constant, '\' must be escaped by typing "\\".
browse_for_folder() returns the full pathname of the selected file or
folder. If the user selects a special object, such as a computer name, the
returned pathname is blank and the object name is in the DisplayName field.
This is only possible if the root path allows access to such an object. If
the user cancels the dialog, both the return value and DisplayName are
blank.
browse_for_folder() is a direct interface to a Windows control that can
behave differently depending on the version of Windows and in some cases
the version of Internet Explorer that is installed. In general, simple
browsing for a file or directory with the default flags works the same on
all systems but for more complex folder browsing, refer to the Microsoft
documentation for the SHBrowseForFolder() function and test on all the
Windows platforms that you need to support. One point worth noting is that
the BIF_NEWDIALOGSTYLE flag creates a "New Folder" button on platforms
that support it but the BIF_NOWNEWFOLDERBUTTON flag, which omits this
button, is not supported on some platforms that support BIF_NEWDIALOGSTYLE.
The sample program browse_for_folder.r in SCULPTOR\examples can be used
to test all combinations of flags and root pathnames.
6. The current text in a textbox, including a textbox that is the currently
focused cell in an editable table, can be retrieved by calling the function
get_text(control_id). This is particularly useful inside an event function.
For a button, this function returns the label. For other controls get_text()
currently returns a null string but this may change in the future.
7. The system variable sys.UseTheme (u1) has been added. A non-zero value
indicates that Sculptor is using a Windows Theme. A zero value indicates
that it is using a classic style. "!compat notheme=0|1" has also been
introduced. Setting this non-zero forces the program to use a classic
style even if the user has selected a theme for the desktop. On versions
of Windows that support themes, sys.UseTheme can be changed at run-time.
BUG: The windows and controls are repainted but a slight remnant from
the previous style exists. This is being investigated.
8. The Sculptor File Manager has been released. This program, written in
Sculptor, is a front end for the keyed file utilities kfcheck, kfri, newkf
and reformat. The output of the utilities is displayed in a table, which
can be printed or saved to a file. The program also contains options to
move, rename, copy or delete a Sculptor keyed file and all associated files
and directories. File Manager also acts as a front end for the Sculptor
directory copying program kcopydir. The File Manager program is called
kfman.q and it is located in the directory $SCULPTOR\manager.
SCULPTOR 5.4.3
1. There are functions to convert between pixel and character co-ordinates:
cols_to_pixels(window_id, ncols)
rows_to_pixels(window_id, nrows)
pixels_to_cols(window_id, npixels)
pixels_to_rows(window_id, npixels)
Each function converts the supplied value and returns the result. The
window_id is needed because the character grid is based on the window's
data font.
SCULPTOR 5.4.2
1. Considerable functionality has been added to nph-srep. For details, see
"Special tags for HTML files" in the Sculptor Reference Manual.
SCULPTOR 5.4.1
1. There is a new function that provides advanced execution and control of
child processes:
execute(server, command, directory, flags, show[, stdin, stdout, stderr])
server Name of server. NULL or a null string for the local machine.
command The program to be executed and any arguments. Prefix the command
with "-" to avoid getting a command shell. A command shell is
needed if the command contains I/O redirection. On Unix but not
on Windows, a shell is needed if there any wildcard arguments.
A trailing "&" is optional because execute() always runs the
child process concurrently.
directory Directory in which program starts. NULL or null string for the
current working directory of the parent program.
flags On Windows, this is passed as the creation flags argument to
the CreateProcess() function. Not used on Unix. Use 0 for
standard options. Some of the more useful flags are defined
in sculptor.h beginning EXEC_. This is an advanced feature for
special requirements. Please read the Microsoft documentation
before using. Multiple flags are combined using the | operator.
show Requested show option for the child process. This must be one
of the AA_ flags defined in sculptor.h. If there is no special
requirement, AA_SHOWNORMAL is recommended. Do not code as 0
(AA_HIDE) unless you want the child process to be hidden. Some
programs will override this flag when they start.
stdin If non-zero, specifies a channel number. Sculptor creates a pipe
that connects this channel in the parent program to the standard
input channel of the child process. The commands put #stdin and
putfield #stdin can then be used to write messages to the child's
standard input (where stdin is this channel number).
The channel number specified for stdin must not be open when
execute() is called and must be closed using close #stdin when
it is no longer required.
If the child process is a Sculptor program, it can open its
standard input channel as follows:
open #channel, "stdin" read
A Sculptor program can also read from its standard input using
get #0 and getfield #0. Channel 0 should not be opened or closed.
stdout If non-zero, specifies a channel number. Sculptor creates a pipe
that connects this channel in the parent program to the standard
output channel of the child process. The commands get #stdout and
getfield #stdout can then be used to read the child's standard
output messages (where stdout is this channel number).
The channel number specified for stdout must not be open when
execute() is called and must be closed using close #stdout when
it is no longer required. stdout cannot be the same as stdin.
If the child process is a Sculptor program, it can open its
standard output channel as follows:
open #channel, "stdout" create
A Sculptor program can also write to its standard output using
put #0 and putfield #0 but this method is not recommended because
put #0 writes to the current report output when used inside a
"run report" command.
Messages written to stdout are buffered by the operating system
and are only flushed when the buffer is full, the program exits,
the channel is closed or an explicit flush command is called.
Programs that communicate through pipes must ensure that any
output to a pipe is flushed before they wait for input on another
pipe. This can be done with the command:
flush #channel
stderr If non-zero, specifies a channel number. Sculptor creates a pipe
that connects this channel in the parent program to the standard
error channel of the child process. The commands get #stderr and
getfield #stderr can then be used to read the child's standard
error messages (where stderr is this channel number).
The channel number specified for stderr must not be open when
execute() is called and must be closed using close #stderr when
it is no longer required. stderr cannot be the same as stdin but
it can be the same as stdout and this is often the most useful
option.
If the child process is a Sculptor program, it can open its
standard error cahnnel as follows:
open #channel, "stderr" create
The comments above about flushing stdout also apply to stderr.
stdin, stdout and stderr are not yet supported for programs executed on a
server.
If execute() fails, it returns -1 and stores the current system error code
in sys.Errno but there can be many reasons for failure and some may not
generate a meaningful error code.
If execute() is successful, it returns a handle to the child process. The
execute() function does not wait for the child process to exit. The handle
must be stored in an i4 field and can be used to get information about and
to control the child process. The close_handle() function must be called
when the handle is no longer required, otherwise system resources allocated
to the child process will not be freed, even after the process has exited.
2. The following new functions work with handles:
2.1 exitcode(server, child_handle, wait_msecs)
server Name of server. NULL or a null string for the local machine.
child_handle A field containing a value returned by execute().
wait_msecs Milliseconds to wait. If wait_msecs is 0, exitcode() returns
the current state of the child process immediately, otherwise
it waits until the child process terminates or the specified
number of millisconds has elapsed, whichever occurs first.
exitcode() returns the child's exit code (0-255) or one of the following
sepcial values, defined in sculptor.h:
CHILD_PROCESS_RUNNING -3
CHILD_PROCESS_INTERRUPTED -2 Terminated by an interrupt.
CHILD_PROCESS_FAILED -1 The execute() was not successful.
If the process exit code is above 255, only the low order byte is returned.
This is a system limitation on both Unix and Windows.
If the Window's Task Manager is used to end a process, it seems to exit with
1 (if "End Task" is used) or 0 (if "End Process" is used) but this has been
determined by experiment and not found in any documentation.
It is bad practice to use a wait time longer than a few seconds because this
prevents Sculptor from processing messages. Windows programs should process
messages at frequent intervals to prevent undesirable effects such as not
repainting a revealed window. On the other hand, a pure code loop wastes
CPU time that can be better allocated to other tasks. Best practice is to use
a delay loop as shown in the following example:
do {
tmp.ExitCode = exitcode(NULL, tmp.ChildHandle, 300)
} while (tmp.ExitCode == CHILD_PROCESS_RUNNING)
2.2 end_process(server_name, child_handle, exitcode)
server Name of server. NULL or a null string for the local machine.
child_handle A field containing a value returned by execute().
exitcode Required exit code (Windows) or interrupt number (Unix).
Forces the specified process to terminate. On Windows, the process exits
with the specified exit code. On Unix, this value is the interrupt to be
sent to the process (0 means use the default, which is SIGTERM).
2.3 close_handle(server_name, child_handle)
server Name of server. NULL or a null string for the local machine.
child_handle A field containing a value returned by execute().
Closes the specified handle and sets the value of the handle field to -1.
This function must be called when the handle is no longer needed, otherwise
resources remain allocated to the child process even though it has exited.
3. server_info(server, rec_id)
Returns information about the named server and places it in fields in the
supplied record buffer. Some or all of the following fields can be defined.
The order of the fields in the record is not important. Other fields not
used by this function can also be defined.
rec_id.MaxUsers The number of licensed users on the server.
rec_id.Platform The server platform: 1=Windows, 2=Unix.
rec_id.ScMajorVersion The major version number of the Sculptor server.
rec_id.ScMinorVersion The minor version number of the Sculptor server.
rec_id.ScFixVersion The fix version number of the Sculptor server.
rec_id.ScDateVersion The release date of the Sculptor server.
server_info() Returns 0 if the call is successful or -1 if the specified
server cannot be contacted.
4. nap(millisecs)
Suspends the calling program for at least the specified number of
milliseconds but sometimes for longer due to clock granularity and task
switching.
5. When Sculptor starts a concurrent (background) child process on Windows, it
normally calls a Windows function that waits for the child process to finish
initialising. A timeout of 30 seconds is used. The parent program does not
continue until the child process is "waiting for user input with no input
pending" or 30 seconds has elapsed. This gives the child process time to
start up and gain focus. This causes an undue delay if the child process
does not normally interact with the user or has substantial work to do
before interacting with the user. To avoid this delay, put "&&" at the end
of the command line. This is valid with exec, execu and execute().
6. Two new functions are available that make it easier to mix the drawing
functions with standard Sculptor print commands:
getprintxy(fld_xpos, fld_ypos)
fld_xpos and fld_ypos receive the current x and y position in device units
associated with the Sculptor print[h] command. These values can be used to
determine suitable co-ordinates to use with a drawing function.
setprintxy(expr_xpos, expr_ypos)
Sets a new x and y origin for the next Sculptor print[h] command. Sculptor
resets it's current column and line numbers to match, rounding up to the
next whole character and line position if necessary. Example:
print "This line precedes the formatted text"
print tab(0); /* Move to start of left margin */
sys.Unit = 0 /* Work in device units */
getprintxy(xpos, ypos)
yinc = DrawFormattedText(NULL, xpos, ypos, packed_text, "Arial@10", \
80 * sys.AvgCharWidth, 4 * sys.LineHeight, \
DT_WORDBREAK | DT_EDITCONTROL)
setprintxy(xpos, ypos+yinc)
print "This line follows the formatted text"
The field "packed_text" in the above example would be an array field with
format "p" used to store text typed into a free format, multiline textbox.
7. Sculptor now conforms to the Windows XP Theme when that is selected.
At present, image and coloured buttons do not adopt the XP theme. These
controls will be enhanced in a later release.
NOTE: Sculptor support for the Windows XP theme is now built in. Any
existing files in the SCULPTOR\BIN directory with extension .manifest
should be deleted.
8. When an EV_KEYSTROKE event or a function called by an "on local" or
"on global" command sets focus to a new control, any new content that was
typed into a textbox is not saved. This is useful because it is possible to
trap a keystroke and cancel the input. To validate and save the input before
the new control gains focus, use the new "save_text" command inside the
function. Note that this command does not save the text immediately. It gets
saved when the function returns provided that the input is valid. If the
textbox has a validation function, this will be called first. Example:
on global KEY_PGDN PageDown
...
!function PageDown() {
save_text
switch (sys.CurrentControl) {
case ?= TextBox1:
return TextBox2
case ?= TextBox2:
return TextBox3
}
}
9. sys.InputRow has been introduced. Sculptor sets this to the current row
number when it saves text in sys.InputBuf. This applies to standard,
multi-row textboxes, not to free format textboxes.
10. The system handle for a window or control can be obtained from its
window_handle property. This read only property can be used to set
an OLE control property that requires a window handle. Example:
oleMPlayer->"hWndDisplay" = winVideo->window_handle
11. Normally, Sculptor keeps a bitmap permanently allocated for each table but
if the environment variable SC_CONSERVE_MEMORY is set, this bitmap is
destroyed and recreated as needed. This variable is provided for use when
several large programs need to run concurrently and the physical memory pool
is being exhausted, causing swapping. Typically, this will only be an issue
in a terminal server environment, such as Citrix. Screen drawing is slower
when this variable is set. (To use SC_CONSERVE_MEMORY, set its value to 1.
Sculptor does not check the value at the moment but in the future, the
value 0 may be interpreted as false.)
12. The event EV_CHANGE is sent to a window event function after the user has
resized the window:
EventFunc(EV_CHANGE, window_id, old_width, old_height)
The new width and height are in window_id->view_width and view_height. This
event must be enabled (event_enable = EV_DEFAULT | EV_CHANGE).
13. fontmetrics(FontDefn, AverageCharWidth, CharHeight)
This function takes a font definition, e.g. "Arial@8" and returns the
average character width and the character height in pixels in the fields
provided. In a program that uses pixel co-ordinates, these values could be
used to set a window width and height to suit a user selected font:
window_id->max_width = AverageCharWidth * 120 /* 120 columns */
window_id->max_height = CharHeight * 40 /* 40 rows */
14. The system temp sys.LoggedOnUser is a variable length, alphanumeric field
that is initialised to the name of the logged on user the first time its
value is read. The name is available on M/S Windows and Unix and is
obtained from an operating system call, not from the environment variable
LOGNAME. This makes sys.LoggedOnUser more secure than sys.UserName. On
some Unix systems this call is very slow, which is why the value is not
initialised automatically when the program starts. Since the field length
is 0 until it has been read for the first time, a textbox that is linked
to this field must be created after retrieving the value. The following
code can be used:
!temp Dummy,,a1 /* Field size not important for this purpose */
tmp.Dummy = sys.LoggedOnUser
create tbLoggedOnUser
display tbLoggedOnUser
15. When a report is run using ppf="winrtf", Sculptor creates a temporary file
and opens it with the default or a specified viewer program. Sculptor then
waits for the viewer to close the file in order to delete it. Some viewers
keep the file open, forcing Sculptor to wait until the program exits. There
has also been a report that on multi-processor systems, the file can be
deleted before the viewer program has opened it. To resolve these issues,
a new program, waitdel.exe, is now supplied with Sculptor. After passing
an rtf file to a viewer, Sculptor runs this program in the background. The
program waits for 30 seconds so that the the viewer program has had time
to load the file, then waits until it is able to delete the file. This
resolves both the above issues.
SCULPTOR 5.3.3
1. Tables and listboxes now support the tooltip clause.
SCULPTOR 5.3.2
1. It is no longer necessary to destroy and recreate a table in order to
change the colour properties of headings, labels, etc.
2. There is an optional, sixth argument to the fileinfo() function:
fileinfo(pathname, size, date_created, date_accessed, date_updated[, mode])
The mode field contains bits that define file type and permissions.
See $SCULPTOR/include/files.h for details.
3. To make it easier to debug Internet applications, a trace option has been
added to nph-srep. To use this, set the environment variable TRACE_NPH-SREP
to the full path to a file, e.g. C:/TMP/nph-srep.txt. This variable must be
set at system level and the system rebooted because nph-srep inherits its
environment from a web server that starts running when the system is booted.
If this variable is defined, nph-srep creates the file and writes debugging
information to it, such as its working directory and the values of web
parameters. If this file is not created, then either nph-srep has not been
called or you are using an old version. Check that you have nph-srep.exe
version 5.3.2d or later in your cgi-bin directory by running it with no
arguments from a DOS command. Later versions display their version number
and the value of TRACE_NPH-SREP. The file xerces-c_1_3.dll must also be in
the cgi-bin directory. Check that this file is not named incorrectly as
xerces_c_1_3.dll. The new version of nph-srep also writes some error
messages into the web page that previously were lost.
4. There are two new functions to control the formatting of text drawn with the
DrawText() function. These are:
GetTextAlign(window_id)
SetTextAlign(window_id, flags)
GetTextAlign() returns the current formatting options as bit flags in an i4
integer. SetTextAlign() defines a new value and returns the previous value.
If window_id is NULL, it refers to the current report. Bit flags are combined
using the bitwise or operator (|). The following flags are defined in
$SCULPTOR/include/draw.h:
TA_LEFT /* Align left */
TA_RIGHT /* Align right */
TA_CENTRE /* Align centre */
TA_TOP /* Align top */
TA_BOTTOM /* Align bottom */
TA_BASELINE /* Align to baseline */
TA_RTLREADING /* Right to left reading (Arabic and Hebrew) */
TA_REPORTDEFAULT /* Default in printed reports */
TA_SCREENDEFAULT /* Default in screen windows */
TA_LEFT informs DrawText() that xpos is the co-ordinate for the left end of
the text. Text printed with the same xpos co-ordinate is left aligned.
TA_RIGHT informs DrawText() that xpos is the co-ordinate for the right end
of the text. Text printed with the same xpos co-ordinate is right aligned.
TA_CENTRE (or TA_CENTER) informs DrawText() that xpos is the co-ordinate for
the centre of the text. Text printed with the same xpos co-ordinate is
centre aligned.
TA_TOP informs DrawText() that ypos is the co-ordinate for the top of the
text. Text printed with the same ypos co-ordinate is aligned along the top
regardless of its font height. This is the default for text drawn in a
window.
TA_BOTTOM informs DrawText() that ypos is the co-ordinate for the bottom of
the text. Text printed with the same ypos co-ordinate is aligned along the
bottom regardless of its font height. This is the default for text drawn in
a report and is compatible with the Sculptor print command.
Note that TA_LEFT and TA_TOP are defined as 0. Conflicting combination such
as TA_LEFT | TA_RIGHT and TA_TOP | TA_BOTTOM cause the non-zero value to
take precedence.
To retain compatibility with other Sculptor code, programs should reset the
text align flags to TA_SCREENDEFAULT or TA_REPORTDEFAULT.
5. There is a new function called DrawFormattedText(). This draws text in a
window or report using various formatting options and is more powerful than
DrawText(). It can format text on a single line or wrap it over multiple
lines. The syntax is:
DrawFormattedText(window_id, xpos, ypos, text, font, width, height, format)
xpos and ypos specify the co-ordinates of the top left corner of a rectangle
with the specified width and height. The width and height parameters must be
supplied to DrawFormattedText(). The text is formatted into this rectangle.
If window_id is NULL, the text is drawn in the current report.
The xpos, ypos co-ordinates and the width, height values are in the unit
specified by sys.Unit. If sys.Unit is zero, device units are used. If
sys.Unit is non-zero its values is the required unit in inches. Some useful
values are defined in $SCULPTOR/include/draw.h.
Because xpos and ypos refer to a rectangle that can span more than one line,
DrawFormattedText() always uses the TA_LEFT and TA_TOP text alignment flags.
This means that text drawn in a report with DrawText() and default alignment
will be about one line higher than text drawn with DrawFormattedText() at the
same ypos co-ordinate.
Format flags are combined using the bitwise or (|) operator. They are the
defined in $SCULPTOR/include/draw.h and begin with DT_. Example:
DrawFormattedText(NULL, 1.4, 2.5, text, font, 5.0, 4.5, \
DT_EDITCONTROL | DT_NOPREFIX | DT_NOCLIP)
DrawFormattedText() returns the height of the text in the current unit
unless DT_VCENTRE or DT_BOTTOM is specified, in which case the return value
is the offset from ypos to the bottom of the text.
SCULPTOR 5.3.1
1. rename(oldname, newname)
Renames a file.
Returns 0 if successful or a negative value if an error occurs and stores
the system error code in sys.Errno. If oldname refers to a file on a server
then newname must refer to the same server or omit the server name, in which
case it is assumed to refer to the same server. Pathnames can be absolute or
relative to the current working directory but it is generally necessary to
use absolute pathnames when renaming files on a server.
A file can be renamed to a different directory. A directory can be renamed
but cannot be moved to a new node in the file system tree. Examples:
rename("c:/olddir/fileoldname", "c:/newdir/filenewname")
The following two calls are equivalent:
rename("myserver:c:/app/data/old.d", "c:/app/data/new.d")
rename("myserver:c:/app/data/old.d", "myserver:c:/app/data/new.d")
2. isnull(ptr)
Returns TRUE if the specified pointer field (!temp type p) is null, i.e.
does not point to another object, otherwise FALSE. This makes it possible
to distinguish between the pointer itself being null and the object being
pointed to having a null value.
3. The OpenIndex() and IndexFieldProp() functions have been implemented. See
readdotd.doc for details.
4. The EV_RIGHT_MOUSE event sends extra arguments and the order of arguments
has changed for tables:
Tables:
func(event_code, table_id, line, column, xctl, yctl, xwin, ywin)
line The line number clicked (0=headings, -1=below last line)
column The column number clicked (0=left of first, -1=right of last)
Other arguments as for other controls below.
Windows and other controls:
func(event_code, object_id, xctl, yctl, xwin, ywin)
xctl X position in pixels relative to the control.
yctl Y position in pixels relative to the control.
xwin X position relative to the control's effective, parent window.
In pixels or characters depending on the program grid.
ywin Y position relative to the control's effective, parent window.
In pixels or characters depending on the program grid.
The effective parent is the highest window in the parent window chain that
has no further parent or has style WS_OWNED. This is the window in which a
popup menu should be opened. Example code:
Character Grid:
at xwin, ywin in parent_id
open popup_id
Pixel Grid:
move cursor to xwin, ywin in parent_id
open popup_id
5. In an RTF printer parameter file, such as winrtf.s, it is now possible to
specify the word "default" (case insensitive) to indicate that the RTF file
produced by a report should be opened with the default application for this
file type. This avoids the need to specify a program pathname, which can
vary between different Windows platforms. If the output is to a temporary
file (no "to filename" clause), the temporary file is deleted automatically
by Sculptor when the application closes it. In the case of Wordpad, this
happens as soon as the file has been read but since Microsoft Word keeps
the file open, Sculptor has to wait until Word exits or the user closes the
file.
6. The following editmodes have been added to LIST_EDIT controls:
EM_READONLY, EM_NOECHO, EM_UPPERCASE, EM_LOWERCASE
7. The event codes EV_RIGHT_MOUSE_DOWN and EV_RIGHT_MOUSE_UP have been added.
If these ecents are required, they must be enabled using the event_enable
clause. Popup menus should be opened when the up event is received, so the
old event code EV_RIGHT_MOUSE is now an alias for EV_RIGHT_MOUSE_UP.
8. The copyfile() function has a new option: COPY_MAKEPATH. If this flag is
specified, all missing directories in the destination path are created.
9. When Sculptor updates application programs to the $SCULPTOR\APP directory
(or to $SCLOCALBIN), printer parameter files to $SCULPTOR\PRINT and
terminal parameter files to $SCULPTOR\TERM, it now creates all directories
in the target path that do not already exist. This makes it possible, for
example, to store application programs in $SCULPTOR\APP\MYAPP\BIN without
having to create any part of this path first.
10. If the new flag EM_SYNC_SOURCE is set for the mode of a table, both the
source and display objects are updated when a cell loses focus instead of
just the display object.
11. The argument to record_count() can now be a file_id, index_id or filename.
12. A "-F " option has been added to kfbuild, kfcheck, kfcopy, kfdet,
kfri and reformat programs. This places all messages that would otherwise
go to the terminal into the named file. It also suppresses all questions.
The main purpose of this option is to enable these programs to be called
from a Windows front end. A suitable front end is being developed and will
be available soon.
SCULPTOR 5.3.0
1. The behaviour of the left and right arrow keys in a textbox group has
changed in programs compiled with Sculptor 5.3. In programs compiled
with scc 5.1 or earlier, the arrow keys navigate as before - at the end
of a textbox, the right arrow key moves to the next textbox in the group
and at the start of a textbox, the left arrow key moves to the previous
textbox in the group. In programs compiled with scc 5.3 or later, the
left and right arrow keys stay in the same textbox, unless the program
contains the line "!compat arrowkeys=N" where N is a digit less than 5.
2. A table has a new property called "cell_properties" to which a record
structure can be assigned as shown below.
!record CellProperties {
cell_type,,i4[numcols]
list_field,,p[numcols]
drop_size,,i4[numcols]
list_size,,i4[numcols]
cell_style,,i4[numcols]
cell_mode,,i4[numcols]
cell_caption,,a###[numcols]
cell_caption_pen,,i2[numcols]
cell_width,,i2[numcols]
}
!table mytable ... {
...
cell_properties = CellProperties
}
numcols is the number of columns in the table. The record does not have
to have the name CellProperties; any valid object name can be used. Also,
it is only necessary to define the fields that the program uses.
To set the properties of a cell at run-time, assign the required values
to the appropriate field elements before the cell gains focus. If the
required values are set in this record, it is not necessary to call the
table_set_type() function. The list_size property sets the maximum size
for the list. This is useful if the list_field is an array but not all
elements are to be listed.
The cell_width field defines the required cell width. Zero is the default,
based on the heading and the linked field. Greater than zero is the
required width in pixels. Negative values are reserved for future use.
NOTE: spw has not yet been updated to take account of this new feature.
Although most values in the cell properties record are for use with editable
tables, the cell_width field can also be used with a non-editable table.
3. The column clicked has been added as the fifth argument to the EV_SELECT
event for an editable table.
4. sys.HTMLHeader has been added. This specifies whether or not nph-srep
should output standard, cgi header information. In general, this should
be ON if nph-srep is running as a CGI program on a web server or OFF
it's output is being redirected to a file for later use as an HTML page.
The default is ON.
5. The utility program kcopydir is now supplied. Full documentation is in
the HTML manual SCULPTOR\HELP\sc5ref.chm.
6. On Windows NT, 2000 and XP, Sculptor now supports read locks and write
locks, which has always been the case on Unix platforms. Windows 95, 98
and ME do not support read locks so all locks obtained locally on these
platforms are write locks. However, a Sculptor client program that is
running client/server on Windows 95, 98 or ME and accessing files via
kfserver on Windows NT, 2000, XP or Unix has the benefit of both read
locks and write locks. This is not the case if the program uses standard,
Windows networking to access the files.
7. The value CURSOR_DEFAULT is now a valid argument to setcursor(). It
selects the user's default cursor icon.
8. There is a new function;
isblank(field_id | record_id)
isblank(field_id[index] | record_id[index])
If there is no index, checks all elements of the specified field or all
elements for all fields in the specified record. Returns TRUE if all
values are null. For numeric fields, zero is the null value. For alpha
fields, all spaces is the null value and for binary fields, all bytes
binary zero is the null value.
If an index is specified, checks that element only. In the case of a
record, checks only those fields whose dimension >= index. (The
behaviour is undefined for fields that have more than one dimension.)
9. The command getfield # can be used to read fields from a sequential file:
getfield #channel, field_id[,field_id]... [err=label] [traps=label]
Unlike get #, which reads a line at a time and then parses it into the
supplied fields, getfield #, reads only the number of fields specified,
so it can be used to read one field at a time if required.
A field is text delimited by any character in sys.Separator. The default
setting for sys.Separator is "," and this value should be used when
reading standard csv (comma separated value) files. However, it is possible
to set sys.Separator another character or to a list of separator characters
if required.
Each time getfield # is executed, the character that terminated the last
field is stored in sys.LastSeparator (a1). The special values CHAR_EOL
(end of line) and CHAR_EOF (end of file) are defined in sculptor.h. The
value of CHAR_EOF is 255. In the extremely unlikely event that this is
also a valid separator, check the value in sys.Error, which will be 0 for
the character 255 and non-zero for end of file.
getfield # honours the following csv conventions:
1) Quoted text is read as a single field. Text is deemed to be quoted
if the first non-blank character is a quotation mark.
2) Within quoted text, two consecutive quotation marks are treated as
a single, embedded quotation mark.
3) Leading spaces before each field are ignored (unless in quotes).
For example, the line
123,"embedded,comma", just text, "embedded""quote",not"quoted
parses into the separate field values
123
embedded,comma
just text
embedded"quote
not"quoted
10. The command putfield # can be used to write values to a sequential file.
putfield #channel, expr[:format][,expr[:format]]... [err=label] [traps=label]
The comma after expr outputs the text in sys.Separator. If there is no
comma after the last field, a newline is output. When writing standard csv
files, set sys.Separator to "," or, for more readable output, to ", ".
The optional format string can be used to format numeric values or to
modify the output of alphanumeric text. If expr is a simple field, the
field's own format string is used if there is no attached format. Leading
and trailing spaces are removed from all values except alphanumeric text
that has the letter "k" (keep spaces) in its format.
putfield # honours the following csv conventions:
1) Values that have the first character in sys.Separator or a quotation
mark embedded in their text are automatically enclosed in quotation
marks.
2) Inside a quoted value, an embedded quotation mark is output twice.
11. In programs compiled with scc 5.3.0 or later, tables with mode EM_MULTIPLE
send a different event when Shift+Click is used to select a block of lines:
EventFunction(EventCode, Table, FirstLine, State, LastLine)
If EventCode is EV_MULTIPLE_SELECT, FirstLine and LastLine are the first
and last lines in the selected block. Previously, the event EV_SELECT was
sent separately for each selected line. There were two problems with this
approach:
1) Sculptor's internal event stack overflowed, so the event was only
sent for the first 255 lines.
2) Sending this many events degraded performance and any fix would make
this worse if a very large number of lines was selected.
Sculptor recommend that programs using tables with EM_MULTIPLE are
modified to make use of EV_MULTIPLE_SELECT before recompiling with the
latest version of scc. If this is not practical, add the line
!compat evselect=4
to the program or to a common include file such as local.h if all
programs are to retain backward compatibility.
EV_MULTIPLE_SELECT is enabled by default.
EV_SELECT (=EV_SINGLE_CLICK) is still sent when a single line is selected.
12. If an alpha array field has the flag character "p" (packed text) set, it
becomes a long text field that can store dim * length characters where dim
is the array size and length is the element length. For example, the field
!temp LongText,,a200(40),,p
can store up to 8000 characters as a single text string. Database fields
can be made into long text fields by placing "p" in their format string.
The compiler recognises this format and sets the field's "p" flag. The
maximum length of a long text field is 60000 characters.
Sculptor treats a long text field as a non-array field. The individual
elements should not be referenced directly. Sculptor does not allow the
"p" flag to be set or cleared at run-time. The statement
field_id->flags = "..." can be used to set other flags but the state of
the "p" flag will be preserved. Functions such as getstr(), getbyte(),
setstr(), setbyte() and instr() all work with long text fields and these
should be used to extract and modify parts of the text.
Long text fields are null terminated unless the full length is used. When
a value is stored in a long text field, Sculptor sets all unused bytes to
null, so If setbyte() or setstr() is used to store new text at the end of
the current text, this must start at the first null character.
In general, Sculptor's built-in functions and operators all work on the
full length of long text fields. Long text can also be used with ODBC and
assigned to and from OLE fields and the clipboard. Long text is truncated
to a maximum of 255 characters when retrieved for any of the following
purposes:
1) For the name of any object.
2) For filenames and pathnames.
3) For headings, titles, labels, etc.
4) For text passed across the DDE interface.
5) In the chain and exec commands.
6) In commands like caption, error, info and prompt.
7) TAPI strings.
8) Web strings such as cookie values.
9) XML attributes.
Some of the above restrictions may be removed in the future.
Long text fields are supported from Sculptor 5.3. Programs must be compiled
and run with this or a later version to work correctly. If a program defines
a !temp as long text, the compiler flags it as suitable for running only
with Sculptor 5.3 or later. This is not done for database fields because it
is not practical for the compiler to determine whether or not a field is
referenced in the program. For safety, programs that make use of long text
fields should declare at least one !temp field with the "p" flag even if it
is not used.
13. Long text fields are ideal for use as the linked field in a free format
textbox. The text is stored as a packed string, so it is not possible to
type more characters into the textbox than can be stored in the field. Hard
line fields (newlines typed by the user) are stored in the standard DOS
format as a carriage return, line feed pair (0x0d, 0x0a). Soft line feeds
(generated by automatic word wrap) are not stored. If the same text is
displayed in a free format textbox with a different width, the word wrap
changes to match the new width but user-typed line feeds are preserved.
Long text that has been stored in a database field from a free format
textbox should not be used in programs running with earlier versions
of Sculptor. The text will not display correctly and can be corrupted if
saved.
14. By default, the open file dialog in spw now lists both .f and .r files.
15. There are new functions for use with tables whose source_object is a file.
These are based on keys instead of line numbers and avoid the anomalies in
the line-based functions which occur only when the source object is a file.
They also make it possible to use editmode EM_MULTIPLE with file driven
tables. See the index entry "tables, functions" in the HTML manual
SCULPTOR\HELP\sc5ref.chm.
16. Pre and post increment and decrement operators have been added to the
language:
field_id++ Adds 1 to a numeric field after using its value.
field_id-- Subtracts 1 from a numeric field after using its value.
++field_id Adds 1 to a numeric field before using its value.
--field_id Subtracts 1 from a numeric field before using its value.
The above statements can be used alone or in an expression. The ++ and --
operators have the same priority as unary minus (group 1). Example:
field1 = field2++ + --field3
is equivalent to the following statements
field3 = field3 - 1
field1 = field2 + field3
field2 = field2 + 1
17. It is now possible to print directly to a file for a named printer:
run report report_id to "PRINTER:printername:filename" [ppf=...]
This outputs the report to the specified file without user dialog -
equivalent to using Print Manager and checking the "Print to file" checkbox.
The file is only suitable for the named printer and can be printed later
with the DOS "type" command:
type /b filename PRN
This feature is also useful for creating PDF format files, since it is
possible to obtain print drivers that output in PDF format. When printing
in PDF format, use ppf="winpm" or an equivalent Windows printer parameter
file. Example:
run report rep_pdf \
to "PRINTER:BroadGun pdfMachine:c:/myapp/pdf" ppf="winpm"
Note that / is recommended in quoted pathnames. This works on DOS/Windows
and avoids the need to use \\.
Not all PDF drivers support printing to a file programmatically. Some only
work correctly through a dialog. Sculptor has briefly checked the following
PDF drivers but the tests were not exhaustive, so always test a driver with
your application before committing to it.
BroadGun pdfMachine (www.broadgun.com)
--------------------------------------
Prints directly to a specified output file, otherwise requests a filename.
Reasonably priced for commercial use, especially for multiple licences.
Free trial version available. This places a watermark on the page but
is otherwise the same as the full version. The best driver found so far
for use with Sculptor. Feedback would be useful.
DocuCom PDF Driver (www.pdfwizard.com/zeoncom/)
-----------------------------------------------
Always produces a user dialog with the report_id name as the default
filename (run report report_id ...). If an output filename is specified,
this is created empty but the report is not written to it. Standard text
is feinter than with other drivers.
Standard and server versions available with trial versions of each.
Trial versions produce an order/registration dialog every time they are
used.
pdf995 (www.pdf995.com)
-----------------------
Does not work if an output filename is specified. Free version available
but this starts an HTML advert page every time it is used.
Information on other drivers would be very welcome.
18. The hide and show commands now work with menus and menu items.
19. The style= clause has been added to top-level menus and the style
WS_POPUP can be set to make a menu a pop-up menu. Use the "at" command
to specify where the menu is to pop up, followed by the "open" command
to make the menu appear. A program will normally do this in response to
an EV_RIGHT_MOUSE event. Note that EV_RIGHT_MOUSE is not a default event
and must be enabled. If the user the selects an item from the menu, the
menu closes and the item's select function is called. If the user clicks
outside the menu, it closes without calling any select function. The
following code fragments show how to use this feature:
+window MyWin ... {
...
event_enable = EV_DEFAULT | EV_RIGHT_MOUSE
...
menu PopUp {
style = WS_POPUP
...
}
}
!function MyWinEvent(EventCode, Object, X, Y) {
switch EventCode {
...
case == EV_RIGHT_MOUSE:
at X,Y in MyWin
open MyWin.PopUp
return
}
}
20. A function has been added that returns the width and height of a text
string in a given window or the selected printer in the current report.
TextSize(window_id, text, font, width, height)
Calculates the width and height, in the units expressed by sys.Unit, for
the supplied text in the given font. The window_id is the identifier of
the window in which the text would be placed. For the current report,
specify NULL instead of a window_id.
The font parameter has the same syntax as a window font clause. If a
valid font specification is not provided, the default specified in
Section 1.4 (Default font) of the terminal parameter file is used.
The standard terminal parameter file for all versions of Windows is
$SCULPTOR/term/mswin.s. If no default font is defined, then
"Courier New@10" is used.
The width and height parameters can be NULL or can be fields. If they
are fields, the function sets them to the actual width and height (in
the logical units specified by sys.Unit) of the rectangle containing
the text.
21. It is now possible for the width of a cell in an editable table to be less
than the width of the linked field. The text scrolls horizontally.
22. Timer events have been introduced. These are controlled using the following
new functions, defined in sculptor.h:
CreateTimer(event_function, millisecond_interval[, option_flags])
Creates a new timer. Multiple timers can be created and can run
concurrently.
event_function
The name of an event function to be called every time the
specified interval elapses.
millisecond_interval
The event interval in milliseconds.
option_flags
The only flag implemented at the moment is TIMER_START. If this
argument is omitted or is 0, the timer is created but does not
start running until the StartTimer() function is called.
DestroyTimer(event_function)
Stops the timer if it is running and then destroys it, releasing
the system resources that have been allocated to it.
StartTimer(event_function[, millisecond_interval])
Starts the timer. If the millisecond_interval is not specified, the
interval specified in the CreateTimer() function is used.
StopTimer(event_function)
Stops the timer. The timer can be restarted later.
The above functions return 0 if successful or a negative value if they fail.
Note that a timer is identified by its event_function. If multiple timers
are created, each must have a different event function.
The timer event function is called each time the specified interval elapses.
Timer events are subject to CPU time being available to the process. Events
can be delayed or missed if the system is busy. A timer event function can
return CLOSE_DIALOG or CANCEL_DIALOG if required.
On Unix, the millisecond_interval is rounded up to the next second because
most Unix system clocks run with granularity of 1 second.
On Windows, the millisecond_interval is used.
Timers do not work in the DOS version of Sculptor.
23. The reference manual is now supplied in compiled HTML format in the file
SCULPTOR\HELP\sc5ref.chm. This HTML manual is up to date. The old manual,
sc5ref.hlp, is also supplied because it contains sections called by descw
and spw. The old manual is not being updated and should not be referenced
directly.
SCULPTOR 5.2
This was an experimental version and will not be released.
The next version will be 5.3.
SCULPTOR 5.1.1
1. The program template default\sp.f used by spw has been improved and spw
has been changed so that at startup, either an existing program must be
loaded or File->New selected.
SCULPTOR 5.1.0
1. A new flag character "c" can be used with fields to indicate that the
text is to be centred within its print column when using the print and
printh commands. This flag can be defined with the field or appended
to a print item:
print fieldname::"c"
2. There is a new function defined in that returns the default
width and height for an image drawn in a given window:
ImageSize(window_id, imagefile, x, y)
Stores the default size into the fields x and y. The unit is defined by
sys.Unit (default is pixels). If window_id is 0, values are returned
for the selected printer.
3. A new event, EV_SELECT_TAB, has been introduced. This is sent to the tab
control window's event function when a new tab is selected.
EventFunc(EV_SELECT_TAB, control_window, selected_tab, selected_tab->xposn)
4. On Windows, text that is printed below the bottom of the current page
is lost. This can happen if the "need" command is not called at the
correct time. To check for this happening, set entry number 3 in the
INFO section of the printer parameter file to "Y" and use the comprint
program to recompile the printer parameter file:
3: Print overflow text on next page (Y/N) = Y
The default is N because many existing programs print an extra blank
line at the bottom of the page. Setting this entry to "Y" will then
generate a blank page.
5. The controls in a window have a new property called "tab_order".
This is an ordinal number that defines the control's position in the tab
sequence of it's parent window. It is possible to store a new value for
a control's tab_order. This moves the control to that position in the
tab order and renumbers the tab_order for other controls in the window.
6. The Tab, BackTab, Control+DownArrow, Control+UpArrow, Control+NextPage
and Control+PrevPage keys move between the editable cells in an editable
table. The Control+Tab and Control+BackTab keys move to other controls.
7. The move command can place the cursor at a given pixel position in a
window:
move cursor to x,y in window_id
The "at" command always works in character positions.
8. The begin, commit and rollback commands that wrote markers to the
transaction log file but had no effect on the files being used by
the program, have been replaced by the functions begin(), commit()
and rollback().
For upward compatibility, The old commands have been renamed begin_mark,
commit_mark and rollback_mark but these should be regarded as obsolescent.
Programs compiled with scc 5.0 and earlier map begin, commit and rollback
to begin_mark, commit_mark and rollback_mark so that they work as before.
In order to recompile programs with scc 5.1, append "_mark" to these
commands, in which case they will work as before or append "()" to get
the new functionality, which is the recommended option.
begin() starts a transaction. All records that are inserted, deleted or
updated remain locked until either commit() or rollback() is called. If
a program attempts to read a record that it has deleted in a transaction,
it gets a "no such record status" as expected and can re-insert the
record. Other programs see the record as still existing but locked; this
prevents them from inserting the record until the transaction has been
committed.
If commit() is called, all records locked by the transaction are
unlocked and the updates become permanent. If rollback() is called, the
updates are reversed and the records are unlocked.
Both commit() and rollback() return 0 if successful or -1 if they fail.
With Sculptor files, commit and rollback should always work. With some
SQL databases, especially if optimistic locking is used, the commit()
function can return an error. This indicates that the transaction could
not be committed because it's updates conflict with another transaction.
It's not obvious why rollback() might fail with SQL databases but the
option for this operation to return an error does exist in ODBC.
Transactions should be reasonably short and quick so that multiple records
are not kept locked for a long time. There is also a greater scope for
deadlocks to occur when multiple records are kept locked, so transactions
must be designed to avoid this.
Note: Large transactions (greater than a few thousand updates) are very
slow with Sculptor Keyed Files at the moment. This will be fixed in a
future release.
9. If a program accesses a closed file, Sculptor opens the file automatically
using the mode in the !file declaration or update mode if a mode is not
specified. This behaviour was introduced in Sculptor 3. To get a warning
when this happens, set sys.Warn >= 4 (default value is 2).
10. The up, down, left and right arrow keys can be used to move a selected
object one pixel at a time in the screen designer.
11. The DrawImage() function now accepts a jpg file as well as bmp file.
12. Sculptor 5.1 supports XML. See the file xml.rtf for details.
13. There is a new Sculptor Program Generator that replaces sg and rg. This
is written in Sculptor. The source code is supplied in DEMO\SPG, so that
it can be modified if required. To call the generator, run the batch
file "spg" in SCULPTOR\BIN.
14. The scroll command scrolls the top line of a listbox or table to a given
row:
scroll table_id | listbox_id to row_number
This command is in Sculptor 4.2 but was previously undocumented.
15. Security features have been added to kfserver and kfservnt. These are
documented in the file security.txt. The new versions of kfserver and
kfservnt will not work until you copy the supplied SCULPTOR/security
directory to your server. For backward compatibility, this security
database is supplied with a single, default entry that permits all
operations. To implement secure server operations, delete this entry
and add specific entries as required.
16. The installation procedure now registers .g and .q files so that
Windows knows how to run them. Since this includes Internet Explorer,
an href on a web page on a Windows server that has Sculptor installed
can point to a Sculptor file. Example: href="http://server/file.q".
17. The load_picture() function can load an image from a server and AVI files
can be run from a server. In both cases, Sculptor first copies the file
to the $SCULPTOR/temp directory on the client. The next time the file is
accesssed, it is copied only if it's timestamp indicates that it has been
updated on the server.
18. A set of functions has been introduced to read Sculptor .d files.
See "Data dictionaries, retrieving information about" in the HTML manual
SCULPTOR\HELP\sc5ref.chm.
19. An automatic currency conversion feature has been introduced.
See "currency conversion" in the HTML manual SCULPTOR\HELP\sc5ref.chm.
20. It is now possible to trap OLE errors. First register a trap function with
the statement:
on ole_error funcname
If an OLE error occurs, the function is called with the following arguments:
funcname(obj_id, hResult, Source, Description, HelpContext, HelpFile)
obj_id The OLE object that caused the error.
hResult The error number.
Source The function or property that caused the error (text).
Description Error description if available, otherwise blank (text).
HelpContext Context id on help file if available. Can be used
with the help file to show an explanation of the error.
HelpFile Pathname to the help file.
If an OLE error function has not been registered, a normal debug message
is displayed if an OLE error occurs.
21. When the EV_KEYSTROKE event is called for an editable table, the program
has been compiled with scc version 5.1.0 RC2 or later and the interpreter
is version 5.1.0 RC2 or later, the function arguments are:
EventFunc(EventCode, Object, Row, Col, Keycode)
This change has been made to make the editable table event function
consistent. If Sculptor 5.1.0 RC2 or later is used to run a program
compiled with an earlier version of Sculptor, the arguments are:
EventFunc(EventCode, Object, Keycode, Row)
22. The path for an avi file can be on a server. Sculptor copies the file to
the directory $SCULPTOR/TEMP and runs it from there. On subsequent use,
the file is copied again only if it has been updated on the server.
23. The WS_PLAIN style can be used with image buttons. It creates the button
with no border or shadow. Image buttons are a useful alternative to
graphic images because they receive events such as gain and lose focus,
which are not available with graphic images.
24. The colours and font of window captions can be set using the new window
properties caption_bgc, caption_fgc and caption_font. The font used is
the default font modified by any style, size or family set using the
caption_font clause. Colour is decided as follows:
1. If the current control has a caption_pen, that is used.
2. Otherwise, caption_bgc and caption_fgc are used if the colours are
active (RGB_ACTIVATE set).
3. Otherwise, if the window has a palette, that is used with PEN_CAPTION.
4. Otherwise, the system default colours for captions are used.
25. AVI files can have a transparent background. The avi control interprets
the upper-left pixel of the first frame as the background colour. If an
active, transparanet colour is defined for the parent window, the control
remaps the avi background colour to the window background colour. The
actual colour defined to be transparent is not relevant but it must be
active (RGB_ACTIVATE set).
26. The EV_CHANGE event has been added to list edit controls. This is sent
after each character typed into a list edit control. This event is not
sent by default. To receive it, add EV_CHANGE to the event_enable clause
of the control. For example:
event_enable = EV_DEFAULT | EV_CHANGE
To retrieve the value typed into a list edit control, either call the
listbox_get_selected() function in the EV_LOSE_FOCUS event or in each
EV_CHANGE event, as preferred.
27. clear record_id[subcript] clears the specified element of array fields
in record_id. Non-array fields are not cleared. Record are not unlocked.
CARE: This code works from Sculptor 5.1 release version only. If the
program is run with an earlier version of Sculptor, the entire record
will be cleared.
28. The debug versions have a dialog to locate source files if they are
not present in the directory in which they were compiled.
29. Foreground and background colours can be defined on a "put" command
using the clauses bgc= and fgc=.
30. The table_focus_cell() function returns more useful values (defined
in sculptor.h):
< 0
Error (parameter out of range).
CELL_NOT_FOCUSED (0)
Focus was refused (e.g. the gain focus event returned ERROR).
CELL_FOCUSED_IN_VIEW (1)
The cell was focused and was in view.
CELL_FOCUSED_INTO_VIEW (2)
The cell was focused by scrolling it into view.
31. The style WS_CLICKONLY can be used with any control. It allows the
control to gain focus when it is clicked but to be skipped when the
user is navigating with the TAB and BACKTAB keys.
--------------------------------------------------------------------
SCULPTOR 5.0.1 - 10 April 2001
--------------------------------------------------------------------
1. Some speed improvements have been made to the ODBC interface to SQL
databases, especially SQLServer.
SCULPTOR 5.0.0 - 2 February 2001
Starting with Sculptor 5.0, a number replaces the date that was
used in previous versions to identify bug fixes. The initial release
is 5.0.0. Bug fix releases will be numbered 5.0.1, etc. and will be
documented in the file bugfixes.txt.
Sculptor 5.0 introduces Sculptor HTML files. See the file internet.doc
for details.
The variable SC_PROG that was used in Beta 1 has been renamed SCPROG.
Please edit any Internet pages that you have created.
-----------------------
1. There are new clauses that provide full foreground and background
colour selection for windows and controls. It is also possible to
specify a transparent colour for graphics images, which allows the
window background colour to show through the specified transparent
colour.
The clause are bgc= (background colour), fgc= (foreground colour),
data_bgc=, data_fgc=, label_bgc=, label_fgc=, title_fgc= and
transparent=. The bgc= clause defines a window's background colour.
A sample set of RGB color values is defined in rgb.h. The most significant
byte of each value contains option flags and an RGB value must have the
flag RGB_ACTIVATE set to switch the colour on. The next three bytes are
the intensity values for blue, green, red (the order required by Microsoft
functions), not for red, green, blue might be expected.
The best way to select colours and to see which clauses are supported
by which controls is to use the screen painter. Typing a ? in a colour
property opens a colour selection dialog. If a standard colour is
selected, spw writes the corresponding RGB definition from rgb.h into
the clause in the code. If a non-standard colour is selected, spw
writes a hex value.
Clauses specified at window and group level are inherited by child
windows and controls. The special value RGB_DEFAULT can be used in
a child window or control to select the user's default preference
instead of the inherited colour.
2. The function SetBrushColor() now takes either two or three arguments:
SetBrushColor(Window, Foreground | Background)
works as before and is limited to the FORE_ and BACK_ colours defined
in SCULPTOR/include/draw.h.
SetBrushColor(Window, Foreground_RGB, Background_RGB)
sets the brush's foreground and background colours to the specified RGB
values.
3. The functions SetOutlineColor(), SetOutlineWidth() and SetOutlineType()
work as before but are obsolescent. They have been replaced by
SetPenColor(), SetPenWidth() and SetPenType(). The function SetPenColor()
takes an RGB value:
SetPenColor(Window, RGB)
The functions SetPenWidth() and SetPenType() are equivalent to the old
functions SetOutlineWidth() and SetOutlineType() but have new names for
consistency.
4. Text, line graphics and graphic images can now be drawn in a window or
printout using drawing modes that merge the output with the existing
background in a variety of different ways.
The required mode is defined in a system variable. There are two new
variables, one for text and line graphics and one for graphic images:
sys.DrawTextMode
When using a Sculptor drawing function to draw text or a line graphic,
this variable defines how to combine the text or line graphic with the
existing background. There are two possible values, defined in draw.h:
TRANSPARENT The line graphic or text is drawn on top of the existing
background, ignoring the background color and style defined
in the current brush. For example, if a retangle is drawn,
the inside retains the existing background.
OPAQUE Uses the background color and style defined in the current
brush. For example, if a retangle is drawn, the inside is
filled according to the current brush. This is the default
value.
sys.DrawGraphicMode
When using a Sculptor function to draw a graphic image, this variable
defines how the graphic bitmap is combined with the existing background.
Possible values, defined in draw.h, are:
Value Description
-----------------------------------------------------------------------
BLACKNESS Sets the existing background black.
DSINVERT Inverts the existing background.
MERGECOPY Combines the current pattern brush with the graphic
using a boolean AND operation and copies the result over
the existing background.
MERGEPAINT Inverts the graphic then combines it with the existing
background using a boolean OR operation.
NOTSRCCOPY Inverts the graphic then copies it over the existing
background.
NOTSRCERASE Combines the graphic with the existing background using
a boolean OR operator and then inverts the result.
PATCOPY Copies the current pattern brush over the existing
background.
PATINVERT Combines the current pattern brush with the existing
background using a boolean XOR operation.
PATPAINT Inverts the graphic and combines it with the current
pattern brush using a boolean OR operation, then combines
the result with the existing background using a boolean
OR operation.
SRCAND Combines the graphic with the existing background using
a boolean AND operation.
SRCCOPY Copies the graphic over the existing background. This is
the default value.
SRCERASE Inverts the existing background then combines the graphic
with the result using a boolean AND operation.
SRCINVERT Combines the graphic with the existing background using
a boolean XOR operation.
SRCPAINT Combines the graphic with the existing background using
a boolean OR operation.
WHITENESS Sets the existing background white.
5. The function activate_app() has an optional, third argument:
activate_app(class, title, option)
Option must be one of:
AA_HIDE Hide the window and activate another
AA_SHOWNORMAL Activate and show in normal size and position
AA_SHOWMINIMIZED Activate and show minimized
AA_SHOWMAXIMIZED Activate and show maximized
AA_SHOWNOACTIVATE Show in normal size and position, don't activate
AA_SHOW Activate and show in current size and position
AA_MINIMIZE Minimize the window and activate another
AA_SHOWMINNOACTIVE Show minimized, don't activate
AA_SHOWNA Show in current size and position, don't activate
AA_RESTORE Activate and show in previous size and position
AA_SHOWDEFAULT Show in default state set by parent task
If the option argument is omitted, AA_RESTORE is used. If the option
used is one that activates the window, the window is also brought to
the foreground if possible but note that Windows 98 and 2000 allow
this only if one of the following is true:
The process is the foreground process.
The process was started by the foreground process.
The process received the last input event.
There is no foreground process.
The foreground process is being debugged.
The foreground is not locked.
6. The environment variable SCMASTERBIN can be set on a client to specify
the directory from which to download a program if the following syntax
is used:
sagewc|srepwc :program
If SCMASTERBIN is not set and SCMASTER is set then programs are
downloaded from the directory $SCMASTER/app.
If SCMASTERBIN is set, SCMASTER can still be set to specify the master
Sculptor directory for terminal and printer parameter files that are
referenced with a leading :.
7. The environment variable SCLOCALBIN can be set on a client to specify
the directory in which to store a downloaded program. If SCLOCALBIN is
not set, the directory $SCULPTOR/app is used.
8. New Internet functionality is included using the interpreter nph-srep.
An outline specification of the new Internet routines is in the file
internet.doc in this directory. Note: If a printer parameter file is not
specified for nph-srep, either on the command line or in a "run report"
command, the default is "nullp" not "printer".
See SCULPTOR/DEMO/INTERNET/SHOP and SCULPTOR/DEMO/INTERNET/SCH for
demonstration applications.
9. The new window properties
window_id->hscroll_posn
window_id->vscroll_posn
contain the current position, in pixels, of the horizontal and vertical
scroll bars in a window that has scroll bars. Changing a value, moves
the corresponding scroll bar. One use is to save and restore the positions
of the scroll bars when a window needs to be destroyed and re-created.
10. Optionally, one or more columns in a table can be edited.
By default, the columns in a table are type TCT_READONLY, which means
that the cells in that column cannot be edited. The type of a column can
be changed by calling the function table_set_type() after the table has
been created:
table_set_type(table_id, column, type [, drop_size, list_field])
This sets the type of the specified column (counting from 1) to one
of the following:
TCT_TEXTBOX Edit using a textbox.
TCT_DYNAMIC The type will be set when the cell receives focus.
TCT_LISTEDIT Edit using a LISTEDIT type listbox.
TCT_LISTBUTTON Edit using a LISTBUTTON type listbox.
TCT_READONLY Set read only.
The drop_size and list parameters are required for types TCT_LISTBUTTON
and TCT_LISTEDIT. The drop_size specifies the number of visible rows in
the listbox (default 5). The list_field must be an array field that
contains the list of permitted values.
table_set_type() returns < 0 if an error occurs (invalid argument).
Three new events have been introduced in the table event function:
TableEventFunc(EV_FOCUS_CELL, table_id, row, col, type)
The EV_FOCUS_CELL event is sent when the user clicks on a cell that
can be edited. The row and col arguments are the co-ordinates of the
cell, counting from 1. The type argument is the current type of the
column (TCT_).
This function is not called if the type is TCT_READONLY.
If the type is TCT_DYNAMIC, the program must call the function
table_set_type() to set another type before returning.
The function must return OKAY to give focus to the cell or ERROR to
refuse it.
TableEventFunc(EV_NOFOCUS_CELL, table_id, row, col)
Called when a cell loses focus. Can be used to reset the type to
TCT_DYNAMIC if required. The return value should be OKAY, which
is the default.
TableEventFunc(EV_VALIDATE, table_id, row, col, data)
Called before the EV_NOFOCUS_CELL event. The data argument contains
the value in the cell, which may have changed. The function should
return OKAY if the content is valid, otherwise ERROR, in which case
focus is locked and the user must enter another value.
There are two other new functions that can be used with tables:
table_focus_cell(table_id, row, col)
Sends the focus to the specfied cell, which should be visible on
the screen. Returns < 0 if an error occurs.
table_set_default_data(table_id, col, data)
Sets a default value that replaces the current value whenever a cell
in the specified column is edited. If desired, can be called during
an EV_FOCUS_CELL event to reset the default value to one that is
appropriate for the cell receiving focus.
See the sample program DEMO\CONTROLS\etable.f
11. There is a new function that deletes a directory:
rmdir(pathname)
The directory must be empty.
The pathname can reference kfserver.
Returns 0 if successful.
Returns non-zero if an error occurs (see sys.Errno).
12. Sculptor 5 introduces pixel positions and sizes for all windows and
controls. It also supports character positioning and sizing for
backward compatibility.
There is an automatic conversion procedure that can be used to convert
programs to pixel positioning. There is no automatic conversion back
from pixels to characters, so it is very important to back up all source
files before starting the conversion process.
To convert a suite of programs to pixel positioning, first edit every
include file in the suite and append the line !ctp (convert to pixels).
It is not nececessary to add this line to include files that don't contain
windows but it does harm to do so. Do not add the line !ctp to top level
program files (.f and .r). Make sure that all include files that contain
!ctp can be upodated, i.e. they are not read only. Note that include files
in <> brackets are always treated as read-only by spw. The compiler does
not recognise the line !ctp, so once this has been added to include files,
they must be converted.
To convert a program from characters to pixels, load it into spw and check
Options->Positioning->Pixel in the menu. All windows and controls in the
program file and in the include files that contain !ctp are converted. The
!ctp lines are removed to prevent the include files from being converted
again when processed in the conversion of another program.
spw convertes all positions and sizes in window and control declarations.
It cannot convert values that are coded into the program logic so these
must be converted manually. To make this process easier, the "at" command
still works in characters and there is a new command
cursor to x,y in window_id
that is equivalent to "at" except that it works in pixels.
The "move" command now works in pixels but there is a new command
"charmove" that has the same syntax and still works in characters.
You can either modify the co-ordinates of existing move commands or
change the command to charmove.
Programs that use pixel co-ordinates and sizes must be compiled using scc
version 5.0 Beta 4 or later. All earlier compilers assume a character grid.
By default, the Sculptor 5 compiler assumes a pixel grid. To select a
character grid, place the following declaration in a program:
!chargrid ON
In order to make existing programs compile correctly, this declaration has
been added to the standard include file . This overrides the new
default. There are two ways to take advantage of pixel positioning:
1. Remove the "!chargrid ON" declaration from and convert all
or most programs to pixels. Add "!chargrid ON" to any programs that
you don't want to convert.
2. Leave "!chargrid ON" in and add "!chargrid OFF" to the
programs that you convert, after !include - spw does
this automatically. This works because spw and scc honour the last
!chargrid declaration that they encounter.
13. There is a new function to starts the default web browser and passes
it a url:
url_exec(url_text)
Returns 0 if successful, otherwise the system error code.
Example: url_exec("http://www.sculptor.com")
14. There is a new function that runs a Windows file using its default,
application binding. The function can also be used to run an installed
Windows executable program without the need to know its location.
run(file_name)
or run(file_name, verb, params, dir, show)
The first syntax runs the file with all defaults. The second syntax
provides the following options:
verb The action to be taken (open, edit, print, etc.). For
parameter values refer to the application's documentation.
Pass 0 for the default.
params Some applications accept parameters. See the application
documentation for details. Pass 0 for the default.
dir The directory in which the command is to start. Pass 0
for the application default.
show One of the AA_ defines in sculptor.h. Determines the mode
in which the application starts. Default is AA_SHOWNORMAL.
Examples:
run("myletter.doc") opens myletter.doc using the application that is
associated with .doc files.
run("winword.exe") starts M/S Word with a blank document.
15. In the debug versions sagewcd, srepwcd, etc. it is possible to change
the value of a field at run-time. Press the Add button in the Watch Field
window. This opens the Select Field window. Select a field and type the
required value in the textbox.
16. In spw, the menu item Edit->Layout in spw can be used to move, align and
change the size of multiple controls. This is an essential tool when pixel
positiong is used. Full details are in the Sculptor Reference Manual.
17. There is a lasso option in the screen designer menu that allows multiple
controls to be selected using a dragged rectangle.
18. The screen designer now allows the colour and pattern of the selection
border to be changed and saved by saving the current configuration.
19. A set of functions has been introduced to support TAPI (telephony API).
20. If the "open #" command is used to open a serial port (COM1 to COM9),
all I/O on that port is now unbuffered. This makes it possible to use
a serial port to send messages between two computers. To set the baud
rate and handshaking parameters, execute the DOS "mode" command before
opening the port. Parameters must be identical on both the sending and
receiving computers. To see the full syntax of the mode command, type
"mode /?" at a DOS prompt.
A program must make its own arrangements to detect end of message. See
the sample programs in \SCULPTOR\DEMO\COMPORTS, which demonstrate one
way to achieve this.
21. Drag and Drop is supported. There are demo programs in the directory
\SCULPTOR\DEMO\DRAGDROP. Full documentation will follow shortly.
22. The style WS_HLIGHT_DARKEN can be used with tables to make the
selected row darken instead of changing to white on blue. This can
look better when using colours in table fields.
23. The following new system temp has been added:
sys.ScFixVersion (type u1) contains the Sculptor 'fix' version number.
The version number syntax is now main_vers.sub_vers.fix_vers.
Starting with Sculptor 5.0, sys.ScDateVersion will always return the
initial release date.
SCULPTOR 4.3 - 11 June 2001
1. The setting of the batch_read flag is now ignored for ODBC databases.
The performance improvements that it provided are now standard.
SCULPTOR 4.3 - 28 March 2001
1. Some speed improvements have been made to the ODBC interface to SQL
databases, especially SQLServer.
SCULPTOR 4.3 - 16 February 2000
1. In order to get adequate performance, the batch_read flag is now ON by
default for ODBC databases. This requires MDAC version 2.6 or later or
SQLServer Service Pack 3. (MDAC = Microsoft Data Access Components).
2. Some ODBC database types do not automatically refresh a read only cursor
when the database is updated. This means that an update (delete, insert
or write) may not be seen by a subsequent readu, nextu, prevu, findu or
matchu command, even in the same program. So far, this behaviour has been
seen only with Oracle. To avoid it, put each set of updates between begin
and commit or use the flush command on the affected file:
flush file_id
SCULPTOR 4.3 - 12 October 2000
1. There is an option to force optimistic locking with an ODBC database. This
is done by setting the DBFL_OPTIMISTIC_LOCKING flag in the database
definition:
+database db1 {
type = DBT_ODBC
flag = DBFL_OPTIMISTIC_LOCKING
...
}
Optimistic locking is the default for the Microsoft Access driver and
the native, Oracle driver. Pessimistic locking is the default for the
Microsoft SQLServer driver and the Microsoft driver for Oracle. In these
cases, the DBFL_OPTIMISTIC_LOCKING flag can be set to force optimistic
locking. Updates are generally faster when optimistic locking is used.
With optimistic locking, records that are read for update are not locked.
Instead, when the record is written back, the driver checks to see if
another user has updated the record since it was last read. If so, the
write is refused and Sculptor returns a UE (update error) trap. This trap
can occur on delete and write commands.
2. If file_id->batch_reads = ON for an ODBC file, a forward only cursor is
used for the nextu, nextkey, prevu, prevkey and findu/matchu commands.
This type of cursor is usually very fast. Despite its name, a forward
only cursor can be used with the prevu and prevkey commands.
NOTE: Sculptor does not use this type of cursor with Microsoft Access
because in some Access drivers it seems to work very slowly.
SCULPTOR 4.3 - 12 September 2000
1. Sculptor 4.3 is identical to Sculptor 4.2 except that the ODBC interface
has been improved substantially. Overall performance is better and some
multi-user conflicts have been resolved. Applications that use ODBC with
Sculptor 4.2 or earlier should be re-tested with Sculptor 4.3.
Careful coding can improve performance in a program that uses ODBC. The
following example shows how a program that uses the next command to step
through a file to update some but not all records can be coded to improve
performance:
while (TRUE) {
nextu FILE nsr=BREAK /* Don't lock unless updating */
if (update needed) {
read FILE nsr=CONTINUE
...
write FILE
}
Unless all the records will be updated, the above code is faster than:
while (TRUE) {
next FILE nsr=BREAK
if (update needed) {
...
write FILE
}
Even better is to enclose an update loop between begin and commit:
begin
while (TRUE) {
next FILE nsr=BREAK
if (update needed) {
...
write FILE
}
commit
This is the fastest option but suffers from the disadvantage that all the
records read remain locked until the commit is executed. This is inherent
in the way that begin and commit work. Adding an unlock command does not
help because unlock must be ignored inside a transaction.
SCULPTOR 4.2 - 11 June 2001
1. The compiler now accepts the commands begin_mark, commit_mark and
rollback_mark, which are synonomous with begin, commit and rollback.
This makes it easier to prepare code changes required by Sculptor 5.1.
SCULPTOR 4.2 - 20 December 2000
1. The maximum number of characters than can be read in a single get #
command has been increased from 1000 to 4000.
SCULPTOR 4.2 - 1 November 2000
1. Three system temps have been added:
sys.ScMajorVersion (type u1) contains the Sculptor major version number.
sys.ScMinorVersion (type u1) contains the Sculptor minor version number.
sys.ScDateVersion (type i4/dn) contains the Sculptor date version.
For example, Sculptor 4.2 (1 November 2000) sets:
sys.ScMajorVersion = 4
sys.ScMinorVersion = 2
sys.ScDateVersion = 1/11/00
Suffix letters, such as 4.2a, are no longer used.
SCULPTOR 4.2 - 12 October 2000
1. The style WS_FIXEDWIDTH has been added for tab windows. It makes all
tabs the same width.
SCULPTOR 4.2 - 12 September 2000
1. scconfig has been enhanced so that it is possible to install Sculptor
without user intervention, the licence details being read from a file.
There are two new options:
scconfig -c filename
The -c option starts scconfig in normal interactive mode but when the
program exits, it saves the licence information that has been entered
or viewed to the specified file as well as updating the registry.
scconfig -f filename
The -f option reads licence information from the specified file and
updates the registry. This is a quiet mode operation. The information
in the file must be valid. There are no error messages.
In both cases, the filename can be a valid path to kfserver/kfservnt,
which must be running on the referenced server.
SCULPTOR 4.2 - 26 June 2000
1. By default on Unix and Linux, programs that are executed by kfserver
now have stdin set to /dev/null and stdout and stderr redirected to the
file /tmp/kfserver.log. This avoids problems with programs that read or
write these channels by mistake. The standard channels can still be
redirected elsewhere in the normal way on the command line. On Windows
the error log file is \kfservnt.log.
SCULPTOR 4.2 - 30 May 2000
NOTE 1: To avoid a !define conflict, the FILE_EXISTS, FILE_CANREAD,
FILE_CANWRITE and FILE_CANEXEC definitions in the beta release have
been changed to TEST_EXISTS, TEST_CANREAD, TEST_CANWRITE and
TEST_CANEXEC. These are used with the new access() function.
Sculptor 4.2 contains major improvements and several bug fixes so it
is essential that applications are fully verified for operation with
this version. Bug fixes and improvements are always capable of
breaking application code that uses an undocumented feature or has a
coding error that is benign on an earlier version of a product.
1. Sculptor 4.2 supports the use of the Windows registry and the registry
should be used instead of the environment. An emulation of the registry
is provided on other platforms, such as Unix. Each Sculptor version has
its own set of variables in the registry. These are keyed on the Sculptor
major version number, ignoring any minor version number and suffix letter.
Thus, there is a set of variables for version 4. A variable can be defined
at both system level and login user level (the local user). A variable is
first checked for at user level. If it does not exist at this level, the
system value is used. In most cases it will only be necessary to define a
variable at system level. If an environment variable is set, this takes
precedence over the registry but it is recommended that the environment
is not used, except for temporary changes during development.
When a Sculptor program runs it picks up the registry variables that
correspond to its major version number. Sculptor 4.2, 4.2a, 4.2b etc.
will all pick up the version 4 variables. Suffix letters indicate bug
fixes and essential minor enhancements.
When a new version of Sculptor is installed, it creates a new set of
registry variables for that major version if none exist or, if registry
variables exist for a previous version of Sculptor, takes a copy of
these and modifies them as necessary.
The user can set their own variables in the Sculptor registry at both
system level and user level. The program scconfig is used to do this
on Windows or chconfig on other platforms, including 16-bit DOS. The
Sculptor function getenv() checks the environment, the local user's
registry and the system registry in that order.
There is a new Sculptor licensing system that uses the registry. The
scconfig program must be used to input a licence number and activation
key. Once this has been done, all Sculptor programs that are valid
under the licence will run. There is no need to serialise individual
programs. Valid updates will also run without the need to edit the key.
A change to the licence, such as the number of run-time users, can be
made by running scconfig or chconfig and entering a new key supplied
by Sculptor.
To set up or edit a licence on Windows, proceed as follows:
1. Run scconfig and click the Reg button.
2. Type in the supplied serial number.
3. Tick the boxes relevant to your licence (Development, Runtime,
Server, etc.) and enter the correct number of users against each
option.
4. Enter the activation key supplied by Sculptor. Spaces are ignored
but can be used to improve readability. The digit 0 and the letter
O are equivalent but the digit 1 and the letter l are not. Case is
not significant.
On Unix and other platforms, run chconfig and reply to the questions.
If scconfig is executed with a -q (quiet) option, information messages
are suppressed. This is useful when running scconfig as part of an
application installation procedure; only the licence information needs
to be entered.
2. The Sculptor keyed file routines have been improved substantially. The
changes increase performance, especially in client/server mode. Also,
although reliability has not been a problem, the new routines will be
more robust and the file system better able to survive a machine or
network failure. The overall speed improvement cannot be quantified
because it varies with application code.
3. There is now no specific limit to the number of Sculptor keyed files
that can be open concurrently, available memory being the only limiting
factor. Exception: Clients who connect to kfserver from an earlier
version of Sculptor are still limited to 400 open files or less,
depending on the client version.
4. An option is available to further increase performance in client/server
mode on specified files by reading records in batches. This option must
be used carefully because in some cases it can have a negative effect
on performance and in other cases it can change the behaviour of the
application. This feature is intended for use when records are being read
sequentially and not locked or only locked occasionally. The driving file
of a report is frequently a suitable candidate. The batch_read property
can be set with the file open or closed:
file_id->batch_read = ON | OFF
By default, this property is OFF. If it is turned ON and the file is
open or is later opened on a server (running kfserver or kfservnt), then
executing any of the following commands twice consecutively, using the
same index, causes Sculptor to perform a read ahead operation and to
obtain a batch of records or keys from the server:
nextu, prevu, nextkey, prevkey
The matchu command also performs a read ahead, the findu command being
taken to be the first of t