Category: Functions

$copytoclient

Copies files from the server side to the client side.

Syntax

$copytoclient(source file name, destination file name, file type)

where

source file namean expression that evaluates to a character string containing a valid file address
destination file namean expression that evaluates to a character string containing a valid file address
file typean expression that evaluates to a character string that starts either with “B” (from “Binary”) or “T” (from “Text”)

Return Value

The value return by this function is the file address of the destination if it is executed correctly; otherwise, it will return a $Null value.

Comments

This function is designed to work under ZIMTC and copies file from the server side to the client side using the file type specified. Files of the binary type are sent as they are, without their contents being checked (like images, videos, etc). On the other hand, files of the text type are copied using text file conventions for Windows and Unix.

Both the source and the destination file names can be either relative or absolute file paths. The following remarks apply to these paths:

source file is absolutethe file is taken from the absolute path
destination file is absolutethe file is written onto the absolute path. Care should be taken because this absolute path refers to a location in the client’s machine; if there are many different users running, all users must have the same valid address
source file is relativenormally, the current directory is the database directory; therefore, the file will be taken from an address calculated inside the current directory
destination file is relativethe file goes to place that is relative to the current directory in the client session which is always where the Zimtc session has been started; therefore, if the file is needed for subsequent operations, then the same relative path must be used. If the file will be needed after the current session is finished, then it is suggested to provide an absolute path to the destination file as Zimtc does not guarantee that files will be preserved after the session finishes

Because ZIMTC actually acts like a Web Browser in most respects, the client side (managed by ZIMTC) does not have the files needed to perform certain operations which should be located in a place only known by the server. This situation is specially important when the file is needed by an external processing capability like an ActiveX component or any other program that uses a file without the direct control of ZIMTC.

If the destination file name contains sub-directories that don’t exist, they are created.

The ZIM executable ignores this function as it makes no sense copying a file to itself.

Example

This is an invocation of an ActiveX property to edit the file specified. It reads the file from a fixed location but writes it to the directory where the session has been started.

let vResult = $objsetproperty(Object, "image", $copytoclient("c:\myfiles\myimage.bmp", "myfiles\myimage.bmp", "binary"))

This example copies the text file from the database path to a fixed location in the client’s machine.

out $copytoclient("mytext.txt", "c:\mextext.txt", "T")

Related Topic

$copytoserver

$substring

Extracts a segment of a character string.

Syntax

$substring(source,position,length)

Parameters

sourcea character string, or an expression that evaluates to a character string
positiona number, or an expression that evaluates to a number
lengtha number, or an expression that evaluates to a number

Return Value

Character string, containing a string extracted from source, whose first character is position characters into source, and whose length is length characters.

Comments

Use $substring to extract a portion of source. The resulting string contains length characters, starting position characters into source.

If source is not a character data type, it is converted to a character data type before the function is applied.

If position is beyond the end of source or if length is zero or negative, the result is the null string.

If position+length is longer than source, the result consists of all characters from position to the end of source.

Example

$substring("the quick brown fox jumped",7,5)

Extracts “ick b” from the string.

$substring(9999,1,1)

Evaluates to ” ” (the number is converted to a string).

$substring(5+4,17,1)

Evaluates to “9” (the number is converted to a string).

See Also

$concat

$delete

$fill

$insert

$left

$position

$right

$squeeze

$translate

About Character Literals

About Functional Expressions

$replace

Replaces a portion of a character string with another character string.

Syntax

$replace(source,position,length,string)

Parameters

sourcea character string, or an expression that evaluates to a character string
positiona number, or an expression that evaluates to a number
lengtha number, or an expression that evaluates to a number
stringa character string, or an expression that evaluates to a character string

Return Value

Character string, consisting of source, with the characters starting at position for a length of length replaced by the characters from string.

Comments

Use $replace to replace, in source, the characters starting at position for a length of length, with string.

In a string, the position of the first character is always 1. If position is beyond the end of source, or if position is zero or negative, then source is left unchanged.

If length is zero or negative, then string is embedded in source starting at position (effect is like $insert).

If there are fewer than length characters from position to the end of source, all characters from position to the end of source are replaced by string.

Example

$replace("abcdef",2,2,"123")

Evaluates to “a123def”.

See Also

$concat

$delete

$fill

$insert

$left

$position

$squeeze

$substring

$translate

About Character Literals

About Functional Expressions

$compilestatus

Checks if an application program needs to be recompiled.

