Skip to main content

%SYSTEM.IS

Class %SYSTEM.IS Extends %SYSTEM.Help [ System = 4 ]

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 %SYSTEM.OS.

Methods​

Receive​

ClassMethod Receive(to As %Integer) As %String

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​

ClassMethod ReceiveReply(to As %Integer) As %String

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)

Execute​

ClassMethod Execute(loop As %Boolean, msgid As %Integer, contxt As %Integer, code As %Integer, to As %Integer) As %Integer

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

DefaultTimeout​

ClassMethod DefaultTimeout(to As %Integer) As %Integer

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 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

Clear​

ClassMethod Clear() As %Integer

Remove any data remaining in the input stream buffer.

Return: 0