Communication Interfaces

Module Version [1.01] (15-Feb-1996) Module XCX

Author:    K. Banse, ESO - Garching

Language:    C

Classification: standard interfaces, communication

Environment:

• UNIX
• #include <midas_def.h>
• #include <xconndef.h>

Comments:

This module contains the routines to open and close a connection to a background Midas as well as routines for getting the status and other info about the background Midas.
The functions provided are:

• Open a connection via ASCII files or sockets (XCZOPN, XCXOPN)
• Start a background Midas and open a connection via ASCII files or sockets (XCZINI, XCXINI)
• Close a connection (XCXCLO)
• Stop a background Midas and close the connection (XCXSTP)
• check status of background Midas (XCXSTA)
• get file descriptor of socket used in communication with background Midas (XCXGFD)

Connections between a program (or a Midas session) and a background Midas are done via ASCII files or sockets. Using ASCII files limits the connections to the same host or different hosts sharing disks but can bridge different host systems, like e.g. Unix and Basic based systems.
Connections based on sockets can be established on the same host or over a network but are limited to Unix systems supporting sockets.

Main arguments used by these routines are:

midasunit

unit of background Midas

cid

connection id of background Midas

Important: The environment variable MID_WORK must be set and point to the same directory as the MID_WORK variable of the background Midas.

Function

XCZOPN
 

XCZOPN(midasunit,myunit,direc,cid)

char *midasunit	IN: unit of background Midas
char *myunit	IN: pseudo Midas unit of calling program
char *direc	IN: directory for send/receive files
int *cid	OUT: connection id of background Midas

• Purpose:Open a connection to a Midas session using files.
• Remarks:`direc' = ' 6#60', indicates we use MID_WORK directory
• Returns:return status (0 = o.k.)
  = -1; problems with file communication
  = -90; invalid input to this interface
  = -92; background Midas not running
  = -99; variable MID_WORK not set

Function

XCXOPN
 

XCXOPN(midasunit,host,cid)

char *midasunit	IN: unit of background Midas
char *host	IN: system name of host where background Midas is running
int *cid	OUT: connection id of background Midas

• Purpose:Open a connection to a Midas session using sockets.
• Remarks:`host' = ' 6#60', indicates local host
• Returns:return status (0 = o.k.)
  = -1; problems with socket communication
  = -90; invalid input to this interface
  = -92; background Midas not running
  = -99; variable MID_WORK not set

Function

XCZINI
 

XCZINI(midasunit,myunit,direc,maxtim,cid)

char *midasunit	IN: unit of background Midas
char *myunit	IN: pseudo Midas unit of calling program
char *direc	IN: directory for send/receive files
int maxtim	IN: max. no. of seconds to wait until background Midas is ready
int *cid	OUT: connection id of background Midas

• Purpose:Start a background Midas and open a connection to that session using files.
• Remarks:`direc' = ' 6#60', indicates we use MID_WORK directory
• Returns:return status (0 = o.k.)
  = -1; problems with file communication
  = -2; requested Midas session could not be started
  = -3; requested Midas session not ready after `maxtim' seconds
  = -90; invalid input to this interface
  = -99; variable MID_WORK not set

Function

XCXINI
 

XCXINI(midasunit,host,maxtim,cid)

char *midasunit	IN: unit of background Midas
char *host	IN: system name of host where background Midas is running
int maxtim	IN: max. no. of seconds to wait until background Midas is ready
int *cid	OUT: connection id of background Midas

• Purpose:Start a background Midas and open a connection to that session usi ng sockets.
• Remarks:`host' = ' 6#60', indicates local host
• Returns:return status (0 = o.k.)
  = -1; problems with socket communication
  = -2; requested Midas session could not be started
  = -3; requested Midas session not ready after `maxtim' seconds
  = -90; invalid input to this interface
  = -99; variable MID_WORK not set

Function

XCXCLO
 

XCXCLO(cid)

int cid	IN: connection id of background Midas

• Purpose:Close connection to background Midas.
• Returns:return status (0 = o.k.)
  = -1; problems with socket/file communication
  = -90; invalid input to this interface

Function

XCXSTP
 

XCXSTP(cid)

int cid	IN: connection id of background Midas

• Purpose:Stop background Midas and close connection to it.
• Returns:return status (0 = o.k.)
  = -1; problems with socket/file communication
  = -90; invalid input to this interface

Function

XCXSTA
 

XCXSTA(cid)

int cid	IN: connection id of background Midas

• Purpose:Check status of background Midas.
• Returns:return status:
  = 0; background Midas idle
  = 1; background Midas busy
  = -1; problems with socket/file communication
  = -90; invalid input to this interface

Function

XCXGFD
 

XCXGFD(cid,fid)

int cid	IN: connection id of background Midas
int *fid	OUT: file descr. of socket used for connection

• Purpose:Get file descriptor of socket used in communication with background Midas.
• Returns:return status (0 = o.k.)
  = -1; problems with socket communication
  = -90; invalid input to this interface

