|
ITK Programmer's Guide |
||||||||
Table of contents
|
Intro
|
General
|
TCP Low Level
|
TCP High Level
|
UDP
|
DNS
|
PPP
|
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: |
|
||||||||||
Example: |
$timer := ITK_TimerStart ... $elapsedTime := ITK_TimerStop($timer) |
ITK_TimerLap |
||||||||||||||||
|
|
|||||||||||||||
Syntax: |
lapTime := ITK_TimerLap (timerRef)
|
|||||||||||||||
Description: |
Returns the number of milliseconds since ITK_TimerStart was called without stopping the timer.
|
|||||||||||||||
Params: |
|
|||||||||||||||
Example: |
$timer := ITK_TimerStart ... $lapTime1 := ITK_TimerLap($timer) ... $lapTime2 := ITK_TimerLap($timer) ... $totalTime := ITK_TimerStop($timer) |
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: |
|
|||||||||||||||
Example: |
$timer := ITK_TimerStart ... $totalTime := ITK_TimerStop($timer) |
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.
|
|||||||||||||||
Params: |
|
|||||||||||||||
Example: |
While (ITK_NbIPCMsg(1)>0) ` process IPC messages ... End While |
ITK_SendIPCMsg |
||||||||||||||||
|
|
|||||||||||||||
Syntax: |
ITK_SendIPCMsg (ipcChannel;message)
|
|||||||||||||||
Description: |
Sends a message on the specified IPC channel.
|
|||||||||||||||
Note: |
IPC channel number are used to create as many IPC channels as you need.
|
|||||||||||||||
Params: |
|
|||||||||||||||
Example: |
ITK_SendIPCMsg(1;"quit") |
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.
|
||||||||||||||||||||
Note: |
IPC channel number are used to create as many IPC channels as you need.
|
||||||||||||||||||||
Params: |
|
||||||||||||||||||||
Example: |
$msg := ITK_RcvIPCMsg(1;0) If ($msg = "quit") QUIT 4D End If |
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.
|
||||||||||
Params: |
|
||||||||||
Example: |
ITK_ResetIPCMsg(1) |
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: |
|
||||||||||
Example: |
` Total number of messages in IPC channels $nbMsg := 0 For ($i;1;ITK_CountIPC) $nbMsg := $nbMsg + ITK_NbIPCMsg(ITK_GetIndIPC($i)) End For |
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: |
|
|||||||||||||||
Example: |
` Total number of messages in IPC channels $nbMsg := 0 For ($i;1;ITK_CountIPC) $nbMsg := $nbMsg + ITK_NbIPCMsg(ITK_GetIndIPC($i)) End For |
ITK_PictSize |
|||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||
Syntax: |
pictSize := ITK_PictSize (pict; top; left; bottom; right; type)
|
||||||||||||||||||||||||||||||||||||||||
Description: |
This routines extracts size informations from a given picture.
|
||||||||||||||||||||||||||||||||||||||||
Params: |
|
||||||||||||||||||||||||||||||||||||||||
Example: |
$size := ITK_PictSize($pict;$top;$left;$bottom;$right;$type) $height := $bottom-$top $width := $right-$left |
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: |
|
|||||||||||||||||||||||||||||||||||
Example: |
$err := ITK_PictSave($pict;"MyHD:MyFolder:MyPict") |
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: |
|
||||||||||||||||||||||||||||||
Example: |
$pict := ITK_PictRead("MyHD:MyFolder:MyPict") $err := ITK_TCPSendPict($stream; $pict) |
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: |
|
|||||||||||||||||||||||||
Example: |
$pingtime := ITK_ICMPEcho(ITK_Name2Addr("www.internet-toolkit.com");2000;64) |
ITK_OpenFile |
||||||||||||||||
|
|
|||||||||||||||
Syntax: |
fileRef := ITK_OpenFile (pathname)
|
|||||||||||||||
Description: |
Opens a file in read-only mode.
|
|||||||||||||||
Note: |
The variable used to store the fileRef value must be types as C_TIME when compiled.
|
|||||||||||||||
Params: |
|
|||||||||||||||
Example: |
$file := ITK_OpenFile("C:\MyFile.TXT") If ($file#0) RECEIVE PACKET($file;$data;32000) ... CLOSE DOCUMENT($file) End If |
ITK_SetPriority |
||||||||||||||||
|
|
|||||||||||||||
Syntax: |
error := ITK_SetPriority (newPriority)
|
|||||||||||||||
Description: |
Changes 4D's priority level in Windows multitasking.
|
|||||||||||||||
Note: |
This routines currently does nothing under MacOS.
|
|||||||||||||||
Params: |
|
|||||||||||||||
Example: |
$err := ITK_SetPriority(64) ` go in Idle mode |
ITK_GetPriority |
|||||||||||
|
|
||||||||||
Syntax: |
priority := ITK_GetPriority
|
||||||||||
Description: |
Retrieves 4D's priority level in Windows multitasking.
|
||||||||||
Note: |
This routines currently does nothing under MacOS.
|
||||||||||
Params: |
|
||||||||||
Example: |
` 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: |
|
||||||||||||||||||||
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 |
ITK_Blob2Pict |
|||||||||||||||||||||
|
|
||||||||||||||||||||
Syntax: |
pict := ITK_Blob2Pict (blob; option) |
||||||||||||||||||||
Description: |
Converts a blob value (variable or field) into a picture. |
||||||||||||||||||||
Note: |
The content in not changed by this routine which simply does some typecasting.
|
||||||||||||||||||||
Params: |
|
||||||||||||||||||||
Example: |
$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: |
|
|||||||||||||||||||||||||||||||||||
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 |
ITK_BlobRead |
||||||||||||||||||||||||||
|
|
|||||||||||||||||||||||||
Syntax: |
blob := ITK_BlobRead (filePath; startOffset; endOffset)
|
|||||||||||||||||||||||||
Description: |
Reads a file or a part of it and returns it a blob.
|
|||||||||||||||||||||||||
Params: |
|
|||||||||||||||||||||||||
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 |
ITK_Record2Blob |
|||||||||||||||||||||
|
|
||||||||||||||||||||
Syntax: |
error := ITK_Record2Blob (tableNum; blob)
|
||||||||||||||||||||
Description: |
Convert the current record of the table specified into a blob.
|
||||||||||||||||||||
Note: |
It is not guaranteed that the same format is used to encode records by all version of 4D (past, current and futures).
|
||||||||||||||||||||
Params: |
|
||||||||||||||||||||
Example: |
GOTO SELECTED RECORD([File1];1) $err:=ITK_Blob2Record($blob;Table(->[File1]) ... |
ITK_Blob2Record |
|||||||||||||||||||||
|
|
||||||||||||||||||||
Syntax: |
err := ITK_Blob2Record (blob; tableNumber) |
||||||||||||||||||||
Description: |
Converts a blob containing a record obtained by ITK_Record2Blob back into a 4D record (in the current selected record). |
||||||||||||||||||||
Note: |
It is not guaranteed that the same format is used to encode records by all version of 4D (past, current and futures).
|
||||||||||||||||||||
Params: |
|
||||||||||||||||||||
Example: |
CREATE RECORD([File1]) $err:=ITK_Blob2Record($blob;Table(->[File1]) SAVE RECORD([File1]) |
ITK_BlobSearch |
|||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
Syntax: |
pos := ITK_BlobSearch (blob;offset;text;nbOcc)
|
||||||||||||||||||||||||||||||
Description: |
Search some text in a blob from a given position, and returns the position of the nth occurence of that text. ITK_BlobSearch can also be used to count the number of occurence of a given text into a blob (see example).
|
||||||||||||||||||||||||||||||
Note: |
Text matching is byte based. This means that "E" and "e" and "é" are different.
|
||||||||||||||||||||||||||||||
Params: |
|
||||||||||||||||||||||||||||||
Example: |
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) |
ITK_BlobReplace |
||||||||||||||||||||||||||||||||||||
|
|
|||||||||||||||||||||||||||||||||||
Syntax: |
err := ITK_BlobReplace (blob; offset; oldText; newText; nbOcc) |
|||||||||||||||||||||||||||||||||||
Description: |
Search some text in a blob from a given position (offsett), and replace it with the new text specified. nbOcc can be used to repeat this search/replace several times.
|
|||||||||||||||||||||||||||||||||||
Note: |
It is not guaranteed that the same format is used to encode records by all version of 4D (past, current and futures).
|
|||||||||||||||||||||||||||||||||||
Params: |
|
|||||||||||||||||||||||||||||||||||
Example: |
TEXT TO BLOB("Test text";$b;3) $p := ITK_BlobReplace($b;0;"te";"Te") ` $p returns 5, blob now contains "Test Text" |
ITK_Blobgzip |
|||||||||||||||||||||
|
|
||||||||||||||||||||
Syntax: |
err := ITK_Blobgzip (blob;compLevel)
|
||||||||||||||||||||
Description: |
Compresses a blob using the gzip compression algorithm.
|
||||||||||||||||||||
Note: |
The blob content has the same format as a gzip compressed file.
|
||||||||||||||||||||
Params: |
|
||||||||||||||||||||
Example: |
$err := ITK_Blobgzip(myBlob;9) ` use best compression |
ITK_Blobgunzip |
|||||||||||||||||||||
|
|
||||||||||||||||||||
Syntax: |
err := ITK_Blobgunzip (blob; originalSize) |
||||||||||||||||||||
Description: |
Decompresses a blob compressed using ITK_Blobgzip . originalSize can help ITK determine how large the decompressed blob will be.
|
||||||||||||||||||||
Note: |
The compression algorithm is not compatible with 4D's builtin COMPRESS BLOB command.
|
||||||||||||||||||||
Params: |
|
||||||||||||||||||||
Example: |
$err := ITK_Blobgunzip(myBlob) ` decompress the blob |