home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD2.mdf / c / library / dos / diverses / text_cla / mos.man < prev    next >
Encoding:
Text File  |  1992-05-12  |  10.7 KB  |  531 lines
  1. NAME
  2.         MosInit - Initialize MOS environment from application.
  3.  
  4. SYNOPSIS
  5.  
  6.         #include <mos.h>
  7.  
  8.         SHORT
  9.         MosInit()
  10.  
  11. DESCRIPTION
  12.  
  13.         MOS internal variables and data structures are initialized
  14.         for subsequent application calls to MOS functions.
  15.  
  16.  
  17.         C_STATUS = MosInit();
  18.  
  19.  
  20. RESOURCE NAME
  21.  
  22.         MOS.LIB
  23.  
  24. DIAGNOSTICS
  25.  
  26.         C_OK      = initialized successful
  27.         C_NOTOK = initialization unsuccessful
  28.  
  29.  
  30. NAME
  31.         MosProcCreate - create a procedure in the MOS environment.
  32.  
  33. SYNOPSIS
  34.  
  35.         #include <mos.h>
  36.  
  37.         SHORT
  38.         MosProcCreate(pProc,szProcName,sPriority)
  39.         SHORT (*pProc)(PROC_P psProc);
  40.         PCHAR szProcName;
  41.         SHORT sPriority;
  42.  
  43. DESCRIPTION
  44.  
  45.         C function pointed to by pProc is announced to the MOS
  46.         environment as a new process.  It is named by szProcName
  47.         and given sPriority process priority.  All functions used
  48.         as MOS processes as of type SHORT (*) (PROC_P).  The PROC_P
  49.         is a pointer to a MOS specific process structure.
  50.       
  51. RESOURCE NAME
  52.  
  53.         MOS.LIB
  54.  
  55. DIAGNOSTICS
  56.  
  57.         C_OK      - initialization successful.
  58.         !C_OK     - error
  59.  
  60.  
  61. NAME
  62.         MosProcTerm - removes process from MOS environment.
  63.  
  64. SYNOPSIS
  65.  
  66.         #include <mos.h>
  67.  
  68.         SHORT
  69.         MosProcTerm(pProc)
  70.         PROC_P pProc;
  71.  
  72. DESCRIPTION
  73.  
  74.         MOS will remove from all data structures the process described
  75.         by pProc.  MosProcTerm() is usually called by the terminating
  76.         process itself.
  77.       
  78. RESOURCE NAME
  79.  
  80.         MOS.LIB
  81.  
  82. DIAGNOSTICS
  83.  
  84.         C_OK    = process terminated
  85.         !C_OK   = error
  86.  
  87. NAME
  88.         MosScheduler - The MOS process scheduler. 
  89.  
  90. SYNOPSIS
  91.  
  92.         #include <memincs.h>
  93.  
  94.         SHORT
  95.         MosScheduler()
  96.  
  97. DESCRIPTION
  98.  
  99.         It is the MOS process scheduler (multi-tasker) and is called
  100.         when all initial processes have been created.  It does not return
  101.         until all processes (other than the NULL process) have terminated.
  102.         
  103.  
  104.         C_STATUS = MosInit();
  105.  
  106.         C_STATUS = MosProcCreate(TestProc,"TEST_PROC,10);
  107.  
  108.         C_STATUS = MosScheduler();
  109.  
  110.  
  111. RESOURCE NAME
  112.  
  113.         MOS.LIB
  114.  
  115. DIAGNOSTICS
  116.  
  117.         C_OK      - always returned
  118.  
  119.  
  120. NAME
  121.         MemSemInit - initialize a new semaphore
  122.  
  123. SYNOPSIS
  124.  
  125.         #include <mos.h>
  126.  
  127.         SHORT
  128.         MosSemInit(pstProc,pcSemName,psSemHandle)
  129.         PROC_P pstProc;
  130.         PCHAR  pcSemName;
  131.         PSHORT psSemHandle;
  132.  
  133. DESCRIPTION
  134.  
  135.         Process pstProc creates semaphore with name pcSemName.
  136.         A handle to the newly created semaphore is returned in
  137.         psSemHandle.
  138.       
  139. RESOURCE NAME
  140.  
  141.         MOS.LIB
  142.  
  143. DIAGNOSTICS
  144.  
  145.         C_OK    - semaphore created
  146.         !C_OK   - error
  147.  
  148.  
  149. NAME
  150.         MosSemTerm - terminate a semaphore
  151.  
  152. SYNOPSIS
  153.  
  154.         #include <mos.h>
  155.  
  156.         SHORT
  157.         MosSemTerm(pstProc,pcSemName,sSemHandle)
  158.         PROC_P pstProc;
  159.         PCHAR pcSemName;
  160.         SHORT sSemHandle;
  161.  
  162. DESCRIPTION
  163.  
  164.         Removes a semaphore from MOS memory when it is no longer 
  165.         needed.
  166.  
  167.         MOS process pstProc requests termination of semaphore
  168.         named pcSemName with handle sSemHandle.
  169.       
  170. RESOURCE NAME
  171.  
  172.         MOS.LIB
  173.  
  174. DIAGNOSTICS
  175.  
  176.         C_OK    - semaphore terminated
  177.  
  178.  
  179. NAME
  180.         MosSemWait - wait for ownership of a semaphore
  181.  
  182. SYNOPSIS
  183.  
  184.         #include <mos.h>
  185.  
  186.         SHORT
  187.         MosSemWait(pstProc,sSemHandle)
  188.         PROC_P pstProc;
  189.         SHORT sSemHandle;
  190.  
  191. DESCRIPTION
  192.  
  193.         Process pstProc requests ownership to semaphore sSemHandle.
  194.         If a semaphore is currently in use by another process, the
  195.         requesting process will be placed in a semaphore-waiting
  196.         queue.  All queued semaphore requests are in FIFO order.
  197.         If a process is placed in the wait queue, it is placed back
  198.         on the ready queue with ownership of the semaphore.
  199.  
  200.  
  201.  
  202.         MosSemInit(pstProc,"Sem1",&sSemHandle);
  203.  
  204.         MosSemWait(pstProc,sSemHandle);
  205.  
  206.         ... other processing which required semaphore ...
  207.  
  208.         MosSemSignal(pstProc,sSemHandle);
  209.  
  210.  
  211.         If MosSemWait() returns MOS_PROC_SUSPENDED, this means that the
  212.         semaphore was not available and the process has been suspeneded.
  213.         The process must immediately C_LEAVE(C_OK).
  214.  
  215.  
  216.  
  217. RESOURCE NAME
  218.  
  219.         MOS.LIB
  220.  
  221. DIAGNOSTICS
  222.  
  223.         C_OK      - always returned
  224.  
  225.  
  226. NAME
  227.         MosSemSignal - release ownership of semaphore
  228.  
  229. SYNOPSIS
  230.  
  231.         #include <mos.h>
  232.  
  233.         SHORT
  234.         MosSemSignal(pstProc,sSemHandle)
  235.         PROC_P pstProc;
  236.         SHORT sSemHandle;
  237.  
  238. DESCRIPTION
  239.  
  240.         Process pstProc releases ownership of a semaphore sSemHandle.
  241.         Semaphore sSemHandle is then available for another process
  242.         waiting for it with a MosSemWait().
  243.         
  244.       
  245. RESOURCE NAME
  246.  
  247.         MOS.LIB
  248.  
  249. DIAGNOSTICS
  250.  
  251.         C_OK      - always returned
  252.  
  253. NAME
  254.         MosSemClear - clears a semaphore and releases it
  255.  
  256. SYNOPSIS
  257.  
  258.         #include <mos.h>
  259.  
  260.         SHORT
  261.         MosSemClear(pstProc,sSemHandle)
  262.         PROC_P pstProc;
  263.         SHORT sSemHandle;
  264.  
  265. DESCRIPTION
  266.  
  267.         Process pstProc clears semaphore sSemHandle. 
  268.  
  269.         MosSemClear is very similar to MosSemSignal but is a 
  270.         different semaphore scheme.  MosSemWait/MosSemSignal
  271.         provide a mechanism for resource exclusivity.  MosSemClear/
  272.         MosSemSet provide a mechanism for process synchronization.
  273.         A synchronizing semaphore scheme is implemented in MFM.
  274.  
  275.         
  276.  
  277. RESOURCE NAME
  278.  
  279.         MOS.LIB
  280.  
  281. DIAGNOSTICS
  282.  
  283.         C_OK      - always returned
  284.  
  285.  
  286. NAME
  287.         MosSemSet - set semaphore to 1
  288.  
  289. SYNOPSIS
  290.  
  291.         #include <mos.h>
  292.  
  293.         SHORT
  294.         MosSemSet(pstProc,sSemHandle)
  295.         PROC_P pstProc;
  296.         SHORT sSemHandle;
  297.  
  298. DESCRIPTION
  299.  
  300.         Process pstProc sets semaphore sSemHandle.  MosSemSet is used
  301.         in conjunction with MosSemClear.
  302.  
  303. RESOURCE NAME
  304.  
  305.         MOS.LIB
  306.  
  307. DIAGNOSTICS
  308.  
  309.         C_OK    - always returned
  310.  
  311.  
  312. NAME
  313.         MosCurTime - get the current time
  314.  
  315. SYNOPSIS
  316.  
  317.         #include <mos.h>
  318.  
  319.         LONG
  320.         MosCurTime()
  321.  
  322. DESCRIPTION
  323.  
  324.         Returns the current time in seconds since Jan 1, 1970.
  325.  
  326. DIAGNOSTICS
  327.  
  328.         Current time returned.
  329.  
  330.  
  331. NAME
  332.         MosSleep - a process puts itself to sleep
  333.  
  334. SYNOPSIS
  335.  
  336.         #include <mos.h>
  337.  
  338.         SHORT
  339.         MosSleep(pstProc)
  340.         PROC_P pstProc;
  341.  
  342. DESCRIPTION
  343.  
  344.         Process pstProc places itself on the sleep queue.  Before the
  345.         MosSleep call, the process will set its wakeup time with
  346.         MOS_SET_WAKE_TIME.
  347.  
  348. RESOURCE NAME
  349.  
  350.         MOS.LIB
  351.  
  352. DIAGNOSTICS
  353.  
  354.         C_OK      - always returned
  355.  
  356.  
  357. NAME
  358.         MosGetPidByName - get the process id of another process
  359.  
  360. SYNOPSIS
  361.  
  362.         #include <mos.h>
  363.  
  364.         SHORT
  365.         MosGetPidByName(pcName,psPid)
  366.         PCHAR pcName;
  367.         PSHORT psPid;
  368.  
  369. DESCRIPTION
  370.  
  371.         Process named pcName is searched for in the MOS environment.
  372.         Parameter psPid will be set to the process id of the process
  373.         if found or MOS_PROC_NULL if the process does not exist.
  374.  
  375. RESOURCE NAME
  376.  
  377.         MOS.LIB
  378.  
  379. DIAGNOSTICS
  380.  
  381.         C_OK    - always returned
  382.  
  383.  
  384.  
  385. NAME
  386.         MosMsgWrite - write a message to another processes message queue
  387.  
  388. SYNOPSIS
  389.  
  390.         #include <mos.h>
  391.  
  392.         SHORT
  393.         MosMsgWrite(pstProc,pcData,sLen,sTargetProcId)
  394.         PROC_P pstProc;
  395.         PCHAR  pcData;
  396.         SHORT  sLen;
  397.         SHORT  sTargetProcId;
  398.  
  399. DESCRIPTION
  400.  
  401.         Process pstProc sends data pcData for length sLen to process
  402.         sTargetProcId.  The target process id can be found with
  403.         MosGetPidByName.
  404.  
  405. RESOURCE NAME
  406.  
  407.         MOS.LIB
  408.  
  409. DIAGNOSTICS
  410.  
  411.         C_OK    - message delivered
  412.         !C_OK   - error
  413.  
  414.  
  415. NAME
  416.         MosMsgRead - read a message on the current processes message queue
  417.  
  418. SYNOPSIS
  419.  
  420.         #include <mos.h>
  421.  
  422.         SHORT
  423.         MosMsgRead(pstProc,ppstMsg)
  424.         PROC_P pstProc;
  425.         MSG_P * ppstMsg;
  426.  
  427. DESCRIPTION
  428.  
  429.         Process pstProc attempts to read a message on its message queue.
  430.         Parameter ppstMsg is based on the MSG_T structure:
  431.  
  432.         struct MSG_S
  433.         {
  434.                 SHORT   sSendPid;   /* Pid of sender */
  435.                 SHORT   sDestPid;   /* Pid of receiver */
  436.                 SHORT   sLen;       /* length of message/data */
  437.                 PCHAR   pcData;     /* ptr to data */
  438.         };
  439.  
  440.         typedef struct MSG_S MSG_T;
  441.         typedef MSG_T * MSG_P;
  442.  
  443.  
  444.         The pcData pointer can be cast to another structure based on
  445.         whatever scheme the application requires.   The process id
  446.         of the sender can also be used if multiple application
  447.         messages exist.
  448.  
  449.         Note:  If a message does not exist, the process will be
  450.         placed in a wait state.  The process can check the state
  451.         of the message queue with the MOS_MSG_WAITING macro before
  452.         making this call.  MOS_MSG_WAITING will return C_TRUE if a message
  453.         if available.
  454.  
  455.  
  456. RESOURCE NAME
  457.  
  458.         MOS.LIB
  459.  
  460. DIAGNOSTICS
  461.  
  462.         C_OK    - message read
  463.         MOS_PROC_SUSPEND - no message, process suspended.
  464.  
  465.  
  466. NAME
  467.         MosEventCreate - create a MOS event handler
  468.  
  469. SYNOPSIS
  470.  
  471.         #include <mos.h>
  472.  
  473.         SHORT
  474.         MosEventCreate(pCheckProc,pEventProc,szEventName,sEventPriority)
  475.         SHORT (*pCheckProc)();
  476.         SHORT (*pEventProc)(PROC_P);
  477.         PCHAR szEventName;
  478.         SHORT sPriority;
  479.  
  480. DESCRIPTION
  481.  
  482.  
  483.     Mos events are defined by the pCheckProc returning TRUE.  
  484.     The pCheckProc defines the nature of the event by any code
  485.     which is in it.  Event checking is performed by the Mos
  486.     scheduler every time before a Mos process is switched to.
  487.     When an event pCheckProc returns TRUE, the pEventProc is
  488.     placed on the Mos ready queue.  
  489.  
  490.     The pEventProc (all event procs should be given higher
  491.     priorities the other Mos procs) will then send a Mos message
  492.     to a Mos proc acting as the 'server' for that event.
  493.  
  494. RESOURCE NAME
  495.  
  496.         MOS.LIB
  497.  
  498. DIAGNOSTICS
  499.  
  500.         C_OK      - initialization successful.
  501.         !C_OK     - error
  502.  
  503.  
  504. NAME
  505.         MosProcTerm - removes process from MOS environment.
  506.  
  507. SYNOPSIS
  508.  
  509.         #include <mos.h>
  510.  
  511.         SHORT
  512.         MosEventTerm(pProc)
  513.         PROC_P pProc;
  514.  
  515. DESCRIPTION
  516.  
  517.         MOS will remove from all data structures the event described
  518.         by pProc.  MosProcTerm() is usually called by the terminating
  519.         Event proc itself.
  520.       
  521. RESOURCE NAME
  522.  
  523.         MOS.LIB
  524.  
  525. DIAGNOSTICS
  526.  
  527.         C_OK    = process terminated
  528.         !C_OK   = error
  529.  
  530.  
  531.