-------------------------------------------------------------------- SCULPTOR 5.8.8 -------------------------------------------------------------------- 1. The index= clause in a !drive declaration can now be assigned to a pointer field: !temp idxptr,,p idxptr = &MYFILE.index2 ... !report myrep { !drive MYFILE index=idxptr ... 2. The following changes have been made to kfserver and kfservnt: For kfserver, the log file is now $SCULPTOR/log/kfserver.log instead of /tmp/kfserver.log. For kfservnt, the log file is now %SCULPTOR%/log/kfservnt.log instead of \kfservnt.log. The log file contains more details for a client connection that has been terminated abnormally. The following command line options can be used with both kfserver and kfservnt: -d Debug mode. Writes client connections and disconnections to the log file. On Unix, writes the stdout and stderr outputs of all executed child processes to the files $SCULPTOR/server/kfserver.stdout $SCULPTOR/server/kfserver.stderr respectively unless these are redirected elsewhere in the execute command. These files are always recreated empty when kfserver is started with the -d option. -l Debug locks. Makes file and record locking details available in the remote monitor program. -n Creates a new empty log file. If this option is not used, messages are appended to the existing log file. -------------------------------------------------------------------- SCULPTOR 5.8.6 -------------------------------------------------------------------- 1. If newkf is used to recreate an existing file and neither -s nor -b is specified, the type of the new file is the same as the old file. 2. If "openfile ... create" is used to recreate an existing file, the type of the new file is the same as the old file. The createbig keyword can be used to force a big file. There is no createsmall keyword. -------------------------------------------------------------------- SCULPTOR 5.8.4 -------------------------------------------------------------------- 1. The programs servmgr.exe, kfserver.exe and kfservnt.exe now request Administrator privilege. The servmgr program should always be used to to start the Sculptor server manager. The program kfsmonw.q should not be run directly as it may then run without required permissions and may be unable to communicate with the server. 2. When printing to a window, the size of the window is adjusted automatically to fit the report and the page length is restricted to the screen height. The visible area of the screen window can be forced larger by setting sys.PageLength and sys.PageWidth but Sculptor prevents the window size from exceeding the screen size. 3. The maximum length of a long text field has been increased to 132,000. -------------------------------------------------------------------- SCULPTOR 5.8.3 -------------------------------------------------------------------- 1. Added sql command line program. This supports SQL queries on Sculptor files. This is an interim version. Joins are very slow on large files. An improved version is being developed. 2. iODBC is supported on many Linux and Unix platforms. -------------------------------------------------------------------- SCULPTOR 5.8.2 -------------------------------------------------------------------- 1. The program servmgr.exe is now a stub that runs "srepwc kfsmonw". -------------------------------------------------------------------- SCULPTOR 5.8.1 -------------------------------------------------------------------- 1. The following functions enable Sculptor programs to communicate with C programs and with other Sculptor programs using shared memory segments. See "Shared Memory Functions.doc" for full details. shm_id = create_shared_memory(share_name, record_id) shm_id = link_shared_memory(share_name, record_id) nbytes = read_shared_memory(shm_id, offset, len, options) nbytes = write_shared_memory(shm_id, offset, len, options) unlock_shared_memory(shm_id) unlink_shared_memory(shm_id) 2. On Microsoft Windows, standard Windows messages can be sent to C programs: result = send_message(hwin, msg, wparam, lparam) result = post_message(hwin, msg, wparam, lparam) Parameters, behaviour and return values for these functions are as described for the corresponding functions in the Windows API. The Sculptor program needs to obtain a Window handle from the C program. This could be supplied in a file or in a shared memory segment. These functions are for advanced use. They can be executed on Unix versions of Sculptor but have no effect. 3. On Unix and Linux, standard Unix messages can be sent to C programs: msg_id = create_msg_queue() msg_id = link_msg_queue() result = read_msg_queue() result = write_msg_queue() result = remove_msg_queue() See "Unix Message Functions.doc" for full details. 4. There are new control features in kfserver and new kfserver management programs have been introduced. On Unix, the C program kfsmon has been replaced by a shell script of the same name. This starts the new Sculptor server monitor for Unix: $SCULPTOR/server/kfsmonc.q On Unix, kfserver can be started and stopped as before by using the shell script startkfs and the C program stopkfs, or it can be started and stopped from the new monitor program. On Windows, a new batch file kfsmon.bat starts the new Sculptor server monitor for Windows: %SCULPTOR%\server\kfsmonw.q On Windows, kfserver can be started from the command line as before and stopped from its own menu option, or it can be started and stopped from the new monitor program, which can also create, start and stop the Sculptor service version kfservnt. The new server monitor provides more details and better control of connected clients. Details of all connections are shown in a table (on Windows) or a listbox (on Unix). This is refreshed automatically at a user selected interval. A line in the table can be expanded by double clicking it. A line in the listbox can be expanded by tabbing into the listbox, using the arrow keys to select the line and then pressing RETURN. In the window that opens there is an option to disconnect the selected client. Note that the automatic refresh is suspended while focus is in the table or the listbox. The new monitor program has a Server Options button. This opens a window with checkbox options. If the remote management checkbox is ticked (+ sign on Unix), a snapshot of all client connections is written to a Sculptor file each time the client list is refreshed. This file can be viewed over a network by running the new remote management program on a Windows client: %SCULPTOR%\server\remmon.q If the Sculptor server allows connections from the Internet, this makes it possible to manage kfserver connections on a remote client site. The remote management option can be turned on and off at any time. It is not necessary to restart kfserver. There is also an option to start kfserver in lock debugging mode. In this mode details of all locks held by all connected clients are written into a Sculptor file. A table of locks can be viewed in the remote management program remmon.q. Although this program is designed to run on a remote client, it can also be run on the server itself. Note that lock debugging mode cannot be selected or deselected once kfserver is running. This mode can only be changed by stopping and restarting kfserver. Lock debugging mode has a performance overhead, so it should only be used to diagnose locking issues. When kfserver is started from the command line, lock debugging mode can be selected by using the command line option -l. The service version kfservnt now also honours command line options. 5. It is now possible to trap a TCP/IP socket error in a Sculptor program by by setting the system variable sys.ServerErrorFunction to point to an event function that is called if an error occurs. Example: sys.ServerErrorFunction = &ServerError !function ServerError(server, errcode, dirn, maincode, subcode) { error "Error " + tostr(errcode) + " on server " + server return 1 } Sculptor calls the function with the following arguments: server The name of the server errcode The system error code dirn 0 if error on sending a command to the server 1 if error on reading response from the server maincode The Sculptor main command code subcode The Sculptor sub command code The dirn, maincode and subcode values are provided for diagnostic purposes. Whatever the dirn value, the command may or may not have reached the server. The best way to guard against application errors caused by socket errors is to wrap related updates between calls to the begin() and commit() functions. The function can exit the program or return one of the following values: < 0 Display a standard socket error message and abort the program. = 0 Continue running the program. The command or function that was being executed when the error occurred will return with an error if possible (e.g. if it has an err= trap), otherwise with a null result. Continuing is not normally a viable option, since the program's connection to the server has been lost and the command or function that was being executed has failed. However, it is technically possible to restablish a connection if the cause of the error has been corrected. Note that a program cannot issue a rollback() on a new connection. When the previous connection times out, kfserver will issue an automatic rollback(). > 0 Abort the program without displaying an error message. 6. There are two new functions that Sculptor programs can use to control client connections: get_client_info(server, port, client_id, random_id) Connects to the specified Sculptor server if not already connected and then returns connection information in the supplied fields: port The TCP/IP port number of the connection (u2 or longer). client_id A unique client id number allocated by the server (i4). random_id A random id number allocated by the server (i4). Valid port and client_id numbers are always non-zero. Function return values: < 0 Cannot connect to server = 0 Successful > 0 Not used, treat as error disconnect_client(server, port, client_id, random_id) Connects to the specified Sculptor server if not already connected and then sends a disconnect client request. The supplied port, client_id and random_id numbers must match a triplet returned by the get_client_info() function. If successful, the designated client is forcibly disconnected by kfserver. If that client had an open transaction, the transaction is rolled back. A program cannot use this function to disconnect itself. Function return values: < 0 Cannot connect to server = 0 Successful > 0 Port or client_id not valid A program could use these two functions to recover after a socket error. After connecting to a server, the program calls get_client_info() and saves its port and id values in a local file. Before exiting it clears these values. If, on starting, the program finds these values still set, it calls the disconnect_client() function to reconnect itself and to make sure that its previous instance is no longer running. If disconnect_client() returns > 0, the program should assume that the previous connection has already timed out. 7. A new set of built-in functions enable Sculptor programs to create and manage Windows Services. This is an advanced feature. To use these functions, it will be necessary to read the Windows API documentation on the equivalent Service Management functions. Manifest constants used with the service management functions are defined in . ------------------------------------------------------------------ result = close_service_handle(handle) Closes a handle obtained from the create_service() or open_scmanager() functions. A handle should be closed when it is no longer required. Returns 0 if successful or non-zero if an error occurs. The Windows error code is in sys.Errno. ------------------------------------------------------------------ result = control_service(service_handle, code) Sends a control code to the specified service. service_handle A handle returned by create_service() or open_service(). code The control code to be sent to the service. Some standard codes (see the Windows API for full list): SERVICE_CONTROL_CONTINUE SERVICE_CONTROL_INTERROGATE SERVICE_CONTROL_PAUSE SERVICE_CONTROL_PARAMCHANGE SERVICE_CONTROL_STOP Codes 128 - 255 are for application use. Returns 0 if successful or non-zero if an error occurs. The Windows error code is in sys.Errno. ------------------------------------------------------------------ service_handle = create_service(manager_handle, \ service_name, \ display_name, \ description, \ pathname, \ dependencies, \ account_name, \ password, \ access_rights, \ service_type, \ start_type, \ error_control) Creates a Windows service and adds it to the service control manager database. See CreateService() in the Windows API. manager_handle A handle obtained by a previous call to open_scmanager(). service_name Internal name for the service (cannot include / or \). display_name Display name for the service in Windows Service Manager. description A short description of the service (can be a null string). pathname Full path to the executable program. If the name contains a space it must be quoted. Arguments may follow the name. dependencies The service names of other services on which this service depends. Separate each name with a comma and avoid spaces. If this service has no dependencies, supply a null string. account_name The name of the account under which the service is to run. If a null string is supplied, the service runs in the LocalSystem account. Other standard accounts are: "NT_AUTHORITY\\LocalService" "NT_AUTHORITY\\NetworkService" The double \\ is needed because \ is an escape character in Sculptor string constants. It becomes a single \ in the compiled program. password The password for the specified account. Supply a null string if the account has no password or the service runs in the LocalSystem, LocalService or NetworkService account. access_rights Desired access to the service. See the Windows API for full details. SERVICE_ALL_ACCESS can be used if the user running the program has Administrator priviliges. service_type One of: SERVICE_FILE_SYSTEM_DRIVER SERVICE_KERNEL_DRIVER SERVICE_WIN32_OWN_PROCESS SERVICE_WIN32_SHARE_PROCESS start_type One of: SERVICE_AUTO_START SERVICE_BOOT_START SERVICE_DEMAND_START SERVICE_DISABLED SERVICE_SYSTEM_START error_control One of: SERVICE_ERROR_CRITICAL SERVICE_ERROR_IGNORE SERVICE_ERROR_NORMAL SERVICE_ERROR_SEVERE Returns a service_handle if successful (store in i4 field) or 0 if the service cannot be created. The Windows error code is in sys.Errno. ------------------------------------------------------------------ result = delete_service(service_handle) Marks the service for deletion from the service control manager database. The service is not deleted until all handles open to it are closed and the service is not running. service_handle A handle returned by create_service() or open_service(). Returns 0 if successful or non-zero if an error occurs. The Windows error code is in sys.Errno. ------------------------------------------------------------------ manager_handle = open_scmanager(machine_name, access_rights) Opens the service manager on a specified computer. machine_name The name of the target computer. A null string means the local computer. access_rights Desired access to the service. See the Windows API for full details. SC_MANAGER_ALL_ACCESS can be used if the user running the program has Administrator priviliges. Returns a manager_handle if successful (store in i4 field) or 0 if the manager cannot be opened. The Windows error code is in sys.Errno. ------------------------------------------------------------------ service_handle = open_service(manager_handle, service_name, access_rights) Opens a service for control purposes. manager_handle A handle obtained by a previous call to open_scmanager(). service_name The name of the service. access_rights Desired access to the service. See the Windows API for full details. SC_MANAGER_ALL_ACCESS can be used if the user running the program has Administrator priviliges. Returns a manager_handle if successful (store in i4 field) or 0 if the manager cannot be opened. The Windows error code is in sys.Errno. ------------------------------------------------------------------ result = start_service(service_handle, arg_string) Starts the specified service. service_handle A handle returned by create_service() or open_service(). arg_string A list of arguments to be passed to the service in standard command line format. Supply a null string if there are no arguments. An argument that contains embedded spaces must be quoted. Example: "-v \"-m=this is a test\"" Returns 0 if successful or non-zero if an error occurs. The Windows error code is in sys.Errno. ------------------------------------------------------------------ result = query_service_config(service_handle, record_id) Queries the configuration of the specified service. service_handle A handle returned by create_service() or open_service(). record_id A Sculptor !record that defines the required information fields. Fields must be named exactly as shown below. It is only necessary to define the fields whose values are required. ServiceType,,i4 StartType,,i4 ErrorControl,,i4 DisplayName,,a64 Description,,a255 BinaryPathName,,a255 Dependencies,,a255 ServiceAccount,,a64 Returns 0 if successful, in which case the service status information has been stored in the supplied fields. See the Windows API for details of the values stored in these fields. Returns non-zero if an error occurs. The Windows error code is in sys.Errno. ------------------------------------------------------------------ result = query_service_status(service_handle, record_id) Queries the current state of the specified service. service_handle A handle returned by create_service() or open_service(). record_id A Sculptor !record that defines the required information fields. Fields must be named exactly as shown below. It is only necessary to define the fields whose values are required. ServiceType,,i4 CurrentState,,i4 ControlsAccepted,,i4 Win32ExitCode,,i4 ServiceSpecificExitCode,,i4 CheckPoint,,i4 WaitHint,,i4 ProcessID,,i4 ServiceFlags,,i4 Returns 0 if successful, in which case the service status information has been stored in the supplied fields. See the Windows API for details of the values stored in these fields. Returns non-zero if an error occurs. The Windows error code is in sys.Errno. ------------------------------------------------------------------ result = add_account_privilege(computer, account, privilege) computer The name of a computer on the network. Use "" for the local computer. account The name of the account to which the privilege is to be added. Can be in the form domain\account. privilege The name of the privilege to be added. Refer to Microsoft documentation for a full list. Examples: add_account_privilege("", ".\\MyAccount", "SeServiceLogonRight") add_account_privilege("", "MyDomain\\MyAccount", "SeServiceLogonRight") Returns 0 if successful. Returns non-zero if an error occurs. The Windows error code is in sys.Errno. 8. Standard Sculptor keyed files hold a maximum of 16,777,215 records. On Microsoft Windows and on Unix and Linux platforms that support large files, it is now possible to create a keyed file up to 128Gb in size with up to 134,217,727 records. A "big" file has a different format to a standard Sculptor keyed file and requires more disk space for the same number of records. Both file types can be used in the same program. To create a big file, use the openfile command with the createbig option: openfile file_id ... createbig or create the file with newkf -b: newkf -b filename The default mode in !file and !ofile can also be createbig but note that using the create or createbig option in the openfile command overrides the default mode. The mode specified in !file is used only if the file is opened automatically. By default, the kfcopy and reformat programs create the new file in the same format as the old file. The -b option forces the new file to be a big file. The -s option forces the new file to be a standard file: kfcopy -b old_filename new_filename reformat -b old_filename new_filename kfcopy -s old_filename new_filename reformat -s old_filename new_filename If the old index exists, the kfri program always creates a new index of the same type as the old index. If the old index does not exist, a big file index can be forced by using the -b option. The kfri program must not be used to change a file from standard type to big type or vice-versa. The -b option must be used only if the file is already a big file type. 9. The function sendmail(record) opens the default email program on the host computer and starts an email. The argument is the name of a !record with some or all of the following fields: !record Email { FileNames,,a80[5] Subject,,a80 Body,,a80[10] To,,a80 Cc,,a80 Bcc,,a80 } Each field can be any alphanumeric size. The a80 sizes above are only examples. A long text field can be used and may be particularly useful for the body. Also, any dimension can be used for FileNames and Body fields, as needed. All non-blank elements of the FileNames field are the names of files to attach. The filenames may have full or relative pathnames. Sculptor converts the pathnames to standard full pathnames before passing them to the email program. sendmail() returns 0 if successful or non-zero if the default email program cannot be started or a specified attachment does not exist. This function works only on Microsoft Windows operating systems. See SCULPTOR\demo\misc\sendmail.f for an example program. -------------------------------------------------------------------- SCULPTOR 5.8.0 -------------------------------------------------------------------- 1. This version is available for devices running Windows CE, such as PDA's, Smartphones and Scanning Devices. 2. It is now possible to change the xcreate and ycreate attributes of a window or control that is in the created state. This does not move the object. It only affects the position if the object is recreated. 3. If a dotted IP address (e.g. 192.168.1.10), is used for the server name, the Sculptor client now connects to the Sculptor server even if no DNS (domain name service) is available to the client. This is particularly useful when the client is a PDA or mobile phone connected to a wireless LAN. 4. An EV_RESTORE event is sent to a window's event function when the window is restored from a maximised size back to its previous size. This is a default event. 5. When a tab window is resized, Sculptor now repaints the window without destroying and recreating the tabs. This is visually smoother. 6. Files have a new property, report_mode, that can be set at run-time. If a !drive or !xfile has report_mode = 0 (default), its records are locked when read automatically during a report, but if report_mode = FOM_READ, the records are read unlocked, even if the file is open update. This applies only to an automatic read generated by a !drive or !xfile. A normal read command still locks the record. A file's report_mode can be changed at any time, even in the middle of a report: file_id->report_mode = FOM_READ 7. Sculptor has a new function that supports system tray icons: system_tray_icon(opcode, window, icon, tip) opcode is one of: STI_ADD Add an icon to the system tray STI_MODIFY Modify an icon in the system tray STI_DELETE Delete an icon in the system tray window The window whose event function receives events from this system tray icon. Normally use wintask but can be another window. icon An icon image file (.ico). If NULL, the standard Sculptor icon is used. tip Text for the tip. NULL if a tip is not required. A system tray icon can generate the following events. Note that a double event code is used to distinguish from the same event in the window itself. EV_SINGLE_CLICK | EV_SYSTEM_TRAY_ICON A single left click on the system tray icon. This is a default event. EV_DOUBLE_CLICK | EV_SYSTEM_TRAY_ICON Double left mouse click on the system tray icon. This is a default event. EV_RIGHT_MOUSE_UP | EV_SYSTEM_TRAY_ICON Right mouse button up on the system tray icon. This is the preferred event for responding to right mouse clicks. This event is not sent by default and must be enabled. EV_RIGHT_MOUSE_DOWN | EV_SYSTEM_TRAY_ICON Right mouse button down on the system tray icon. Rarely used. This event is not sent by default and must be enabled.