OS/2 Shareware BBS: 18 REXX

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / rxipc.zip / REXXIPC.INF (.txt) < prev next >

Wrap

OS/2 Help File | 1996-01-14 | 65KB | 3,353 lines

ΓòÉΓòÉΓòÉ 1. Copyright (c) Serge Brisson 1994, 1995 ΓòÉΓòÉΓòÉ Copyright (c) Serge Brisson 1994, 1995. All rights reserved. Distribution The copyright owner allows the free distribution of the following files, as long as they are kept together, unmodified: o REXXIPC.DLL -- The library. o REXXIPC.INF -- The documentation. o REXXIPC.TXT -- Distribution text. o TESTIPC.CMD -- A test program. o TESTIPC.CFG -- A test configuration. o FILE_ID.DIZ -- Identification. ΓòÉΓòÉΓòÉ 2. Introduction ΓòÉΓòÉΓòÉ The RexxIPC library provides access to OS/2 Inter Process Communication capabilities for Rexx programs. Threads, named pipes, semaphores (event, mutex and muxwait) and queues are supported. The design requirements for this library specified support of multi-threaded Rexx applications, support of access to the same IPC services by other C or C++ functions, simplicity of use and non-interference in the application's design. Since the underlying system services already meet these requirements, the library's design is mostly a straightforward Rexx interface to these services. This document is supplied as a reference to this interface. It assumes that the reader has access to the Control Program Guide and Reference from the Developer's Toolkit for OS/2. Note: The explicit use of system handles in the Pipe interface allows the access to multiple instances of the same pipe (useful in a multi-threaded environment). The explicit use of system handles in the Semaphore interface allows the use of unnamed semaphores. ΓòÉΓòÉΓòÉ 3. IPC Procedures and Functions ΓòÉΓòÉΓòÉ The IPC prefix identifies a few generic routines related to the operation of the library. The IPCLoadFuncs and IPCDropFuncs register and deregister all the external routines. It is possible to be more specific by using the PipeLoadFuncs, SemLoadFuncs and PipeDropFuncs, SemLoadFuncs procedures. The IPCVersion function returns a version identification string. The IPCContext functions are used to support threads and asynchronous services. ΓòÉΓòÉΓòÉ 3.1. IPCContextClose function ΓòÉΓòÉΓòÉ Syntax rc = IPCContextClose(ctxHandle) Description IPCContextClose is used to free the memory resources consumed by the IPC Context structure. Arguments ctxHandle as obtained from IPCCreateContext. Returns IPCContextClose returns 0. Notes If a thread is still associated with the context when IPCContextClose is called, that thread is killed. See also IPCContextCreate. Examples To close an IPC Context: call IPCContextClose myContext if result \= 0 then signal ContextCloseError ΓòÉΓòÉΓòÉ 3.2. IPCContextCreate function ΓòÉΓòÉΓòÉ Syntax rc = IPCContextCreate(handleVar, [ semHandle ]) Description IPCContextCreate is used to create a context for the execution of an asynchronous (multi-threaded) function. This context holds the completion status and may hold an event semaphore handle to signal the completion of the requested function. It will also hold the result string returned by a thread started with ProcCreateThread. Arguments handleVar is the name of the variable which is to receive the handle to the allocated context. semHandle is the handle of the event semaphore which will be used to signal the completion of the asynchronous function. If this semaphore is not supplied, the function IPCContextWait may be used to wait for completion. Returns IPCContextCreate returns 0. Notes An IPCContext is a structure local to the RexxIPC library. It consumes a few bytes and an internal event semaphore in the current process. The memory and the semaphore is released by a call to IPCContextClose. The internal event semaphore is used for thread synchronization and is not related to the optional semaphore supplied as an argument to this function. See also IPCContextClose, SemEventCreate, PipeConnectAsync, ProcCreateThread. Examples To create an IPC Context: call SemEventCreate 'myContextEvent' if result \= 0 then signal SemCreateError call IPCContextCreate 'myContext', myContextEvent if result \= 0 then signal ContextCreateError . . . call IPCContextClose myContext if result \= 0 then signal ContextCloseError call SemEventClose myContextEvent if result \= 0 then signal SemCloseError ΓòÉΓòÉΓòÉ 3.3. IPCContextQuery function ΓòÉΓòÉΓòÉ Syntax rc = IPCContextQuery(ctxHandle, [ threadVar ]) Description IPCContextQuery is used to get the completion code of the last thread associated with the context. If the thread is still active, the system Id may be returned in an optional parameter. Arguments ctxHandle as obtained from IPCCreateContext. threadVar is the name of the variable which is to receive the system Id of the thread active on the context. If there is no such thread, the value will be 0 (zero). Returns IPCContextQuery returns the completion code. Notes If a thread is still active on the context, IPCContextQuery will return the code ERROR_BUSY (170). It will also put a non-zero value in the optional variable parameter. See also IPCContextCreate, IPCContextWait. Examples To query an IPC Context used in a PipeConnectAsync: call IPCContextQuery myContext if result \= 0 then signal PipeConnectError To query an IPC Context used in a ProcCreateThread: call IPCContextQuery myContext, 'threadId' if result = 170 then say 'Thread' threadId 'is still active.' else say 'Thread completed with return code' result'.' ΓòÉΓòÉΓòÉ 3.4. IPCContextResult function ΓòÉΓòÉΓòÉ Syntax threadResult = IPCContextResult(ctxHandle) Description IPCContextResult is used to get the string returned by the thread associated with the context. Arguments ctxHandle as obtained from IPCCreateContext. Returns IPCContextResult returns the string produced by the last Rexx thread associated with the context. It will return a null string if the thread is still active or did not return a string. See also IPCContextCreate, IPCContextQuery, IPCContextWait, ProcCreateThread. Examples To get the result from the last thread started by ProcCreateThread: call IPCContextResult myContext say 'The thread returned: "'result'".' ΓòÉΓòÉΓòÉ 3.5. IPCContextWait function ΓòÉΓòÉΓòÉ Syntax rc = IPCContextWait(ctxHandle) Description IPCContextWait is used to wait for the thread associated with the context and get the completion code. If the thread has already completed execution at the time of the call, there will be no wait but the completion code will be returned. Arguments ctxHandle as obtained from IPCCreateContext. Returns IPCContextWait returns the completion code. Notes After IPCContextWait returns, IPCContextResult may be called to get the string (if any) returned by the thread. See also IPCContextCreate, IPCContextQuery, IPCContextResult, ProcCreateThread. Examples To wait for an IPC Context used in a PipeConnectAsync: call IPCContextWait myContext if result \= 0 then signal PipeConnectError ΓòÉΓòÉΓòÉ 3.6. IPCDropFuncs procedure ΓòÉΓòÉΓòÉ Syntax call IPCDropFuncs Description IPCDropFuncs deregisters all the library procedures and functions. Arguments No arguments are required by IPCDropFuncs. Returns Nothing is returned by IPCDropFuncs. Notes IPC procedures and functions may be deregistered individually. IPCDropFuncs is only a shortcut to have them all deregistered with one call. See also IPCLoadFuncs, PipeLoadFuncs, PipeDropFuncs, ProcLoadFuncs, ProcDropFuncs, SemLoadFuncs, SemDropFuncs. ΓòÉΓòÉΓòÉ 3.7. IPCLoadFuncs procedure ΓòÉΓòÉΓòÉ Syntax call IPCLoadFuncs Description IPCLoadFuncs registers all the library procedures and functions. Arguments No arguments are required by IPCLoadFuncs. Returns Nothing is returned by IPCLoadFuncs. Notes IPC procedures and functions must be registered before they can be used. They may be registered individually. IPCLoadFuncs is only a shortcut to have them all registered with one call. See also IPCDropFuncs, PipeLoadFuncs, PipeDropFuncs, ProcLoadFuncs, ProcDropFuncs, SemLoadFuncs, SemDropFuncs. Examples To register all the RexxIPC functions: call RxFuncAdd 'IPCLoadFuncs', 'REXXIPC', 'IPCLoadFuncs' call IPCLoadFuncs ΓòÉΓòÉΓòÉ 3.8. IPCVersion function ΓòÉΓòÉΓòÉ Syntax versionString = IPCVersion() Description IPCVersion may be used to identify the version of the IPC library. Arguments No arguments are required by IPCVersion. Returns IPCVersion currently returns a string with the format producer product major.minor-revision but this may change in the future. ΓòÉΓòÉΓòÉ 4. Pipe Procedures and Functions ΓòÉΓòÉΓòÉ The Pipe prefix identifies named pipe related functions. Some of these are not pipe specific in the operating system implementation (like DosRead used by PipeRead, or DosClose used by PipeClose), but are needed for pipe operations. Some functions are most often used by the server side of an application (like PipeCreate, PipeConnect and PipeDisconnect), while others are used by the client side (like PipeOpen, PipeWait, PipeCall and PipeTransact). The "Control Program Guide and Reference" (Developer's Toolkit for OS/2) or "Client/Server Programming with OS/2" (Van Nostrand Reinhold) are valuable sources of information. Note: The pipe handle mentionned in the individual Pipe functions description is the actual value used by the operating system, converted to an unsigned decimal number character string. It is not associated with internal structures of the RexxIPC library and may be created/used by other modules of the same process. ΓòÉΓòÉΓòÉ 4.1. PipeCall function ΓòÉΓòÉΓòÉ Syntax rc = PipeCall(name, output, inputVar, [ inputLimit ], [ timeout ]) Description PipeCall executes a call operation. It combines the effect of PipeOpen, PipeTransact and PipeClose. Arguments name specifies the name for the pipe. It must have the form: [\\serverName ]\PIPE\pipeName where: serverName is the name of the server on which the pipe has been created; pipeName is the actual name of the pipe. output is the string expression to be sent on the pipe. inputVar is the name of the variable which will receive the response. inputLimit is the size limit (in bytes) for the response. If zero or omitted, a default of 4096 is used. timeout is the wait timeout in milliseconds. The default is 50. This timeout refers to the time the directive will wait for a pipe instance to become available. Returns PipeCall returns the code supplied by the DosCallNPipe system directive. Expected: 000 -- NO_ERROR 002 -- ERROR_FILE_NOT_FOUND 011 -- ERROR_BAD_FORMAT 095 -- ERROR_INTERRUPT 231 -- ERROR_PIPE_BUSY Notes The named pipe must have been created in duplex mode with message format. See also PipeOpen, PipeWait, PipeTransact, PipeClose. Examples To make a call on a named pipe: call PipeCall '\PIPE\MY_PIPE', 'Hello?', 'answer' if result \= 0 then signal PipeCallError say 'Pipe answer: "'answer'".' ΓòÉΓòÉΓòÉ 4.2. PipeClose function ΓòÉΓòÉΓòÉ Syntax rc = PipeClose(pipeHandle) Description PipeClose closes a pipe. It is called both for a created pipe (server side), and for an opened pipe (client side). Arguments pipeHandle as obtained from PipeCreate or PipeOpen. Returns PipeClose returns the code supplied by the DosClose system directive. Expected: 000 -- NO_ERROR 006 -- ERROR_INVALID_HANDLE See also PipeCreate, PipeOpen. Examples To close a named pipe: call PipeClose pipe if result \= 0 then signal PipeCloseError ΓòÉΓòÉΓòÉ 4.3. PipeConnect function ΓòÉΓòÉΓòÉ Syntax rc = PipeConnect(pipeHandle) Description PipeConnect listens for a connection on a named pipe. Arguments pipeHandle as obtained from PipeCreate. Returns PipeConnect returns the code supplied by the DosConnectNPipe system directive. Expected: 000 -- NO_ERROR 095 -- ERROR_INTERRUPT 109 -- ERROR_BROKEN_PIPE 230 -- ERROR_BAD_PIPE See also PipeCreate, PipeConnectAsync, PipeOpen, PipeDisconnect. Examples To create a named pipe and listen for a connection: call PipeCreate 'pipe', '\PIPE\MY_PIPE' if result \= 0 then signal PipeCreateError call PipeConnect pipe if result \= 0 then signal PipeConnectError To answer requests from PipeCall or PipeTransact calls: call PipeCreate 'pipe', '\PIPE\MY_PIPE' if result \= 0 then signal PipeCreateError do forever call PipeConnect pipe if result \= 0 then signal PipeConnectError do forever call PipeRead pipe, 'request' if result \= 0 then signal PipeReadError if request = '' then leave . . . call PipeWrite pipe, 'answer' if result \= 0 then signal PipeWriteError end call PipeDisconnect pipe if result \= 0 then signal PipeDisconnectError end ΓòÉΓòÉΓòÉ 4.4. PipeConnectAsync function ΓòÉΓòÉΓòÉ Syntax rc = PipeConnectAsync(pipeHandle, ctxHandle) Description PipeConnectAsync listens for a connection on a named pipe. Arguments pipeHandle as obtained from PipeCreate. ctxHandle as obtained from IPCContextCreate. Returns PipeConnectAsync returns the code supplied by the DosCreateThread system directive. Expected: 000 -- NO_ERROR 008 -- ERROR_NOT_ENOUGH_MEMORY 095 -- ERROR_INTERRUPT 164 -- ERROR_MAX_THRDS_REACHED See also IPCContextCreate, PipeConnect, SemEventWait. Examples To create a pipe and start a process which will immediately open the pipe: call PipeCreate 'pipe', '\PIPE\REDIRECTED_INPUT' if result \= 0 then signal PipeCreateError call IPCContextCreate 'context' if result \= 0 then signal ContextCreateError call PipeConnectAsync pipe, context if result \= 0 then signal PipeConnectAsyncError 'DETACH RED_PROC <\PIPE\REDIRECTED_INPUT >NUL' call IPCContextWait context if result \= 0 then signal PipeConnectError ΓòÉΓòÉΓòÉ 4.5. PipeCreate function ΓòÉΓòÉΓòÉ Syntax rc = PipeCreate(handleVar, name, [ mode ], [ format ], [ instances ], [ outBufSize ], [ inpBufSize ], [ timeout ]) Description PipeCreate is used to create a named pipe. Arguments handleVar is the name of a variable which will receive the handle to the named pipe. name specifies the name for the pipe. It must have the form: \PIPE\pipeName where: pipeName is the actual name of the pipe. mode is the pipe access mode. If present, it must be one of the following keywords: Inbound for an inbound pipe (receive only); Outbound for an outbound pipe (transmit only); Duplex for a duplex pipe (transmit and receive), this is the default. The keywords are case insensitive and may be abbreviated. format is the pipe format. If present, it must be one of the following keywords: Byte for a byte pipe (no implicit length); Message for a message pipe (implicit length), this is the default. The keywords are case insensitive and may be abbreviated. instances is the maximum number of instances for this pipe. It must be a value between 1 and 255, or -1 (meaning no limit). The default is 1. outBufSize is the output buffer size. The default is 1024. inpBufSize is the input buffer size. The default is 1024. timeout is the default wait timeout in milliseconds. The default is 50. Returns PipeCreate returns the code supplied by the DosCreateNPipe system directive. Expected: 000 -- NO_ERROR 003 -- ERROR_PATH_NOT_FOUND 008 -- ERROR_NOT_ENOUGH_MEMORY 084 -- ERROR_OUT_OF_STRUCTURES 231 -- ERROR_PIPE_BUSY Notes If the return code is non-zero, handleVar is not created or modified. See also PipeOpen, PipeClose. Examples To create a named pipe: call PipeCreate 'pipe', '\PIPE\MY_PIPE' if result \= 0 then signal PipeCreateError ΓòÉΓòÉΓòÉ 4.6. PipeDisconnect function ΓòÉΓòÉΓòÉ Syntax rc = PipeDisconnect(pipeHandle) Description PipeDisconnect drops a connection on a named pipe. Arguments pipeHandle as obtained from PipeCreate. Returns PipeDisconnect returns the code supplied by the DosDisConnectNPipe system directive. Expected: 000 -- NO_ERROR 230 -- ERROR_BAD_PIPE See also PipeCreate, PipeConnect. ΓòÉΓòÉΓòÉ 4.7. PipeDropFuncs procedure ΓòÉΓòÉΓòÉ Syntax call PipeDropFuncs Description PipeDropFuncs deregisters all the Pipe procedures and functions. Arguments No arguments are required by PipeDropFuncs. Returns Nothing is returned by PipeDropFuncs. Notes Pipe procedures and functions may be deregistered individually. PipeDropFuncs is only a shortcut to have them all deregistered with one call. IPCDropFuncs will by itself call PipeDropFuncs and deregister it. See also IPCDropFuncs, PipeLoadFuncs. ΓòÉΓòÉΓòÉ 4.8. PipeFlush function ΓòÉΓòÉΓòÉ Syntax rc = PipeFlush(pipeHandle) Description PipeFlush flushes the write buffer of a named pipe. It may be called both for a created pipe (server side), and for an opened pipe (client side). Arguments pipeHandle as obtained from PipeCreate or PipeOpen. Returns PipeFlush returns the code supplied by the DosResetBuffer system directive. Expected: 000 -- NO_ERROR 005 -- ERROR_ACCESS_DENIED 006 -- ERROR_INVALID_HANDLE See also PipeClose. Examples To flush a named pipe: call PipeFlush pipe if result \= 0 then signal PipeFlushError ΓòÉΓòÉΓòÉ 4.9. PipeLoadFuncs procedure ΓòÉΓòÉΓòÉ Syntax call PipeLoadFuncs Description PipeLoadFuncs registers all the Pipe procedures and functions. Arguments No arguments are required by PipeLoadFuncs. Returns Nothing is returned by PipeLoadFuncs. Notes Pipe procedures and functions must be registered before they can be used. They may be registered individually. PipeLoadFuncs is only a shortcut to have them all registered with one call. IPCLoadFuncs will by itself register and call PipeLoadFuncs. See also IPCLoadFuncs, PipeDropFuncs. ΓòÉΓòÉΓòÉ 4.10. PipeOpen function ΓòÉΓòÉΓòÉ Syntax rc = PipeOpen(handleVar, name, [ mode ], [ format ]) Description PipeOpen is used to open a named pipe. Arguments handleVar is the name of a variable which will receive the handle to the named pipe. name specifies the name for the pipe. It must have the form: [\\serverName ]\PIPE\pipeName where: serverName is the name of the server on which the pipe has been created; pipeName is the actual name of the pipe. mode is the pipe access mode. If present, it must be one of the following keywords: Inbound for an inbound pipe (receive only); Outbound for an outbound pipe (transmit only); Duplex for a duplex pipe (transmit and receive), this is the default. The keywords are case insensitive and may be abbreviated. format is the pipe format. If present, it must be one of the following keywords: Byte for a byte pipe (no implicit length); Message for a message pipe (implicit length), this is the default. The keywords are case insensitive and may be abbreviated. Returns PipeOpen returns the code supplied by the DosOpen system directive. Expected: 000 -- NO_ERROR 002 -- ERROR_FILE_NOT_FOUND 003 -- ERROR_PATH_NOT_FOUND 005 -- ERROR_ACCESS_DENIED 087 -- ERROR_INVALID_PARAMETER 231 -- ERROR_PIPE_BUSY Notes If the return code is non-zero, handleVar is not created or modified. See also PipeCreate, PipeClose. Examples To open a named pipe: call PipeOpen 'pipe', '\PIPE\MY_PIPE' if result \= 0 then signal PipeOpenError ΓòÉΓòÉΓòÉ 4.11. PipePeek function ΓòÉΓòÉΓòÉ Syntax rc = PipePeek(pipeHandle, [ inputVar ], [ inputLimit ], [ pipeBytesVar ], [ msgBytesVar ], [ stateVar ]) Description PipePeek performs a read operation on a named pipe. The operation returns immediatly with the currently available data as well as with other requested informations. Arguments pipeHandle as obtained from PipeCreate or PipeOpen. inputVar is the name of the variable which will receive the data. inputLimit is the allowed size limit for the response. If zero or omitted, a default limit of 4096 is used. pipeBytesVar is the name of the variable which will receive the number of bytes held in the pipe buffer. msgBytesVar is the name of the variable which will receive the number of bytes held in the pipe buffer for the current message. stateVar is the name of the variable which will receive a code identifying the state of the pipe: 1: the pipe is disconnected; 2: the pipe is listening for a connection; 3: the pipe is connected; 4: the pipe is closing. Returns PipePeek returns the code supplied by the DosPeekNPipe system directive. Expected: 000 -- NO_ERROR 230 -- ERROR_BAD_PIPE 231 -- ERROR_PIPE_BUSY 233 -- ERROR_PIPE_NOT_CONNECTED See also PipeRead. Examples To peek for a maximum of 80 bytes from a named pipe: call PipePeek pipe, 'data', 80, 'pipeBytes', 'msgBytes', 'state' if result \= 0 then signal PipePeekError say 'Pipe data:' data say 'Pipe bytes held:' pipeBytes say 'Pipe bytes in message:' msgBytes say 'Pipe state:' state ΓòÉΓòÉΓòÉ 4.12. PipeRead function ΓòÉΓòÉΓòÉ Syntax rc = PipeRead(pipeHandle, inputVar, [ inputLimit ]) Description PipeRead performs a blocking read operation on a named pipe. Arguments pipeHandle as obtained from PipeCreate or PipeOpen. inputVar is the name of the variable which will receive the data. inputLimit is the allowed size limit for the response. If zero or omitted, a default limit of 4096 is used. Returns PipeRead returns the code supplied by the DosRead system directive. Expected: 000 -- NO_ERROR 005 -- ERROR_ACCESS_DENIED 006 -- ERROR_INVALID_HANDLE 109 -- ERROR_BROKEN_PIPE See also PipeReadAsync, PipeWrite, PipePeek. Examples To read from a named pipe: call PipeRead pipe, 'data' if result \= 0 then signal PipeReadError say 'Pipe data:' data ΓòÉΓòÉΓòÉ 4.13. PipeReadAsync function ΓòÉΓòÉΓòÉ Syntax rc = PipeReadAsync(pipeHandle, ctxHandle, [ inputLimit ]) Description PipeReadAsync starts a read operation on a named pipe. It does not wait for completion. When the read has completed (see IPCContextCreate), the data can be obtained with IPCContextResult. Arguments pipeHandle as obtained from PipeCreate or PipeOpen. ctxHandle as obtained from IPCContextCreate. inputLimit is the allowed size limit for the response. If zero or omitted, a default limit of 4096 is used. Returns PipeReadAsync returns the code supplied by the DosCreateThread system directive. Expected: 000 -- NO_ERROR 008 -- ERROR_NOT_ENOUGH_MEMORY 095 -- ERROR_INTERRUPT 164 -- ERROR_MAX_THRDS_REACHED See also IPCContextCreate, IPCContextResult, PipeRead, PipeWriteAsync. Examples To start a read operation from a named pipe and, later, get the data: call IPCContextCreate 'context' if result \= 0 then signal ContextCreateError call PipeReadAsync pipe, context if result \= 0 then signal PipeReadAsyncError . . . call IPCContextWait context if result \= 0 then signal ContextWaitError data = IPCContextResult(context) ΓòÉΓòÉΓòÉ 4.14. PipeSetSem function ΓòÉΓòÉΓòÉ Syntax rc = PipeSetSem(pipeHandle, semHandle) Description PipeSetSem associates a shared event semaphore with the pipe. Read and write operations on the other end of the pipe will post events on that semaphore. Arguments pipeHandle as obtained from PipeCreate or PipeOpen. semHandle as obtained from SemEventCreate or SemEventOpen Returns PipeSetSem returns the code supplied by the DosSetNPipeSem system directive. Expected: 000 -- NO_ERROR 001 -- ERROR_INVALID_FUNCTION 006 -- ERROR_INVALID_HANDLE 187 -- ERROR_SEM_NOT_FOUND 230 -- ERROR_BAD_PIPE 233 -- ERROR_PIPE_NOT_CONNECTED See also SemEventCreate, SemEventWait, PipeRead, PipeWrite. Examples To associate a shared event semaphore to a pipe: call SemEventCreate 'event', 'Shared' if result \= 0 then signal SemCreateError call PipeSetSem pipe, event if result \= 0 then signal PipeSetSemError . . . call SemEventWait event if result \= 0 then signal SemWaitError ΓòÉΓòÉΓòÉ 4.15. PipeTransact function ΓòÉΓòÉΓòÉ Syntax rc = PipeTransact(pipeHandle, output, inputVar, [ inputLimit ]) Description PipeTransact combines the effect of PipeWrite and PipeRead. Arguments pipeHandle as obtained from PipeCreate or PipeOpen. output is the string expression to be sent on the pipe. inputVar is the name of the variable which will receive the response. inputLimit is the allowed size limit for the response. If zero or omitted, a default limit of 4096 is used. Returns PipeTransact returns the code supplied by the DosTransactNPipe system directive. Expected: 000 -- NO_ERROR 011 -- ERROR_BAD_FORMAT 230 -- ERROR_BAD_PIPE 233 -- ERROR_PIPE_NOT_CONNECTED Notes The pipe must have been created in duplex mode with message format. See also PipeCall, PipeRead, PipeWrite. Examples To make a named pipe transaction: call PipeTransact pipe, 'Hello?', 'answer' if result \= 0 then signal PipeTransactError say 'Pipe answer:' answer ΓòÉΓòÉΓòÉ 4.16. PipeWait function ΓòÉΓòÉΓòÉ Syntax rc = PipeWait(name, [ timeout ]) Description PipeWait performs a wait on a busy named pipe. Arguments name specifies the name for the pipe. It must have the form: [\\serverName ]\PIPE\pipeName where: serverName is the name of the server on which the pipe has been created; pipeName is the actual name of the pipe. timeout is the wait timeout in milliseconds. A value of -1 means an infinite wait; 0 or no value uses the value specified in the PipeCreate call. Returns PipeWait returns the code supplied by the DosWaitNPipe system directive. Expected: 000 -- NO_ERROR 002 -- ERROR_FILE_NOT_FOUND 095 -- ERROR_INTERRUPT 231 -- ERROR_PIPE_BUSY See also PipeOpen. Examples To open a very busy named pipe: do forever call PipeOpen 'pipe', '\PIPE\MY_PIPE' if result = 0 then leave if result \= 231 then signal PipeOpenError call PipeWait '\PIPE\MY_PIPE', -1 if result \= 0 then signal PipeWaitError end ΓòÉΓòÉΓòÉ 4.17. PipeWrite function ΓòÉΓòÉΓòÉ Syntax rc = PipeWrite(pipeHandle, output) Description PipeWrite performs a blocking write operation on a named pipe. Arguments pipeHandle as obtained from PipeCreate or PipeOpen. output is the string expression to be sent on the pipe. Returns PipeWrite returns the code supplied by the DosWrite system directive. Expected: 000 -- NO_ERROR 005 -- ERROR_ACCESS_DENIED 006 -- ERROR_INVALID_HANDLE 109 -- ERROR_BROKEN_PIPE See also PipeRead. Examples To write on a named pipe: call PipeWrite pipe, 'Hello, Pipe!' if result \= 0 then signal PipeWriteError ΓòÉΓòÉΓòÉ 4.18. PipeWriteAsync function ΓòÉΓòÉΓòÉ Syntax rc = PipeWriteAsync(pipeHandle, ctxHandle, output) Description PipeWriteAsync starts a write operation on a named pipe. Arguments pipeHandle as obtained from PipeCreate or PipeOpen. ctxHandle as obtained from IPCContextCreate. output is the string expression to be sent on the pipe. Returns PipeWriteAsync returns the code supplied by the DosCreateThread system directive. Expected: 000 -- NO_ERROR 008 -- ERROR_NOT_ENOUGH_MEMORY 095 -- ERROR_INTERRUPT 164 -- ERROR_MAX_THRDS_REACHED See also IPCContextCreate, PipeReadAsync, PipeWrite. Examples To start a write operation on a named pipe: call IPCContextCreate 'context' if result \= 0 then signal ContextCreateError call PipeWriteAsync pipe, context, 'Hello, Pipe!' if result \= 0 then signal PipeWriteAsyncError ΓòÉΓòÉΓòÉ 5. Process Procedures and Functions ΓòÉΓòÉΓòÉ The Proc prefix identifies process related functions. The "Control Program Guide and Reference" (Developer's Toolkit for OS/2) or "Client/Server Programming with OS/2" (Van Nostrand Reinhold) are valuable sources of information. Note: The facilities provided by these functions are simple mapping to the corresponding system services. They should by used with caution, since they are much more likely to affect other processes in the system than the other function groups in this library. ΓòÉΓòÉΓòÉ 5.1. ProcCreateThread function ΓòÉΓòÉΓòÉ Syntax rc = ProcCreateThread([ ctxHandle ], commandFile, [ ... ]) Description ProcCreateThread is used to create and start a Rexx thread. Arguments ctxHandle as obtained from IPCContextCreate. This context is used to anchor the execution of the thread. If this parameter is not supplied, a temporary context will be automatically generated before the thread is started and discarded after the thread has terminated. commandFile is the name of a Rexx command file to be executed by the Rexx interpreter in the thread. ... these parameters will be passed to the Rexx program. Returns ProcSendSignal returns the code supplied by the DosCreateThread system directive. Expected: 000 -- NO_ERROR 008 -- ERROR_NOT_ENOUGH_MEMORY 095 -- ERROR_INTERRUPT 164 -- ERROR_MAX_THRDS_REACHED Notes The use of an explicit context allows for a more controlled execution of the started thread. It is then possible to specify an event semaphore to IPCContextCreate which will be posted when the thread terminates, to periodically check the thread with IPCContextQuery, to wait for the thread to terminate and get the return code with IPCContextWait, to get the result string returned by the thread with IPCContextResult, and to terminate the thread with IPCContextClose. Thread synchronization and resource access control may be done with Semaphore functions. The Rexx Queue facility (RxQueue and LineIn functions; Push, Pull and Queue keywords) may be used to support communication between threads. Examples To start and forget a thread: call ProcCreateThread , 'thread.cmd' if result \= 0 then signal CreateThreadError To start a thread, do some processing, then wait and get the thread result: call IPCContextCreate 'context' if result \= 0 then signal CreateContextError call ProcCreateThread context, 'thread.cmd', '1st', '2nd' if result \= 0 then signal CreateThreadError . . . call IPCContextWait context if result \= 0 then signal ThreadTerminatedOnError call IPCContextResult context say 'The thread returned: "'result'".' ΓòÉΓòÉΓòÉ 5.2. ProcDropFuncs procedure ΓòÉΓòÉΓòÉ Syntax call ProcDropFuncs Description ProcDropFuncs deregisters all the process procedures and functions. Arguments No arguments are required by ProcDropFuncs. Returns Nothing is returned by ProcDropFuncs. Notes Process procedures and functions may be deregistered individually. ProcDropFuncs is only a shortcut to have them all deregistered with one call. IPCDropFuncs will by itself call ProcDropFuncs and deregister it. See also IPCDropFuncs, ProcLoadFuncs. ΓòÉΓòÉΓòÉ 5.3. ProcGetThreadInfo function ΓòÉΓòÉΓòÉ Syntax call ProcGetThreadInfo [ threadIdVar ], [ priorityClassVar ], [ priorityVar ], [ processIdVar ], [ parentProcessIdVar ] Description ProcGetThreadInfo is used to get informations on the current thread. Arguments threadIdVar is the name of the variable which, if present, will receive the system identification for the thread. priorityClassVar is the name of the variable which will receive the priority class. If present, it will get one of the following keywords: Idle identifies the Idle (lowest) priority class; Regular identifies the Regular (default) priority class; Server identifies the Server (high) priority class; Critical identifies the Critical (highest) priority class. priorityVar is the name of the variable which, if present, will receive the priority within the current class. processIdVar is the name of the variable which, if present, will receive the system identification for the process. parentProcessIdVar is the name of the variable which, if present, will receive the system identification for the parent process. Returns Nothing is returned by ProcGetThreadInfo. ΓòÉΓòÉΓòÉ 5.4. ProcLoadFuncs procedure ΓòÉΓòÉΓòÉ Syntax call ProcLoadFuncs Description ProcLoadFuncs registers all the process procedures and functions. Arguments No arguments are required by ProcLoadFuncs. Returns Nothing is returned by ProcLoadFuncs. Notes Process procedures and functions must be registered before they can be used. They may be registered individually. ProcLoadFuncs is only a shortcut to have them all registered with one call. IPCLoadFuncs will by itself register and call ProcLoadFuncs. See also IPCLoadFuncs, ProcDropFuncs. ΓòÉΓòÉΓòÉ 5.5. ProcSendSignal function ΓòÉΓòÉΓòÉ Syntax rc = ProcSendSignal(processId, signal) Description ProcSendSignal is used to send a signal (Break, Interrupt or Kill) to a process. Arguments processId is the process identification for the target process. signal identifies the signal to send. It must be one of the following keywords: Break send a Break (Ctrl+Break) signal; Interrupt send an Interrupt (Ctrl+C) signal; Kill send a Kill signal. The keywords are case insensitive and may be abbreviated. Returns ProcSendSignal returns the code supplied by the DosSendSignalException or DosKillProcess system directive. Expected: 000 -- NO_ERROR 156 -- ERROR_SIGNAL_REFUSED 205 -- ERROR_NO_SIGNAL_SENT 217 -- ERROR_ZOMBIE_PROCESS 303 -- ERROR_INVALID_PROCID 305 -- ERROR_NOT_DESCENDANT Examples To kill a process: call ProcSendSignal processId, 'Kill' if result \= 0 then signal ProcessKillError ΓòÉΓòÉΓòÉ 5.6. ProcSetPriority function ΓòÉΓòÉΓòÉ Syntax rc = ProcSetPriority([ processId ], [ class ], [ delta ]) Description ProcSetPriority is used to modify the execution priority of a process. Arguments processId is the system identification for the target process. Absence or 0 (zero) identifies the calling process. class is the new priority class. If present, it must be one of the following keywords: Idle identifies the Idle (lowest) priority class; Regular identifies the Regular (default) priority class; Server identifies the Server (high) priority class; Critical identifies the Critical (highest) priority class. The keywords are case insensitive and may be abbreviated. delta if the class is not specified, this is the priority variation within the current class and may range from -31 to +31; if the class is specified, this is the absolute priority within that class and may range from 0 to +31. Returns ProcSetPriority returns the code supplied by the DosSetPriority system directive. Expected: 000 -- NO_ERROR 303 -- ERROR_INVALID_PROCID 304 -- ERROR_INVALID_PDELTA 305 -- ERROR_NOT_DESCENDANT See also ProcSetThreadPriority, ProcSetTreePriority. Examples To set the priority of the current process to 20 in the Idle class: call ProcSetPriority 0, 'Idle', 20 if result \= 0 then signal SetPriorityError ΓòÉΓòÉΓòÉ 5.7. ProcSetThreadPriority function ΓòÉΓòÉΓòÉ Syntax rc = ProcSetThreadPriority([ threadId ], [ class ], [ delta ]) Description ProcSetThreadPriority is used to modify the execution priority of a thread. Arguments threadId is the system identification for the target thread. Absence or 0 (zero) identifies the calling thread. class is the new priority class. If present, it must be one of the following keywords: Idle identifies the Idle (lowest) priority class; Regular identifies the Regular (default) priority class; Server identifies the Server (high) priority class; Critical identifies the Critical (highest) priority class. The keywords are case insensitive and may be abbreviated. delta if the class is not specified, this is the priority variation within the current class and may range from -31 to +31; if the class is specified, this is the absolute priority within that class and may range from 0 to +31. Returns ProcSetThreadPriority returns the code supplied by the DosSetPriority system directive. Expected: 000 -- NO_ERROR 304 -- ERROR_INVALID_PDELTA 309 -- ERROR_INVALID_THREADID See also ProcSetPriority, ProcSetTreePriority. Examples To set the priority of the current thread to 20 in the Idle class: call ProcSetThreadPriority 0, 'Idle', 20 if result \= 0 then signal SetPriorityError ΓòÉΓòÉΓòÉ 5.8. ProcSetTreePriority function ΓòÉΓòÉΓòÉ Syntax rc = ProcSetTreePriority([ processId ], [ class ], [ delta ]) Description ProcSetPriority is used to modify the execution priority of a process tree. Arguments processId is the system identification for the parent process of the target process tree. Absence or 0 (zero) identifies the calling process as the parent. class is the new priority class. If present, it must be one of the following keywords: Idle identifies the Idle (lowest) priority class; Regular identifies the Regular (default) priority class; Server identifies the Server (high) priority class; Critical identifies the Critical (highest) priority class. The keywords are case insensitive and may be abbreviated. delta if the class is not specified, this is the priority variation within the current class and may range from -31 to +31; if the class is specified, this is the absolute priority within that class and may range from 0 to +31. Returns ProcSetPriority returns the code supplied by the DosSetPriority system directive. Expected: 000 -- NO_ERROR 303 -- ERROR_INVALID_PROCID 304 -- ERROR_INVALID_PDELTA 305 -- ERROR_NOT_DESCENDANT See also ProcSetPriority, ProcSetThreadPriority. Examples To set the priority of the current process tree to 20 in the Idle class: call ProcSetTreePriority 0, 'Idle', 20 if result \= 0 then signal SetPriorityError ΓòÉΓòÉΓòÉ 6. Queue Procedures and Functions ΓòÉΓòÉΓòÉ The Queue prefix identifies queue related functions. Some functions are most often used by the server side of an application (like QueueCreate, QueuePeek and QueueRead), while others are used by the client side (like QueueOpen and QueueWrite). The "Control Program Guide and Reference" (Developer's Toolkit for OS/2) or "Client/Server Programming with OS/2" (Van Nostrand Reinhold) are valuable sources of information. Note: The queue handle mentionned in the individual Queue functions description is the value of a pointer to an internal structure of the RexxIPC library, converted to an unsigned decimal number character string. To simplify the use of OS/2 queues by Rexx programs, this implementation handles the memory issues related with the management of queue data; for this, it needs to associate some informations to the system provided queue handle. ΓòÉΓòÉΓòÉ 6.1. QueueClose function ΓòÉΓòÉΓòÉ Syntax rc = QueueClose(queueHandle) Description QueueClose closes a queue. It is called both for a created queue (server side), and for an opened queue (client side). Arguments queueHandle as obtained from QueueCreate or QueueOpen. Returns QueueClose returns the code supplied by the DosCloseQueue system directive. Expected: 000 -- NO_ERROR 337 -- ERROR_QUE_INVALID_HANDLE See also QueueCreate, QueueOpen. Examples To close a queue: call QueueClose queue if result \= 0 then signal QueueCloseError ΓòÉΓòÉΓòÉ 6.2. QueueCreate function ΓòÉΓòÉΓòÉ Syntax rc = QueueCreate(handleVar, name, [ algorithm ], [ semHandle ]) Description QueueCreate is used to create a queue. Arguments handleVar is the name of a variable which will receive the handle to the queue. name specifies the name for the queue. It must have the form: \QUEUES\queueName where: queueName is the actual name of the queue. algorithm is the queue access algorithm. If present, it must be one of the following keywords: FIFO for a FIFO queue (First In, First Out), this is the default; LIFO for a LIFO queue (Last In, First Out); Priority for a Priority queue. The keywords are case insensitive and may be abbreviated. semHandle is the handle to a shared event semaphore which will be used in QueuePeek and QueueRead calls when the wait parameter is set to NoWait. Returns QueueCreate returns the code supplied by the DosCreateQueue system directive. Notes If the return code is non-zero, handleVar is not created or modified. Expected: 000 -- NO_ERROR 332 -- ERROR_QUE_DUPLICATE 334 -- ERROR_QUE_NO_MEMORY 335 -- ERROR_QUE_INVALID_NAME See also QueueOpen, QueueClose. Examples To create a queue: call QueueCreate 'queue', '\QUEUES\MY_QUEUE' if result \= 0 then signal QueueCreateError ΓòÉΓòÉΓòÉ 6.3. QueueDropFuncs procedure ΓòÉΓòÉΓòÉ Syntax call QueueDropFuncs Description QueueDropFuncs deregisters all the Queue procedures and functions. Arguments No arguments are required by QueueDropFuncs. Returns Nothing is returned by QueueDropFuncs. Notes Queue procedures and functions may be deregistered individually. QueueDropFuncs is only a shortcut to have them all deregistered with one call. IPCDropFuncs will by itself call QueueDropFuncs and deregister it. See also IPCDropFuncs, QueueLoadFuncs. ΓòÉΓòÉΓòÉ 6.4. QueueLoadFuncs procedure ΓòÉΓòÉΓòÉ Syntax call QueueLoadFuncs Description QueueLoadFuncs registers all the Queue procedures and functions. Arguments No arguments are required by QueueLoadFuncs. Returns Nothing is returned by QueueLoadFuncs. Notes Queue procedures and functions must be registered before they can be used. They may be registered individually. QueueLoadFuncs is only a shortcut to have them all registered with one call. IPCLoadFuncs will by itself register and call QueueLoadFuncs. See also IPCLoadFuncs, QueueDropFuncs. ΓòÉΓòÉΓòÉ 6.5. QueueOpen function ΓòÉΓòÉΓòÉ Syntax rc = QueueOpen(handleVar, name, [ serverVar ], [ semHandle ]) Description QueueOpen is used to open a queue. Arguments handleVar is the name of a variable which will receive the handle to the queue. name specifies the name for the queue. It must have the form: \QUEUES\queueName where: queueName is the actual name of the queue. serverVar is the name of a variable which will receive the process identification of the queue server. semHandle is the handle to a shared event semaphore which will be used in QueuePeek and QueueRead calls when the wait parameter is set to NoWait. Returns QueueOpen returns the code supplied by the DosOpenQueue system directive. Expected: 000 -- NO_ERROR 334 -- ERROR_QUE_NO_MEMORY 341 -- ERROR_QUE_PROC_NO_ACCESS 343 -- ERROR_QUE_NAME_NOT_EXIST Notes If the return code is non-zero, handleVar is not created or modified. See also QueueCreate, QueueClose. Examples To open a queue: call QueueOpen 'queue', '\QUEUES\MY_QUEUE' if result \= 0 then signal QueueOpenError ΓòÉΓòÉΓòÉ 6.6. QueuePeek function ΓòÉΓòÉΓòÉ Syntax rc = QueuePeek(queueHandle, [ dataVar ], [ requestVar ], [ priorityVar ], [ clientVar ], [ elementVar ], [ wait ]) Description QueuePeek performs a read operation on a queue. The operation returns immediatly with the currently available data as well as with other requested informations. Arguments queueHandle as obtained from QueueCreate or QueueOpen. dataVar is the name of the variable which will receive the data. requestVar is the name of the variable which will receive the request information associated with the data. priorityVar is the name of the variable which will receive the priority associated with the data. clientVar is the name of the variable which will receive the process identification of the client from which the data originated. elementVar is the name of the variable which will receive the element position in the queue. If present, initialized and non-zero, it must contain a value returned from a previous QueuePeek call on the same queue; otherwise, the first element according to the queue algorithm will be returned. wait is the wait option. If present, it must be one of the following keywords: Wait to wait until a queue element is available; NoWait to return an error code (342) if the queue is empty, this is the default; this will also trigger the use of the shared event semaphore if supplied in QueueCreate or QueueOpen. The keywords are case insensitive and may be abbreviated. Returns QueuePeek returns the code supplied by the DosPeekQueue system directive. Expected: 000 -- NO_ERROR 330 -- ERROR_QUE_PROC_NOT_OWNED 333 -- ERROR_QUE_ELEMENT_NOT_EXIST 337 -- ERROR_QUE_INVALID_HANDLE 340 -- ERROR_QUE_PREV_AT_END 342 -- ERROR_QUE_EMPTY See also QueueRead. Examples To peek for the first element from a queue: element = 0 call QueuePeek queue, 'data', 'request', 'priority', 'client', 'element' if result \= 0 then signal QueuePeekError say 'Queue data:' data say 'Queue request:' request say 'Queue priority:' priority say 'Queue client:' client say 'Queue element:' element ΓòÉΓòÉΓòÉ 6.7. QueuePurge function ΓòÉΓòÉΓòÉ Syntax rc = QueuePurge(queueHandle) Description QueuePurge purges a queue. It may be called only from the server side. Arguments queueHandle as obtained from QueueCreate or QueueOpen. Returns QueuePurge returns the code supplied by the DosPurgeQueue system directive. Expected: 000 -- NO_ERROR 330 -- ERROR_QUE_PROC_NOT_OWNED 337 -- ERROR_QUE_INVALID_HANDLE See also QueueCreate, QueueClose. Examples To purge a queue: call QueuePurge queue if result \= 0 then signal QueuePurgeError ΓòÉΓòÉΓòÉ 6.8. QueueQuery function ΓòÉΓòÉΓòÉ Syntax rc = QueueQuery(queueHandle, elementsVar) Description QueueQuery gets the number of entries in the queue. Arguments queueHandle as obtained from QueueCreate or QueueOpen. elementsVar is the number of elements currently in the queue. Returns QueueQuery returns the code supplied by the DosQueryQueue system directive. Expected: 000 -- NO_ERROR 337 -- ERROR_QUE_INVALID_HANDLE See also QueuePeek. Examples To get the number of elements in a queue: call QueueQuery queue, 'elements' if result \= 0 then signal QueueQueryError say 'Queue elements:' elements ΓòÉΓòÉΓòÉ 6.9. QueueRead function ΓòÉΓòÉΓòÉ Syntax rc = QueueRead(queueHandle, dataVar, [ requestVar ], [ priorityVar ], [ clientVar ], [ element ], [ wait ]) Description QueueRead performs a blocking read operation on a queue. Arguments queueHandle as obtained from QueueCreate or QueueOpen. dataVar is the name of the variable which will receive the data. requestVar is the name of the variable which will receive the request information associated with the data. priorityVar is the name of the variable which will receive the priority associated with the data. clientVar is the name of the variable which will receive the process identification of the client from which the data originated. element is the position of the requested element in the queue, as obtained from QueuePeek. wait is the wait option. If present, it must be one of the following keywords: Wait to wait until a queue element is available, this is the default; NoWait to return an error code (342) if the queue is empty; this will also trigger the use of the shared event semaphore if supplied in QueueCreate or QueueOpen. The keywords are case insensitive and may be abbreviated. Returns QueueRead returns the code supplied by the DosReadQueue system directive. Expected: 000 -- NO_ERROR 330 -- ERROR_QUE_PROC_NOT_OWNED 333 -- ERROR_QUE_ELEMENT_NOT_EXIST 337 -- ERROR_QUE_INVALID_HANDLE 342 -- ERROR_QUE_EMPTY See also QueueWrite, QueuePeek. Examples To read from a queue: call QueueRead queue, 'data' if result \= 0 then signal QueueReadError say 'Queue data:' data ΓòÉΓòÉΓòÉ 6.10. QueueWrite function ΓòÉΓòÉΓòÉ Syntax rc = QueueWrite(queueHandle, data, [ request ], [ priority ]) Description QueueWrite performs a write operation on a queue. Arguments queueHandle as obtained from QueueCreate or QueueOpen. data is the data to be put on the queue. request is the request information (numeric value representing an unsigned long) to associate with the data. priority is the priority to associate with the data. Returns QueueWrite returns the code supplied by the DosWriteQueue system directive. Expected: 000 -- NO_ERROR 334 -- ERROR_QUE_NO_MEMORY 337 -- ERROR_QUE_INVALID_HANDLE See also QueueRead. Examples To write on a queue: call QueueWrite queue, 'Hello, Queue!' if result \= 0 then signal QueueWriteError ΓòÉΓòÉΓòÉ 7. Semaphore Procedures and Functions ΓòÉΓòÉΓòÉ The Sem prefix identifies semaphore related function. Except for a few procedures (SemLoadFuncs and SemDropFuncs), the prefix is expressed as SemEvent, SemMutex or SemMuxwait, to specify to which type of semaphore the function applies. The "Control Program Guide and Reference" (Developer's Toolkit for OS/2) or "Client/Server Programming with OS/2" (Van Nostrand Reinhold) are valuable sources of information. Note: The semaphore handle mentionned in the individual semaphore functions description is the actual value used by the operating system, converted to an unsigned decimal number character string. It is not associated with internal structures of the RexxIPC library and may be created/used by other modules of the same process. ΓòÉΓòÉΓòÉ 7.1. SemDropFuncs procedure ΓòÉΓòÉΓòÉ Syntax call SemDropFuncs Description SemDropFuncs deregisters all the semaphore procedures and functions. Arguments No arguments are required by SemDropFuncs. Returns Nothing is returned by SemDropFuncs. Notes Semaphore procedures and functions may be deregistered individually. SemDropFuncs is only a shortcut to have them all deregistered with one call. IPCDropFuncs will by itself call SemDropFuncs and deregister it. See also IPCLoadFuncs, IPCDropFuncs, SemLoadFuncs. ΓòÉΓòÉΓòÉ 7.2. SemEventClose function ΓòÉΓòÉΓòÉ Syntax rc = SemEventClose(semHandle) Description SemEventClose closes an event semaphore. Arguments semHandle as obtained from SemEventCreate or SemEventOpen. Returns SemEventClose returns the code supplied by the DosCloseEventSem system directive. Expected: 000 -- NO_ERROR 006 -- ERROR_INVALID_HANDLE 301 -- ERROR_SEM_BUSY See also SemEventCreate, SemEventOpen. Examples To close an event semaphore: call SemEventClose sem if result \= 0 then signal SemCloseError ΓòÉΓòÉΓòÉ 7.3. SemEventCreate function ΓòÉΓòÉΓòÉ Syntax rc = SemEventCreate(handleVar, [ name ], [ initial ]) Description SemEventCreate is used to create an event semaphore. Arguments handleVar is the name of a variable which will receive the handle to the event semaphore. name specifies the name for the semaphore. If present, it must have the form: \SEM32\semName where: semName is the name of the semaphore. If a name is not specified, the keyword Shared (case insensitive and may be abbreviated) can be used to create a shared unnamed semaphore; otherwise a local semaphore is created. initial is the initial state of the event semaphore: posted (1) or reset (0). The default is 0. Returns SemEventCreate returns the code supplied by the DosCreateEventSem system directive. Expected: 000 -- NO_ERROR 008 -- ERROR_NOT_ENOUGH_MEMORY 123 -- ERROR_INVALID_NAME 285 -- ERROR_DUPLICATE_NAME 290 -- ERROR_TOO_MANY_HANDLES Notes If the return code is non-zero, handleVar is not created or modified. See also SemEventOpen, SemEventClose. Examples To create an event semaphore or just open if it already exists: semName = '\SEM32\MY_SEMAPHORE' call SemEventCreate 'sem', semName if result = 285 then call SemEventOpen 'sem', semName if result \= 0 then signal SemCreateError ΓòÉΓòÉΓòÉ 7.4. SemEventOpen function ΓòÉΓòÉΓòÉ Syntax rc = SemEventOpen(handleVar, name) rc = SemEventOpen(semHandle) Description SemEventOpen is used to open either a named event semaphore (first form), or a shared unnamed event semaphore (second form). Arguments handleVar is the name of a variable which will receive the handle to the event semaphore. name specifies the name for the semaphore. It must have the form: \SEM32\semName where: semName is the name of the semaphore. semHandle is a handle to a shared unnamed event semaphore. This handle has to be obtained from the process which created the semaphore. Returns SemEventOpen returns the code supplied by the DosOpenEventSem system directive. Expected: 000 -- NO_ERROR 006 -- ERROR_INVALID_HANDLE 008 -- ERROR_NOT_ENOUGH_MEMORY 123 -- ERROR_INVALID_NAME 187 -- ERROR_SEM_NOT_FOUND 291 -- ERROR_TOO_MANY_OPENS Notes If the return code is non-zero, handleVar is not created or modified. See also SemEventCreate, SemEventClose. Examples To open a named event semaphore: call SemEventOpen 'sem', '\SEM32\A_NAMED_SEMAPHORE' if result \= 0 then signal SemOpenError ΓòÉΓòÉΓòÉ 7.5. SemEventPost function ΓòÉΓòÉΓòÉ Syntax rc = SemEventPost(semHandle) Description SemEventPost posts an event semaphore. Arguments semHandle as obtained from SemEventCreate or SemEventOpen. Returns SemEventPost returns the code supplied by the DosPostEventSem system directive. Expected: 000 -- NO_ERROR 006 -- ERROR_INVALID_HANDLE 298 -- ERROR_TOO_MANY_POSTS 299 -- ERROR_ALREADY_POSTED Notes OS/2 limits the number of posts without a reset to 65535. See also SemEventReset, SemEventQuery, SemEventWait. Examples To post an event: call SemEventPost sem if result \= 0 then signal SemPostError ΓòÉΓòÉΓòÉ 7.6. SemEventQuery function ΓòÉΓòÉΓòÉ Syntax rc = SemEventQuery(semHandle, postCountVar) Description SemEventQuery queries informations from an event semaphore. Arguments semHandle as obtained from SemEventCreate or SemEventOpen postCountVar is the name of the variable which will receive the number of post actions since the last time the semaphore was in a reset state. Returns SemEventQuery returns the code supplied by the DosQueryEventSem system directive. Expected: 000 -- NO_ERROR 006 -- ERROR_INVALID_HANDLE See also SemEventReset, SemEventPost, SemEventWait. Examples To query an event semaphore: call SemEventQuery sem, 'count' if result \= 0 then signal SemQueryError say 'Semaphore post count:' count ΓòÉΓòÉΓòÉ 7.7. SemEventReset function ΓòÉΓòÉΓòÉ Syntax rc = SemEventReset(semHandle, [ postCountVar ]) Description SemEventReset resets an event semaphore. Arguments semHandle as obtained from SemEventCreate or SemEventOpen. postCountVar if present, is the name of the variable which will receive the number of post actions since the last time the semaphore was in a reset state. Returns SemEventReset returns the code supplied by the DosResetEventSem system directive. Expected: 000 -- NO_ERROR 006 -- ERROR_INVALID_HANDLE 300 -- ERROR_ALREADY_RESET See also SemEventPost, SemEventQuery, SemEventWait. Examples To reset an event semaphore: call SemEventReset sem if result \= 0 then signal SemResetError ΓòÉΓòÉΓòÉ 7.8. SemEventWait function ΓòÉΓòÉΓòÉ Syntax rc = SemEventWait(semHandle, [ timeout ]) Description SemEventWait waits for an event semaphore to be in a non reset state. Arguments semHandle as obtained from SemEventCreate or SemEventOpen. timeout is the wait timeout in milliseconds. A value of -1 means an infinite wait; this is the default. Returns SemEventWait returns the code supplied by the DosWaitEventSem system directive. Expected: 000 -- NO_ERROR 006 -- ERROR_INVALID_HANDLE 008 -- ERROR_NOT_ENOUGH_MEMORY 095 -- ERROR_INTERRUPT 640 -- ERROR_TIMEOUT See also SemEventPost, SemEventReset, SemEventQuery. Examples To wait for an event semaphore: call SemEventWait sem if result \= 0 then signal SemWaitError ΓòÉΓòÉΓòÉ 7.9. SemLoadFuncs procedure ΓòÉΓòÉΓòÉ Syntax call SemLoadFuncs Description SemLoadFuncs registers all the semaphore procedures and functions. Arguments No arguments are required by SemLoadFuncs. Returns Nothing is returned by SemLoadFuncs. Notes Semaphore procedures and functions must be registered before they can be used. They may be registered individually. SemLoadFuncs is only a shortcut to have them all registered with one call. IPCLoadFuncs will by itself register and call SemLoadFuncs. See also IPCLoadFuncs, SemDropFuncs. ΓòÉΓòÉΓòÉ 7.10. SemMutexClose function ΓòÉΓòÉΓòÉ Syntax rc = SemMutexClose(semHandle) Description SemMutexClose closes a mutex semaphore. Arguments semHandle as obtained from SemMutexCreate or SemMutexOpen. Returns SemMutexClose returns the code supplied by the DosCloseMutexSem system directive. Expected: 000 -- NO_ERROR 006 -- ERROR_INVALID_HANDLE 301 -- ERROR_SEM_BUSY See also SemMutexCreate, SemMutexOpen. Examples To close a mutex semaphore: call SemMutexClose sem if result \= 0 then signal SemCloseError ΓòÉΓòÉΓòÉ 7.11. SemMutexCreate function ΓòÉΓòÉΓòÉ Syntax rc = SemMutexCreate(handleVar, [ name ], [ initial ]) Description SemMutexCreate is used to create a mutex semaphore. Arguments handleVar is the name of a variable which will receive the handle to the mutex semaphore. name specifies the name for the semaphore. If present, it must have the form: \SEM32\semName where: semName is the name of the semaphore. If a name is not specified, the keyword Shared (case insensitive and may be abbreviated) can be used to create a shared unnamed semaphore; otherwise a local semaphore is created. initial is the initial state of the mutex semaphore: held (1) or released (0). The default is 0. Returns SemMutexCreate returns the code supplied by the DosCreateMutexSem system directive. Expected: 000 -- NO_ERROR 008 -- ERROR_NOT_ENOUGH_MEMORY 123 -- ERROR_INVALID_NAME 285 -- ERROR_DUPLICATE_NAME 290 -- ERROR_TOO_MANY_HANDLES Notes If the return code is non-zero, handleVar is not created or modified. See also SemMutexOpen, SemMutexClose. Examples To create a mutex semaphore: call SemMutexCreate 'sem', '\SEM32\MY_SEMAPHORE' if result \= 0 then signal SemCreateError ΓòÉΓòÉΓòÉ 7.12. SemMutexOpen function ΓòÉΓòÉΓòÉ Syntax rc = SemMutexOpen(handleVar, name) rc = SemMutexOpen(semHandle) Description SemMutexOpen is used to open either a named mutex semaphore (first form), or a shared unnamed mutex semaphore (second form). Arguments handleVar is the name of a variable which will receive the handle to the mutex semaphore. name specifies the name for the semaphore. It must have the form: \SEM32\semName where: semName is the name of the semaphore. semHandle is a handle to a shared unnamed mutex semaphore. This handle has to be obtained from the process which created the semaphore. Returns SemMutexOpen returns the code supplied by the DosOpenMutexSem system directive. Expected: 000 -- NO_ERROR 006 -- ERROR_INVALID_HANDLE 008 -- ERROR_NOT_ENOUGH_MEMORY 105 -- ERROR_SEM_OWNER_DIED 123 -- ERROR_INVALID_NAME 187 -- ERROR_SEM_NOT_FOUND 291 -- ERROR_TOO_MANY_OPENS Notes If the return code is non-zero, handleVar is not created or modified. See also SemMutexCreate, SemMutexClose. Examples To open a named mutex semaphore: call SemMutexOpen 'sem', '\SEM32\A_NAMED_SEMAPHORE' if result \= 0 then signal SemOpenError ΓòÉΓòÉΓòÉ 7.13. SemMutexQuery function ΓòÉΓòÉΓòÉ Syntax rc = SemMutexQuery(semHandle, [ processIdVar ], [ threadIdVar ], [ countVar ]) Description SemMutexQuery queries informations from a mutex semaphore. Arguments semHandle as obtained from SemMutexCreate or SemMutexOpen. processIdVar if present, is the name of the variable which will receive the id of the owner process. threadIdVar if present, is the name of the variable which will receive the id of the owner thread. countVar if present, is the name of the variable which will receive the request count from the owner process. If the semaphore is unowned, the count is zero. Returns SemMutexQuery returns the code supplied by the DosQueryMutexSem system directive. Expected: 000 -- NO_ERROR 006 -- ERROR_INVALID_HANDLE 105 -- ERROR_SEM_OWNER_DIED See also SemMutexRequest, SemMutexRelease. Examples To query a mutex semaphore: call SemMutexQuery sem, 'processId', 'threadId', 'count' if result \= 0 then signal SemQueryError say 'Semaphore post count:' count if count \= 0 then do say 'Semaphore owner process:' processId say 'Semaphore owner thread:' threadId end ΓòÉΓòÉΓòÉ 7.14. SemMutexRelease function ΓòÉΓòÉΓòÉ Syntax rc = SemMutexRelease(semHandle) Description SemMutexRelease releases a mutex semaphore. Arguments semHandle as obtained from SemMutexCreate or SemMutexOpen. Returns SemMutexRelease returns the code supplied by the DosReleaseMutexSem system directive. Expected: 000 -- NO_ERROR 006 -- ERROR_INVALID_HANDLE 288 -- ERROR_NOT_OWNER See also SemMutexRequest, SemMutexQuery. Examples To release a mutex semaphore: call SemMutexRelease sem if result \= 0 then signal SemReleaseError ΓòÉΓòÉΓòÉ 7.15. SemMutexRequest function ΓòÉΓòÉΓòÉ Syntax rc = SemMutexRequest(semHandle, [ timeout ]) Description SemMutexRequest requests to be the owner of a mutex semaphore. Arguments semHandle as obtained from SemMutexCreate or SemMutexOpen. timeout is the wait timeout in milliseconds. A value of -1 means an infinite wait; this is the default. Returns SemMutexRequest returns the code supplied by the DosRequestMutexSem system directive. Expected: 000 -- NO_ERROR 006 -- ERROR_INVALID_HANDLE 095 -- ERROR_INTERRUPT 103 -- ERROR_TOO_MANY_SEM_REQUESTS 105 -- ERROR_SEM_OWNER_DIED 640 -- ERROR_TIMEOUT See also SemMutexCreate, SemMutexRelease, SemMutexQuery. Examples To request a mutex semaphore: call SemMutexRequest sem if result \= 0 then signal SemRequestError ΓòÉΓòÉΓòÉ 7.16. SemMuxwaitAdd function ΓòÉΓòÉΓòÉ Syntax rc = SemMuxwaitAdd(semHandle, otherSemHandle, [ userValue ]) Description SemMuxwaitAdd adds a semaphore to the associated semaphores list. Arguments semHandle as obtained from SemMuxwaitCreate or SemMuxwaitOpen. otherSemHandle as obtained from SemEventCreate, SemEventOpen, SemMutexCreate, or SemMutexOpen. userValue a numeric value to be returned by SemMuxwaitWait. Returns SemMuxwaitAdd returns the code supplied by the DosAddMuxWaitSem system directive. Expected: 000 -- NO_ERROR 006 -- ERROR_INVALID_HANDLE 008 -- ERROR_NOT_ENOUGH_MEMORY 100 -- ERROR_TOO_MANY_SEMAPHORES 105 -- ERROR_SEM_OWNER_DIED 284 -- ERROR_DUPLICATE_HANDLE 292 -- ERROR_WRONG_TYPE See also SemMuxwaitCreate, SemMuxwaitOpen, SemMuxwaitRemove, SemEventCreate, SemEventOpen, SemMutexCreate, SemMutexOpen. Examples To add an event semaphore to a muxwait semaphore: call SemEventCreate 'eventSem' if result \= 0 then signal SemCreateError call SemMuxwaitAdd muxSem, eventSem, 1 if result \= 0 then signal SemAddError ΓòÉΓòÉΓòÉ 7.17. SemMuxwaitClose function ΓòÉΓòÉΓòÉ Syntax rc = SemMuxwaitClose(semHandle) Description SemMuxwaitClose closes a muxwait semaphore. Arguments semHandle as obtained from SemMuxwaitCreate or SemMuxwaitOpen. Returns SemMuxwaitClose returns the code supplied by the DosCloseMuxWaitSem system directive. Expected: 000 -- NO_ERROR 006 -- ERROR_INVALID_HANDLE 301 -- ERROR_SEM_BUSY See also SemMuxwaitCreate, SemMuxwaitOpen. Examples To close a muxwait semaphore: call SemMuxwaitClose sem if result \= 0 then signal SemCloseError ΓòÉΓòÉΓòÉ 7.18. SemMuxwaitCreate function ΓòÉΓòÉΓòÉ Syntax rc = SemMuxwaitCreate(handleVar, [ name ], mode) Description SemMuxwaitCreate is used to create a muxwait semaphore. Arguments handleVar is the name of a variable which will receive the handle to the muxwait semaphore. name specifies the name for the semaphore. If present, it must have the form: \SEM32\semName where: semName is the name of the semaphore. If a name is not specified, the keyword Shared (case insensitive and may be abbreviated) can be used to create a shared unnamed semaphore; otherwise a local semaphore is created. mode is the muxwait semaphore wait mode. It must be one of the following keywords: And wait for all associated semaphores; Or wait for any associated semaphore. The keywords are case insensitive and may be abbreviated. Returns SemMuxwaitCreate returns the code supplied by the DosCreateMuxWaitSem system directive. Expected: 000 -- NO_ERROR 008 -- ERROR_NOT_ENOUGH_MEMORY 123 -- ERROR_INVALID_NAME 285 -- ERROR_DUPLICATE_NAME 290 -- ERROR_TOO_MANY_HANDLES Notes If the return code is non-zero, handleVar is not created or modified. See also SemMuxwaitAdd, SemMuxwaitClose, SemMuxwaitOpen, SemMuxwaitWait. Examples To create a muxwait semaphore: call SemMuxwaitCreate 'sem', '\SEM32\MY_MUXWAIT_SEM', 'Or' if result \= 0 then signal SemCreateError ΓòÉΓòÉΓòÉ 7.19. SemMuxwaitOpen function ΓòÉΓòÉΓòÉ Syntax rc = SemMuxwaitOpen(handleVar, name) rc = SemMuxwaitOpen(semHandle) Description SemMuxwaitOpen is used to open either a named muxwait semaphore (first form), or a shared unnamed muxwait semaphore (second form). Arguments handleVar is the name of a variable which will receive the handle to the muxwait semaphore. name specifies the name for the semaphore. It must have the form: \SEM32\semName where: semName is the name of the semaphore. semHandle is a handle to a shared unnamed muxwait semaphore. This handle has to be obtained from the process which created the semaphore. Returns SemMuxwaitOpen returns the code supplied by the DosOpenMuxWaitSem system directive. Expected: 000 -- NO_ERROR 006 -- ERROR_INVALID_HANDLE 008 -- ERROR_NOT_ENOUGH_MEMORY 105 -- ERROR_SEM_OWNER_DIED 123 -- ERROR_INVALID_NAME 187 -- ERROR_SEM_NOT_FOUND 291 -- ERROR_TOO_MANY_OPENS Notes If the return code is non-zero, handleVar is not created or modified. See also SemMuxwaitCreate, SemMuxwaitClose. Examples To open a named muxwait semaphore: call SemMuxwaitOpen 'sem', '\SEM32\A_NAMED_MUXWAIT_SEM' if result \= 0 then signal SemOpenError ΓòÉΓòÉΓòÉ 7.20. SemMuxwaitRemove function ΓòÉΓòÉΓòÉ Syntax rc = SemMuxwaitRemove(semHandle, otherSemHandle) Description SemMuxwaitRemove removes a semaphore from the associated semaphores list. Arguments semHandle as obtained from SemMuxwaitCreate or SemMuxwaitOpen. otherSemHandle as obtained from SemEventCreate, SemEventOpen, SemMutexCreate, or SemMutexOpen. Returns SemMuxwaitRemove returns the code supplied by the DosDeleteMuxWaitSem system directive. Expected: 000 -- NO_ERROR 006 -- ERROR_INVALID_HANDLE 286 -- ERROR_EMPTY_MUXWAIT See also SemMuxwaitAdd. Examples To remove an event semaphore from a muxwait semaphore: call SemMuxwaitRemove muxSem, eventSem if result \= 0 then signal SemRemoveError ΓòÉΓòÉΓòÉ 7.21. SemMuxwaitWait function ΓòÉΓòÉΓòÉ Syntax rc = SemMuxwaitWait(semHandle, [ timeout ], [ userVar ]) Description SemMuxwaitWait waits for a muxwait semaphore. Arguments semHandle as obtained from SemMuxwaitCreate or SemMuxwaitOpen. timeout is the wait timeout in milliseconds. A value of -1 means an infinite wait; this is the default. userVar is the name of a variable which will receive the optional value specified with the SemMuxwaitAdd function. Returns SemMuxwaitWait returns the code supplied by the DosWaitMuxWaitSem system directive. Expected: 000 -- NO_ERROR 006 -- ERROR_INVALID_HANDLE 008 -- ERROR_NOT_ENOUGH_MEMORY 095 -- ERROR_INTERRUPT 105 -- ERROR_SEM_OWNER_DIED 286 -- ERROR_EMPTY_MUXWAIT 287 -- ERROR_MUTEX_OWNED 640 -- ERROR_TIMEOUT See also SemMuxwaitAdd. Examples To wait for a muxwait semaphore: call SemMuxwaitWait sem if result \= 0 then signal SemWaitError ΓòÉΓòÉΓòÉ 7.22. SemStartTimer function ΓòÉΓòÉΓòÉ Syntax rc = SemStartTimer([ handleVar ], interval, semHandle, [ type ]) Description SemStartTimer is used to create and start a timer which will post a shared event semaphore. Arguments handleVar is the name of a variable which will receive the handle to the timer. interval is the time interval in milliseconds. semHandle is a shared event semaphore handle as obtained from SemEventCreate or SemEventOpen. type is the timer type. It must be one of the following keywords: Repeat the timer will repeat; Single the timer will execute only once; this is the default. The keywords are case insensitive and may be abbreviated. Returns SemStartTimer returns the code supplied by the DosAsyncTimer or DosStartTimer system directive. Expected: 000 -- NO_ERROR 323 -- ERROR_TS_SEMHANDLE 324 -- ERROR_TS_NOTIMER Notes If the return code is non-zero, handleVar is not created or modified. See also SemStopTimer, SemEventCreate, SemEventWait. Examples To start a timer and wait until it fires (60 seconds): call SemEventCreate 'timerSem', 'Shared' if result \= 0 then signal SemCreateError call SemStartTimer , 60 * 1000, timerSem if result \= 0 then signal TimerStartError call SemEventWait timerSem if result \= 0 then signal SemWaitError ΓòÉΓòÉΓòÉ 7.23. SemStopTimer function ΓòÉΓòÉΓòÉ Syntax rc = SemStopTimer(timerHandle) Description SemStopTimer is used to stop a timer started with SemStartTimer. Arguments timerHandle is the handle created by SemStartTimer. Returns SemStopTimer returns the code supplied by the DosStopTimer system directive. Expected: 000 -- NO_ERROR 326 -- ERROR_TS_HANDLE See also SemStartTimer.