ITK Programmer's Guide

---

These routines can be used to accurately measure elapsed time in some critical code portions.
Under MacOS, these routines use the Time Manager to get a high level of accuracy (up to the millisecond).

ITK_TimerStart
Syntax:	timerRef := ITK_TimerStart
Description:	Start a timer and returns a reference to it. These reference will be used when calling ITK_TimerLap and ITK_TimerStop .
Params:	In/Out Parameter Type     Example or note <- timerRef Longint Timer reference number
Example:	$timer := ITK_TimerStart  ... $elapsedTime := ITK_TimerStop($timer)

Back to top

ITK_TimerLap
Syntax:	lapTime := ITK_TimerLap (timerRef)
Description:	Returns the number of milliseconds since ITK_TimerStart was called without stopping the timer.
Params:	In/Out Parameter Type     Example or note -> timerRef Longint Timer reference number As returned by ITK_TimerStart <- lapTime Longint Elapsed time in milliseconds
Example:	$timer := ITK_TimerStart  ... $lapTime1 := ITK_TimerLap($timer) ... $lapTime2 := ITK_TimerLap($timer) ... $totalTime := ITK_TimerStop($timer)

Back to top

ITK_TimerStop
Syntax:	totalTime := ITK_TimerStop (timerRef)
Description:	Returns the number of milliseconds since ITK_TimerStart was called and then stops the timer.
Note:	After calling ITK_TimerStop, the Timer Reference number returned by ITK_TimerStart is not valid anymore.
Params:	In/Out Parameter Type     Example or note -> timerRef Longint Timer reference number As returned by ITK_TimerStart <- totalTime Longint Elapsed time in milliseconds
Example:	$timer := ITK_TimerStart  ... $totalTime := ITK_TimerStop($timer)

Back to top

ITK's IPC routines are useful to exchange data between processes through communications channels. These channels are memory based to provide speed efficient communications.

The number of channels and the number of messages queued in a channel is limited to 2 billions and by the available memory.

It is not recommended to keep a large number of messages in IPC channels as they can use a lot of memory and fragment 4D's memory.

ITK_NbIPCMsg
Syntax:	nbMsg := ITK_NbIPCMsg (ipcChannel)
Description:	Returns the number of messages currently stored on the specified IPC channel.
Note:	IPC channel number are used to create as many IPC channels as you need. For example, you can use the Current Process instruction in 4D language to allocate one IPC channel for each 4D process or use any other channel numbering.
Params:	In/Out Parameter Type     Example or note -> ipcChannel Longint IPC Channel Number see note above. <- nbMsg Longint Number of messages stored in this IPC channel.
Example:	While (ITK_NbIPCMsg(1)>0) ` process IPC messages ... End While

Back to top

ITK_SendIPCMsg
Syntax:	ITK_SendIPCMsg (ipcChannel;message)
Description:	Sends a message on the specified IPC channel. The message will be stored in the channel message queue.
Note:	IPC channel number are used to create as many IPC channels as you need. For example, you can use the Current Process instruction in 4D language to allocate one IPC channel for each 4D process or use any other channel numbering.
Params:	In/Out Parameter Type     Example or note -> ipcChannel Longint IPC Channel Number see note above. -> message Text Message to send in the above channel
Example:	ITK_SendIPCMsg(1;"quit")

Back to top

ITK_RcvIPCMsg
Syntax:	message := ITK_RcvIPCMsg (ipcChannel;option)
Description:	Reads a message from the specified IPC channel. If no message is available, returns an empty string. The option parameter can be used to keep the message in the IPC channel queue. In that case, the same message will be returned on the next call to ITK_RcvIPCMsg.
Note:	IPC channel number are used to create as many IPC channels as you need. For example, you can use the Current Process instruction in 4D language to allocate one IPC channel for each 4D process or use any other channel numbering.
Params:	In/Out Parameter Type     Example or note -> ipcChannel Longint IPC Channel Number see note above. -> option Longint     0 = default behaviour 1 = keep message in channel queue <- message Text Receive message will be empty if no message available on the requested IPC channel.
Example:	$msg := ITK_RcvIPCMsg(1;0) If ($msg = "quit") QUIT 4D End If

Back to top

ITK_ResetIPCMsg
Syntax:	ITK_ResetIPCMsg (ipcChannel)
Description:	Removes all the messages stored on the specified IPC channel.
Note:	IPC channel number are used to create as many IPC channels as you need. For example, you can use the Current Process instruction in 4D language to allocate one IPC channel for each 4D process or use any other channel numbering.
Params:	In/Out Parameter Type     Example or note -> ipcChannel Longint IPC Channel Number see note above.
Example:	ITK_ResetIPCMsg(1)

Back to top

ITK_CountIPC
Syntax:	ipcCount := ITK_CountIPC
Description:	Returns the current number of existing IPC channels.
Note:	This routine has been introduced in version 2.0.3 of Internet ToolKit.
Params:	In/Out Parameter Type     Example or note <- ipcCount Longint Number of IPC Channels
Example:	` Total number of messages in IPC channels $nbMsg := 0 For ($i;1;ITK_CountIPC) $nbMsg := $nbMsg + ITK_NbIPCMsg(ITK_GetIndIPC($i)) End For

