p4ExecTask()

Execute Task on Specified Kernel

Task Execution Calls

Introduction

The P4API p4ExecTask() function is used to request execution of a task by the kernel session identified by kernelSessionHandle.

BOOL p4ExecTask (
   SESSION_HANDLE_T kernelSessionHandle
   const char *szTaskName,
   const char *sParamFormat,
   int *pnParams,
   int nParamLenIn,
   int *pnParamMaxLenOut,
   char *sParams,
   int *pnSysEnvVars,
   int nSysEnvVarsLenIn,
   int *pnSysEnvVarsMaxLenOut,
   char *sSysEnvVars
);

Parameters

kernelSessionHandle

[in] The kernel-session-id for a PROIV Virtual Machine session, as returned by a prior call to p4OpenPro4().

szTaskName

[in] The name of the required PROIV task. Undergoes codeset conversion if p4SetCode() is active.

sParamFormat

[in] This describes the format of the szParams and szSysEnvVars parameters. (See the Remarks section below for details.) Valid values are:

D, Delimiter Separated List Stream Format, with the second and subsequent bytes being the delimiter string. In this example, the delimiter is a comma. Note that the delimiter string can be more than one character long, which may be useful for multi-byte character sets. Certain control characters (in the ASCII range 0x00 0x1F) can be specified as follows:

D\t specifies a delimiter of TAB (Control-I, ASCII codepoint 9.)

D\n specifies a delimiter of LF (Control-J, ASCII codepoint 12.)

D\r specifies a delimiter of CR (Control-M, ASCII codepoint 13.)

L Length Prefixed Stream Format.

pnParams

[in out] Number of parameters in the task parameters list sParams.

Ignored for sParamFormat D.

On return, this will be updated to indicate the number of output parameters.

nParamLenIn

[in] The total length of the task parameter list sParams in bytes.

For sParamFormat D, if zero is specified then the first NUL byte in sParams is used to detect the end of the list.

Ignored for sParamFormat A, as the input size is indicated at the start of each parameter.

pnParamMaxLenOut

[in out] The maximum total length (in bytes) allowed for the output parameters in the Task parameter list sParams (namely, the size of the callers buffer). This parameter is updated to reflect the length of the returned data.

sParams

[in out] The task parameter list. See below for the format of this parameter. Undergoes codeset conversion if p4SetCode() is active.

pnSysEnvVars

This parameter is currently unused but reserved, and must be set to zero for all calls.

[in out] Number of parameters in the System Variable Values list sSysEnvVars.

Ignored for sParamFormat D.

On return, this will be updated to indicate the number of changed values of the System Variables that have been returned.

nSysEnvVarsLenIn

This parameter is currently unused but reserved, and must be set to zero for all calls.

[in] The total length of the System Variable Values list sSysEnvVars.

For sParamFormat D, if zero is specified then the first NUL byte in sParams is used to detect the end of the list.

pnSysEnvVarsMaxLenOut

This parameter is currently unused but reserved, and must be set to zero on all calls.

[in out] The maximum total length allowed for the output parameters in the System Variable Values list sSysEnvVars (namely, the size of the callers buffer).

sSysEnvVars

[in out] The PROIV System Variable Values to initialise for the Task. For more information, see Table 12. System Variable Names, page 112. This has the same format as szParams. The variable names are limited to a subset of the PROIV System Value Variables. Undergoes codeset conversion if p4SetCode() is active.

For the first release, no variable values will be returned (they are all treated as In parameters).

Return Values

If no error occurs, p4ExecTask() returns TRUE. Otherwise, it returns a value of FALSE, and a specific error code can be retrieved by calling p4GetLastError().

Remarks

p4ExecTask() is used to execute a PROIV Task in the requested PROIV Virtual Machine environment.

p4SystemLogon() must first be called to establish a connection with a PROIV Virtual Machine. This returns the value of kernelSessionHandle. p4OpenPro4() must then be called. Once this is done, multiple p4ExecTask() calls can be made against the same or different tasks using the same environment on the same machine as specified in the kernelSessionHandle.

The szParams parameter specifies the Task Parameter List. This can be specified in one of two different formats as defined by the sParamFormat parameter.

The kernel will validate the operator-ID, company/division code and password combination.

Comment on this topic

Topic ID: 540186