:НAhgInєИHHBџќџїEKg{рHHи(dh ŽПќџџ#Ъќџџ$ŽПќџџ#Ъќџџ$$Normalџџџџј џоџџџџџџџџ< ШB6666$$№LраO2Z–JVV™›VЃXЃXЃXЃXЃXЃXЃX $ Ѕ SOCKIT џџџџџџџџџџџџџџTThe SOCKIT XOP adds the following TCP/IP external functions and operations to IGOR.  ЅHSOCKITopenconnection [/NOID /LOG=pathToLogFile /Q[=quiet] /TOK="TokenizerStr" /PROC=processorFunction /TIME=timeoutsecs ] socketID,hostnameStr,portNumber,bufferWave џџџџџџџџџџџџ>џџџџџџNџџџџџџ< The SOCKITopenconnection opens a TCP/IP network connection. џџџџџџFlags c$/Q[=quiet] the received messages from the socket connection are not printed to the history window. џџџџџџ џџџџџџџџ  optional: ( quiet = 0 - same as /Q, no printing. $ quiet = 1 - printing is allowed.  (/LOG=pathToLogFile pathToLogFile is an IGOR symbolic path. If this flag is specified all incoming and outgoing messages are saved in an XML logfile in this directory. This logfile is kept in memory so should only be used for debugging purposes, otherwise the file may become large very quickly.  а/NOID the XOP does not process incoming messages for the sockID socket if this flag is present. In this case the processor function is ignored, and incoming messages are not placed into the buffer wave. In order to receive messages for sockID you will need to use the (Threadsafe) SOCKITpeek function. Warning: If you do not call SOCKITpeek repeatedly (CtrlNamedBackground, or a preemptive thread) then IGOR's memory usage will increase as the messages backup. 9џџџџџџ@џџџџџџџџэџџџџџџєџџџџџџџџџџџџџџ&џџџџџџџџ1џџџџџџ:џџџџџџџџ $/TOK=tokenizerStr The received messages are tokenized by the characters in tokenizerStr. Successive tokens are stored independently in the bufferWave, and are handled separately by the processorFunction. e.g. /TOK=" \r\n" will separate new lines, carriage returns and whitespace. LџџџџџџXџџџџџџџџ /PROC=processorFunction H is the name of a user procedure or XOP that is called when an entry is made into bufferWave. This allows one to respond to each server event with an appropriate response. Each open socket can have its own processor function. One example could be to parse the response into a new IGOR command, which is then executed. The function should not be calculation intensive as the function will be called whenever a message is received from a socket. This could cause IGOR to slow down significantly. An example of the processor function is given below. The processor function may be specified at a later stage using the SOCKITregisterProcessor function. Rџџџџџџ\џџџџџџџџkџџџџџџ‚џџџџџџџџ }/TIME=timeoutsecs The operation will wait for a maximum of timeoutsecs before deciding that the connection cannot be opened.  Main keywords  $*sockitID - A user defined variable or NVAR that is used to refer to the open connection. If the connection fails to initialise then sockitID will set to -1. џџџџџџ џџџџџџџџ k(hostnameStr - the name of the host you are trying to connect to, e.g. "www.wavemetrics.com", "127.0.0.1"  FportNumber - the portNumber you are trying to connect to on the host.  џџџџџџџ~(bufferWave - the name of a user-supplied text wave. This text wave is redimensioned to a two column, multi row wave. When messages are received from the server they are first tokenized, using the token delimeters in tokenizerStr, then placed into the first column of bufferWave. Each token occupies successive rows. The second column contains a timestamp for when the corresponding message entry was made into bufferWave. The user defined processorFunction is called as each entry is made into bufferWave. кџџџџџџцџџџџџџџџ џџџџџџџџџџџџџџžџџџџџџЋџџџџџџџџѓџџџџџџ Variables S8The SOCKITopenconnection operation returns information in the following variables: V(V_flag V_flag is set to 0 if the connection succeeded, to 1 if the connection failed. q(sockitID sockitID is set to a number greater than 0 if the connection succeeded, to -1 if the connection failed. 0 Other details ‰0A reasonable number of sockets can be open concurrently (e.g. <100). The SOCKIT XOP checks for new messages for all connections in IGORs IDLE loop. Therefore, if IGOR is busy doing a time-intensive calculation, then you won't receive messages until the calculation has finished that has finished. Multiple sockets may use the same bufferwave, but only one bufferwave per socket is allowed. в$2If the /NOID flag is specifed then incoming messages will not be automatically dealt with. Your own code is responsible for processing incoming messages. To acquire the messages you regularly have to call the SOCKITpeek function for a given socket. You are then responsible for tokenizing, storing and processing the data as the bufferwave is not used, nor is the processor function used. These methods allow you to acquire messages in a dedicated IGOR thread. вџџџџџџмџџџџџџџџН2The processor function allows one to respond to each server event with an appropriate response. Each open socket can have its own processor function. It must have the following signature: 0 )4Function myProcessorFunc(textWave,entry) <6wave/t textWave //a reference to the bufferwave of interest C6variable entry //which row has just been filled in the bufferwave. 4 6//do something here 4print textWave[entry][0] )6print " received at"+ textWave[entry][1] 4End 4 Example 6variable sockNum = 0 4make/t bufferwave V4sockitopenconnection/proc=myprocessorFunc sockNum,"www.wavemetrics.com",80,bufferwave 4//now get the webpage #6sockitsendmsg sockNum,"GET / \r\n" 4 <SOCKITopenconnectionF(hostnameStr, portNumber, timeoutsecs) џџџџџџ‡6 The SOCKITopenconnectionF function opens a TCP/IP network connection in a threadsafe manner. If you are not working in a threadsafe function it is usually better to use the SOCKITopenconnection operation, as this will allow you to specify more options (bufferwaves for incoming messages, tokenizers for splitting messages and processor functions for dealing with incoming messages, etc). џџџџџџЎџџџџџџТџџџџџџЊ6If you open a socket with this function your code is responsible for downloading messages using the SOCKITpeek function, as well as their processing (tokenization, etc). џџџџџџdџџџџџџnџџџџџџ k(hostnameStr - the name of the host you are trying to connect to, e.g. "www.wavemetrics.com", "127.0.0.1"  FportNumber - the portNumber you are trying to connect to on the host.  џџџџџџ timeoutsecs - The function will wait for a maximum of timeoutsecs before deciding that the connection cannot be opened. 0 „0The function returns the reference number of the socket opened, which is used to refer to the socket in other operations/functions. 4 (Threadsafe) Example  6variable sockNum = 0 4 B4//since this may be in a thread use all the threadsafe functions. ;6sockNum=sockitopenconnectionF("www.wavemetrics.com",80,10) 4 4//send the message &4sockitsendmsgF(sockNum, "GET / \r\n") 6 4//get the reply 4print sockitpeek(sockNum) 4 E6//the connection will already be closed, since it is an HTTP request 6//but lets make sure. 6sockitcloseconnection(sockNum) 6 6 SOCKITcloseconnection(socketID) џџџџџџЉl2Closes an open connection, referred to by socketID, that is currently open. If socketID =-1 then all open connections are closed. The function returns 0 if successful. *џџџџџџ2џџџџџџџџKџџџџџџLџџџџџџџџOџџџџџџXџџџџџџџџ2 SOCKITpeek(socketID) џџџџџџч$0Returns incoming messages queued from socketID. The messages are returned as a string. You are then responsible for doing message processing as the messages are not placed in the bufferwave, nor is the processor function called. &џџџџџџ.џџџџџџџџЖl2This function is threadsafe and can be used in conjunction with the /NOID flag of SOCKITopenconnection or the SOCKITopenconnectionF function to provide a threadsafe socket communication protocol. If /NOID is specified for that operation or the socket was opened with SOCKITopenconnectionF then SOCKITpeek must be called frequently (CtrlNamedBackground, or a preemptive thread) to prevent messages backing up and causing memory problems. Rџџџџџџgџџџџџџџџnџџџџџџƒџџџџџџџџ џџџџџџ!џџџџџџџџ6 SOCKITisitopen(socketID) џџџџџџy$0returns 1 if there is an open connection, referred to by sockitID, or 0 if there is no socket open with that descriptor. 9џџџџџџAџџџџџџџџ6 0SOCKITregisterProcessor(socketID, processorStr) џџџџџџЈl2processorStr is the name of a user procedure or XOP that is called when a message is received on a socket with a descriptor = socketID. This allows one to respond to each server event with an appropriate response. Each open socket can have its own processor function. To deregister a socket then one passes a null string to this function, i.e. processorStr = "". The function returns 0 if registration is successful. џџџџџџ џџџџџџџџ~џџџџџџ†џџџџџџџџ[џџџџџџgџџџџџџџџЉ0The processor function is NOT called if one uses the SOCKITsendnrecv and SOCKITsendnrecvF operation/function, or if the /NOID flag is specified in SOCKITopenconnection. 0It is a good idea for this function to be an independently compilable module, which wil ensure it's availability when a message is received. €0One example could be to parse the response into a new IGOR command, which is then executed. This procedure should not be calculation intensive as the function will be called whenever a message is received from a socket. This could cause IGOR to slow down significantly. An example of the processor function is given below. Note that the arguments for the function must be the same: 0 )4Function myProcessorFunc(textWave,entry) <6wave/t textWave //a reference to the bufferwave of interest C6variable entry //which row has just been filled in the bufferwave. 4 6//do something here 4print textWave[entry][0] )6print " received at"+ textWave[entry][1] 4End  !$SOCKITsendmsgF(socketID, msgStr) џџџџџџџџџџџџЬA threadsafe function that can be used to send an asynchronous message to a TCP/IP network socket. Returns 0 if successful, 1 if unsuccessful. Useful for socket communication in a threaded environment. џџџџџџ џџџџџџ6$SOCKITsendnrecvF(socketID, msgStr, smallVal, timeVal) џџџџџџџџџџџџгlA threadsafe function that can be used for synchronous communication with a TCP/IP network socket. Useful for socket communication in a threaded environment. The message string, msgStr, is sent to socketID. џџџџџџДџџџџџџКџџџџџџџџЛџџџџџџЧџџџџџџЯџџџџџџџџG$The send will wait for a maximum of timeVal seconds before timing out. $џџџџџџ+џџџџџџџџ4lIf a small reply is expected (<4096 characters) then only a single read of the socket is carried out by the function if smallVal=1. In otherwords the read will still wait for a maximum of timeVal seconds, but it won't wait to see if there is going to be more to come. To get a larger reply set smallVal=0. xџџџџџџ€џџџџџџџџНџџџџџџФџџџџџџџџ(џџџџџџ0џџџџџџџџThe message sent by the other end will be returned as a string. Please note that the message received is NOT processed by the processor function for that socket, NOR is it placed in the bufferwave. You are responsible for tokenizing the reply and processing any messages.  џџџџџџ3$SOCKITsendmsg [/TIME=timeoutsecs] socketID, msgStr џџџџџџџџџџџџOan operation that sends a message asynchronously with a TCP/IP network socket. џџџџџџFlags m/TIME=timeoutsecs - the operation will wait for a maximum of timeoutsecs for the write operation to proceed. џџџџџџMain keywords [$*sockitID - A user defined variable or NVAR that is used to refer to the open connection. џџџџџџ џџџџџџџџ `l(msgStr - the message you are trying to send to socketID. (msgStr is limited to 4096 characters) џџџџџџ/џџџџџџ7џџџџџџ:џџџџџџ@џџџџџџAџџџџџџџџ џџџџџџVariables and Strings N8The SOCKITsendnrecv operation returns information in the following variables: a(V_flag V_flag is set to 0 if the message was sent successfully, or to 1 if the operation failed.  џџџџџџOther details ц$This operation returns as soon as the data is sent, it doesn't wait for any incoming messages on socketID, i.e. asynchronous communication. Incoming messages are received by the XOP in IGOR's IDLE loop. If one is performing intensive calculation at that time, then messages won't be received until the SOCKIT XOP receives IDLE time. When incoming messages are eventually received the output is placed into the bufferwave associated with the socket, calling any associated Processors. aџџџџџџiџџџџџџџџA For synchronous communication use the SOCKITsendnrecv operation. Example 6variable sockNum = 0 4make/t bufferwave V4sockitopenconnection/proc=myprocessorFunc sockNum,"www.wavemetrics.com",80,bufferwave 4//now get the webpage *6sockitsendmsg/TIME=2 sockNum,"GET / \r\n" 4print bufferwave[inf][0]  џџџџџџU~SOCKITsendnrecv [/FILE=filenameStr/TIME=timeout /SMAL] socketID, msgStr [,outputStr] џџџџџџџџџџџџ"џџџџџџ(џџџџџџ1џџџџџџIџџџџџџSџџџџџџRa synchronous way of sending and receiving messages with a TCP/IP network socket. џџџџџџFlags W6/FILE=fileNameStr the received messages from the socket connection are put into a file џџџџџџџџџџџџџџџџџџџџ |Д/TIME=timeout the send will wait for a maximum of timeout seconds before timing out. To ensure that all data is received in a single call to the operation the XOP waits for a maximum of timeout seconds for successive reads from the socket. This means that although the first and subsequent reads may happen quickly, when the last data has been received there is a delay of timeout seconds before the XOP returns. The XOP will therefore take a minimum of timeout seconds. If you do not want this to happen, because the message is small, then use the /SMAL flag. If the /TIME flag is not specified then timeout defaults to 1 second. 2џџџџџџ9џџџџџџџџЛџџџџџџТџџџџџџџџwџџџџџџ~џџџџџџџџЩџџџџџџаџџџџџџџџ^џџџџџџeџџџџџџџџў$/SMAL If a small reply is expected (<4096 characters) then only a single read of the socket is carried out by the operation. i.e. the read will still wait for a maximum of timeout seconds, but it won't wait to see if there is going to be more to come. ­џџџџџџДџџџџџџџџ Main keywords [$*sockitID - A user defined variable or NVAR that is used to refer to the open connection. џџџџџџ џџџџџџџџ `l(msgStr - the message you are trying to send to socketID. (msgStr is limited to 4096 characters) џџџџџџ/џџџџџџ7џџџџџџ:џџџџџџ@џџџџџџAџџџџџџџџ Al*outputStr - if the optional outputStr is specified then the returned message from the server is put into this string. It must be a local string variable or SVAR. Using outputStr is the only way to ensure that incoming binary data is handled properly. Whilst S_tcp is always created it doesn't handle binary data well. џџџџџџ џџџџџџџџџџџџџџ&џџџџџџџџЋџџџџџџДџџџџџџџџ џџџџџџVariables and Strings N8The SOCKITsendnrecv operation returns information in the following variables: n(V_flag V_flag is set to 0 if the message was sent and received successfully, or to 1 if the operation failed. €H*S_tcp This string contains the message that was received from socketID. Doesn't handle binary data properly, unlike outputStr. >џџџџџџFџџџџџџџџuџџџџџџ~џџџџџџџџ џџџџџџOther details ŽHAs well as putting the data into outputStr/S_tcp and/or a file, the output is also placed into the bufferwave associated with the socket. However, any associated Processors are NOT called. This is because the processor function could also have a SOCKITsendnrecv operation which would lead to recursion. You are responsible for tokenizing the reply and calling any processor functions yourself. !џџџџџџ*џџџџџџџџ+џџџџџџ1џџџџџџџџЊThis function differs from the normal socket communication in that the received messages are collected directly after the sent message, i.e. synchronized transmission.  Example 6variable sockNum = 0 4make/t bufferwave V4sockitopenconnection/proc=myprocessorFunc sockNum,"www.wavemetrics.com",80,bufferwave 4//now get the webpage ,6sockitsendnrecv/TIME=2 sockNum,"GET / \r\n" 4print S_tcp 4 )SOCKITstringToWave [/B] waveType, msgStr џџџџџџіconverts the data in the binary string msgStr into a numeric wave (such as when you receive an image over a socket). waveType is the type of wave to create. For more details on the types of wave available look at the builtin function Wavetype. џџџџџџ;*/B - the string is assumed to contain big endian numbers. џџџџџџ'SOCKITwaveToString /B wavename, msgStr џџџџџџМoutputs the data from the numeric wave, wavename, into the string msgStr, which will then contain binary information. Useful for sending images and numeric data over a socket connection. џџџџџџD(/B - the created string will be big endian (low endian is default). џџџџџџZŽш№ф8Dвф<Drzрш. 6 T 0 8 М Ф и ЂЊ$pŠ&€мT\pќРШј:„ŒІЦі2JІТьєH ђњltРктhpњ&BJ’дмі" * @ ` h Д а і ў !>!Z"b""Ђ#Ъ%в%&Ј&А&ј&)Т)V*м+ф+,V, ,Ј,Т,т,--$-p-T.n.Ю.0†0,2D3^3М3$404Ж4Ъ4P5X5*6D6`6Д6767J7Z9Ђ9А9Ь9ф9@:\:Œ:Ќ:Ц: ; <<Њ<В<ш?AA,AВAКAŒB”BHDbD~DвDFEF.FBFHЮHжHфHIItIIТIдIмIJ,K€KРK”LSubtopicџџHд џFunctionBody1џџТ џTopicџџ дH џTopicBodyџџ АHи џOperationBody1aџџџџА џOperationSectionџџАHи џOperationKeywords1aџџџџА џTopicBody1aџџ дHи џ Code_Indented1џџд/CWk“ЇЛЯуї 3G[oƒ—Ћ џ OperationFlags1aџџlАД џ FunctionBody1+џџ- џ Code_Indented1+ џџ-/CWk“ЇЛЯуї 3G[oƒ—Ћ џOperationKeywords1a+џџа џ кб@еxц GenevaCourierHelveticaMonacoNew YorkPalatinoTimesChicagoSymbolOsakaCourier NewMonaco CEAmerican Typewriter LightfЩ?џџџџџџџџўџўџўџџџџџџџџџЬЬkнТЂџџџџЬЬ ЬЬ џџ@@ ЬЬ ™™ ffЬЬжЃџџџџЬЬЬЬ™™уMffэ3“>џџЬЬкgлL™™€€€€€@џџ@.3ff™™џџаннннннЊЊЊЊЊЊ @@џџ!2ЬЬ"џџЊЊ#ˆˆˆˆˆˆ$ffffff%џџџПџП&џџUU'џџff(ЛЛЛЛЛЛ)џџ@Хй*``џџ+,@юnџџ-ЬЬŽˆ.џџЬЬ/™™™™™™0`ђ1ЬЬ@D23333333џџќџ@4ЬЬЩЬ5ЬЬЬЬЬЬ6]fЬЬ7™™8+gЬЬ9Tsfц:€€џџ;џџќ@<џ=wwwwww> Ѓ9fц?