HP-UX Reference (11i v2 07/12) - 3 Library Functions N-Z (vol 7)

p
prcmd(3N) prcmd(3N)
Usage Notes
Once a connection is made, and a host is in one of the
PRC_READ_* states, control of the "conversation"
between the calling program and remote host belongs to the calling program. Conversations are of two
types:
1. calling program communicates first
2. remote command communicates first
If the calling program communicates first, it must use the
prc_caller_status
field, or other means,
to remember whether or not it has sent initial data to the command; and it must send that data upon the
host entering the
PRC_READ_WAIT
state the first time. If the command communicates first, or in any
conversation after the calling program sends initial data, the calling program must "track" the conversation
to know when to send more data, if any, and when to close the conversation by setting
prc_conn_close
.
Before the calling program can send the next input, or close the connection, it might have to wait through a
series of
PRC_READ_WAIT
and PRC_READ_READY
states (until all bytes of a single response from a
command are received).
After each
prcmd() call, the calling program should check the return value for a serious error. If the
return value is PRC_OK, the calling program should next scan the hostp array and check
prc_prev_status (if desired) and
prc_conn_status fields for each host. The calling program
only needs to take action for certain status values (marked with a asterisk (
*) below).
PRC_CONN_NONE After the first
prcmd() call: Indicates the process ran out of socket (file) descrip-
tors, or reserved ports, after making at least one (still open) connection (in this call, or
in a previous call). Connection to this host is attempted again on the next call. The
calling program can increase the number of available file descriptors (by closing files
or calling
rlimit()), or wait for existing connections to finish their communica-
tions.
PRC_CONN1_WAIT
PRC_CONN2_WAIT
PRC_CONN3_WAIT
These are internal states of little interest to the calling program. No action is needed
except to call prcmd() again later. If (prc_prev_status !=
prc_conn_status)
, the calling program might log/display the host’s new status.
PRC_READ_WAIT *
Command is running but has not yet produced output. If the calling program com-
municates first, meaning the command needs some initial input, write it to the file
specified by prc_fp and remember that this was done, probably by using the
prc_caller_status
field. Otherwise no action is required, except maybe to
log/display the connection’s status.
PRC_READ_READY *
Command produced output that is ready for reading. After reading the output, if the
command needs more input, write it now to the file specified by
prc_fp
.Ifinstead
the conversation is done, set the
prc_conn_close
field non-zero.
PRC_CONN_DONE Command is done; connection was closed in response to the calling program setting
the
prc_conn_close field. No action is required.
The calling program can use (prc_conn_status & PRC_CSBIT_ERR)
to quickly detect any error
status. It can use
(prc_prev_status != prc_conn_status)
to detect that any failure condi-
tion is new so it is only handled once, or use
prc_caller_status to record that it was processed the
first time it appears in a return from
prcmd(). In each case the calling program should handle or report
the error as desired.
PRC_CONN_NO_IPS *
The prc_hostid field appears to be a name, not an address, and gethost-
byname()
fails for it, or inet_addr() fails on a numeric prc_hostid value.
The remaining conditions only refer to the cause of failure on the last of the host’s IP addresses, if it has
more than one.
PRC_CONN_FAILED *
Connection could not be initiated for some reason (on any of the host’s IP addresses)
154 Hewlett-Packard Company − 5 − HP-UX 11i Version 2: December 2007 Update