processScreenRequired()

User-Supplied Function for Client Handling

Screen Output

Introduction

The caller supplied function processScreenRequired() is called when the kernel requires a Screen Client to process screen input or output. The actual name of the function can be anything: the name used is specified on a call to p4SetScreenRequestFunction().

int processScreenRequired (
   SESSION_HANDLE_T sessionHandle,
   BOOL bGuiMode,
   const char *szHostName,
   int nClientPort,
   const char *pCommand,
   const char *pCommandDir
);

Parameters

kernelSessionHandle

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

bGuiMode

[in] Flag to indicate whether a GUI mode Client or Green screen mode Client is required. 0 indicates a green screen Client, 1 is a GUI Client.

szHostName

[in] The DNS Name or IP address of the kernel to connect to.

nClientPort

[in] The port number of the kernel to connect to.

pCommand

[in] The command line to use to start the Client.

pCommandDir

[in] The directory to use to start the Client in.

Return Values

The function should return:

Value	Meaning
0	Screen Client was started successfully.
1	Function wants the kernel to do its default processing
any other value	Error has occurred.

Remarks

The bGuiMode value is defined by the kernel session settings in the same way as for non-Pro4 Bus sessions. (i.e. the Terminal Type set in $TERM or defined via the PROTERM environment variable, and the GUI environment variable if specified). For green screen Clients (i.e. a Telnet Client), the kernel will carry out Telnet negotiations to determine the actual green screen terminal type.

The pCommand value is the command line to execute to start up the screen Client. It is the value of the P4API_CLIENT_CMD environment variable setting on the machine running the API (if not specified, the default value telnet %s %d will be passed). This would normally only be used for green screen Clients, and may be ignored by the function if it chooses. Note that this is a sprintf type string, with the first substitution variable (%s) occurring where the hostname is expected, and the second (%d) occurring where the port number is expected. See the example code below.

The pCommandDir value is the directory to use to execute the command line from. It is the value of the P4API_CLIENT_DIR environment variable setting on the machine running the API (the default value is a pointer to a null string). This would normally only be used for green screen Clients, and may be ignored by the function if it chooses.

An example screen request function follows. Note that the green screen action is equivalent to what P4API does if no report output processor is defined. For GUI Mode this example returns a status code back to the API to tell it to do its default processing. (The default API processing for starting a GUI screen Client is to use the PROIV.EXE COM Interface to start it.)

int
processScreenRequired(
   SESSION_HANDLE_T hKrnlSession,
   BOOL bGuiMode,
   const char *szHostMachine,
   int nClientPort,
   const char *pCommand,
   const char *pCommandDir)
{
int nStat;/* return status code */

/*printf("processScreenRequired: entry, session %lu, Gui %d, \
       Host '%s', Port %d, Cmd '%s', Dir '%s'\n",
       (unsigned long) sessionHandle, bGuiMode, szHostMachine,
       nClientPort, pGreenCmd, pGreenDir);
*/
if (bGuiMode) {
   /* can't cope with starting a GUI Client, so let the API do it */
   nStat = 1;
}
else {
   char cmdbuf[256];
   /* format the command line to insert the hostname & port: */
   sprintf(cmdbuf, pCommand, szHostMachine, nClientPort);
   nStat = system(cmdbuf);
   if (nStat != 0) {
       fprintf(stderr,
       "processScreenRequired: system('%s') returned stat %d\n",
       cmdbuf, nStat);
       /* return 0 as telnet seems to return non-zero when it succeeds
       * on some Unixes: */
       nStat = 0;
      }
}
return nStat;
}

There is no call to terminate the Client. p4GetLastError().

Comment on this topic

Topic ID: 540196