dt_converse

Daylight v4.9
Release Date: 1 February 2008

Name

dt_converse - communicate with a program object

Generic Prototype

dt_converse(dt_Handle, dt_Handle) => dt_Handle

C Prototype

#include "dt_progob.h"

dt_Handle dt_converse(dt_Handle program, dt_Handle sendmessage)

FORTRAN Prototype

include 'dt_f_progob.inc'

integer*4 dt_f_converse(program, sendmessage)

integer*4 program
integer*4 sendmessage

Description

Send strings in 'sendmessage' to the program, and assembles the program's response into a sequence of string objects.

The parameter 'sendmessage' may be any object that responds to dt_stringvalue(3), or may be a sequence or stream of one or more such objects, or may be NULL_OB. The stringvalue or values are sent to the program, each separated by a newline. If an object returns the invalid string, an empty (zero-length) string is sent instead.

If 'sendmessage' is NULL_OB, a special message is sent to the program telling it to quit, possibly sending a final message back prior to quitting. The "normal" way to end a program is to send it a NULL_OB message, examine the closing message it returns (if any), then deallocate the object itself. Once NULL_OB has been sent, and the program's closing message has been received, no further communication with the program is possible.

There are two different types of return values, depending on the "delimiter" specified (see dt_delimiter(3) and dt_setdelimiter(3)). If the delimiter is DX_PT_NONE, then the returned object is a newly-allocated string object that contains the program object's entire response, including all newline characters.

If the delimiter is DX_PT_CR, then the returned object is a newly-allocated sequence of string objects. Each string object contains one line of the program's reply (where lines are separated by the newline character). The sequence and strings returned by this function becomes "owned" by the function that calls this function; the sequence and its contents must eventually be deallocated via calls to dt_dealloc(3).

If, during the course of "conversing" with a program, the program should "crash" or otherwise cease running, this function will return NULL_OB. The program object itself is not deallocated when this happens, but any further attempts to communicate with it will fail, and will cause error messages to be put in the error queue (see dt_errors(3)).

Return Value