Syntax
#include <sys/types.h>
#include <sys/socket.h>
int givedescriptor(int descriptor,
char *target_job)
Threadsafe: Yes
|
The givedescriptor() function is
used to pass a
descriptor
from one OS/400 job to another OS/400 job.
Parameters
- descriptor
- (Input) The descriptor that is to be passed to the
target job.
- target_job
- (Input) A pointer to the internal job identifier of the
target job that is to receive the descriptor referenced by the
descriptor parameter.
Authorities
To give a descriptor, the source thread must be
running under one of the following user profiles:
- A user profile that is the same as the job user
identity of the target job
- A user profile that has all object (*ALLOBJ)
special authority
The job user identity
is the name of the user
profile by which a job is known to other jobs. It is described
in more detail in the
Work Management book.
Return Value
givedescriptor() returns an integer. Possible values are:
- -1 (unsuccessful)
- 0 (successful)
Error Conditions
When givedescriptor() fails, errno
can be set to one of the following:
- [EACCES]
- Permission denied.
The job does not have the appropriate privileges required to give
the descriptor.
- [EBADF]
- Descriptor not valid.
- [EFAULT]
- Bad address.
The system detected an address which
was not valid while attempting to access the target_job parameter.
- [EINVAL]
- Parameter not valid.
This error code indicates one of the following:
- The target_job parameter points to data that is not valid.
- The target_job parameter refers to a job that is not active.
- [EIO]
- Input/output error.
- [EOPNOTSUPP]
- Operation not supported.
The underlying instance represented by the descriptor
does not support passing access rights.
- [EUNKNOWN]
- Unknown system state.
Error Messages
- CPE3418 E
- Possible APAR condition or hardware failure.
- CPF9872 E
- Program or service program &1
in library &2 ended. Reason code &3.
- CPFA081 E
- Unable to set return value or error code.
Usage Notes
-
The information to specify in the target_job parameter can be
obtained in the actual target job by
using a work management API (for
example, QUSRJOBI) to retrieve the
internal job identifier.
It is
the responsibility of the application programmer to privately pass
this information from the target job to the job that issues the
givedescriptor(). One possible method that could be used to exchange this
information is to use data queues.
-
The target_job does not have to be waiting on a takedescriptor()
for the givedescriptor() to complete successfully.
-
If both the job in which the givedescriptor() is issued and the
target_job end while a descriptor is in transit, the
descriptor is reclaimed by the system, and the resource that it
represents is closed.
-
For files and directories, givedescriptor() is only supported for objects
in the root and QOpenSys file systems.
Related Information