Jump to content

DosFlagProcess: Difference between revisions

From EDM2
Ak120 (talk | contribs)
Ak120 (talk | contribs)
mNo edit summary
Line 1: Line 1:
[[image:legacy.png]]
This call allows one process to set an external event flag for another.
This function has been eliminated since OS/2 2.0 [https://books.google.com.ec/books?id=u7WbsmbttwYC&pg=PT372&lpg=PT372&dq#v=onepage&q&f=false]


==Description==
This function has been eliminated since OS/2 2.0.
This call allows one process to set an external event flag for another.  


==Syntax==
==Syntax==
<PRE>
  DosFlagProcess (ProcessID, ActionCode, Flagnum, Flagarg)
  DosFlagProcess


    (ProcessID, ActionCode, Flagnum, Flagarg)
</PRE>
==Parameters==
==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.  
;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.
; 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.
'''Value        Definition'''
::1 - Only the indicated process is flagged. Any process can be specified.
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:
; Flagnum (USHORT) - input : Number of the flag event whose occurrence is to be signalled as shown below:
  '''Value    Definition'''
  '''Value    Definition'''
  0            Flag A
  0            Flag A
  1            Flag B
  1            Flag B
  2            Flag C.  
  2            Flag C.  
; Flagarg (USHORT) - input : An argument passed to indicated processes.


; Flagarg (USHORT) - input : An argument passed to indicated processes.
==Return Code==
==Return Code==
  rc (USHORT) - return
  rc (USHORT) - return
Return code descriptions are:
Return code descriptions are:
* 0          NO_ERROR  
* 0          NO_ERROR  
* 1          ERROR_INVALID_FUNCTION  
* 1          ERROR_INVALID_FUNCTION  
Line 38: Line 26:
* 186        ERROR_INVALID_FLAG_NUMBER  
* 186        ERROR_INVALID_FLAG_NUMBER  
* 303        ERROR_INVALID_PROCID
* 303        ERROR_INVALID_PROCID
==Remarks==
==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.
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.
Line 92: Line 81:
                           FlagArg);                  /* Flag argument */
                           FlagArg);                  /* Flag argument */
</PRE>
</PRE>
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.  
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.
 
<PRE>
<PRE>
#define INCL_DOSPROCESS
#define INCL_DOSPROCESS
Line 180: Line 168:
*  
*  


 
[[Category:Dos]]
[[Category:The OS/2 API Project]]

Revision as of 10:06, 14 February 2017

This call allows one process to set an external event flag for another.

This function has been eliminated since OS/2 2.0.

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:
Value     Definition
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.

Example Code

C Binding

#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 */

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);
}

MASM Binding

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

Related Functions