Back to top

ITK_GetIndIPC
Syntax:	ipcChannel := ITK_GetIndIPC (index)
Description:	Returns the nth IPC channel.
Note:	This routine has been introduced in version 2.0.3 of Internet ToolKit. It is not available in previous versions.
Params:	In/Out Parameter Type     Example or note -> index Longint IPC Channel index Must be between 1 and ITK_CountIPC <- ipcChannel Longint IPC Channel number
Example:	` Total number of messages in IPC channels $nbMsg := 0 For ($i;1;ITK_CountIPC) $nbMsg := $nbMsg + ITK_NbIPCMsg(ITK_GetIndIPC($i)) End For

Back to top

ITK_PictSize
Syntax:	pictSize := ITK_PictSize (pict; top; left; bottom; right; type)
Description:	This routines extracts size informations from a given picture.
Params:	In/Out Parameter Type     Example or note -> pict Picture         -> top Longint Top coordinates of the picture     -> left Longint Left coordinate of the picture     -> bottom Longint Bottom coordinate of the picture     -> right Longint Right coordinate of the picture     -> type Longint type of picture 0 = Mac style PICT 1 = GIF image 2 = JPEG/JFIF image 3 = Mac PICT containing JPEG data (since ITK v2.0.3) <- pictSize Longint Size (in bytes) of the picture For Mac PICT containing JPEG data, this size correspond to the JPEG data size, not the full PICT size.
Example:	$size := ITK_PictSize($pict;$top;$left;$bottom;$right;$type) $height := $bottom-$top $width := $right-$left

Back to top

ITK_PictSave
Syntax:	error := ITK_PictSave (pict; filePath; startOffset; endOffset; options)
Description:	Saves the content of a picture field or variable into a file. If the picture is encoded in the GIF format, a standard GIF file will be saved. If the picture contains a JPEG portion, this portion will be save as a JPEG/JFIF file. Otherwise, the picture will be saved as a standard Picture (PICT). If startOffset and/or endOffset and not zero, only the corresponding portion of the picture filed will be saved. Options can be used to require ITK_PictSave to add the 512 bytes header required by the standard PICT file format.
Params:	In/Out Parameter Type     Example or note -> pict Picture Picture field or variable to save     -> filePath String File pathname     -> startOffset Longint Starting offset of data to save 0 = save from the beginning of the pict -> endOffset Longint End offset of data to save 0 = save up to the end of the pict -> options Longint     0 = default behaviour 1 = add 512 bytes header. (introduced in v2.0.4) <- error Longint OS Error code
Example:	$err := ITK_PictSave($pict;"MyHD:MyFolder:MyPict")

Back to top

ITK_PictRead
Syntax:	pict := ITK_PictRead (filePath; startOffset; endOffset; options)
Description:	Reads a picture file (PICT, GIF or JFIF/JPEG) and returns it as a 4D pict.
Params:	In/Out Parameter Type     Example or note -> filePath String Filepath of the Picture file to read     -> startOffset Longint Starting offset Leave 0 to start reading at the beginning of the file. -> endOffset Longint End offset Leave 0 to read up to the end of the file. -> options Longint     0 = default behaviour 1 = remove the 512 header bytes in PICT files. (introduced in v2.0.4) <- pict Picture Picture read from file. If an error occured, this picture will have its size set to 0.
Example:	$pict := ITK_PictRead("MyHD:MyFolder:MyPict") $err := ITK_TCPSendPict($stream; $pict)

Back to top

ITK_ICMPEcho
Syntax:	time := ITK_ICMPEcho (IPaddr; timeout; size)
Description:	This routines sends an "ICMP Echo" packet to the remote IP address and measures the time needed for the echo to come back. It is an equivallent to the famous "ping" function.
Note:	Under Windows, this routine can only be used if 4D is running with administrative rights (this is due to a Winsock limitation).
Params:	In/Out Parameter Type     Example or note -> IPaddr Longint Remote host IP address As returned by ITK_Name2Addr. -> timeout Longint Timeout in seconds     -> size Longint Size of the ICMP Echo packet to send. 0 will use a default size of 64 bytes. <- result Longint Measured time in milliseconds Negative values indicate that an error occured.
Example:	$pingtime := ITK_ICMPEcho(ITK_Name2Addr("www.e-node.net");2000;64)

Back to top

$file := ITK_OpenFile("C:\MyFile.TXT")
If ($file#0)
  RECEIVE PACKET($file;$data;32000)
  ...
  CLOSE DOCUMENT($file)
End If

$err := ITK_SetPriority(64) ` go in Idle mode