Module Version [1.00] (15-Dec-1994) Module XCC

Author:    K. Banse, ESO - Garching

Language:    C

Classification: standard interfaces, communication

Environment:

• UNIX
• #include <midas_def.h>
• #include <xconndef.h>

Comments:

This module contains the routines to send a command to background Midas, to wait for return from a command which was sent to background Midas before or to get the status of a command sent without wait.
The functions provided are:

• Send a command to background Midas (XCCSND)
• Wait until a command which has been sent to background Midas finishes (XCCWAI)
• Read the execution status of a command which has been sent to background Midas without wait before (XCCRDX)

ASCII files or sockets are used for the communication and the transfer of data, depending on how the connection to the background Midas has been opened.

Main arguments used by the routines are:

cid

connection id of background Midas

retstat

returns Midas status from command execution in the background Midas if communication o.k., else the communication error code itself

Function

XCCSND
 

XCCSND(cid,comline,secs,retstat)

int cid	IN: connection id of background Midas
char *comline	IN: command to be executed by background Midas
int secs	IN: max. no. of seconds to wait
int retstat[2]	OUT: Midas status from Background Midas (if we wait)

• Purpose:Send a command to background Midas with or without waiting for its termination.
• Remarks:`secs' = 0, indicates no wait
  `secs'= -1; indicates that we wait forever
• Returns:return status (0 = o.k.)
  = 2; time out, `secs' seconds have passed without return
  = -1; problems with socket/file communication
  = -90; invalid input to this interface

Function

XCCWAI
 

XCCWAI(cid,retstat)

int cid	IN: connection id of background Midas
int retstat[2]	OUT: return status from Background Midas

• Purpose:Wait until a command is executed which has been sent to background Midas (without wait) before.
• Returns:return status (0 = o.k., retstat holds status from command executed in background Midas)
  = 2; time out, `secs' seconds have passed without return
  = -1; problems with socket/file communication
  = -90; invalid input to this interface

Function

XCCRDX
 

XCCRDX(cid,retstat)

int cid	IN: connection id of background Midas
int retstat[2]	OUT: return status from Background Midas

• Purpose:Read the status of a command which has been sent to background Midas (without wait) before.
• Returns:return status (0 = o.k., retstat holds status from command executed in background Midas)
  = 1; background Midas still busy
  = 2; time out, `secs' seconds have passed without return
  = -1; problems with socket/file communication
  = -90; invalid input to this interface

Module Version [1.00] (15-Jan-1995) Module XCK

Author:    K. Banse, ESO - Garching

Language:    C

Classification: standard interfaces, communication

Environment:

• UNIX
• #include <midas_def.h>
• #include <xconndef.h>

Comments:

This module contains the routines to read and write keywords of a background Midas.
The following keyword access routines can ONLY be used if the connection to the background Midas has been established via sockets, i.e. via XCXOPN.

The functions provided are:

• Read contents of keywords of background Midas (XCKRDC,
  XCKRDD, XCKRDI, XCKRDR)
• Write contents of keywords of background Midas (XCKWRC,
  XCKWRD, XCKWRI,XCKWRR)

Main arguments used by the routines are:

cid

connection id of background Midas

key

name of keyword, max. 8 chars. long and must begin with an alphabetic char.

felem

first element to be accessed, the very first element is indicated by 1 (not by 0 as in C-arrays) for compatibility with the relevant SCKRDx and SCKWRx interfaces

maxvals

maximum number of elements required

actvals

actual number of elements accessed, value returned by the routines

unit

unit of keyword, currently not implemented - just used as a placeholder for now

null

no. of null values in keyword, currently not implemented - just used as a placeholder for now

kstat

status from the corresponding SCKRDx or SCKWRx routine executed in the background Midas

Function

XCKRDC
 

XCKRDC(cid,key,noelm,felem,maxvals,actvals,values,unit,null,kstat)

int cid	IN: connection id of background Midas
char *key	IN: keyword name (max. 8 chars.)
int noelm	IN: no. of bytes per data value
int felem	IN: first data item to be read
int maxvals	IN: no. of elements to get
int *actvals	OUT: actual no. of elements returned
char *values	OUT: buffer for data values
int *unit	OUT: address of unit-pointer
int *null	OUT: no. of null values in keyword
int *kstat	OUT: status from SCKRDC in background Midas

• Purpose:Read data from character keyword of background Midas.
• Returns:return status (0 = o.k.)
  = 1; background Midas busy
  = -1; problems with socket communication
  = -90; invalid input to this interface
  = -91; only non-socket communication established
• Algorithm:`actvals' will be set to the actual no. of values returned.
• Remarks:`noelm' > 1 enables you to use character arrays, where each data value is in effect a char. string of `noelm' bytes

Function

XCKRDD
 

XCKRDD(cid,key,felem,maxvals,actvals,values,unit,null,kstat)

