SECTION 7 -- INTERPROC COMMUNICATION FUNCTIONS

The interproc communication package provides C function calls for receiving and transmitting messages of any format. If, however, a C program restricts itself to sending and receiving TAE V-BLOCKs, then the program is compatible with the SENDVAR/RECVAR TCL commands; such a program may communicate with ASYNC TCL procedures.

All functions in this package begin with the c_ prefix. To use the c_ functions, the caller must include the COMMINC include file as shown in the server example of Appendix B.3.

7.1 c_crepath - Create Path (mailbox (VMS) Or SOCKET (UNIX))

CODE c_crepath (path, path size, path_name, type )

Function return:

SUCCESS - Path created successfully.
FAIL - Path could not be created. If FAIL, then the path.errmsg field contains a host-dependent error message string and the path.host_code field contains a host-dependent integer error code.

Arguments:

```
path: input/output, struct PATH *path;
```
This is the context block for the path to be created. A "path" is mailbox under VMS and a socket under BSD UNIX.
```
path_size: input, COUNT path size;
```
Number of bytes to be allocated to the path.
```
path_name: input, TEXT path name [];
```
Name to be assigned to the path. Other processes will send to the path using this name.
```
type: input, CODE type;
```
Temporary (TMPMBX) or permanent (PRMBMX). For UNIX, TMPMBX means to automatically delete the socket on disconnect.

Under the server model, c_crepath is used to create the input queue. By convention, the name of the input queue is the job name.

7.2 c_delpath - Delete Path

VOID c_delpath (path)

Function return:

SUCCESS - Path deleted successfully.
FAIL - Path could not be deleted. If FAIL, then the path.errmsg field contains a host-dependent error message string and the path.host_code field contains a host-dependent integer error code.

Arguments:

```
path: input/output, struct PATH *path;
```
Context block for the path to be deleted.

7.3 c_getmsg - Receive Message

CODE c_getmsg(path, buffer, size)

Function return:

SUCCESS - Message received successfully.
FAIL - Message not received. If FAIL, then the path.errmsg field contains a host-dependent error message string and the path.host_code field contains a host-dependent integer error code.

Arguments:

```
path: input/output, struct PATH *path;
```
The context block for the path from which a message is to be received.
```
buffer: input, GENPTR buffer;
```
Buffer to receive the incoming message.
```
size: output, COUNT *size;
```
The size (in bytes) of the received message is returned in this parameter's data item.

This message transmission call is blocking, i.e., the calling program is suspended until a message is received.

7.4 c_pmwcd - Put Message with Connect/Disconnect

VOID c_pmwcd (path_name, buffer, size, errmsg)

Function return:

SUCCESS - Message Sent successfully.
FAIL - Message could not be sent or could not connect or disconnect. If FAIL, then the path.errmsg field contains a host-dependent error message string and the path.host_code field contains a host-dependent integer error code.

Arguments:

```
path_name: input, TEXT path name [];
```
Name of the path to receive the message.
```
buffer: input, GENPTR buffer;
```
Pointer to a buffer to be transmitted to the path.
```
size: input, COUNT size;
```
Number of bytes to be transmitted.
```
errmsg: output, TEXT errmsg[];
```
If the transmission fails, this string contains a host-dependent error description string.

This message transmission function will connect with the desired path before sending the message and disconnect afterward. The function is non-blocking, i.e., the calling program continues to execute immediately after the message has been queued to the destination path.