IS Class Reference

Input Stream

This class contains methods to receive items framed in $LIST format from a TCP stream. More...

Inheritance diagram for IS:

Collaboration diagram for IS:

Static Public Member Functions
_.Library.Integer	Clear ()
	Input Stream This class contains methods to receive items framed in $LIST format from a TCP stream. More...
_.Library.Integer	DefaultTimeout (_.Library.Integer to)
	Get and optionally set the default timeout for the input stream methods. More...
_.Library.Integer	Execute (_.Library.Boolean loop, _.Library.Integer msgid, _.Library.Integer contxt, _.Library.Integer code, _.Library.Integer to)
	Execute a client request. More...
_.Library.String	Receive (_.Library.Integer to)
	Read a single $LIST() item from the input stream. More...
_.Library.String	ReceiveReply (_.Library.Integer to)
	Read a new message from the input stream and return its header as a $LB(type,msgid,contxt,code). More...
Static Public Member Functions inherited from Help
_.Library.String	Help (_.Library.String method)
	This is a helper class that is used by the various SYSTEM classes to provide a Help method. More...

Detailed Description

Input Stream

This class contains methods to receive items framed in $LIST format from a TCP stream.

It is part of the InterSystems IRIS Native API. The other endpoint is usually a client written in a language other than ObjectScript. For clients in ObjectScript see <class>SYSTEM.OS</class>.

Member Function Documentation

Clear()

_.Library.Integer Clear ( )

static

Input Stream

This class contains methods to receive items framed in $LIST format from a TCP stream.

It is part of the InterSystems IRIS Native API. The other endpoint is usually a client written in a language other than ObjectScript. For clients in ObjectScript see <class>SYSTEM.OS</class>.

Remove any data remaining in the input stream buffer.

Return: 0

DefaultTimeout()

_.Library.Integer DefaultTimeout ( _.Library.Integer  to )

static

Get and optionally set the default timeout for the input stream methods.

All input methods (IS.Receive(), IS.ReceiveReply() and IS.Execute()) are subject to a timeout. If no data arrives within the established period, the method throws a <TIMEOUT> error. The timeout value can be passed as the last argument to these methods but, if omitted, a default value is used. Timeouts are expressed in seconds and -1 means infinite timeout (no timeout).

Parameter:
to - Optional - New timeout in seconds (default = 300).

Return:

• Current timeout if no argument was passed
• Previous timeout if a new value was passed

Execute()

_.Library.Integer Execute ( _.Library.Boolean  loop, _.Library.Integer  msgid, _.Library.Integer  contxt, _.Library.Integer  code, _.Library.Integer  to  )

static

Execute a client request.

Parameters:
loop

• True: execute requests until a STOP command is received
• False: execute one request and return

msgid - Optional - Message id (val1 in header).
contxt - Optional - Context (val2 in header).
code - Optional - Op code or reply code.
to - to - Optional - Timeout in seconds.

Return:

• 0 - Single opcode was executed
• -1 - STOP opcode was received
• $LB(type, msgid, contxt, code) - this code is not handled by the kernel

Receive()

_.Library.String Receive ( _.Library.Integer  to )

static

Read a single $LIST() item from the input stream.

Consumes a framed item from the input stream and returns the corresponding ObjectScript data value. If there are not enough bytes to form a complete item, the method will wait until the device driver produces the necessary number of bytes. A timeout argument is optional and if present overrides the default timeout. See the Timeout() method below for details.

Parameter:
to - Optional - New timeout in seconds (default = 300).

Return: the value read from the stream.

ReceiveReply()

_.Library.String ReceiveReply ( _.Library.Integer  to )

static

Read a new message from the input stream and return its header as a $LB(type,msgid,contxt,code).

Retrieve the msgid, the contxt and the code from the input stream. In most situations the msgid and the contxt will be the same as the ones sent with a SendRequest(msgid,...) and the code will be an error code for that operation.

Depending on the opcode that was requested, one of more response items can be available in the input stream. These can be read with further calls to Receive(). In less common situations, msgid will be a new identifier sent by the other end as the beginning of a new (reentrant) request. In this case the code will be the corresponding opcode.

The type is a small integer that quickly characterizes the header. Strictly speaking this information is not necessary because just by looking at the integer value of the code one can determine the type of the message. But the 'type' field is included as a convenience. Besides, depending on the type, the code field has been changed to be in a more suitable format:

type:

• = 0 -> Return code (number starting from 0)
• = 1 -> Native DB request code (number starting from 0)
• = 2 -> DBSRV code (2-character string)

Normally, following a SendRequest() you will get a header with a return code (type = 0), but the format is more generic and also used by Execute(). A timeout argument is optional and if present overrides the default timeout. See the Timeout section below for details.

Parameter:
to - Optional - New timeout in seconds (default = 300).

Return:The header of the message as $LB(type,msgid,contxt,code)