C Interface

Defines

PSI_MSG_MAX

Maximum message size.

PSI_MSG_EOF

End of file message.

_psiTrackChannels

Maximum number of channels.

error
debug
info

Typedefs

typedef struct msgbuf_t msgbuf_t

Message buffer structure.

typedef struct psiInput_t psiInput_t

Input queue structure. Contains information on an input queue.

typedef struct psiOutput_t psiOutput_t

Output queue structure. Contains information on an output queue.

typedef struct psiRpc_t psiRpc_t

Remote Procedure Call (RPC) structure. Contains information required to coordinate sending/receiving response/requests from/to an RPC server/client.

Remote Procedure Call (RPC) IO

Handle IO case of a server receiving input from clients, performing some calculation, and then sending a response back to the client.

Server Usage:

  1. One-time: Create server channels with format specifiers for input and output. psiRpc_t srv = psiRpcServer(“srv_name”, “%d”, “%d %d”);
  2. Prepare: Allocate space for recovered variables from request. int a;
  3. Receive request: int ret = rpcRecv(srv, &a);
  4. Process: Do tasks the server should do with input to produce output. int b = 2*a; int c = 3*a;
  1. Send response: ret = rpcSend(srv, b, c);

Client Usage:

  1. One-time: Create client channels to desired server with format specifiers for output and input (should be the same arguments as for the server except for name). psiRpc_t cli = psiRpcClient(“cli_name”, “%d”, “%d %d”);
  2. Prepare: Allocate space for recovered variables from response. int b, c;
  3. Call server: int ret = rpcCall(cli, 1, &b, &c);

Clients can also send several requests at once before receiving any responses. This allows the server to be processing the next requests while the client handles the previous response, thereby increasing efficiency. The responses are assumed to be in the same order as the generating requests (i.e. first come, first served).

typedef struct psiAsciiFileOutput_t psiAsciiFileOutput_t

Structure of information for output to a file line by line.

File IO

Handle I/O from/to a local or remote file line by line.

Input Usage:

  1. One-time: Create file interface by providing either a channel name or a path to a local file. psiAsciiFileInput_t fin = psiAsciiFileInput(“file_channel”, 1); // channel psiAsciiFileInput_t fin = psiAsciiFileInput(“/local/file.txt”, 0); // local file
  2. Prepare: Allocate space for lines. char line[PSI_MSG_MAX];
  3. Receive each line, terminating when receive returns -1 (EOF or channel closed). int ret = 1; while (ret > 0) { ret = af_recv_line(fin, line, PSI_MSG_MAX); Do something with the line }
  4. Cleanup. Call functions to deallocate structures and close files. cleanup_pafi(&fin);

Output Usage:

  1. One-time: Create file interface by providing either a channel name or a path to a local file. psiAsciiFileOutput_t fout = psiAsciiFileOutput(“file_channel”, 1); // channel psiAsciiFileOutput_t fout = psiAsciiFileOutput(“/local/file.txt”, 0); // local file
  2. Send lines to the file. If return value is not 0, the send was not succesfull. int ret; ret = af_send_line(fout, “Line 1\n”); ret = af_send_line(fout, “Line 2\n”);
  3. Send EOF message when done to close the file. ret = af_send_eof(fout);
  4. Cleanup. Call functions to deallocate structures and close files. cleanup_pafo(&fout);

typedef struct psiAsciiFileInput_t psiAsciiFileInput_t

Structure of information for input from a file line by line.

typedef struct psiAsciiTableOutput_t psiAsciiTableOutput_t

Structure for handling output to an ASCII table.

Table IO

Handle I/O from/to a local or remote ASCII table either line-by-line or as an array.

Row-by-Row

Input by Row Usage:

  1. One-time: Create file interface by providing either a channel name or a path to a local file. psiAsciiTableInput_t fin = psiAsciiTableInput(“file_channel”, 1); // channel psiAsciiTableInput_t fin = psiAsciiTableInput(“/local/file.txt”, 0); // local table
  2. Prepare: Allocate space for variables in row (the format in this example is “%5s %d %f\n” like the output example below). char a[5]; int b; double c;
  3. Receive each row, terminating when receive returns -1 (EOF or channel closed). int ret = 1; while (ret > 0) { ret = at_recv_row(fin, &a, &b, &c); Do something with the row }
  4. Cleanup. Call functions to deallocate structures and close files. cleanup_pati(&fin);