Syntax

$compilestatus(docname)

Parameters

docnamethe name of an application document (not in quotation marks)

Return Value

Number, with no decimal places.

Comments

$compilestatus checks, in order, a series of conditions in relation to docname. As soon as docname fails to meet a condition, $compilestatus returns the code number (1 through 8) associated with that condition. If docname meets all the conditions, $compilestatus returns a 0.
A $compilestatus expression can be compiled, but its value is fixed at compile time and does not change thereafter.

CodeCondition
1The docname is not currently compiled.
2The source file for docname is missing.
3The compiled file for docname is missing.
4The source file bears a date more recent than that of the compiled file.
5No dependency information could be found for docname.
6The dependency information predates the most recent compile and could therefore be out of date.
7An object that docname depends on could not be found, it can be erased or located in an unaccessed directory.
8An object that docname depends on has been modified since docname was last compiled.
0No inconsistencies in the compilation status of docname were noted.

Example

let status = $compilestatus(MyZIMProgram)
case
   when status = 0
      output "No need to compile"
   when status =2
      output "No source file"
   when status = 7
      output "Could not find a dependent object"
   otherwise
      compile MyZIMProgram
endcase

$fill

Fills part of a string with a specified character

Syntax

$fill(source,position,length,string)

Parameters

sourcea character string, or an expression that evaluates to a character string
positiona number, or an expression that evaluates to a number
lengtha number, or an expression that evaluates to a number
stringa character string, or an expression that evaluates to a character string

Return Value

Character string, consisting of source filled with the first character from string, starting at position, for a length of length.

Comments

Use $fill to initialize strings to specific values. The function fills source with the (first) character from string, starting at position, for length number of characters. The fill character replaces any characters that already exist in the string in the specified positions.

In a string, the position of the first character is always 1. If position is beyond the end of source, or if position is zero or negative, then source is left unchanged.

If length is zero or negative, then source is left unchanged.

If there are fewer than length characters from position to the end of source, then all characters from position to the end of source are replaced by the fill character.

If string is the null string, then a space is used as the fill character.

Example

$fill(Title,1,$length(Title)," ")

The above expression fills Title with spaces.

See Also

$concat

$delete

$insert

$left

$position

$replace

$right

$squeeze

$substring

$translate

About Character Literals

About Functional Expressions

$messagebox

Presents a message box to the application user and waits for a response.

Syntax

$messagebox(message,type,style,defaultbutton[,heading])

Parameters

messageA character string, or an expression that evaluates to a character string.
typeA number that determines the type of message box. It also determines the icon that appears in the message box.
styleA number that determines the responses (push buttons) available to the application user.
defaultbuttonA number that determines which push button is the default button. Buttons are numbered 1, 2, and 3 from left to right.
headingA title for the message box. If you do not specify a heading, one is assigned based on type.

Message box types include:

TypeMeaningConstant Name

1

Error

cErrorMsg

2

Warning

cWarningMsg

3

Information

cInfoMsg

4

Question

cQuestionMsg

Push button styles include:

TypeButtons SuppliedConstant Name
1OKcOKStyle
2OK, CancelcOKCancelStyle

3

Retry, CancelcRetryCancelStyle

4

Yes, NocYesNoStyle

5

Yes, No, CancelcYesNoCancelStyle

6

Abort, Retry, IgnorecAbortRetryStyle

Return Value

Character string.

Comments

Use $messagebox to display a message in a dialog box of the specified type, with the specified heading or a default heading in the caption. The application user responds by activating one of the buttons provided by style, one of which is a defaultbutton. $Messagebox returns a character string containing the label of the button pressed by the application user.

Example

$messagebox("Delete file?",2,5,2,"File Operations")

$filebrowse

Presents the application user with a File Open common dialog box.

Syntax

$filebrowse(directorypath, pattern, flags ,[heading])

Parameters

directorypathA character string or an expression that evaluates to a character string, naming the default directory path to show in the dialog box. If path is the null string (”), the current directory is used as the default directory.
patternA character string or an expression that evaluates to a character string, specifying the pattern names and associated patterns that can be searched for, in the dialog box. If pattern is the null string (”), no patterns are searched for. Otherwise, pattern is specified in the form:
“patternname1|pattern1[«|patternname2|pattern2»]”
flagsA number or an expression that evaluates to a number, determining the attributes of the dialog box.
headingA character string, or an expression that evaluates to a character string, setting the title for the dialog box.
FlagsMeaningConstant Name
0The dialog box opens for saving a file. 
2Path must exist.cPathMustExist
4Prevent read-only files from being returned.cNoReadOnlyFiles
8Enable multiple selections.cAllowMultiSelect

