p4GetTaskStatus() |
DEVELOPER |
 |
p4GetTaskStatus()
Inquire on Task Status
Task Utility
Introduction
The P4API p4GetTaskStatus() function is used to retrieve the error status variables returned by the last p4ExecTask() call for the kernel session identified by kernelSessionHandle.
BOOL p4GetTaskStatus (
SESSION_HANDLE_T kernelSessionHandle
const char *sStatusVarsFormat,
int *pnStatusVars,
int nStatusVarsLenIn,
int *pnStatusVarsMaxLenOut,
char *sStatusVars
);
Parameters
kernelSessionHandle
[in] The kernel session id for a PROIV Virtual Machine session, as returned by a prior call to p4OpenPro4().
sStatusVarsFormat
[in] This describes the format of the szStatusVars parameter. See Remarks below for details. Valid values are:
D, Delimiter Separated List Stream Format, with the second and subsequent bytes being the delimiter string. Note that the delimiter string can be more than one character long, which may be useful for multi-byte character sets.
L Length Prefixed Stream Format.
pnStatusVars
[in out] Number of parameters in the Task Status Variables List sStatusVars.
Ignored for sStatusVarsFormat D.
On return, this will be updated to indicate the number of status variables that were returned.
nStatusVarsLenIn
[in] The total length of the Task Status Variables List sStatusVars in bytes.
For sStatusVarsFormat D, if zero is specified then the first NUL byte in sStatusVars is used to detect the end of the list.
pnStatusVarsMaxLenOut
[in out] The maximum total length (in bytes) allowed for the status variables in the Task Status Variables List sStatusVars (namely, the size of the callers buffer).
sStatusVars
[in out] The Task Status Variables List. See Remarks below for the format of this parameter. Undergoes codeset conversion if p4SetCode() is active.
Return Values
If no error occurs, p4GetTaskStatus() returns TRUE. Otherwise, it returns a value of FALSE, and a specific error code can be retrieved by calling p4GetLastError().
Remarks
p4GetTaskStatus() is used to retrieve the Task Status Variable values for the last PROIV Task executed in the requested PROIV Virtual Machine session.
When a p4ExecTask() call return a fail status, the application should call p4GetLastError() to find out why it failed. If this returns P4AERR_KERNELSTATUS, indicating that the kernel returned an error, then the application should call p4GetTaskStatus() to get the detailed kernel error codes and messages.
The szStatusVars parameter specifies the Task Parameter List. This is returned in the same format as the Task Parameter List and System Environment Variables parameters of p4ExecTask().
The list of variable names is the same as the error status system variables supported by the kernel, plus some extra variables (@FUNCT, etc) that are useful for identifying where the error occurred. Currently, these are:
System Variable Names
|
Variable Name |
Length |
Description |
|
@MSG |
4 |
PROIV message number |
|
@MSGTEXT |
80 |
Text description for @MSG |
|
@MSGARGS |
80 |
Parameters for @MSG |
|
@ERR |
12 |
Portable error code |
|
@ERRTEXT |
80 |
Text description for @ERR |
|
@ERRARGS |
80 |
Parameters for @ERR |
|
@SYSERR |
20 |
Native error code |
|
@SYSERRTEXT |
250 |
Text description for @SYSERR |
|
@RETCD |
8 |
As for Mainframe |
|
@FUNCT |
8 |
Function that was executing at task termination |
|
@PFUNCT |
8 |
Previous function to @FUNCT |
|
@OPR |
3 |
Users PROIV Operator-Id |
|
@COMP |
3 |
Users PROIV Company/Division Code |
|
@TERM |
8 |
Users PROIV Terminal-id |
See Task Parameter List and System Environment Variables List for p4ExecTask(), for a description of the formats supported for the szStatusVars parameter.
Topic ID: 540189