` Set 4D's at least in "normal" priority
If (ITK_GetPriority=64)
  $err := ITK_SetPriority(32)
End If

All ITK blob related routines are also available in "pre-v6" version of 4D. In that case, blobs are in fact picture fields or variables which will act the same as blobs.

ITK_Pict2Blob
Syntax:	blob := ITK_Pict2Blob (pict; option)
Description:	Converts a picture value (variable or field) into a blob.
Note:	The content in not changed by this routine which simply does some typecasting.
Params:	In/Out Parameter Type     Example or note -> pict Picture picture to convert     -> option Longint option to indicate if a copy of the blob is requested 0 = a copy of the original pict is returned 1= the original picture is returned and emptied This parameter has been introduced in version 2.0.2 of Internet ToolKit. <- blob Blob typecasted blob
Example:	$myBlob := ITK_Pict2Blob($myPict) ` return a copy (uses more memory) $myBlob := ITK_Pict2Blob($myPict;1) ` "transfers" the pict into a blob, the original pict is emptied

Back to top

$myPict := ITK_Blob2Pict($myBlob) ` return a copy (uses more memory)
$myPict := ITK_Blob2Pict ($myBlob;1) ` "transfers" the blob into a pict, the original blob is emptied

ITK_BlobSave
Syntax:	error := ITK_BlobSave (blob; filePath; startOffset; endOffset; fileStart)
Description:	Saves the content of a blob into a file. If startOffset and/or endOffset and not zero, only the corresponding portion of the blob will be saved. FileStart allows to save the blob at a given position in an existing file instead of storing the blob at the beginning of the file.
Params:	In/Out Parameter Type     Example or note -> blob Blob Blob field or variable to save     -> filePath String File pathname     -> startOffset Longint Starting offset of data to save 0 = save from the beginning of the pict -> endOffset Longint End offset of data to save 0 = save up to the end of the pict -> fileStart Longint File offset where to start storing the blob 0 = store at the beginning of the file 1..n = store at file start + 1..n bytes. <- error Longint OS Error code
Example:	$err := ITK_BlobSave($blob;"MyHD:MyFolder:MyPict") ` same as BLOB TO DOCUMENT $err := ITK_BlobSave($blob;"MyHD:MyFolder:MyPict";1;10) ` saves a portion of the blob

Back to top

ITK_BlobRead
Syntax:	blob := ITK_BlobRead (filePath; startOffset; endOffset)
Description:	Reads a file or a part of it and returns it a blob.
Params:	In/Out Parameter Type     Example or note -> filePath String Filepath of the file to read     -> startOffset Longint Starting offset Leave 0 to start reading at the beginning of the file. -> endOffset Longint End offset Leave 0 to read up to the end of the file. <- blob Blob Blob read from the file If an error occured while accessing, the blob will have its size set to 0.
Example:	$pict := ITK_BlobRead("MyHD:MyFolder:MyPict") ` same as DOCUMENT TO BLOB $pict := ITK_BlobRead("MyHD:MyFolder:MyPict";1;10) ` read only a portion of the file

Back to top

GOTO SELECTED RECORD([File1];1)
$err:=ITK_Blob2Record($blob;Table(->[File1])
...

CREATE RECORD([File1])
$err:=ITK_Blob2Record($blob;Table(->[File1])
SAVE RECORD([File1])

TEXT TO BLOB("Test text";$b;3)
$p := ITK_BlobSearch($b;0;"text") ` returns 5
         
` count occurences
$nb := BLOB size($b) ` max number of occurences to count (up to size of blob)
$p := ITK_blobSearch($b;0;"e";$nb) ` $p returns 6, $nb returns 2 (2 "e" found" in blob)

TEXT TO BLOB("Test text";$b;3)
$p := ITK_BlobReplace($b;0;"te";"Te") ` $p returns 5, blob now contains "Test Text"

$err := ITK_Blobgzip(myBlob;9) ` use best compression

$err := ITK_Blobgunzip(myBlob) ` decompress the blob