Flags can contain any single number, or the sum of two or more numbers from the Flags column.

Return Value

For EntitySets, relationships, and application directories, the value returned is the number associated with the disk file that contains the specified object.

For application documents, the value returned is the number associated with the disk file that contains the application directory in which the application document was created.

Comments

Use $filebrowse to display the File Open common dialog box and select a file.

The value returned by the function depends on the application user’s interaction with the dialog box:

  • If the application user activates the Cancel push button, $Null is returned.
  • If the application user makes a selection (multiple selections not enabled), the function returns the directory path concatenated with the file name.
  • If the application user makes a selection (multiple selections enabled), the function returns the directory path and a list of one or more file names separated by semicolons.

Example

A properly constructed pattern appears as shown below:

'All files |*.*|ZIM files|*.zim;zim0*'

In the following code fragment, the variable vIconFileSel is assigned the results of the user’s interaction with the File Open dialog box:

let vIconFileSel= $filebrowse ($concat($DBPath, "\Icons"), "Icon files|*.ico|All files|*.*", cFileMustExist + cPathMustExist, "Icon File Selection")

$getproperty

Returns the current settings of certain device or registry properties.

Syntax #1

Returns the current settings of certain desktop properties.

$getproperty("desktop",property)

Parameters

propertyA character string or an expression that evaluates to a character string. Properties include MousePresent, ScreenColors (or ScreenColours), ScreenHeight, ScreenUnits, and ScreenWidth.

Return Value

Character string or $null if property is not a recognized string.

Syntax #2

Returns the current settings of certain printer properties in the Windows environment.

$getproperty("printer",property)

Parameters

propertyA character string, or an expression that evaluates to a character string. Properties include CharsPerLine, Color (or Colour), DeviceName, DisplayPrintDialog, DriverVersion, Duplex, FontName, FontSize, LinesPerPage, MonospacedFont, Orientation, PaperBin, PaperLength, PaperSize, PaperWidth, PrintQuality, Scale, TrueTypeOption, and YResolution.

Return Value

Character string or $null if property is not a recognized string.

Comments

The string contains the current setting of property.

Syntax #3

Returns the current settings of the Zim variables stored in the Windows Registry.

$getproperty (registry_section,registry_variable)

Parameters

registry_sectionA character string, or an expression that evaluates to a character string with the format “REG:[sectionname]” or “SERVREG:[sectionname]”. The sectionname can be ODBC, ZIM or a user-defined name.
registry_variableThe registry variable being queried.

Return Value

Character string or $null if the section or the variable is not present in the Registry.

Syntax #4

$GetProperty ("session", <config_setting>)

Parameters

sessionThe operating environment of one particular invocation of a Zim executable.
config_settingA valid configuration setting.

Return Value

The return value is the current value of the specified config_setting.

Syntax #5

$GetProperty ("OleVerbList", FileOrClassName)

Parameters

OleVerbListThe list of verb names supported by an OLE object.
FileOrClassNameA valid OLE file or classname.

Return Value

The return value is the list of supported verbnames of a file or OLE class. Semicolons separate the verbs in the returned list.

Examples

>out $getproperty ("OleVerbList", "ztizim.bmp")
Edit;Open

In the above command, the OleVerbList associated with a .bmp file is “Edit;Open” which means that there are two available verbs: Edit and Open.

let vFontSize = $getproperty ("printer", "fontsize")

In the above command, vFontSize can be a character or number variable. (The software converts the character string returned by $getproperty to a number, if required.)

let vODBCVersion = $getproperty ("REG:[ODBC]", "VERSION")

Gets the version of the installed Zim ODBC Driver.

See Also

$printersetup
$setproperty

$setproperty

Changes the settings of certain device properties of the registry variables file.

Syntax

$setproperty(section, property, newsetting)

Parameters

sectionA character string or an expression that evaluates to a character string to indicate the group of properties or registry values that should be changed.
propertyA character string or an expression that evaluates to a character string to name the property or register that should be changed.
newsettingA character string or an expression that evaluates to a character string containing the new value for the property or register value.

Return Value

A character string containing “1” ($True) if the arguments to the function were valid and newsetting was applied. Otherwise, it returns “0” ($False).

