DosFlagProcess
 Legacy Function Warning
| |
|---|---|
| It is recommended to use a newer replacement for this function. | |
| Replacement: | N/A |
| Remarks: | This function has been eliminated since OS/2 2.0. [1] |
This call allows one process to set an external event flag for another.
Syntax
DosFlagProcess (ProcessID, ActionCode, Flagnum, Flagarg)
Parameters
- ProcessID (PID) - input
- ID of the process or root process of the process tree, who is to receive notification that the flag event has occurred.
- ActionCode (USHORT) - input
- Indicates who is to receive notification that the flag event has occurred.
- 0 - The indicated process and all its descendant processes are flagged. (Detached processes cannot be flagged.) The indicated process must be the current process or one it has created as a non-detached process. If the indicated process terminates, its descendants are still flagged.
- 1 - Only the indicated process is flagged. Any process can be specified.
- Flagnum (USHORT) - input
- Number of the flag event whose occurrence is to be signalled, as shown below:
- 0 Flag A
- 1 Flag B
- 2 Flag C.
- Flagarg (USHORT) - input
- An argument passed to indicated processes.
Return Code
- rc (USHORT) - return
- Return code descriptions are:
- 0 NO_ERROR
- 1 ERROR_INVALID_FUNCTION
- 156 ERROR_SIGNAL_REFUSED
- 186 ERROR_INVALID_FLAG_NUMBER
- 303 ERROR_INVALID_PROCID
Remarks
A process issues DosFlagProcess to set one of three user-defined flags available to the process. The meaning of the flag is defined by the flag user - the process that receives the signal generated by the OS/2 signal mechanism upon the setting of the flag.
When the flag user is signaled, its reaction to the signal depends on values it has specified with DosSetSigHandler. For example, it can respond by giving control to a signal handler it has registered with DosSetSigHandler for the signal that corresponds to the user flag (SIGPFA corresponds to Flag A, and so on). Or, the flag user can ignore the signal and return an error code to the flagger.
If no action is specified with DosSetSigHandler by a process for a user flag, the default is to ignore the signal.
Bindings
C
#define INCL_DOSSIGNALS USHORT rc = DosFlagProcess(ProcessID, ActionCode, Flagnum, Flagarg); PID ProcessID; /* Process ID to flag */ USHORT ActionCode; /* Indicate to flag descendants */ USHORT Flagnum; /* Flag number */ USHORT Flagarg; /* Flag argument */ USHORT rc; /* return code */
MASM
EXTRN DosFlagProcess:FAR INCL_DOSSIGNALS EQU 1 PUSH WORD ProcessID ;Process ID to flag PUSH WORD ActionCode ;Indicate to flag descendants PUSH WORD Flagnum ;Flag number PUSH WORD Flagarg ;Flag argument CALL DosFlagProcess Returns WORD
Example
This example starts a program named 'simple2.exe', and then signals the program with the external flag A.
#define INCL_DOSPROCESS
#define INCL_DOSSIGNALS
#define PROGRAM_NAME "simple2.exe"
CHAR LoadError[100];
PSZ Args;
PSZ Envs;
RESULTCODES ReturnCodes;
USHORT FlagArg;
USHORT rc;
FlagArg = 2;
if(!DosExecPgm(LoadError, /* Object name buffer */
sizeof(LoadError), /* Length of object name buffer */
EXEC_ASYNC, /* Asynchronous/Trace flags */
Args, /* Argument string */
Envs, /* Environment string */
&ReturnCodes, /* Termination codes */
PROGRAM_NAME)) /* Program file name */
rc = DosFlagProcess(ReturnCodes.codeTerminate, /* Process ID to
flag */
FLGP_PID, /* Indicate to flag
descendants */
PFLG_A, /* Flag number */
FlagArg); /* Flag argument */
The following example illustrates the use of a user-defined flag to signal time-critical events. The main thread installs a routine, named FlagA_Handler(), as the signal handler for user-defined Flag A. It then creates a thread and blocks on a reserved RAM semaphore; this thread obtains its process ID and signals the main thread via Flag A. The main thread responds by executing the signal handler.
#define INCL_DOSPROCESS
#define INCL_DOSSIGNALS
#define INCL_DOSERRORS
#include <os2.h>
#define TIMEOUT 5000L
TID ThreadID;
BYTE ThreadStack[4000];
VOID APIENTRY FlagA_Handler(arg1, arg2) /* Define signal handler */
USHORT arg1;
USHORT arg2;
{
printf("Handler for Flag A now running.\n");
return;
}
VOID APIENTRY Thread_A()
{
PIDINFO PidInfo;
USHORT FlagArg;
USHORT rc;
DosGetPID(&PidInfo);
printf("Process ID is %d\n", PidInfo.pid);
if(!(rc = DosFlagProcess(PidInfo.pid,
FLGP_PID,
PFLG_A,
FlagArg)))
printf("FlagA signal sent from ThreadA to main thread.\n");
else
printf("FlagProcess rc is %d\n", rc)/* Error processing on rc */;
DosExit(EXIT_THREAD, /* Action Code */
RETURN_CODE); /* Result Code */
}
main()
{
ULONG RamSem = 0L;
ULONG far *RamSemHandle = &RamSem;
USHORT rc;
if(!(rc=DosSetSigHandler((PFNSIGHANDLER) FlagA_Handler,
NULL,
NULL,
SIGA_ACCEPT,
SIG_PFLG_A)))
printf("Main thread has set FlagA handler.\n");
else
/* Error processing on rc */;
if(!(rc=DosSemRequest(RamSemHandle,
TIMEOUT)))
printf("Semaphore obtained.\n");
if(!(DosCreateThread((PFNTHREAD) Thread_A,
&ThreadID,
&ThreadStack[3999])))
printf("ThreadA created.\n");
printf("Main thread will now wait on a Ramsem for a while.\n");
if((rc=DosSemRequest(RamSemHandle,
TIMEOUT))
== ERROR_INTERRUPT)
printf("Main thread interrupted while waiting, rc is %d.\n", rc);
}