Output by Row Usage:

  1. One-time: Create file interface by providing either a channel name or a path to a local file and a format string for rows. psiAsciiTableOutput_t fout = psiAsciiTableOutput(“file_channel”, // channel “%5s %d %f\n”, 1); psiAsciiTableOutput_t fout = psiAsciiTableOutput(“/local/file.txt”, // local table “%5s %d %f\n”, 0);
  2. Send rows to the file by providing entries. Formatting is handled by the interface. If return value is not 0, the send was not succesful. int ret; ret = at_send_row(fout, “one”, 1, 1.0); ret = at_send_row(fout, “two”, 2, 2.0);
  3. Send EOF message when done to close the file. ret = at_send_eof(fout);
  4. Cleanup. Call functions to deallocate structures and close files. cleanup_pato(&fout);

Array

Input by Array Usage:

  1. One-time: Create file interface by providing either a channel name or a path to a local file. psiAsciiTableInput_t fin = psiAsciiTableInput(“file_channel”, 1); // channel psiAsciiTableInput_t fin = psiAsciiTableInput(“/local/file.txt”, 0); // local table
  2. Prepare: Declare pointers for table columns (they will be allocated by the interface once the number of rows is known). char *aCol; int *bCol; double *cCol;
  3. Receive entire table as columns. Return value will be the number of elements in each column (the number of table rows). Negative values indicate errors. int ret = at_recv_array(fin, &a, &b, &c);
  4. Cleanup. Call functions to deallocate structures and close files. cleanup_pati(&fin);

Output by Array Usage:

  1. One-time: Create file interface by providing either a channel name or a path to a local file and a format string for rows. psiAsciiTableOutput_t fout = psiAsciiTableOutput(“file_channel”, // channel “%5s %d %f\n”, 1); psiAsciiTableOutput_t fout = psiAsciiTableOutput(“/local/file.txt”, // local table “%5s %d %f\n”, 0);
  2. Send columns to the file by providing pointers (or arrays). Formatting is handled by the interface. If return value is not 0, the send was not succesful. char aCol[] = {“one ”, “two ”, “three”}; \ Each str is of len 5 int bCol[3] = {1, 2, 3}; float cCol[3] = {1.0, 2.0, 3.0}; int ret = at_send_array(fout, a, b, c);
  3. Cleanup. Call functions to deallocate structures and close files. cleanup_pato(&fout);

typedef struct psiAsciiTableInput_t psiAsciiTableInput_t

Structure for handling input from an ASCII table.

Functions

static void psiLog(const char *prefix, const char *fmt, va_list ap)

Print a log message. Prints a formatted message, prepending it with the process id and appending it with a newline.

Logging

Alliases are set at compile-time based on the value of PSI_CLIENT_DEBUG. If set to INFO, only messages logged with info or error alias are printed. If set to DEBUG, messages logged with error, info or debug aliases are printed. Otherwise, only error messages are printed. If the PSI_CLIENT_DEBUG is changed, any code including this header must be recompiled for the change to take effect.

Parameters
  • prefix: a constant character pointer to the prefix that should preceed the message and process id.
  • fmt: a constant character pointer to a format string.
  • ap: va_list of arguments to be formatted in the format string.

static void psiInfo(const char *fmt, ...)

Print an info log message. Prints a formatted message, prepending it with INFO and the process id. A newline character is added to the end of the message.

Parameters
  • fmt: a constant character pointer to a format string.
  • ...: arguments to be formatted in the format string.

static void psiDebug(const char *fmt, ...)

Print an debug log message. Prints a formatted message, prepending it with DEBUG and the process id. A newline character is added to the end of the message.

Parameters
  • fmt: a constant character pointer to a format string.
  • ...: arguments to be formatted in the format string.

static void psiError(const char *fmt, ...)

Print an error log message. Prints a formatted message, prepending it with ERROR and the process id. A newline character is added to the end of the message.

Parameters
  • fmt: a constant character pointer to a format string.
  • ...: arguments to be formatted in the format string.

static int psi_mq(char *name, const char *yamlName)

Get a sysv_ipc queue identifier based on its name. The queue name is used to locate the queue key stored in the associated environment variable. That key is then used to get the queue ID.

Basic IO

Output Usage:

  1. One-time: Create output channel (store in named variables) psiOutput_t output_channel = psiOutput(“out_name”);
  2. Prepare: Format data to a character array buffer. char buffer[PSI_MSG_MAX]; sprintf(buffer, “a=%d, b=%d”, 1, 2);
  3. Send: ret = psi_send(output_channel, buffer, strlen(buffer));

Input Usage:

  1. One-time: Create output channel (store in named variables) psiInput_t input_channel = psiInput(“in_name”);
  2. Prepare: Allocate a character array buffer. char buffer[PSI_MSG_MAX];
  3. Receive: int ret = psi_recv(input_channel, buffer, PSI_MSG_MAX);

Return
int queue identifier.
Parameters
  • name: character pointer to name of environment variable that the queue key should be shored in.
  • yamlName: constant character pointer to the original name of the queue, absent any suffix. This is used to check if there is an existing queue with that name, but a different suffix.

static int is_eof(const char *buf)

Check if a character array matches the internal EOF message.

Return
int 1 if buf is the EOF message, 0 otherwise.
Parameters
  • buf: constant character pointer to string that should be checked.

static psiOutput_t psiOutput(const char *name)

Constructor for psiOutput_t structure. Create a psiOutput_t structure based on a provided name that is used to locate a particular sysv_ipc queue key stored in the environment variable name + “_OUT”.

Return
psiOutput_t output queue structure.
Parameters
  • name: constant character pointer to name of queue.

static psiInput_t psiInput(const char *name)

Constructor for psiInput_t structure. Create a psiInput_t structure based on a provided name that is used to locate a particular sysv_ipc queue key stored in the environment variable name + “_IN”.

Return
psiInput_t input queue structure.
Parameters
  • name: constant character pointer to name of queue.

static psiOutput_t psi_output(const char *name)

Alias for psiOutput.

static psiInput_t psi_input(const char *name)

Alias for psiInput.

static psiOutput_t psiOutputFmt(const char *name, char *fmtString)

Constructor for psiOutput_t structure with format. Create a psiOutput_t structure based on a provided name that is used to locate a particular sysv_ipc queue key stored in the environment variable name + “_OUT” and a format string that can be used to format arguments into outgoing messages for the queue.

Return
psiOutput_t output queue structure.
Parameters
  • name: constant character pointer to name of queue.
  • fmtString: character pointer to format string.

static psiInput_t psiInputFmt(const char *name, char *fmtString)

Constructor for psiInput_t structure with format. Create a psiInput_t structure based on a provided name that is used to locate a particular sysv_ipc queue key stored in the environment variable name + “_IN” and a format stirng that can be used to extract arguments from messages received from the queue.

Return
psiInput_t input queue structure.
Parameters
  • name: constant character pointer to name of queue.
  • fmtString: character pointer to format string.

static int psi_output_nmsg(psiOutput_t psiQ)

Get the number of messages in an output queue. Check how many messages are waiting in the associated queue for an output queue structure.

Return
int number of messages in the queue. -1 if the queue cannot be accessed.
Parameters

static int psi_input_nmsg(psiInput_t psiQ)

Get the number of messages in an input queue. Check how many messages are waiting in the associated queue for an input queue structure.

Return
int number of messages in the queue. -1 if the queue cannot be accessed.
Parameters

static int psi_send(psiOutput_t psiQ, char *data, int len)

Send a message to an output queue. Send a message smaller than PSI_MSG_MAX bytes to an output queue. If the message is larger, it will not be sent.

Return
int 0 if send succesfull, -1 if send unsuccessful.
Parameters
  • psiQ: psiOutput_t structure that queue should be sent to.
  • data: character pointer to message that should be sent.
  • len: int length of message to be sent.

static int psi_recv(psiInput_t psiQ, char *data, int len)

Receive a message from an input queue. Receive a message smaller than PSI_MSG_MAX bytes from an input queue.

Return
int -1 if message could not be received. Length of the received message if message was received.
Parameters
  • psiQ: psiOutput_t structure that message should be sent to.
  • data: character pointer to allocated buffer where the message should be saved.
  • len: int length of the allocated message buffer in bytes.

static int psi_send_nolimit(psiOutput_t psiQ, char *data, int len)

Send a large message to an output queue. Send a message larger than PSI_MSG_MAX bytes to an output queue by breaking it up between several smaller messages and sending initial message with the size of the message that should be expected. Must be partnered with psi_recv_nolimit for communication to make sense.

Return
int 0 if send succesfull, -1 if send unsuccessful.
Parameters
  • psiQ: psiOutput_t structure that message should be sent to.
  • data: character pointer to message that should be sent.
  • len: int length of message to be sent.

static int psi_recv_nolimit(psiInput_t psiQ, char **data, int len0)

Receive a large message from an input queue. Receive a message larger than PSI_MSG_MAX bytes from an input queue by receiving it in parts. This expects the first message to be the size of the total message.

Return
int -1 if message could not be received. Length of the received message if message was received.
Parameters
  • psiQ: psiOutput_t structure that message should be sent to.
  • data: character pointer to pointer for allocated buffer where the message should be stored. A pointer to a pointer is used so that the buffer may be reallocated as necessary for the incoming message.
  • len0: int length of the initial allocated message buffer in bytes.

static int vpsiSend(psiOutput_t psiQ, va_list ap)

Send arguments as a small formatted message to an output queue. Use the format string to create a message from the input arguments that is then sent to the specified output queue. If the message is larger than PSI_MSG_MAX or cannot be encoded, it will not be sent.

Formatted IO

Output Usage:

  1. One-time: Create output channel with format specifier. psiOutput_t output_channel = psiOutputFmt(“out_name”, “a=%d, b=%d”);
  2. Send: ret = psiSend(output_channel, 1, 2);

Input Usage:

  1. One-time: Create output channel with format specifier. psiInput_t input_channel = psiInput(“in_name”, “a=%d, b=%d”);
  2. Prepare: Allocate space for recovered variables. int a, b;
  3. Receive: int ret = psiRecv(input_channel, &a, &b);

Return
int 0 if send succesfull, -1 if send unsuccessful.
Parameters
  • psiQ: psiOutput_t structure that queue should be sent to.
  • ap: va_list arguments to be formatted into a message using sprintf.

static int vpsiRecv(psiInput_t psiQ, va_list ap)

Assign arguments by receiving and parsing a message from an input queue. Receive a message smaller than PSI_MSG_MAX bytes from an input queue and parse it using the associated format string.

Return
int -1 if message could not be received or could not be parsed. Length of the received message if message was received and parsed.
Parameters
  • psiQ: psiOutput_t structure that message should be sent to.
  • ap: va_list arguments that should be assigned by parsing the received message using sscanf. As these are being assigned, they should be pointers to memory that has already been allocated.

static int psiSend(psiOutput_t psiQ, ...)

Send arguments as a small formatted message to an output queue. Use the format string to create a message from the input arguments that is then sent to the specified output queue. If the message is larger than PSI_MSG_MAX or cannot be encoded, it will not be sent.

Return
int 0 if send succesfull, -1 if send unsuccessful.
Parameters
  • psiQ: psiOutput_t structure that queue should be sent to.
  • ...: arguments to be formatted into a message using sprintf.

static int psiRecv(psiInput_t psiQ, ...)

Assign arguments by receiving and parsing a message from an input queue. Receive a message smaller than PSI_MSG_MAX bytes from an input queue and parse it using the associated format string.

Return
int -1 if message could not be received or could not be parsed. Length of the received message if message was received and parsed.
Parameters
  • psiQ: psiOutput_t structure that message should be sent to.
  • ...: arguments that should be assigned by parsing the received message using sscanf. As these are being assigned, they should be pointers to memory that has already been allocated.

static int vpsiSend_nolimit(psiOutput_t psiQ, va_list ap)

Send arguments as a large formatted message to an output queue. Use the format string to create a message from the input arguments that is then sent to the specified output queue. The message can be larger than PSI_MSG_MAX. If it cannot be encoded, it will not be sent.

Return
int 0 if formatting and send succesfull, -1 if formatting or send unsuccessful.
Parameters
  • psiQ: psiOutput_t structure that queue should be sent to.
  • ap: va_list arguments to be formatted into a message using sprintf.

static int vpsiRecv_nolimit(psiInput_t psiQ, va_list ap)

Assign arguments by receiving and parsing a message from an input queue. Receive a message larger than PSI_MSG_MAX bytes in chunks from an input queue and parse it using the associated format string.

Return
int -1 if message could not be received or could not be parsed. Length of the received message if message was received and parsed.
Parameters
  • psiQ: psiOutput_t structure that message should be sent to.
  • ap: va_list arguments that should be assigned by parsing the received message using sscanf. As these are being assigned, they should be pointers to memory that has already been allocated.

static int psiSend_nolimit(psiOutput_t psiQ, ...)

Send arguments as a large formatted message to an output queue. Use the format string to create a message from the input arguments that is then sent to the specified output queue. The message can be larger than PSI_MSG_MAX. If it cannot be encoded, it will not be sent.

Return
int 0 if formatting and send succesfull, -1 if formatting or send unsuccessful.
Parameters
  • psiQ: psiOutput_t structure that queue should be sent to.
  • ...: arguments to be formatted into a message using sprintf.

static int psiRecv_nolimit(psiInput_t psiQ, ...)

Assign arguments by receiving and parsing a message from an input queue. Receive a message larger than PSI_MSG_MAX bytes in chunks from an input queue and parse it using the associated format string.

Return
int -1 if message could not be received or could not be parsed. Length of the received message if message was received and parsed.
Parameters
  • psiQ: psiInput_t structure that message should be sent to.
  • ...: arguments that should be assigned by parsing the received message using sscanf. As these are being assigned, they should be pointers to memory that has already been allocated.

static psiRpc_t psiRpc(const char *outName, char *outFormat, const char *inName, char *inFormat)

Constructor for RPC structure. Creates an instance of psiRpc_t with provided information.

Return
psiRpc_t structure with provided info.
Parameters
  • outName: constant character pointer name of the output queue.
  • outFormat: character pointer to format that should be used for formatting output.
  • inName: constant character pointer to name of the input queue.
  • inFormat: character pointer to format that should be used for parsing input.

static psiRpc_t psiRpcClient(const char *name, char *outFormat, char *inFormat)

Constructor for client side RPC structure. Creates an instance of psiRpc_t with provided information.

Return
psiRpc_t structure with provided info.
Parameters
  • name: constant character pointer to name for queues.
  • outFormat: character pointer to format that should be used for formatting output.
  • inFormat: character pointer to format that should be used for parsing input.

static psiRpc_t psiRpcServer(const char *name, char *inFormat, char *outFormat)

Constructor for server side RPC structure. Creates an instance of psiRpc_t with provided information.

Return
psiRpc_t structure with provided info.
Parameters
  • name: constant character pointer to name for queues.
  • inFormat: character pointer to format that should be used for parsing input.
  • outFormat: character pointer to format that should be used for formatting output.

static int vrpcSend(psiRpc_t rpc, va_list ap)

Format and send a message to an RPC output queue. Format provided arguments list using the output queue format string and then sends it to the output queue under the assumption that it is larger than the maximum message size.

Return
integer specifying if the send was succesful. Values >= 0 indicate success.
Parameters
  • rpc: psiRpc_t structure with RPC information.
  • ap: va_list variable list of arguments for formatting.

static int vrpcRecv(psiRpc_t rpc, va_list ap)

Receive and parse a message from an RPC input queue. Receive a message from the input queue under the assumption that it is larger than the maximum message size. Then parse the message using the input queue format string to extract parameters and assign them to the arguments.

Return
integer specifying if the receive was succesful. Values >= 0 indicate success.
Parameters
  • rpc: psiRpc_t structure with RPC information.
  • ap: va_list variable list of arguments that should be assigned parameters extracted using the format string. Since these will be assigned, they should be pointers to memory that has already been allocated.

static int rpcSend(psiRpc_t rpc, ...)

Format and send a message to an RPC output queue. Format provided arguments using the output queue format string and then sends it to the output queue under the assumption that it is larger than the maximum message size.

Return
integer specifying if the send was succesful. Values >= 0 indicate success.
Parameters
  • rpc: psiRpc_t structure with RPC information.
  • ...: arguments for formatting.

static int rpcRecv(psiRpc_t rpc, ...)

Receive and parse a message from an RPC input queue. Receive a message from the input queue under the assumption that it is larger than the maximum message size. Then parse the message using the input queue format string to extract parameters and assign them to the arguments.

Return
integer specifying if the receive was succesful. Values >= 0 indicate success.
Parameters
  • rpc: psiRpc_t structure with RPC information.
  • ...: mixed arguments that should be assigned parameters extracted using the format string. Since these will be assigned, they should be pointers to memory that has already been allocated.

static int vrpcCall(psiRpc_t rpc, va_list ap)

Send request to an RPC server from the client and wait for a response. Format arguments using the output queue format string, send the message to the output queue, receive a response from the input queue, and assign arguments from the message using the input queue format string to parse it.

Return
integer specifying if the receive was succesful. Values >= 0 indicate success.
Parameters
  • rpc: psiRpc_t structure with RPC information.
  • ap: va_list mixed arguments that include those that should be formatted using the output format string, followed by those that should be assigned parameters extracted using the input format string. These that will be assigned should be pointers to memory that has already been allocated.

static int rpcCall(psiRpc_t rpc, ...)

Send request to an RPC server from the client and wait for a response. Format arguments using the output queue format string, send the message to the output queue, receive a response from the input queue, and assign arguments from the message using the input queue format string to parse it.

Return
integer specifying if the receive was succesful. Values >= 0 indicate success.
Parameters
  • rpc: psiRpc_t structure with RPC information.
  • ...: mixed arguments that include those that should be formatted using the output format string, followed by those that should be assigned parameters extracted using the input format string. These that will be assigned should be pointers to memory that has already been allocated.

static psiAsciiFileOutput_t psiAsciiFileOutput(const char *name, int dst_type)

Constructor for psiAsciiFileOutput_t. Based on the value of dst_type, either a local file will be opened for output (dst_type == 0), or a psiOutput_t connection will be made.

Return
psiAsciiFileOutput_t for line-by-line output to a file or channel.
Parameters
  • name: constant character pointer to path of local file or name of an output queue.
  • dst_type: int 0 if name refers to a local file, 1 if it is a queue.

static psiAsciiFileInput_t psiAsciiFileInput(const char *name, int src_type)

Constructor for psiAsciiFileInput_t. Based on the value of src_type, either a local file will be opened for input (src_type == 0), or a psiInput_t connection will be made.

Return
psiAsciiFileInput_t for line-by-line input from a file or channel.
Parameters
  • name: constant character pointer to path of local file or name of an input queue.
  • src_type: int 0 if name refers to a local file, 1 if it is a queue.

static int af_send_eof(psiAsciiFileOutput_t t)

Send EOF message to output file, closing it.

Return
int 0 if send was succesfull. All other values indicate errors.
Parameters

static int af_recv_line(psiAsciiFileInput_t t, char *line, size_t n)

Receive a single line from an associated file or queue.

Return
int Number of bytes read/received. Negative values indicate that there was either an error or the EOF message was received.
Parameters
  • t: psiAsciiFileInput_t input structure.
  • line: character pointer to allocate memory where the received line should be stored.
  • n: size_t Size of the allocated memory block in bytes.

static int af_send_line(psiAsciiFileOutput_t t, char *line)

Send a single line to a file or queue.

Return
int 0 if send was succesfull. Other values indicate errors.
Parameters

static void cleanup_pafi(psiAsciiFileInput_t *t)

Deallocate and clean up psiAsciiFileInput_t structure.

Parameters

static void cleanup_pafo(psiAsciiFileOutput_t *t)

Deallocate and clean up psiAsciiFileOutput_t structure.

Parameters

static psiAsciiTableOutput_t psiAsciiTableOutput(const char *name, char *format_str, int dst_type)

Constructor for psiAsciiTableOutput_t.

Return
psiAsciiTableOutput_t output structure.
Parameters
  • name: constant character pointer to local file path or message queue name.
  • format_str: character pointer to format string that should be used to format rows into table lines.
  • dst_type: int 0 if name is a local file path, 1 if it is the name of a message queue.

static psiAsciiTableInput_t psiAsciiTableInput(const char *name, int src_type)

Constructor for psiAsciiTableInput_t.

Return
psiAsciiTableInput_t input structure.
Parameters
  • name: constant character pointer to local file path or message queue name.
  • src_type: int 0 if name is a local file path, 1 if it is the name of a message queue.

static int at_psi_send(psiAsciiTableOutput_t t, char *data, int len)

Send a nolimit message to a table output queue.

Return
int 0 if send succesfull, -1 if send unsuccessful.
Parameters
  • t: psiAsciiTableOutput_t output structure.
  • data: character pointer to message that should be sent.
  • len: int length of message to be sent.

static int at_psi_recv(psiAsciiTableInput_t t, char **data, int len)

Recv a nolimit message from a table input queue.

Return
int -1 if message could not be received. Length of the received message if message was received.
Parameters
  • t: psiAsciiTableInput_t input structure.
  • data: character pointer to pointer to memory where received message should be stored. It does not need to be allocated, only defined.
  • len: int length of allocated buffer.

static int at_send_eof(psiAsciiTableOutput_t t)

Send a nolimit EOF message to a table output queue.

Return
int 0 if send succesfull, -1 if send unsuccessful.
Parameters

static int vsend_row(psiAsciiTableOutput_t t, va_list ap)

Format and send a row to the table file/queue.

Return
int 0 if send succesfull, -1 if send unsuccessful.
Parameters

static int vrecv_row(psiAsciiTableInput_t t, va_list ap)

Recv and parse a row from the table file/queue.

Return
int -1 if message could not be received or parsed, otherwise the length of the received is returned.
Parameters
  • t: psiAsciiTableInput_t input structure.
  • ap: va_list Pointers to memory where variables from the parsed should be stored.

static int at_send_row(psiAsciiTableOutput_t t, ...)

Format and send a row to the table file/queue.

Return
int 0 if send succesfull, -1 if send unsuccessful.
Parameters

static int at_recv_row(psiAsciiTableInput_t t, ...)

Recv and parse a row from the table file/queue.

Return
int -1 if message could not be received or parsed, otherwise the length of the received is returned.
Parameters
  • t: psiAsciiTableInput_t input structure.
  • ...: Pointers to memory where variables from the parsed row should be stored.

static int vsend_array(psiAsciiTableOutput_t t, int nrows, va_list ap)

Format and send table columns to the table file/queue.

Return
int 0 if send succesfull, -1 if send unsuccessful.
Parameters
  • t: psiAsciiTableOutput_t output structure.
  • nrows: int Number of rows in the columns.
  • ap: va_list Pointers to memory containing table columns that should be formatted.

static int vrecv_array(psiAsciiTableInput_t t, va_list ap)

Recv and parse columns from a table file/queue.

Return
int Number of rows received. Negative values indicate errors.
Parameters
  • t: psiAsciiTableInput_t input structure.
  • ap: va_list Pointers to pointers to memory where columns from the parsed table should be stored. They need not be allocated, only declared.

static int at_send_array(psiAsciiTableOutput_t t, int nrows, ...)

Format and send table columns to the table file/queue.

Return
int 0 if send succesfull, -1 if send unsuccessful.
Parameters
  • t: psiAsciiTableOutput_t output structure.
  • nrows: int Number of rows in the columns.
  • ...: Pointers to memory containing table columns that should be formatted.

static int at_recv_array(psiAsciiTableInput_t t, ...)

Recv and parse columns from a table file/queue.

Return
int Number of rows received. Negative values indicate errors.
Parameters
  • t: psiAsciiTableInput_t input structure.
  • ...: Pointers to pointers to memory where columns from the parsed table should be stored. They need not be allocated, only declared.

static void cleanup_pati(psiAsciiTableInput_t *t)

Deallocate and clean up psiAsciiTableInput_t structure.

Parameters

static void cleanup_pato(psiAsciiTableOutput_t *t)

Deallocate and clean up psiAsciiTableOutput_t structure.

Parameters

Variables

char *_psiChannelNames[_psiTrackChannels]

Names of channels in use.

unsigned _psiChannelsUsed = 0

Number of channels in use.

struct msgbuf_t
#include <PsiInterface.h>

Message buffer structure.

Public Members

long mtype

Message buffer type.

char data[PSI_MSG_MAX]

Buffer for the message.

struct psiInput_t
#include <PsiInterface.h>

Input queue structure. Contains information on an input queue.

Public Members

int _handle

Queue handle.

const char *_name

Queue name.

char *_fmt

Format for interpreting queue messages.

int _nfmt

Number of fields expected from format string.

struct psiOutput_t
#include <PsiInterface.h>

Output queue structure. Contains information on an output queue.

Public Members

int _handle

Queue handle.

const char *_name

Queue name.

char *_fmt

Format for formatting queue messages.

int _nfmt

Number of fields expected from format string.

struct psiRpc_t
#include <PsiInterface.h>

Remote Procedure Call (RPC) structure. Contains information required to coordinate sending/receiving response/requests from/to an RPC server/client.

Remote Procedure Call (RPC) IO

Handle IO case of a server receiving input from clients, performing some calculation, and then sending a response back to the client.

Server Usage:

  1. One-time: Create server channels with format specifiers for input and output. psiRpc_t srv = psiRpcServer(“srv_name”, “%d”, “%d %d”);
  2. Prepare: Allocate space for recovered variables from request. int a;
  3. Receive request: int ret = rpcRecv(srv, &a);
  4. Process: Do tasks the server should do with input to produce output. int b = 2*a; int c = 3*a;
  1. Send response: ret = rpcSend(srv, b, c);

Client Usage:

  1. One-time: Create client channels to desired server with format specifiers for output and input (should be the same arguments as for the server except for name). psiRpc_t cli = psiRpcClient(“cli_name”, “%d”, “%d %d”);
  2. Prepare: Allocate space for recovered variables from response. int b, c;
  3. Call server: int ret = rpcCall(cli, 1, &b, &c);

Clients can also send several requests at once before receiving any responses. This allows the server to be processing the next requests while the client handles the previous response, thereby increasing efficiency. The responses are assumed to be in the same order as the generating requests (i.e. first come, first served).

Public Members

psiInput_t _input

Input queue structure.

psiOutput_t _output

Output queue structure.

char *_inFmt

Format string used for input queue.

char *_outFmt

Format string used for output queue.

struct psiAsciiFileOutput_t
#include <PsiInterface.h>

Structure of information for output to a file line by line.

File IO

Handle I/O from/to a local or remote file line by line.

Input Usage:

  1. One-time: Create file interface by providing either a channel name or a path to a local file. psiAsciiFileInput_t fin = psiAsciiFileInput(“file_channel”, 1); // channel psiAsciiFileInput_t fin = psiAsciiFileInput(“/local/file.txt”, 0); // local file
  2. Prepare: Allocate space for lines. char line[PSI_MSG_MAX];
  3. Receive each line, terminating when receive returns -1 (EOF or channel closed). int ret = 1; while (ret > 0) { ret = af_recv_line(fin, line, PSI_MSG_MAX); Do something with the line }
  4. Cleanup. Call functions to deallocate structures and close files. cleanup_pafi(&fin);

Output Usage:

  1. One-time: Create file interface by providing either a channel name or a path to a local file. psiAsciiFileOutput_t fout = psiAsciiFileOutput(“file_channel”, 1); // channel psiAsciiFileOutput_t fout = psiAsciiFileOutput(“/local/file.txt”, 0); // local file
  2. Send lines to the file. If return value is not 0, the send was not succesfull. int ret; ret = af_send_line(fout, “Line 1\n”); ret = af_send_line(fout, “Line 2\n”);
  3. Send EOF message when done to close the file. ret = af_send_eof(fout);
  4. Cleanup. Call functions to deallocate structures and close files. cleanup_pafo(&fout);

Public Members

int _valid

Indicates if the structure was succesfully initialized.

const char *_name

Path to local file or name of output channel.

int _type

0 for local file, 1 for output channel.

asciiFile_t _file

Associated output handler for local files.

psiOutput_t _psi

Associated output handler for output channel.

struct psiAsciiFileInput_t
#include <PsiInterface.h>

Structure of information for input from a file line by line.

Public Members

int _valid

Indicates if the structure was succesfully initialized.

const char *_name

Path to local file or name of input channel.

int _type

0 for local file, 1 for input channel.

asciiFile_t _file

Associated input handler for local files.

psiInput_t _psi

Associated input handler for input channel.

struct psiAsciiTableOutput_t
#include <PsiInterface.h>

Structure for handling output to an ASCII table.

Table IO

Handle I/O from/to a local or remote ASCII table either line-by-line or as an array.

Row-by-Row

Input by Row Usage:

  1. One-time: Create file interface by providing either a channel name or a path to a local file. psiAsciiTableInput_t fin = psiAsciiTableInput(“file_channel”, 1); // channel psiAsciiTableInput_t fin = psiAsciiTableInput(“/local/file.txt”, 0); // local table
  2. Prepare: Allocate space for variables in row (the format in this example is “%5s %d %f\n” like the output example below). char a[5]; int b; double c;
  3. Receive each row, terminating when receive returns -1 (EOF or channel closed). int ret = 1; while (ret > 0) { ret = at_recv_row(fin, &a, &b, &c); Do something with the row }
  4. Cleanup. Call functions to deallocate structures and close files. cleanup_pati(&fin);

Output by Row Usage:

  1. One-time: Create file interface by providing either a channel name or a path to a local file and a format string for rows. psiAsciiTableOutput_t fout = psiAsciiTableOutput(“file_channel”, // channel “%5s %d %f\n”, 1); psiAsciiTableOutput_t fout = psiAsciiTableOutput(“/local/file.txt”, // local table “%5s %d %f\n”, 0);
  2. Send rows to the file by providing entries. Formatting is handled by the interface. If return value is not 0, the send was not succesful. int ret; ret = at_send_row(fout, “one”, 1, 1.0); ret = at_send_row(fout, “two”, 2, 2.0);
  3. Send EOF message when done to close the file. ret = at_send_eof(fout);
  4. Cleanup. Call functions to deallocate structures and close files. cleanup_pato(&fout);

Array

Input by Array Usage:

  1. One-time: Create file interface by providing either a channel name or a path to a local file. psiAsciiTableInput_t fin = psiAsciiTableInput(“file_channel”, 1); // channel psiAsciiTableInput_t fin = psiAsciiTableInput(“/local/file.txt”, 0); // local table
  2. Prepare: Declare pointers for table columns (they will be allocated by the interface once the number of rows is known). char *aCol; int *bCol; double *cCol;
  3. Receive entire table as columns. Return value will be the number of elements in each column (the number of table rows). Negative values indicate errors. int ret = at_recv_array(fin, &a, &b, &c);
  4. Cleanup. Call functions to deallocate structures and close files. cleanup_pati(&fin);

Output by Array Usage:

  1. One-time: Create file interface by providing either a channel name or a path to a local file and a format string for rows. psiAsciiTableOutput_t fout = psiAsciiTableOutput(“file_channel”, // channel “%5s %d %f\n”, 1); psiAsciiTableOutput_t fout = psiAsciiTableOutput(“/local/file.txt”, // local table “%5s %d %f\n”, 0);
  2. Send columns to the file by providing pointers (or arrays). Formatting is handled by the interface. If return value is not 0, the send was not succesful. char aCol[] = {“one ”, “two ”, “three”}; \ Each str is of len 5 int bCol[3] = {1, 2, 3}; float cCol[3] = {1.0, 2.0, 3.0}; int ret = at_send_array(fout, a, b, c);
  3. Cleanup. Call functions to deallocate structures and close files. cleanup_pato(&fout);

Public Members

int _valid

Success or failure of initializing the structure.

const char *_name

Path to local table or name of message queue.

int _type

0 if _name is a local table, 1 if it is a message queue.

asciiTable_t _table

Associated output handler for local tables.

psiOutput_t _psi

Associated output handler for queues.

struct psiAsciiTableInput_t
#include <PsiInterface.h>

Structure for handling input from an ASCII table.

Public Members

int _valid

Success or failure of initializing the structure.

const char *_name

Path to local table or name of message queue.

int _type

0 if _name is a local table, 1 if it is a message queue.

asciiTable_t _table

Associated input handler for local tables.

psiInput_t _psi

Associated input handler for queues.