xpaset(3)

✨ xpaset(3) — XPASet ✨

okay bestie, this is a page from the SAORD Documentation set, and it's literally all about yeeting data at XPA servers 💖 it lives in section 3 of the manual (yes, the C-library section, we love a library function moment).

---

🌸 NAME 🌸

XPASet — send data to one or more XPA servers 💌

---

🎀 SYNOPSIS 🎀

#include <xpa.h>

int XPASet(XPA xpa,
           char *template, char *paramlist, char *mode,
           char *buf, size_t len, char **names, char **messages,
           int n);

---

🦋 DESCRIPTION 🦋

So the whole vibe here is: you're sending data to one or more XPA servers whose class:name identifier matches the template you pass in. That's it, that's the plot 🫶

You hand over a template shaped like "class1:name1", and it gets sent to the XPA name server. The name server hands back a list of at most n matching XPA servers. Then a connection gets established with each one of those servers, and the paramlist string gets passed to the server right as the data transfer request kicks off. ✨

Now, if you pass an XPA struct into the call, the persistent connections get updated (as described above, iykyk). If you don't, then temporary connections are made to the servers instead — and those get closed the moment the call finishes. bye bestie 👋

The XPASet() routine transfers data from buf to the XPA servers. And the length of buf, in bytes, goes in the len variable. Don't forget it, fr fr, it matters 💅

A string with the class:name and ip:port of each of those servers comes back in the name array. And if a given server returned an error, or the server callback sends a message back to the client, then that message gets stored in the matching element of the messages array. 👑

NB: if you specify them, the name and messages arrays must be of size n or greater. no cap, this is not optional 😭

The returned message string is gonna look like this:

XPA$ERROR   [error] (class:name ip:port)

or

XPA$MESSAGE [message] (class:name ip:port)

The return value is the actual number of servers that were processed 🔥. So that number is literally the count of valid entries sitting in your names and messages arrays, which means you can use it to loop through them. Iconic. And if names and/or messages is NULL, then no information gets passed back in that particular array at all. no harm, no foul 💜

---

🧚 the mode string 🧚

The mode string is shaped like this: "key1=value1,key2=value2,..."

And these are the keywords it recognizes, bestie:

• ack — value true/false, default true — if false, don't wait for ack from server (after callback completes)
• verify — value true/false, default false — send buf from XPASet[Fd] to stdout
• doxpa — value true/false, default true — client processes xpa requests

---

🌈 the deets on ack 🌈

The ack keyword is your bestie in situations where you do not want to wait for the server to finish. Like, say there's a ton of processing the server needs to do on the data you handed over, or when whether the server operation succeeded just isn't relevant to the client. Lowkey a lifesaver 💖

---

⭐ the deets on doxpa ⭐

Normally, an XPA client will process incoming XPA server requests while it's waiting for the client request to complete. Setting this variable to "false" will stop XPA server requests from being processed by the client. That's the whole thing, bestie. 🙈

---

💅 Example 💅

#include <xpa.h>

#define NXPA 10
int  i, got;
size_t  len;
char *buf;
char *names[NXPA];
char *messages[NXPA];
...
[fill buf with data and set len to the length, in bytes, of the data]
...
/* send data to all access points */
got = XPASet(NULL, "ds9", "fits", NULL, buf, len, names, messages, NXPA);
/* error processing */
for(i=0; i<got; i++){
  if( messages[i] ){
    fprintf(stderr, "ERROR: %s (%s)\n", messages[i], names[i]);
  }
  if( names[i] )    free(names[i]);
  if( messages[i] ) free(messages[i]);
}

---

👑 SEE ALSO 👑

See xpa(n) for a list of XPA help pages 💖

---

okay that's the whole page bestie, go forth and XPASet() responsibly 🎀✨

this has been version 2.1.15, dated July 23, 2013, and it's the xpaset(3) page — mwah, take care of her 💜🦋