Comments

If more than one $setproperty is used during the generation of a report, then only the last $setproperty is in effect when the report is printed.

Care should be taken when changing the setting of registry values, as improper manipulation can result in program or system failure.

The following are possible values for section, property and their corresponding newsetting:

“DESKTOP”Changes properties of Zim desktop.
property and newsettingThe only possible value for a desktop property is “ScreenUnits” which accepts the following newsetting:0 = screen units are pixels;
1 = screen units are twips;
2 = screen units are points;
3 = screen units are logical inches;
“PRINTER”Sets printer properties of the default printer.
property and newsettingPossible values for a printer property and corresponding newsetting are:”Color” or “Colour” = 1, Monochrome; 2, color;
“Copies” = number of copies;
“DisplayPrintDialog” = 0 or 1, prints the dialog; 2, doesn’t print it;
“Duplex” = 1, Simplex; 2, Vertical; 3, Horizontal;
“FontName” = a valid font name;
“FontSize” = a valid font size;
“MonospacedFont” = 0 or 1, uses mono-spaced fonts; 2, doesn’t use it;
“Orientation” = 1 for Portrait and 2 for Landscape;
“PaperBin” = a number indicating the paper bin (see the printer manual);
“PaperLength” = a number to indicate the paper length (see the printer manual);
“PaperSize” = a number to indicate the paper size (see the printer manual);
“PaperWidth” = a number to indicate the paper width (see the printer manual);
“PrintQuality” = a number indicating the printing quality (see the printer manual);
“Reset” = any value resets to the default values (the value is ignored);
“Scale” = a number indicating the scale to be used for printing;
“TrueTypeOption” = 1, bitmap; 2, download; 3, substitute; 4, outline;
“YResolution” = a number indicating the Y resolution.
“SESSION”Sets properties for the current session of Zim.
property and newsettingPossible values for the Zim session property and the corresponding newsetting are the ones described in the Zim configuration options for the current database. See Zim Database Configuration File (zimconfig.zim) for further details.
“REG:[sub-section]” or “INI:[sub-section]”Sets any properties of this user-defined sub-section.
property and newsettingproperty and newsetting can have any values because they are user-defined.

“SESSION”:

“REG:[ODBC]”To programmatically create an ODBC data source connection.
property and newsettingPossible values for the ODBC Driver data source property and the corresponding newsetting are:The data source name = must be $getproperty(“REG:[ODBC]”, “VERSION”);
“DBQ” = the database name to connect to;
“Driver” = must be $getproperty(“REG:[ODBC]”, “DRIVER”);
“DSN NAME” = the name of the data source;
“Host” = the address of the machine running Zim Server;
“PWD” = the password of the connecting user;
“Server” = the port number that Zim Server is listening to;
“UID” = user name identification;
“WorkPath” = work path of the current session.

For more information, see Configuring a Data Source.

If running the Zim executable, the section “REG:[…]” sets the registry values in the machine where Zim Server is running because Zim only runs in the same machine as Zim Server runs.

If running the Zim Thin executable, the section “REG:[…]” sets the registry values in the machine where Zim Thin is running.

In order to set registry values in the machine where Zim Server is running when running Zim Thin, you must use the section “SERVREG:[…]” which has the same meaning and syntax as “REG:[…]”.

Examples

let vSet = $setproperty ("printer", "fontsize", "12")

Sets the font size of the default printer to 12.

let vSet = $setproperty ("REG:[MYSET]", "My Setting", "I like this one.")

Sets “I like this one.” in the property “My Setting” belonging to the sub-section “MYSET”. This kind of setting is useful for applications to keep track of values used in the Zim application.

let vSet = $setproperty ("SESSION", "Parameter Size", "2000")

Sets the database configuration option “Parameter Size” to 2000.

See Also

$getproperty
$printersetup

$year

Extracts the year number associated with a specified date value.

Syntax

$year(date)

Parameters

datea data, or an expression that evaluates to a date, in the form YYYYMMDD

Return Value

Character string.

Comments

This function extracts day information from standard date values. Date is often the system variable $Date.

Example

$year(19981225)

Evaluates to “1998”.

$year($date + 7)

Evaluates to “1999” when $Date is 19991225.

See Also

$addyears

$Date

$day

$dayname

$month

$monthname

$weekday

About Data Types

About Functional Expressions

en_CAEnglish
pt_BRPortuguese en_CAEnglish