int cid	IN: connection id of background Midas
char *key	IN: keyword name (max. 8 chars.)
int felem	IN: first data item to be read
int maxvals	IN: no. of elements to get
int *actvals	OUT: actual no. of elements returned
double *values	OUT: buffer for data values
int *unit	OUT: address of unit-pointer
int *null	OUT: no. of null values in keyword
int *kstat	OUT: status from SCKRDD in background Midas

• Purpose:Read data from double precision keyword of background Midas.
• Returns:return status (0 = o.k.)
  = 1; background Midas busy
  = -1; problems with socket communication
  = -90; invalid input to this interface
  = -91; only non-socket communication established
• Algorithm:`actvals' will be set to the actual no. of values returned.

Function

XCKRDI
 

XCKRDI(cid,key,felem,maxvals,actvals,values,unit,null,kstat)

int cid	IN: connection id of background Midas
char *key	IN: keyword name (max. 8 chars.)
int felem	IN: first data item to be read
int maxvals	IN: no. of elements to get
int *actvals	OUT: actual no. of elements returned
int *values	OUT: buffer for data values
int *unit	OUT: address of unit-pointer
int *null	OUT: no. of null values in keyword
int *kstat	OUT: status from SCKRDI in background Midas

• Purpose:Read data from integer keyword of background Midas.
• Returns:return status (0 = o.k.)
  = 1; background Midas busy
  = -1; problems with socket communication
  = -90; invalid input to this interface
  = -91; only non-socket communication established
• Algorithm:`actvals' will be set to the actual no. of values returned.

Function

XCKRDR
 

XCKRDR(cid,key,felem,maxvals,actvals,values,unit,null,kstat)

int cid	IN: connection id of background Midas
char *key	IN: keyword name (max. 8 chars.)
int felem	IN: first data item to be read
int maxvals	IN: no. of elements to get
int *actvals	OUT: actual no. of elements returned
float *values	OUT: buffer for data values
int *unit	OUT: address of unit-pointer
int *null	OUT: no. of null values in keyword
int *kstat	OUT: status from SCKRDR in background Midas

• Purpose:Read data from real keyword of background Midas.
• Returns:return status (0 = o.k.)
  = 1; background Midas busy
  = -1; problems with socket communication
  = -90; invalid input to this interface
  = -91; only non-socket communication established
• Algorithm:`actvals' will be set to the actual no. of values returned.

Function

XCKWRC
 

XCKWRC(cid,key,noelm,values,felem,maxvals,unit,kstat)

int cid	IN: connection id of background Midas
char *key	IN: keyword name (max. 8 chars.)
int noelm	IN: no. of bytes per data value
char *values	IN: buffer with data values
int felem	IN: first data item to be written
int maxvals	IN: no. of elements to write
int *unit	IN: unit-pointer
int *kstat	OUT: status from SCKWRC in background Midas

• Purpose:Write data into character keyword of background Midas.
• Returns:return status (0 = o.k.)
  = 1; background Midas busy
  = -1; problems with socket communication
  = -90; invalid input to this interface
  = -91; only non-socket communication established
• Remarks:`noelm' > 1 enables you to use character arrays, where each data value is in effect a char. string of `noelm' bytes

Function

XCKWRD
 

XCKWRD(cid,key,values,felem,maxvals,unit,kstat)

int cid	IN: connection id of background Midas
char *key	IN: keyword name (max. 8 chars.)
double *values	IN: buffer with data values
int felem	IN: first data item to be written
int maxvals	IN: no. of elements to write
int *unit	IN: unit-pointer
int *kstat	OUT: status from SCKWRD in background Midas

• Purpose:Write data into double precision keyword of background Midas.
• Returns:return status (0 = o.k.)
  = 1; background Midas busy
  = -1; problems with socket communication
  = -90; invalid input to this interface
  = -91; only non-socket communication established

Function

XCKWRI
 

XCKWRI(cid,key,values,felem,maxvals,unit,kstat)

int cid	IN: connection id of background Midas
char *key	IN: keyword name (max. 8 chars.)
int *values	IN: buffer with data values
int felem	IN: first data item to be written
int maxvals	IN: no. of elements to write
int *unit	IN: unit-pointer
int *kstat	OUT: status from SCKWRI in background Midas

• Purpose:Write data into integer keyword of background Midas.
• Returns:return status (0 = o.k.)
  = 1; background Midas busy
  = -1; problems with socket communication
  = -90; invalid input to this interface
  = -91; only non-socket communication established

Function

XCKWRR
 

XCKWRR(cid,key,values,felem,maxvals,unit,kstat)

int cid	IN: connection id of background Midas
char *key	IN: name of keyword
float *values	IN: buffer with data values
int felem	IN: first data item to be written
int maxvals	IN: no. of elements to write
int *unit	IN: unit-pointer
int *kstat	OUT: status from SCKWRR in background Midas

• Purpose:Write data into real keyword of background Midas.
• Returns:return status (0 = o.k.)
  = 1; background Midas busy
  = -1; problems with socket communication
  = -90; invalid input to this interface
  = -91; only non-socket communication established

=1 =11 =1992