home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / rxu1a.zip / rxu.inf (.txt) < prev    next >
OS/2 Help File  |  1996-05-02  |  107KB  |  3,952 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Name Changed! ΓòÉΓòÉΓòÉ
  3.  
  4. Starting with this version of the RXU function package, all the pieces of the 
  5. package will have the name RXU (no longer any references to YDBAUTIL). I'm 
  6. doing this for two reasons: 
  7.  
  8.   1) The package is known and distributed in many places as RXU
  9.   2) The name YDBAUTIL isn't as easy to build on as RXU
  10.  
  11. I don't think this will have any effect on anyone using the package, other than 
  12. that you must now have RXU.DLL in your LIBPATH to use the functions, and the 
  13. function registration function is now called "RxuInit()" (rather than the old 
  14. "RxYdbaUtilInit()").  My apologies for any inconvenience this name change may 
  15. cause (forseen and unforseen). 
  16.  
  17.  
  18. ΓòÉΓòÉΓòÉ 2. About RXU ΓòÉΓòÉΓòÉ
  19.  
  20. RXU is a package of diverse OS/2 Rexx External Functions. Almost all the 
  21. functions in this package are in use in many of my own programs and are fairly 
  22. well de-bugged.  Please let me know of any problems you encounter in using the 
  23. functions, or of any suggestions for enhancements to existing functions, or 
  24. ideas for new ones. 
  25.  
  26. I've written the functions in RXU both to more fully enable Rexx as a 
  27. programming language for the OS/2 environment, and as a personal technical 
  28. challenge.  Since I'm not making any money off them, I do from time to time put 
  29. support/enhancement on the back burner due to other distractions. 
  30.  
  31. I'm waiting to see what the Rexx landscape will look like in the Win95 world 
  32. before I explore porting RXU (at least, the portable parts) from OS/2 to Win95. 
  33.  
  34.  
  35.   With the functions in the RXU function package, you can make
  36.   use of some of OS/2's most powerful facilities, such as multi-threading,
  37.   processes, sessions, semaphores, memory access, OS/2 queues, etc.
  38.   Some of these features are not only useful in pure Rexx applications,
  39.   but they allow you to write Rexx programs which can talk to compiled
  40.   programs on their level (i.e. reference memory by address, use
  41.   semaphores, etc.).
  42.  
  43.   Another benefit is the ability to quickly prototype real OS/2 programs
  44.   using real OS/2 APIs so that you can cheaply 'prove' techniques
  45.   before committing them to 'C' code.
  46.  
  47.   The capabilities provided to Rexx programs by this package, in
  48.   conjunction with those provided by other Rexx function packages
  49.   (database access, APPC, etc.) and the base language itself allow
  50.   you to prototype or build Rexx applications with much of the
  51.   functional sophistication (and complexity, unfortunately) of "real"
  52.   OS/2 applications.
  53.  
  54.   In addition to the many OS/2 API "passthrough" functions, there are
  55.   many Rexx-specific enhancements and additions.
  56.  
  57.  
  58.   Author:        Dave Boll
  59.                  (CompuServe = 74170,2016)
  60.                  Internet: 74170.2016@compuserve.com
  61.   Release Date:  6 April, 1996
  62.   Version:       1.a
  63.  
  64.  
  65. ΓòÉΓòÉΓòÉ 3. Release Notes ΓòÉΓòÉΓòÉ
  66.  
  67. Release information follows: 
  68.  
  69. Release 1.a features:
  70.   RxMalloc              - Allocate memory on the 'C' runtime-managed heap
  71.   RxFree                - Free memory allocated with "RxMalloc()"
  72.   RxuMth...             - Set of math library functions
  73.   RxSetExtLibPath       - Set extended LIBPATH for current process
  74.                           (allows you to dynamically alter LIBPATH per process)
  75.   RxQueryExtLibPath     - Query extended LIBPATH for current process
  76.   RxSetNPHState         - Set state of a named pipe
  77.  
  78. Release 1.9 features:
  79.                           (The PassByName functions were motivated by seeing many posts in
  80.                            various places inquiring whether variables could be shared twixt
  81.                            separate command files, and by David Durgee, who specifically inquired
  82.                            about this capability and provided feedback during development of
  83.                            these functions (thanks David).  In fairness to him, he suggested a far
  84.                            more rich and useful function scheme than I could figure out how to
  85.                            implement (sorry for not doing justice to the concept).  But I do think
  86.                            the way variable sharing is implemented here will be at least somewhat
  87.                            useful.
  88.                           )
  89.   RxPassByName          - Allows rexx program to call another rexx program (external .CMD file),
  90.                           passing rexx variables (including stems) by name (reference or value).
  91.   RxReturnByName        - Allows a called rexx program to return rexx variables (including stems)
  92.                           by name (reference or value) back to a calling rexx program.
  93.   RxPBNBufSize          - Set/Query fetch buffer size (used by RxPassByName)
  94.   RxPhysicalDisk        - Query information about partitionable disks
  95.   RxTmrQueryFreq        - Query frequency of IRQ0 high-resolution timer
  96.   RxTmrQueryTime        - Query snapshot of IRQ0 high-resolution timer value
  97.  
  98. Release 1.8 features:
  99.   RxSetRelMaxFH         - Set max file handles for process (relative to current value)
  100.   RxSetMaxFH            - Set maximum file handles for process
  101.   RxDevConfig           - Obtain device configuration information
  102.   RxDevIOCtl            - Do DosDevIOCtl calls (to talk to character devices directly)
  103.   RxWaitChild           - Wait for child process(es) to end
  104.   RxDosRead             - Alias for "RxRead()"
  105.   RxDosWrite            - Alias for "RxWrite()"
  106.   RxSetExceptionExit    - Specify the address of exception exit function
  107.  
  108. Release 1.7 features:
  109.   RxRsoe2q              - Redirect StdOut/StdErr to a rexx queue (by queue name)
  110.   RxGlobalVar           - Put,Get,Delete system-wide global variables
  111.  
  112. Release 1.6 features:
  113.   RxRegisterFunctionExe - Use "RexxRegisterFunctionExe()"
  114.   RxRegisterExitDll     - Use "RexxRegisterExitDll()"
  115.   RxRegisterExitExe     - Use "RexxRegisterExitExe()"
  116.   RxQueryExit           - Use "RexxQueryExit()"
  117.   RxDeregisterExit      - Use "RexxDeregisterExit()"
  118.  
  119. Release 1.5 features:
  120.   RxOpen          - open a file with full DosOpen() capabilities
  121.   RxGetInfoBlocks - get DosGetInfoBlocks() info
  122.   RxStem2Struct   - map values of a stem into a structure (finally implemented)
  123.   RxQueryAppType  - query application type of an executable file
  124.  
  125.   RxVioPopUp            - Start a VioPopUp display screen
  126.   RxVioEndPopUp         - Close a VioPopUp display screen
  127.   RxVioWrtCharStrAtt    - Write characters to a VioPopUp display screen
  128.   RxKbCharIn            - Get a character from a VioPopUp display screen
  129.   RxDupHandle           - Do a "DosDupHandle()"
  130.   RxSetFHState          - Set file handle state
  131.   RxQueryFHState        - Query file handle state
  132.  
  133. Also, the "RxPstat()" function was reincarnated as "RxQProcStatus()" and is 
  134. documented herein (it now works properly). 
  135.  
  136. In this version (v1.5), "RxQProcStatus()" stores Library, Shared-Memory, and 
  137. 16-Bit Semaphore information differently.  See that section for more 
  138. information. 
  139.  
  140. This function package is 32-bit code and will only work on OS/2 2.x 
  141.  
  142.  
  143. ΓòÉΓòÉΓòÉ 4. How to Use It ΓòÉΓòÉΓòÉ
  144.  
  145. How to register the functions: 
  146.  
  147. In order to use the functions, you have to register them with Rexx like this:
  148.  
  149.   call rxfuncadd 'rxuinit','rxu','rxuinit'
  150.   call rxuinit
  151.  
  152. The .DLL "rxu.dll" must be in your libpath.
  153. The program "RXSRS.EXE" must be in your path in order to use the functions
  154. "RxStartRexxSession" and "RxDetachRexxPgm".
  155.  
  156.  
  157. ΓòÉΓòÉΓòÉ 5. Available External Functions ΓòÉΓòÉΓòÉ
  158.  
  159. The available functions are: 
  160.  
  161.  
  162.   Function Package utility functions
  163.   ----------------------------------
  164.   RxuInit               - Register all RXU Rexx functions
  165.   RxuTerm               - De-Register all RXU Rexx functions
  166.   RxuQuery              - Query function package version and available
  167.                           external function entry point names
  168.  
  169.   Math Library Functions
  170.   ----------------------
  171.   RxuMthceil
  172.   RxuMthcosh
  173.   RxuMthexp
  174.   RxuMthfloor
  175.   RxuMthfmod
  176.   RxuMthfrexp
  177.   RxuMthldexp
  178.   RxuMthlog
  179.   RxuMthlog10
  180.   RxuMthmodf
  181.   RxuMthpow
  182.   RxuMthsinh
  183.   RxuMthtanh
  184.   RxuMthasin
  185.   RxuMthacos
  186.   RxuMthatan2
  187.   RxuMthatan
  188.   RxuMthsin
  189.   RxuMthcos
  190.   RxuMthtan
  191.   RxuMthsqrt
  192.   RxuMthfabs
  193.   RxuMtherf
  194.   RxuMtherfc
  195.   RxuMthgamma
  196.   RxuMthhypot
  197.  
  198.   UPM/Net Related
  199.   -----------
  200.   RxUpm                 - Rexx interface to UPM
  201.   RxNet                 - Rexx interface to certain NET calls
  202.                           (also some UPM-related calls)
  203.  
  204.   System-Info related
  205.   -------------------
  206.   RxSetExtLibPath       - Set extended LIBPATH for current process
  207.                           (allows you to dynamically alter LIBPATH per process)
  208.   RxQueryExtLibPath     - Query extended LIBPATH for current process
  209.   RxTmrQueryFreq        - Query frequency of IRQ0 high-resolution timer
  210.   RxTmrQueryTime        - Query snapshot of IRQ0 high-resolution timer value
  211.   RxProcId              - Get process' own PID and TID information
  212.   RxGetInfoBlocks       - Get information about current process/thread
  213.   RxQueryAppType        - Get information about an executable file
  214.   RxQuerySysInfo        - Invoke DosQuerySysInfo
  215.   RxQProcStatus         - Obtain Process Status Information (like PSTAT)
  216.   RxSetError            - Set DosError settings (enable/disable HardError
  217.                           and Exception popups)
  218.   RxReplaceModule       - Replace an active .DLL or .EXE file
  219.   RxExitList            - Use DosExitList
  220.   RxDevConfig           - Obtain device configuration information
  221.   RxPhysicalDisk        - Query information about partitionable disks
  222.   RxDevIOCtl            - Do DosDevIOCtl calls (to talk to character devices directly)
  223.  
  224.   Rexx programming and debugging functions
  225.   ----------------------------------------
  226.   RxVlist               - List, manipulate Rexx variable pool
  227.   RxGlobalVar           - Put,Get,Delete system-wide global variables
  228.   RxScount              - Count strings (needle) in another string (haystack)
  229.   RxPmPrintf            - Write lines to a PMPrintf Monitor
  230.   RxCallInStore         - Execute a string as a program
  231.   RxPassByName          - Allows rexx program to call another rexx program (external .CMD file),
  232.                           passing rexx variables (including stems) by name (reference or value).
  233.   RxReturnByName        - Allows a called rexx program to return rexx variables (including stems)
  234.                           by name (reference or value) back to a calling rexx program.
  235.   RxPBNBufSize          - Set/Query fetch buffer size (used by RxPassByName)
  236.   RxTokenize            - Tokenize ("Compile") a program string
  237.   RxPullQueue           - Pull items from any Rexx data queue
  238.   RxAddQueue            - Add items to any Rexx data queue
  239.   RxQueued              - Query number of items on any Rexx data queue
  240.   RxQExists             - Query existence of a Rexx Queue
  241.   RxSearchPath          - Find a file in a path
  242.   RxRegisterFunctionExe - Use "RexxRegisterFunctionExe()"
  243.   RxRegisterExitDll     - Use "RexxRegisterExitDll()"
  244.   RxRegisterExitExe     - Use "RexxRegisterExitExe()"
  245.   RxQueryExit           - Use "RexxQueryExit()"
  246.   RxDeregisterExit      - Use "RexxDeregisterExit()"
  247.  
  248.   I/O related
  249.   -----------
  250.   RxRsoe2f              - Redirect StdOut/StdErr to a file (by file name)
  251.   RxRsoe2q              - Redirect StdOut/StdErr to a rexx queue (by queue name)
  252.   RxSoSe2H              - Redirect StdOut/StdErr to a file (by file handle)
  253.   RxSi2H                - Redirect StdIn from a file (by file handle)
  254.   RxRSi2F               - Redirect StdIn from a file (by file name)
  255.   RxOpen                - Open a file (with full DosOpen capabilities)
  256.   RxRead                - Read data from a file handle
  257.   RxDosRead             - Alias for "RxRead()"
  258.   RxWrite               - Write data to a file handle
  259.   RxDosWrite            - Alias for "RxWrite()"
  260.   RxCloseH              - Close a file handle
  261.   RxExecI               - Read data into a Rexx queue or stem from a file
  262.   RxExecO               - Write data from a Rexx queue or stem to a file
  263.   RxVioPopUp            - Start a VioPopUp display screen
  264.   RxVioEndPopUp         - Close a VioPopUp display screen
  265.   RxVioWrtCharStrAtt    - Write characters to a VioPopUp display screen
  266.   RxKbCharIn            - Get a character from a VioPopUp display screen
  267.   RxDupHandle           - Do a "DosDupHandle()"
  268.   RxSetFHState          - Set file handle state
  269.   RxQueryFHState        - Query file handle state
  270.   RxSetMaxFH            - Set maximum file handles for process
  271.   RxSetRelMaxFH         - Set max file handles for process (relative to current value)
  272.  
  273.   OS/2 Pipes
  274.   ----------
  275.   RxCreateNPipe         - Create a named pipe
  276.   RxSetNPHState         - Set state of a named pipe
  277.   RxConnectNPipe        - Connect to a named pipe
  278.   RxDisConnectNPipe     - Disconnect from a named pipe
  279.   RxCreatePipe          - Create an un-named pipe
  280.   RxDestroyPipe         - Destroy a pipe
  281.  
  282.   OS/2 Queues
  283.   ----------
  284.   RxCreateQueue         - DosCreateQueue
  285.   RxOpenQueue           - DosOpenQueue
  286.   RxPeekQueue           - DosPeekQueue
  287.   RxReadQueue           - DosReadQueue
  288.   RxWriteQueue          - DosWriteQueue
  289.   RxPurgeQueue          - DosPurgeQueue
  290.   RxQueryQueue          - DosQueryQueue
  291.   RxCloseQueue          - DosCloseQueue
  292.   RxReadQueueStr        - Returns data from de-referenced queue pointer
  293.  
  294.   NetBios information
  295.   -------------------
  296.   RxNbSessionStatus     - Obtain NETBIOS session status information
  297.  
  298.   Tasking, threads, etc.
  299.   ----------------------
  300.   RxSetPriority         - Set the priority of processes or threads
  301.             Process - Related
  302.   RxKillProcess         - Kill an OS/2 process by process-id
  303.   RxExecPgm             - Execute a program using DosExecPgm
  304.   RxWaitChild           - Wait for a child process to end
  305.   RxStartSession        - Start a program in another session (DosStartSession)
  306.   RxStartRexxSession    - Start a Rexx program in another session
  307.   RxDetachRexxPgm       - Detach a Rexx program
  308.             Thread - Related
  309.   RxCreateRexxThread    - Execute a Rexx program on another thread
  310.   RxSetExceptionExit    - Specify the address of a "_System" linkage function
  311.                           which is called when an OS/2 exception occurs on a
  312.                           thread started with "RxCreateRexxThread".
  313.   RxCreateThread        - Call a procedure address on another thread
  314.   RxKillThread          - Kill a thread by thread-id
  315.   RxResumeThread        - Resume thread execution by thread-id
  316.   RxSuspendThread       - Suspend thread execution by thread-id
  317.   RxCallEntryPoint      - Call a (non-Rexx) routine by entry point address
  318.  
  319.   OS/2 Memory managment
  320.   ---------------------
  321.   RxMalloc              - Allocate memory using "malloc()"
  322.   RxFree                - Free memory allocated by "rxmalloc()" using "free()"
  323.   RxStructMap           - Generate a structure map for RxStruct2Stem()
  324.   RxStruct2Stem         - Map structure elements into a stem
  325.   RxStem2Struct         - Map a stem into structure elements
  326.   RxStorage             - Query/Alter storage by address
  327.   RxAdd2Ptr             - Pointer Arithmetic (Add/Subtract)
  328.   RxThunkAddr           - Thunk an address Flat->Segmented, Segmented->Flat
  329.   RxAllocMem            - Allocate Memory
  330.   RxFreeMem             - Free Memory
  331.   RxAllocSharedMem      - Allocated Shared memory (named or un-named)
  332.   RxGetSharedMem        - Get (gettable) shared memory
  333.   RxGiveSharedMem       - Give (giveable) shared memory
  334.   RxGetNamedSharedMem   - Get named shared memory
  335.   RxSetMem              - Set memory attributes
  336.   RxQueryMem            - Query memory attributes
  337.   RxSubAllocMem         - Suballocate memory
  338.   RxSubFreeMem          - Free suballocated memory
  339.   RxSubSetMem           - Set memory for suballocation
  340.   RxSubUnsetMem         - Unset previously "SubSet" memory
  341.  
  342.   OS/2 Semaphores
  343.   ---------------
  344.              Event Semaphore
  345.   RxCreateEventSem      - Create an event semaphore
  346.   RxCloseEventSem       - Close an event semaphore
  347.   RxOpenEventSem        - Open an event semaphore
  348.   RxPostEventSem        - Post an event semaphore
  349.   RxQueryEventSem       - Query an event semaphore
  350.   RxResetEventSem       - Reset an event semaphore
  351.   RxWaitEventSem        - Wait on an event semaphore
  352.              Mutex Semaphore
  353.   RxCreateMutexSem      - Create a Mutex semaphore
  354.   RxOpenMutexSem        - Invoke DosOpenMutexSem
  355.   RxCloseMutexSem       - Invoke DosCloseMutexSem
  356.   RxQueryMutexSem       - Invoke DosQueryMutexSem
  357.   RxReleaseMutexSem     - Invoke DosReleaseMutexSem
  358.   RxRequestMutexSem     - Invoke DosRequestMutexSem
  359.              MuxWait Semaphore
  360.   RxCreateMuxWaitSem    - Invoke DosCreateMuxWaitSem
  361.   RxCloseMuxWaitSem     - Invoke DosCloseMuxWaitSem
  362.   RxOpenMuxWaitSem      - Invoke DosOpenMuxWaitSem
  363.   RxWaitMuxWaitSem      - Invoke DosWaitMuxWaitSem
  364.   RxAddMuxWaitSem       - Invoke DosAddMuxWaitSem
  365.   RxDeleteMuxWaitSem    - Invoke DosDeleteMuxWaitSem
  366.   RxQueryMuxWaitSem     - Invoke DosQueryMuxWaitSem
  367.  
  368.   DLL Handling
  369.   ------------
  370.   RxLoadModule          - Load a DLL
  371.   RxFreeModule          - Free a DLL
  372.   RxQueryModuleName     - Query the fully qualified name of a DLL (by handle)
  373.   RxQueryModuleHandle   - Query the module handle of a DLL (by name)
  374.   RxQueryProcType       - Query the addressing mode of an entry point in a DLL
  375.   RxQueryProcAddr       - Query the procedure address of an entry point in a DLL
  376.  
  377.   Rexx Macro Space Handling
  378.   -------------------------
  379.   RxAddMacro            - Add a particular Macro Space function
  380.   RxDropMacro           - Drop a particular Macro Space function
  381.   RxClearMacroSpace     - Clear the Rexx Macro Space
  382.   RxSaveMacroSpace      - Save a particular Macro Space function to a file
  383.   RxLoadMacroSpace      - Load a particular Macro Space function from a file
  384.   RxQueryMacro          - Query the position of a particular Macro Space function
  385.   RxReorderMacro        - Reorder a function's position in a Macro Space
  386.  
  387.   PM / Wp related functions
  388.   -------------------------
  389.   RxWinQueryObject      - Query object handle of a WP object
  390.   RxWinDestroyObject    - Destroy a WP object
  391.  
  392.  
  393. ΓòÉΓòÉΓòÉ 6. Miscellaneous Programming Notes ΓòÉΓòÉΓòÉ
  394.  
  395. A few things to keep in mind when using the functions in this package. 
  396.  
  397.  
  398. ΓòÉΓòÉΓòÉ 6.1. Documentation of Parameter Values ΓòÉΓòÉΓòÉ
  399.  
  400. Many functions in this package are meant to provide a "pass-through" to the 
  401. underlying OS/2 API set.  For this reason, in most cases, I did not "simplify" 
  402. the parameter lists (one man's simplification is often another man's 
  403. complication anyway).  I also did not document the meaning of most of the API 
  404. parameter values (because of duplication effort, copyright, playing "keep-up", 
  405. etc.). 
  406.  
  407.  
  408. ΓòÉΓòÉΓòÉ 6.2. Binary Parameter Values ΓòÉΓòÉΓòÉ
  409.  
  410. Many of the OS/2 API pass-through functions that deal with file-handles, memory 
  411. addresses, semaphore handles, etc., treat these arguments/returned-values as 
  412. binary values (i.e. 16-/32-bit values) and do not convert these values to 
  413. hexadecimal strings. The reason for this is that these values are typically 
  414. only meant to be used as tokens that are passed back into some relevant 
  415. function (e.g. a semaphore handle obtained by a create-semaphore API is passed 
  416. back into some other semaphore function) and not scrutinized by the rexx code 
  417. itself.  In some cases, some functions return an integer value (as a normal 
  418. rexx integer number), but this number would subsequently be used by some other 
  419. function as a binary value (e.g. rxcreaterexxthread returns thread-id as a 
  420. normal rexx integer number, but rxkillthread() takes a binary value for the 
  421. thread-id argument).  The binary values required in these cases are typically 
  422. 32-bit integers, and also must be in little-endian form (i.e. byte-reversed). 
  423. A simple way to convert the integer value to the proper binary form is as such: 
  424.  
  425.   binary_value = reverse(d2c(integer_value,4))
  426.  
  427.  
  428. ΓòÉΓòÉΓòÉ 6.3. How Functions Return Values ΓòÉΓòÉΓòÉ
  429.  
  430. The functions in this package return essentially three categories of values: 
  431.  
  432.   1) An unknown number of values (e.g. rxvlist())
  433.   2) A known or fixed number of values that can be strung together as blank-delimited
  434.      tokens
  435.   3) A known or fixed number of values that may contain binary data (i.e. not what
  436.      we'd consider character strings)
  437.  
  438. For case #1, the values are usually returned either under a stem, or on a 
  439. queue.  For case #2, the values are often (but not always) returned as 
  440. blank-delimited tokens following the return code of the underlying OS/2 API 
  441. (thus, the values are most easily obtained by using the PARSE instruction, for 
  442. instance).  For case #3, the function usually requires you to supply a Rexx 
  443. variable name (or names) in which the binary values will be returned. 
  444.  
  445.  
  446. ΓòÉΓòÉΓòÉ 7. UPM Related Functions ΓòÉΓòÉΓòÉ
  447.  
  448. Functions which allow certain UPM activities to be performed. 
  449.  
  450.  
  451. ΓòÉΓòÉΓòÉ 7.1. RxUpm - Rexx/UPM Interface ΓòÉΓòÉΓòÉ
  452.  
  453. This function allows you to make most UPM calls from a Rexx program. 
  454.  
  455. Syntax:
  456.  
  457.   func  = 'Logon'     For Process level logon, only usable by that process */
  458.           'Logonp'
  459.         = 'Logonu'    For "User" logon, usable by all processes
  460.         = 'Logoff'    For Process level logoff, undoes a "LOGONP"
  461.           'Logoffp'
  462.         = 'Logoffu'   For "User" logoff, undoes a "LOGONU"
  463.         = 'LogonList' Gets list of current active logons
  464.   uid   = 'Userid'    Userid to be logged on/off
  465.         = 'stemname'  Name of Rexx stem variable under which results
  466.                       of "LogonList" are mapped as such:
  467.                       stem.0    - Number of logons reported on
  468.                       stem.n.1  - Userid
  469.                       stem.n.2  - Node/Domain name
  470.                       stem.n.3  - Session-Id
  471.                       stem.n.4  - Logon type (Local/Node/Domain)
  472.   pw    = 'Password'  Password to be used with 'Userid' (for logon)
  473.   type  = 'Local'     Logs you on/off UPM locally (default is LOCAL if
  474.                       no value supplied)
  475.         = 'Node'      Logs you on/off a node
  476.         = 'Domain'    Logs you on/off a LAN domain
  477.         = 'dataBase'  Logs you on/off the correct node for a database
  478.   name  = 'Name'      The name of the node/domain/database, depending on
  479.                       what "TYPE" was chosen
  480.   check = 'Admin'     Checks to see if userid has Admin authority
  481.         = 'User'      Checks to see if userid has User authority
  482.         = 'Config'    Checks to see if logon was done from Config.Sys
  483.  
  484.   upmrc = RxUpm(func, uid, pw, type, name, check)
  485.  
  486.  
  487. ΓòÉΓòÉΓòÉ 7.2. RxNet - Rexx/NET Interface ΓòÉΓòÉΓòÉ
  488.  
  489. This function allows you to make certain NetApi calls from Rexx.  This enables 
  490. you to do such things as changing passwords, adding and deleting userids, 
  491. validating a userid/pw, listing users and logons. 
  492.  
  493. Syntax:
  494.  
  495. /* General syntax */
  496.   netrc = RxNet(func, server, arg3, arg4, arg5, arg6)
  497.  
  498. where:
  499.  
  500.   func   = 'UserPwSet'    /* Change a user's password */
  501.          = 'UserAdd'      /* Add a user to UPM */
  502.          = 'UserDel'      /* Delete a user from UPM */
  503.          = 'UserVal'      /* Validate a userid/password without logging on */
  504.          = 'UserEnum'     /* List users in UPM */
  505.          = 'UserGetInfo'  /* Get user information */
  506.          = 'LogonEnum'    /* List active logons */
  507.          = 'FileEnum'     /* File usage on the LAN */
  508.          = 'UseAdd'       /* Do a "Net Use dev \\srv\alias" */
  509.          = 'UseDel'       /* Do a "Net Use dev /d" */
  510.          = 'UseEnum'      /* Do a "Net Use" */
  511.   server = name of server, or '00'x for local
  512.   netrc  = return code from NetApi call. If netrc < 2100, then it's probably
  513.            a base OS/2 return code, otherwise, it's defined in NETCONS.H
  514.  
  515. /* Specific calls */
  516.   netrc = RxNet('UserPwSet', server, userid, oldpw, newpw)
  517.  
  518.   netrc = RxNet('UserAdd', server, userid, password, type, comment)
  519.           type = 'User', 'Guest', or 'Admin'
  520.  
  521.   netrc = RxNet('UserDel', server, userid)
  522.  
  523.   netrc = RxNet('UserVal', server, userid, password)
  524.  
  525.   netrc = RxNet('UserEnum',server, rexxstem [,uidfilter][,infotype])
  526.           uidfilter = userid prefix filter (i.e. only return info on
  527.                       those userids whose leading characters match
  528.                       this prefix).
  529.           infotype  = "FULL" or "USERNAME" which indicates what type
  530.                       of information to return
  531.           rexxstem  = Rexx stem name, under which results are mapped as:
  532.                       stem.0 = if "uidfilter" not supplied:
  533.                                  - number of entries returned in stem
  534.                                if "uidfilter" was supplied, two blank
  535.                                delimited integers:
  536.                                  - number of entries returned in stem
  537.                                  - total number of entries
  538.                       stem.n.1 = userid
  539.  
  540.                       If infotype = "FULL", the following also:
  541.  
  542.                       stem.n.2 = privilege level (Guest, User, Admin, ?)
  543.                       stem.n.3 = password age (in seconds)
  544.                       stem.n.4 = comment
  545.                       stem.n.5 = script path
  546.                       stem.n.6 = full name
  547.                       stem.n.7 = user comment
  548.                       stem.n.8 = parms
  549.                       stem.n.9 = logon server
  550.  
  551.   netrc = RxNet('UserGetInfo',server, rexxstem ,username)
  552.           username  = username to get information for
  553.           rexxstem  = Rexx stem name, under which results are mapped as:
  554.                       stem.1 = userid
  555.                       stem.2 = privilege level (Guest, User, Admin, ?)
  556.                       stem.3 = password age (in seconds)
  557.                       stem.4 = comment
  558.                       stem.5 = script path
  559.                       stem.6 = full name
  560.                       stem.7 = user comment
  561.                       stem.8 = parms
  562.                       stem.9 = logon server
  563.  
  564.   netrc = RxNet('LogonEnum',server, rexxstem)
  565.           rexxstem = Rexx stem name, under which results are mapped as:
  566.                      stem.0 = number of users
  567.                      stem.n.1 = userid
  568.  
  569.   netrc = RxNet('FileEnum',server, basepath, username, rexxstem)
  570.           basepath = file path/name qualifier
  571.           username = username qualifier
  572.           rexxstem = Rexx stem name, under which results are mapped as:
  573.                      stem.0 = number of entries
  574.                      stem.n.1 = file-id
  575.                      stem.n.2 = permissions
  576.                      stem.n.3 = numlocks
  577.                      stem.n.4 = pathname
  578.                      stem.n.5 = username
  579.  
  580.   netrc = RxNet('UseAdd', server, device, name, password)
  581.           device   = Local name for resource, such as a drive letter
  582.           name     = server\alias (must be like "\\servname\alias")
  583.           password = optional password to use resource
  584.  
  585.   netrc = RxNet('UseDel', server, device, forcemode)
  586.           device    = Local name for resource, such as a drive letter
  587.           forcemode = 'F'orce
  588.                       'N'o force
  589.                       'M'ax force
  590.  
  591.   netrc = RxNet('UseEnum',server, rexxstem)
  592.           rexxstem = Rexx stem name, under which results are mapped as:
  593.                      stem.0 = number of entries
  594.                      stem.n.1 = device name
  595.                      stem.n.2 = name
  596.                      stem.n.3 = status, values are:
  597.                                 Ok
  598.                                 Paused
  599.                                 Disconnected/SessionLost
  600.                                 NetError
  601.                                 Connecting
  602.                                 Reconnecting
  603.                                 ?
  604.                      stem.n.4 = asg_type, values are:
  605.                                 WildCard
  606.                                 DiskDevice
  607.                                 SpooledPrinter
  608.                                 SerialDevice
  609.                                 IPC (InterProcessCommunication)
  610.                                 ?
  611.                      stem.n.5 = refcount
  612.                      stem.n.5 = usecount
  613.  
  614.  
  615. ΓòÉΓòÉΓòÉ 8. Math Library Functions ΓòÉΓòÉΓòÉ
  616.  
  617. Passthrough functions to standard 'C' math library functions. 
  618.  
  619. All functions take a single floating point value as an argument and return a 
  620. double precision floating point value as a result (with a few exceptions, where 
  621. noted by @). 
  622.  
  623.   RxuMthceil(x)    - smallest integer that is greater than or equal to "x" (from "ceiling")
  624.   RxuMthexp(x)     - "e" to the "x" power
  625.   RxuMthfloor(x)   - largest integer less than or equal to "x" (from "floor")
  626.  @RxuMthfmod(x,y)  - floating point remainder of x/y
  627.  @RxuMthfrexp(x)   - returns mantissa and exponent of "x" (two blank delimited values)
  628.  @RxuMthldexp(x,y) - computes x*(2**y)
  629.   RxuMthlog(x)     - natural logarithm of "x"
  630.   RxuMthlog10(x)   - base-10 logarithm of "x"
  631.  @RxuMthmodf(x)    - returns fractional and integral parts of "x" (two blank delimited values)
  632.  @RxuMthpow(x,y)   - "x" to the "y" power (x**y)
  633.   RxuMthsinh(x)    - hyperbolic sine of "x" ("x" in radians)
  634.   RxuMthcosh(x)    - hyperbolic cosine of "x" ("x" in radians)
  635.   RxuMthtanh(x)    - hyperbolic tangent of "x" ("x" in radians)
  636.   RxuMthasin(x)    - arcsine of "x" (in radians)
  637.   RxuMthacos(x)    - arccosine of "x" (in radians)
  638.  @RxuMthatan2(y,x) - arctangent of "y/x" (in radians)
  639.   RxuMthatan(x)    - arctangent of "x" (in radians)
  640.   RxuMthsin(x)     - sine of "x" ("x" in radians)
  641.   RxuMthcos(x)     - cosine of "x" ("x" in radians)
  642.   RxuMthtan(x)     - tangent of "x" ("x" in radians)
  643.   RxuMthsqrt(x)    - square root of "x"
  644.   RxuMthfabs(x)    - absolute value of "x"
  645.   RxuMtherf(x)     - error function of "x"
  646.   RxuMtherfc(x)    - computes 1.0 - erf(x) (used for large values of "x")
  647.   RxuMthgamma(x)   - gamma function of "x" ( ln(|G(x)|) )
  648.  @RxuMthhypot(x,y) - hypoteneuse of right triangle of sides "x" and "y" ( sqrt(x**2 + y**2) )
  649.  
  650.  
  651. ΓòÉΓòÉΓòÉ 9. Rexx Programming/Debugging ΓòÉΓòÉΓòÉ
  652.  
  653. Tools for developing Rexx programs. 
  654.  
  655.  
  656. ΓòÉΓòÉΓòÉ 9.1. RxSCount - Count instances of a string ΓòÉΓòÉΓòÉ
  657.  
  658. This function returns a count of the number of instances of a string "needle" 
  659. in a string "haystack", optionally ignoring case. 
  660.  
  661. Syntax:
  662.  
  663.   numitem = rxscount(needle,haystack[,case])
  664.  
  665. where:
  666.  
  667.   needle   = string you want to count instances of
  668.   haystack = string in which you want to count instances of "needle"
  669.   case     = any character to indicate that case (upper/lower) is to
  670.              be ignored
  671.   numitem  = number of times "needle" is found in "haystack"
  672.  
  673.  
  674. ΓòÉΓòÉΓòÉ 9.2. RxPmPrintf - Write lines to a PMPrintf Monitor ΓòÉΓòÉΓòÉ
  675.  
  676. This function writes data lines to a PMPrintf "Monitor" program. 
  677.  
  678. Syntax:
  679.  
  680.   bytes = RxPmPrintf(qname, [data1 [,data2 [,data3 [...]]]] )
  681.  
  682. where:
  683.  
  684.   qname    = name of PMPrintf queue
  685.              If blank, uses default PMPrintf Queue (PRINTF32).
  686.   data1    = data to be written to PMPrintf
  687.   ...        Each argument is written as a separate line
  688.   datan
  689.  
  690.   bytes    = number of bytes written in this operation
  691.  
  692. Notes:
  693.  
  694.   The PMPrintf tool can be downloaded from the OS/2 Bulletin Board.
  695.   This Rexx function does work with PMPrintf v2.5, but may not work
  696.   with earlier versions.  You can start the PMPrintf program with
  697.   a command line argument specifying an alternate queue name for it
  698.   to use.  This queue name can be supplied as the first argument of
  699.   RxPmPrintf to direct the data to a specific running instance of
  700.   PMPrintf.
  701.  
  702.   If only the queue name is supplied (i.e. args 2-n are not supplied),
  703.   nothing at all is written to queue.  If an argument has zero length,
  704.   no data will be written to the queue for that argument (i.e. you
  705.   must supply at least one byte to be written to queue).
  706.  
  707.  
  708. ΓòÉΓòÉΓòÉ 9.3. RxPassByName - Pass variables (by name) to external rexx (.CMD file) program ΓòÉΓòÉΓòÉ
  709.  
  710. This function allows one Rexx program to call another Rexx program (i.e. 
  711. another .CMD file), passing it rexx variables by name.  In addition, these 
  712. variables can be passed "by reference" or "by value." 
  713.  
  714. The normal method of invoking a Rexx external function is by the "call" 
  715. instruction or by function reference.  In these cases, arguments can be passed 
  716. as expressions and are accessed in the called routine by the "parse arg" 
  717. instruction or the "arg()" built-in function. 
  718.  
  719. To pass a variable name "by value" means that the variable's name and value 
  720. will be placed in the called program's variable pool before that called program 
  721. begins executing.  To pass a variable "by reference" means the same as "by 
  722. value," but additionally, any changes to the variable in the called program 
  723. will be reflected in the variable pool of the calling program upon return of 
  724. control (to the caller). 
  725.  
  726. Syntax:
  727.  
  728.   result = RxPassByName(yourfunc, varlist [,arg1,arg2,...,arg18])
  729.  
  730. where:
  731.  
  732.   yourfunc = name of rexx program file to be called (as function or subroutine)
  733.                    or
  734.              a '$' immediately preceding a rexx program source string
  735.                    or
  736.              a '&' immediately preceding a tokenized program string
  737.                    or
  738.              a '+' immediately preceding the name of a program in the macrospace
  739.  
  740.              whatever form of rexx program is specified, it can be run on a 2ndary
  741.              thread by preceding "yourfunc" with a tilda (~).  If the rexx program
  742.              is run on a 2ndary thread, "by reference" will not have an effect on
  743.              the calling program.
  744.   varlist  = list of blank delimited variable names to be passed to "yourfunc"
  745.              Individual items in the list are passed "by value" unless the item is
  746.              preceded by an ampersand (&), in which case it is passed by
  747.              reference.  For instance, in the following example,
  748.  
  749.                call rxpassbyname 'yourfunc','abc  &frank st1. &st2.', date()
  750.  
  751.              the variable "abc", and the stem "st1." would be passed "by value"
  752.              to "yourfunc", whereas the variable "frank" and the stem "st2." would
  753.              be passed "by reference" to "yourfunc".  That is, "abc" and all values
  754.              of the stem "st1." would be passed to "yourfunc" (but whatever "yourfunc"
  755.              does to these variables has no effect on their values in the caller), and
  756.              "frank" and all values of the stem "st2." would be passed to "yourfunc"
  757.              (and whatever "yourfunc" does to these variables WILL have an effect on
  758.              their values in the caller).
  759.  
  760.              Note that the called Rexx program ("yourfunc") will receive "arg1" as
  761.              its first argument, "arg2" as its second argument, and so on.  If you want
  762.              the called routine to know what variables were passed to it, you must
  763.              supply this variable list as a separate argument.
  764.   arg1     = subsequent argument(s) to "yourfunc", passed on as-is (i.e. in normal Rexx
  765.   ...        fashion.  Note that given the Rexx restriction of 20 arguments, and the
  766.   argn       fact that two arguments are "used up" by the called routine's name and
  767.              the variable name list, only 18 remain for normal argument passing.
  768.   result   = whatever value is returned by "yourfunc" (independent of what "flows"
  769.              back from "yourfunc" as a result of "by reference" variables).
  770.                    or
  771.              the thread-id of the 2ndary thread, if called routine was run on a 2ndary
  772.              thread
  773.  
  774. Notes:
  775.  
  776.   When variables are passed "by reference," whatever is done to a variable (or stem) in
  777.   the called routine will show up back in the calling routine, including dropping the
  778.   variable ("drop" instruction) with all that this implies for stems.  Thus, passing a
  779.   variable "by reference" to an external Rexx routine should have the same effect that
  780.   the "expose" option of the "procedure" instruction has on internal Rexx routines.
  781.   The difference is that "expose" is specified by the called routine, and "by reference"
  782.   is specified by the calling routine.
  783.  
  784.   RxPassByName() is multi-thread safe.  It may also be called by nested Rexx programs
  785.   (i.e. "pgma.cmd" calls "pgmb.cmd" which calls "pgmc.cmd", etc.), as would be expected.
  786.  
  787.  
  788. ΓòÉΓòÉΓòÉ 9.4. RxReturnByName - Return variables (by name) to external calling Rexx program ΓòÉΓòÉΓòÉ
  789.  
  790. This function allows a RxPassByName-called Rexx program to return rexx 
  791. variables (by name) to the calling rexx program (i.e. another .CMD file). 
  792. These variables are always passed "by value."  Values are obtained for return 
  793. at the time the rexx routine actually terminates (NOT when this function is 
  794. called).  So, this function has the effect of specifying what variables are to 
  795. be returned (actually, simple variables are specified at this time (i.e. 
  796. non-stems), but only the stem of compound variables are specified -- the actual 
  797. tails of a stem are resolved at return time). 
  798.  
  799. Syntax:
  800.  
  801.   successful = RxReturnByName(varlist)
  802.  
  803. where:
  804.  
  805.   varlist    = list of blank delimited variable names to be returned to caller
  806.                Individual variables are passed "by value".
  807.   successful = boolean (1 or 0) indicating whether items to be returned were noted
  808.  
  809. Notes:
  810.  
  811.   When using this function, it is up to you to ensure that the rexx routine from which
  812.   you call this function was itself invoked via the "RxPassByName()" function.  If this
  813.   is not the case, but some prior rexx routine in the call chain (on current thread) was
  814.   invoked via "RxPassByName()", that routine's caller will pick up the variable values
  815.   being passed back, and furthermore that "RxPassByName()"-invoked rexx program's values
  816.   will be returned, not those values from the current rexx program's variable pool.
  817.  
  818.   The upshot is that you must be careful when using this function that you call it only
  819.   from within a rexx program that was itself invoked (directly) via "RxPassByName()".
  820.  
  821.   RxReturnByName() is multi-thread safe.
  822.  
  823.  
  824. ΓòÉΓòÉΓòÉ 9.5. RxPBNBufSize - Set/Query fetch buffer size (used by RxPassByName) ΓòÉΓòÉΓòÉ
  825.  
  826. This function allows you to set the working buffer size used by RxPassByName to 
  827. fetch subsets of the variable pool when passing stem variables between Rexx 
  828. programs.  You do not have to use this function in order to use RxPassByName 
  829. (working buffer defaults to 32k), but you could use this function if, for 
  830. instance, many stem values are more than the default size (32k).  In this case, 
  831. you would specify a larger work buffer size to prevent RxPassByName from having 
  832. to access the variable pool twice for each stem value.  The size you specify 
  833. would ideally be as large as the longest stem value, but doesn't have to be 
  834. (i.e. RxPassByName will always work, just not as efficiently as it could). 
  835.  
  836. As a rule, you should never need to use this function.  It is just provided as 
  837. a means to tune RxPassByName in cases where tuning would matter (memory 
  838. constrained environment where you can't afford the default of 32k and stem 
  839. value lengths are usually much less than 32k, stem values longer than 32k, 
  840. etc.). 
  841.  
  842. Also, note that the work buffer size applies to all threads in a process. That 
  843. is, Rexx programs running on different threads in the same process will all use 
  844. the current value, so that any changes made to the buffer size will affect all 
  845. threads. 
  846.  
  847. Syntax:
  848.  
  849.   oldval = RxPBNBufSize([newsize])
  850.  
  851. where:
  852.  
  853.   newsize  = optional, new work buffer size
  854.   oldval   = previous work buffer size
  855.  
  856.  
  857. ΓòÉΓòÉΓòÉ 9.6. RxCallInStore - Execute a string as a program ΓòÉΓòÉΓòÉ
  858.  
  859. This function allows the Rexx program developer to execute a string as though 
  860. it were a Rexx program.  This allows you to build the equivalent of a Rexx 
  861. program's text in a variable, and then execute it from the string.  Actually, 
  862. the Rexx program text can come from anywhere -- a file, over a communications 
  863. link, from a database. For repeated execution of a program, use "RxTokenize" to 
  864. "compile" the program, then call "RxCallInStore" with "&" to re-use the 
  865. tokenized program. 
  866.  
  867. Syntax:
  868.  
  869.   result = RxCallInStore strtext, arg1, arg2, ..., arg19
  870.  
  871. where:
  872.  
  873.   strtext  = text of a Rexx program, complete with crlf and eof markers
  874.                   or
  875.              a '$' immediately preceding a source program string
  876.                   or
  877.              a '&' immediately preceding a tokenized program string
  878.   arg1     = arguments to the called program
  879.   ...
  880.   arg19
  881.  
  882. Note:
  883.  
  884.   Example of executing a program string:
  885.  
  886.     crlf = '0d0a'x
  887.     str = '/* Rexx */'crlf
  888.     str = str 'Do i=1 To Arg()'crlf
  889.     str = str '  Say "Arg#"i "= {"arg(i)"}"'crlf
  890.     str = str 'End'crlf
  891.     str = str||'1a'x       /* EOF marker */
  892.     call rxcallinstore str, date(), time()
  893.                ( or )
  894.     call rxcallinstore '$'str, date(), time()
  895.                ( or )
  896.     tstr = rxtokenize(str)
  897.     call rxcallinstore '&'tstr, date(), time()
  898.  
  899.  
  900. ΓòÉΓòÉΓòÉ 9.7. RxTokenize - Tokenize a program source string ΓòÉΓòÉΓòÉ
  901.  
  902. This function in effect "compiles" a program source string for re-use with 
  903. subsequent "RxCallInstore" or "RxCreateRexxThread" calls. This provides better 
  904. performance when a program string is repeatedly called. 
  905.  
  906. Syntax:
  907.  
  908.   tokenstr = RxTokenize(progstr)
  909.   rxrc = RxTokenize(progstr,rexxvar)
  910.  
  911. where:
  912.  
  913.   progstr  = actual Rexx program source string
  914.   rexxvar  = name of rexx variable in which tokenized version is returned
  915.   tokenstr = tokenized ("compiled") result of "progstr"
  916.   rxrc     = two blank delimited integers:
  917.              1) return code from invoking rexx interpreter
  918.              2) rexx return code
  919.  
  920. Note:
  921.  
  922.   This function, in conjunction with the "RxCallInstore" and/or
  923.   "RxCreateRexxThread" functions, can be used to achieve the same
  924.   effect as the Rexx Macrospace, except that this technique is local
  925.   to the program using it (whereas the Macrospace is system global).
  926.  
  927.  
  928. ΓòÉΓòÉΓòÉ 9.8. RxVlist - Display/Process Rexx Variables ΓòÉΓòÉΓòÉ
  929.  
  930. This function allows the Rexx program developer to view portions of the Rexx 
  931. variable pool.  It also allows you to effectively "pass" variable pools (or 
  932. subsets thereof) between execs across Rexx queues. 
  933.  
  934. Syntax:
  935.  
  936.   numvar = RxVlist( [vnamepat] [,func] [,qname] )
  937.  
  938. where:
  939.  
  940.   func     = 'V'  /* Puts variable name/value pairs on a queue */
  941.            = 'N'  /* Puts variable names on a queue */
  942.            = 'G'  /* Gets variable name/value pairs off a queue */
  943.                   /* and incorporates them into the current variable pool */
  944.            = 'D'  /* display variables and their values (default) */
  945.   vnamepat = variable name prefix (every variable whose name begins with this
  946.              value is processed according to the specified function)
  947.              (default is all variables)
  948.   qname    = name of a Rexx queue to use (default is the current queue)
  949.  
  950.  
  951. ΓòÉΓòÉΓòÉ 9.9. RxPullQueue - Pull items off any Rexx queue ΓòÉΓòÉΓòÉ
  952.  
  953. This function does what the Rexx "Pull" instruction and "LineIn" functions do, 
  954. except this function allows you to specify the queue name as part of the call, 
  955. regardless of what the current queue may be. 
  956.  
  957. Syntax:
  958.  
  959.   data = RxPullQueue( [qname] [,type] [,rexxvar] )
  960.  
  961. where:
  962.  
  963.   qname   = name of Rexx queue to pull from (default is current queue)
  964.   type    = 'Wait' or 'Nowait' (default is 'Wait')
  965.   rexxvar = name of a Rexx variable into which is put the queue-insertion-
  966.             timestamp for the retreived element
  967.   data    = data obtained from queue
  968.  
  969.  
  970. ΓòÉΓòÉΓòÉ 9.10. RxGlobalVar - Put,Get,Delete system-wide global variables ΓòÉΓòÉΓòÉ
  971.  
  972. This function manages a global variable pool (among all processes).  It 
  973. implements the pool using named Rexx queues (lazy but effective).  Each global 
  974. variable is just a queue whose name is derived from the variable's name and 
  975. which contains just one element (the variable's value).  The queue name is just 
  976. the variable name bracketed by "RXUGV".  For example, the variable name "FRANK" 
  977. would be implemented with a queue named "RXUGVFRANKRXUGV".  This obviously 
  978. presents the possibility of stepping on queues created for other purposes (that 
  979. happen to have the same name), but this isn't likely. 
  980.  
  981. Syntax:
  982.  
  983.   value = RxGlobalVar(action,varname[,newvalue])
  984.  
  985. where:
  986.  
  987.   action   = 'Put'
  988.              'Get'
  989.              'Delete'
  990.   varname  = name of variable to put, get, delete
  991.   newvalue = value for "varname" (put only)
  992.   value    = value of "varname" (get only)
  993.  
  994.  
  995. ΓòÉΓòÉΓòÉ 9.11. RxPullQueue - Pull items off any Rexx queue ΓòÉΓòÉΓòÉ
  996.  
  997. This function does what the Rexx "Pull" instruction and "LineIn" functions do, 
  998. except this function allows you to specify the queue name as part of the call, 
  999. regardless of what the current queue may be. 
  1000.  
  1001. Syntax:
  1002.  
  1003.   data = RxPullQueue( [qname] [,type] [,rexxvar] )
  1004.  
  1005. where:
  1006.  
  1007.   qname   = name of Rexx queue to pull from (default is current queue)
  1008.   type    = 'Wait' or 'Nowait' (default is 'Wait')
  1009.   rexxvar = name of a Rexx variable into which is put the queue-insertion-
  1010.             timestamp for the retreived element
  1011.   data    = data obtained from queue
  1012.  
  1013.  
  1014. ΓòÉΓòÉΓòÉ 9.12. RxAddQueue - Add items to any Rexx queue ΓòÉΓòÉΓòÉ
  1015.  
  1016. This function does what the Rexx "Queue" and "Push" instructions, and the 
  1017. "LineOut" function do, except this function allows you to specify the queue 
  1018. name as part of the call, regardless of what the current queue may be. 
  1019.  
  1020. Syntax:
  1021.  
  1022.   qrc = RxAddQueue( data [,qname] [,type] )
  1023.  
  1024. where:
  1025.  
  1026.   data  = data to be placed on queue
  1027.   qname = name of Rexx queue to add to (default is current queue)
  1028.   type  = 'Queue' or 'Push' (default is 'Queue')
  1029.  
  1030.  
  1031. ΓòÉΓòÉΓòÉ 9.13. RxQueued - Query number of items on any Rexx queue ΓòÉΓòÉΓòÉ
  1032.  
  1033. This function does what the Rexx "Queued" function does, except this function 
  1034. allows you to specify the queue name as part of the call, regardless of what 
  1035. the current queue may be. 
  1036.  
  1037. Syntax:
  1038.  
  1039.   numq = RxQueued( [qname] )
  1040.  
  1041. where:
  1042.  
  1043.   qname = name of Rexx queue to report on (default is current queue)
  1044.  
  1045.  
  1046. ΓòÉΓòÉΓòÉ 9.14. RxQExists - Query existence of a Rexx Queue ΓòÉΓòÉΓòÉ
  1047.  
  1048. This function returns "1" or "0", indicating the existence of the Rexx Queue 
  1049. whose name you supply as an argument. 
  1050.  
  1051. Syntax:
  1052.  
  1053.   bool = RxQExists( [qname] )
  1054.  
  1055. where:
  1056.  
  1057.   qname = name of Rexx queue to check for existence of
  1058.   bool  = truth value of queue's existence
  1059.  
  1060.  
  1061. ΓòÉΓòÉΓòÉ 9.15. RxSearchPath - Find a file in a path ΓòÉΓòÉΓòÉ
  1062.  
  1063. This function does what REXXUTIL's "SysSearchPath" does, but allows full use of 
  1064. DosSearchPath capabilities. 
  1065.  
  1066. Syntax:
  1067.  
  1068.   info = RxSearchPath(fname,path[,flags])
  1069.  
  1070. where:
  1071.  
  1072.   fname = name of file to search for (can contain pattern characters)
  1073.   path  = either an actual path string, or the name of an environment
  1074.           variable containing a path string
  1075.   flags = any combination of:
  1076.           V - indicates that "path" is an environment variable name,
  1077.               rather than an actual path string
  1078.           I - ignore network errors when searching through network
  1079.               drives
  1080.           C - search current directory first
  1081.           The default is "Not V, Not I, Not C".
  1082.   info  = two blank delimited tokens:
  1083.           1) return code from DosSearchPath
  1084.           2) If (1) is zero, the fully qualified name of the file found
  1085.  
  1086.  
  1087. ΓòÉΓòÉΓòÉ 9.16. RxRegisterFunctionExe - Use "RexxRegisterFunctionExe()" ΓòÉΓòÉΓòÉ
  1088.  
  1089. This function allows you to register an external function for the current .EXE 
  1090. only. 
  1091.  
  1092. Syntax:
  1093.  
  1094.   rxrc = RxRegisterFunctionExe(funcname,funcaddr)
  1095.  
  1096. where:
  1097.  
  1098.   funcname = name of external function
  1099.   funcaddr = address of function implementation
  1100.              (e.g. - could be obtained by RxQueryProcAddr)
  1101.   rxrc     = return code from RexxRegisterFunctionExe()
  1102.  
  1103.  
  1104. ΓòÉΓòÉΓòÉ 9.17. RxRegisterExitDll - Use "RexxRegisterExitDll()" ΓòÉΓòÉΓòÉ
  1105.  
  1106. This function allows you to register a Rexx exit handler that resides in a .DLL 
  1107.  
  1108. Syntax:
  1109.  
  1110.   rxrc = RxRegisterExitDll(hname,dllname,procname,udata,dropflag)
  1111.  
  1112. where:
  1113.  
  1114.   hname    = handler name
  1115.   dllname  = name of .DLL where handler code resides
  1116.   procname = name of procedure in .DLL that implements handler
  1117.   udata    = user data (1-8 bytes)
  1118.   dropflag = D - can be dropped
  1119.              N - cannot be dropped
  1120.   rxrc     = return code from RexxRegisterExitDll()
  1121.  
  1122.  
  1123. ΓòÉΓòÉΓòÉ 9.18. RxRegisterExitExe - Use "RexxRegisterExitExe()" ΓòÉΓòÉΓòÉ
  1124.  
  1125. This function allows you to register a Rexx exit handler that resides in a .EXE 
  1126.  
  1127. Syntax:
  1128.  
  1129.   rxrc = RxRegisterExitExe(hname,funcaddr,udata)
  1130.  
  1131. where:
  1132.  
  1133.   hname    = handler name
  1134.   funcaddr = address of handler function implementation
  1135.              (e.g. - could be obtained by RxQueryProcAddr)
  1136.   udata    = user data (1-8 bytes)
  1137.   rxrc     = return code from RexxRegisterExitExe()
  1138.  
  1139.  
  1140. ΓòÉΓòÉΓòÉ 9.19. RxQueryExit - Use "RexxQueryExit()" ΓòÉΓòÉΓòÉ
  1141.  
  1142. This function allows you to query exit information 
  1143.  
  1144. Syntax:
  1145.  
  1146.   rxrc = RxQueryExit(hname,modname)
  1147.  
  1148. where:
  1149.  
  1150.   hname    = name of handler
  1151.   modname  = handler module name
  1152.   rxrc     = return code from RexxQueryExit()
  1153.  
  1154.  
  1155. ΓòÉΓòÉΓòÉ 9.20. RxDeregisterExit - Use "RexxDeregisterExit()" ΓòÉΓòÉΓòÉ
  1156.  
  1157. This function allows you to de-register a Rexx exit 
  1158.  
  1159. Syntax:
  1160.  
  1161.   rxrc = RxDeregisterExit(hname,modname)
  1162.  
  1163. where:
  1164.  
  1165.   hname    = name of handler
  1166.   modname  = handler module name
  1167.   rxrc     = return code from RexxDeregisterExit()
  1168.  
  1169.  
  1170. ΓòÉΓòÉΓòÉ 10. Memory Management/Access ΓòÉΓòÉΓòÉ
  1171.  
  1172. These functions allow Rexx programs to create, access, and manage OS/2 memory 
  1173. objects by address.  This includes objects such as shared memory (named and 
  1174. un-named). 
  1175.  
  1176. Note that for named shared memory, the memory name must begin with 
  1177. "\sharemem\".  Thus, a valid shared memory name would be "\sharemem\frank" 
  1178. whereas "\frank" would not be valid. 
  1179.  
  1180.  
  1181. ΓòÉΓòÉΓòÉ 10.1. RxMalloc - Allocate memory using "malloc()" ΓòÉΓòÉΓòÉ
  1182.  
  1183. This function allocates memory using the 'C' "malloc()" function and returns 
  1184. the address of this memory.  This will allocate memory faster and more 
  1185. efficiently than the "RxAllocMem()" function (as a rule). Whereas the 
  1186. granularity of "RxAllocMem()" is at best a 4k page, the "rxmalloc()" 
  1187. granularity is much better as a rule. 
  1188.  
  1189. Memory allocated with "rxmalloc()" must only be freed with "rxfree()" and NOT 
  1190. with "RxFreeMem()". 
  1191.  
  1192. Syntax:
  1193.  
  1194.   address = RxMalloc(size)
  1195.  
  1196. where
  1197.  
  1198.   address = 32-bit address of allocated storage
  1199.   size    = bytes of storage to allocate
  1200.  
  1201.  
  1202. ΓòÉΓòÉΓòÉ 10.2. RxFree - Free memory allocated by "rxmalloc()" using "free()" ΓòÉΓòÉΓòÉ
  1203.  
  1204. This function frees memory using the 'C' "free()" function and returns the 
  1205. address of this memory. 
  1206.  
  1207. "rxfree()" must only be used to free memory allocated with the "rxmalloc()" 
  1208. function and NOT to free memory allocated with "RxAllocMem()" or 
  1209. "RxAllocSharedMem()", etc. 
  1210.  
  1211. Syntax:
  1212.  
  1213.   done = RxFree(address)
  1214.  
  1215. where
  1216.  
  1217.   address = 32-bit address of storage to be freed
  1218.   done    = always '1'
  1219.  
  1220.  
  1221. ΓòÉΓòÉΓòÉ 10.3. RxStructMap - Generate a structure map for RxStruct2Stem() ΓòÉΓòÉΓòÉ
  1222.  
  1223. This function builds a "structure map" which can be used by the function 
  1224. RxStruct2Stem() to map the elements of a structure into a Rexx stem.  The 
  1225. elements of the structure must be described by the Rexx program.  This can be 
  1226. used to access the elements of a structure whose address is passed to the Rexx 
  1227. program by a compiled program. 
  1228.  
  1229. Syntax:
  1230.  
  1231.   map = RxStructMap(stemname)
  1232.  
  1233. where
  1234.  
  1235.   stemname = name of Rexx stem under which structure is described as such:
  1236.  
  1237.              stem.0   = Number of elements in structure (1-n)
  1238.              stem.P   = Packing mode of structure (default = 1)
  1239.              stem.n.T = Type of element "n" in structure.  Valid
  1240.                         values are:
  1241.                         l = signed long integer    (4 bytes)
  1242.                         L = unsigned long integer  (4 bytes)
  1243.                         s = signed short integer   (2 bytes)
  1244.                         S = unsigned short integer (2 bytes)
  1245.                         d = double                 (8 bytes)
  1246.                         D = double                 (8 bytes)
  1247.                         c = character array        (stem.n.L bytes)
  1248.                         C = character array        (stem.n.L bytes)
  1249.              stem.n.L = Length of character array (if type = 'C'
  1250.                         or 'c')
  1251.  
  1252.   map      = binary structure map used by RxStruct2Stem()
  1253.  
  1254.  
  1255. ΓòÉΓòÉΓòÉ 10.4. RxStruct2Stem - Map structure elements into a stem ΓòÉΓòÉΓòÉ
  1256.  
  1257. This function allows a Rexx program to map the elements of a structure into a 
  1258. Rexx stem.  The structure is referred to by its address.  The structure is 
  1259. described by the map built with RxStructMap().  This can be used to access the 
  1260. elements of a structure whose address is passed to the Rexx program by a 
  1261. compiled program. 
  1262.  
  1263. Syntax:
  1264.  
  1265.   bytes = RxStruct2Stem(stemname, pointer, map)
  1266.  
  1267. where
  1268.  
  1269.   stemname = name of Rexx stem under which structure elements' values
  1270.              are returned, as such:
  1271.  
  1272.              stem.0   = Number of elements in structure
  1273.              stem.n   = Actual value of element "n" in structure
  1274.  
  1275.   pointer  = 32-bit pointer (address) to base of structure
  1276.   map      = structure map generated by RxStructMap()
  1277.   bytes    = total number of bytes in structure
  1278.  
  1279.  
  1280. ΓòÉΓòÉΓòÉ 10.5. RxStem2Struct - Map a stem into structure elements ΓòÉΓòÉΓòÉ
  1281.  
  1282. This function allows a Rexx program to map a stem variable into the elements of 
  1283. a structure.  The structure is referred to by its address. 
  1284.  
  1285.  
  1286. Syntax:
  1287.  
  1288.   bytes = RxStem2Struct(stemname, pointer, map)
  1289.  
  1290. where
  1291.  
  1292.   stemname = name of Rexx stem under which structure elements' values
  1293.              are provided, as such:
  1294.  
  1295.              stem.n   = Actual value of element "n" in structure
  1296.  
  1297.   pointer  = 32-bit pointer (address) to base of structure
  1298.   map      = structure map generated by RxStructMap()
  1299.   bytes    = total number of bytes in structure
  1300.  
  1301.  
  1302. ΓòÉΓòÉΓòÉ 10.6. RxStorage - Access/Alter memory by address ΓòÉΓòÉΓòÉ
  1303.  
  1304. This function allows a Rexx program to access and/or alter storage by address. 
  1305. This could be used to process data passed to it by a program.  This could also 
  1306. be used to "Pass By Reference" among Rexx programs when using the RxAllocMem 
  1307. and RxFreeMem functions. 
  1308.  
  1309. Syntax:
  1310.  
  1311.   outdata = RxStorage( pointer [, length] [, indata] )
  1312.  
  1313. where
  1314.  
  1315.   pointer  = 32-bit pointer (address)
  1316.   length   = Length of storage to be queried (defaults to 1)
  1317.   indata   = Data to place at address "pointer" for the length of the data
  1318.              (regardless of "length" value)
  1319.   outdata  = Data at address "pointer" for length "length" (truncated if
  1320.              "length" takes you beyond allowed storage)
  1321.  
  1322. Note:
  1323.  
  1324.   A request to query memory out-of-bounds returns a string up to the bound-
  1325.   ary.  A request to set memory out-of-bounds, sets memory up to the bound-
  1326.   ary.  All memory is allocated in 4k chunks.  Therefore, some query or set
  1327.   operations will access memory up to the next 4k boundary.
  1328.  
  1329.  
  1330. ΓòÉΓòÉΓòÉ 10.7. RxAdd2Ptr - Pointer Arithmetic (Add/Subtract) ΓòÉΓòÉΓòÉ
  1331.  
  1332. This function allows a Rexx program to add or subtract from an OS/2 32-bit 
  1333. linear address. 
  1334.  
  1335. Syntax:
  1336.  
  1337.   newptr = RxAdd2Ptr( pointer , [number] )
  1338.  
  1339. where:
  1340.  
  1341.   pointer  = 32-bit pointer (address)
  1342.   number   = amount by which "pointer" is to be incremented/decremented
  1343.              in bytes.  Default is zero.
  1344.   newptr   = result of addition/subtraction
  1345.  
  1346.  
  1347. ΓòÉΓòÉΓòÉ 10.8. RxThunkAddr - Thunk an address Flat->Segmented, Segmented->Flat ΓòÉΓòÉΓòÉ
  1348.  
  1349. This function allows a Rexx program to "thunk" an address from flat to 
  1350. segmented, or from segmented to flat (i.e. 32->16 bit or 16->32 bit). 
  1351.  
  1352. Syntax:
  1353.  
  1354.   newptr = RxThunkAddr( pointer , type )
  1355.  
  1356. where:
  1357.  
  1358.   pointer  = input address
  1359.   type     = indicates what to convert input address to:
  1360.              S - convert input address from flat to segmented (32->16)
  1361.              F - convert input address from segmented to flat (16->32)
  1362.   newptr   = thunked address
  1363.  
  1364.  
  1365. ΓòÉΓòÉΓòÉ 10.9. RxAllocMem - Allocate memory (using DosAllocMem) ΓòÉΓòÉΓòÉ
  1366.  
  1367. This function allows a Rexx program to allocate memory.  This memory can then 
  1368. be accessed using RxStorage. 
  1369.  
  1370. Syntax:
  1371.  
  1372.   allocrc = RxAllocMem(rexxvar, length, flags)
  1373.  
  1374. where
  1375.  
  1376.   rexxvar = name of a rexx variable in which pointer is returned
  1377.   length  = a decimal integer indicating amount of storage (in bytes) to
  1378.             allocate
  1379.   flags   = any combination of:
  1380.             C - Pag_Commit
  1381.             T - Obj_Tile
  1382.             X - Pag_Execute
  1383.             R - Pag_Read
  1384.             W - Pag_Write
  1385.             G - Pag_Guard
  1386.   allocrc = return code from DosAllocMem()
  1387.  
  1388. for example:
  1389.             /* Following would get 4k committed read/write */
  1390.   allocrc = RxAllocMem('pointer', 4096, 'crw')
  1391.  
  1392. Note:
  1393.  
  1394.   All memory is allocated in 4k chunks.  Therefore, even if you allocate 200
  1395.   bytes, you will get access to 4096 bytes.
  1396.  
  1397.  
  1398. ΓòÉΓòÉΓòÉ 10.10. RxFreeMem - Free memory allocated by RxAllocMem ΓòÉΓòÉΓòÉ
  1399.  
  1400. This function allows a Rexx program to free memory allocated by RxAllocMem. 
  1401.  
  1402. Syntax:
  1403.  
  1404.   freerc = RxFreeMem(pointer)
  1405.  
  1406. where
  1407.  
  1408.   pointer - A valid 32 bit pointer.
  1409.  
  1410. Note:
  1411.  
  1412.   Returned value is return code from DosFreeMem
  1413.  
  1414.  
  1415. ΓòÉΓòÉΓòÉ 10.11. RxAllocSharedMem - Allocate shared memory ΓòÉΓòÉΓòÉ
  1416.  
  1417. This function allocates shared (named or un-named) memory.  Other processes can 
  1418. access this memory with either RxGetSharedMem (un-named), or 
  1419. RxGetNamedSharedMem (named), or if it is "Given", followed by calls to 
  1420. RxStorage. 
  1421.  
  1422. Syntax:
  1423.  
  1424.   allocrc = RxAllocSharedMem(rexxvar, length, flags [,memname] )
  1425.  
  1426. where
  1427.  
  1428.   rexxvar = name of a rexx variable in which pointer is returned
  1429.   length  = a decimal integer indicating amount of storage (in bytes) to
  1430.             allocate
  1431.   flags   = any combination of:
  1432.             C - Pag_Commit
  1433.             T - Obj_Tile
  1434.             I - Obj_Giveable
  1435.             E - Obj_Gettable (sic)
  1436.             X - Pag_Execute
  1437.             R - Pag_Read
  1438.             W - Pag_Write
  1439.             G - Pag_Guard
  1440.   memname = name of shared memory object, if this is to be named shared
  1441.             memory
  1442.   allocrc = return code from DosAllocSharedMem()
  1443.  
  1444. for example:
  1445.  
  1446.   /* To allocate an un-named, gettable object */
  1447.   allocrc = RxAllocSharedMem('pointer', 4096, 'cerw')
  1448.  
  1449.   /* To allocate a named object */
  1450.   allocrc = RxAllocSharedMem('pointer', 4096, 'crw','\SHAREMEM\TEST.MEM')
  1451.  
  1452. Note:
  1453.  
  1454.   All memory is allocated in 4k chunks.  Therefore, even if you allocate 200
  1455.   bytes, you will get access to 4096 bytes.
  1456.  
  1457.  
  1458. ΓòÉΓòÉΓòÉ 10.12. RxGiveSharedMem - Give access to shared memory ΓòÉΓòÉΓòÉ
  1459.  
  1460. This function gives access to shared, un-named memory to a process-id 
  1461.  
  1462. Syntax:
  1463.  
  1464.   giverc = RxGiveSharedMem(pointer, pid [,flags])
  1465.  
  1466. where
  1467.  
  1468.   pointer = valid 32-bit pointer
  1469.   pid     = valid process-id (as a decimal integer)
  1470.   flags   = any combination of:
  1471.             X - Pag_Execute
  1472.             R - Pag_Read
  1473.             W - Pag_Write
  1474.             G - Pag_Guard
  1475.  
  1476. for example:
  1477.  
  1478.   /* To give shared memory */
  1479.   giverc = RxGiveSharedMem(pointer, 23, 'rw')
  1480.  
  1481. Note:
  1482.  
  1483.   A valid pointer must be supplied.  This is obtained from the process which
  1484.   allocated the shared un-named memory via RxAllocSharedMem.  The process-id
  1485.   supplied must be valid (i.e. must currently exist).
  1486.  
  1487.  
  1488. ΓòÉΓòÉΓòÉ 10.13. RxGetSharedMem - Get access to shared memory ΓòÉΓòÉΓòÉ
  1489.  
  1490. This function gets access to shared, un-named, gettable memory. 
  1491.  
  1492. Syntax:
  1493.  
  1494.   getrc = RxGetSharedMem(pointer, flags)
  1495.  
  1496. where
  1497.  
  1498.   pointer = valid 32-bit pointer
  1499.   flags   = any combination of:
  1500.             X - Pag_Execute
  1501.             R - Pag_Read
  1502.             W - Pag_Write
  1503.             G - Pag_Guard
  1504.  
  1505. for example:
  1506.  
  1507.   /* To get shared memory */
  1508.   getrc = RxGetSharedMem(pointer, 'rw')
  1509.  
  1510. Note:
  1511.  
  1512.   A valid pointer must be supplied.  This is obtained from the process which
  1513.   allocated the shared un-named memory via RxAllocSharedMem.
  1514.  
  1515.  
  1516. ΓòÉΓòÉΓòÉ 10.14. RxGetNamedSharedMem - Get access to named shared memory ΓòÉΓòÉΓòÉ
  1517.  
  1518. This function gets access to shared, named memory. 
  1519.  
  1520. Syntax:
  1521.  
  1522.   getrc = RxGetNamedSharedMem(rexxvar, memname, flags)
  1523.  
  1524. where
  1525.  
  1526.   rexxvar = name of a rexx variable in which pointer is returned
  1527.   memname = valid name of a shared memory object
  1528.   flags   = any combination of:
  1529.             X - Pag_Execute
  1530.             R - Pag_Read
  1531.             W - Pag_Write
  1532.             G - Pag_Guard
  1533.   getrc   = return code from DosGetNamedSharedMem()
  1534.  
  1535. for example:
  1536.  
  1537.   /* To get named shared memory */
  1538.   getrc = RxGetNamedSharedMem('pointer', '\SHAREMEM\TEST.MEM', 'rw')
  1539.  
  1540.  
  1541. ΓòÉΓòÉΓòÉ 10.15. RxSetMem - Set memory attributes ΓòÉΓòÉΓòÉ
  1542.  
  1543. This function sets memory attributes using DosSetMem 
  1544.  
  1545. Syntax:
  1546.  
  1547.   setrc = RxSetMem(pointer [,memsize [,flags]])
  1548.  
  1549. where
  1550.  
  1551.   pointer = valid 32-bit pointer
  1552.   memsize = size of memory block to set
  1553.   flags   = any combination of:
  1554.             C - Pag_Commit
  1555.             D - Pag_Decommit
  1556.             F - Pag_Default
  1557.             X - Pag_Execute
  1558.             R - Pag_Read
  1559.             W - Pag_Write
  1560.             G - Pag_Guard
  1561.  
  1562. for example:
  1563.  
  1564.   /* To set memory attributes */
  1565.   setrc = RxSetMem(pointer, 4096, 'crw')
  1566.  
  1567. Note:
  1568.  
  1569.   Returned value is return code from DosSetMem.
  1570.  
  1571.  
  1572. ΓòÉΓòÉΓòÉ 10.16. RxQueryMem - Query memory attributes ΓòÉΓòÉΓòÉ
  1573.  
  1574. This function queries memory attributes using DosQueryMem 
  1575.  
  1576. Syntax:
  1577.  
  1578.   qinfo = RxQueryMem(pointer [,memsize])
  1579.  
  1580. where
  1581.  
  1582.   pointer = valid 32-bit pointer
  1583.   memsize = size of memory block to query
  1584.   qinfo   = either one or three blank-delimited tokens:
  1585.             1) return code from DosQueryMem
  1586.                If #1 is zero:
  1587.                  2) actual memory size
  1588.                  3) memory attribute flags, which can be any combination of:
  1589.                     C - Pag_Commit
  1590.                     F - Pag_Free
  1591.                     S - Pag_Shared
  1592.                     B - Pag_Base
  1593.                     X - Pag_Execute
  1594.                     R - Pag_Read
  1595.                     W - Pag_Write
  1596.                     G - Pag_Guard
  1597.  
  1598. for example:
  1599.  
  1600.   /* To query memory attributes */
  1601.   qinfo = RxQueryMem(pointer, 4096)
  1602.   /* "Say qinfo" might say -> "0 4096 CSRW" for instance */
  1603.  
  1604. Note:
  1605.  
  1606.   If first token is not zero, no other information was returned.
  1607.  
  1608.  
  1609. ΓòÉΓòÉΓòÉ 10.17. RxSubSetMem - Set memory for suballocation ΓòÉΓòÉΓòÉ
  1610.  
  1611. This function sets memory for suballocation using DosSubSetMem 
  1612.  
  1613. Syntax:
  1614.  
  1615.   subsetrc = RxSubSetMem(pointer [,memsize [,flags]])
  1616.  
  1617. where
  1618.  
  1619.   pointer = valid 32-bit pointer to pool
  1620.   memsize = size of memory block to subset
  1621.   flags   = any combination of:
  1622.             I - DosSub_Init
  1623.             G - DosSub_Grow
  1624.             S - DosSub_Sparse
  1625.             R - DosSub_Serialize
  1626.  
  1627. for example:
  1628.  
  1629.   /* To subset some memory */
  1630.   subsetrc = RxSubSetMem(pointer, 4096, 'i')
  1631.  
  1632. Note:
  1633.  
  1634.   Returned value is return code from DosSubSetMem.
  1635.  
  1636.  
  1637. ΓòÉΓòÉΓòÉ 10.18. RxSubUnSetMem - UnSet memory from suballocation ΓòÉΓòÉΓòÉ
  1638.  
  1639. This function unsets memory from suballocation using DosSubUnSetMem 
  1640.  
  1641. Syntax:
  1642.  
  1643.   subunsetrc = RxSubUnSetMem(pointer)
  1644.  
  1645. where
  1646.  
  1647.   pointer = valid 32-bit pointer to pool
  1648.  
  1649. for example:
  1650.  
  1651.   /* To subunset some memory */
  1652.   subunsetrc = RxSubUnSetMem(pointer)
  1653.  
  1654. Note:
  1655.  
  1656.   Returned value is return code from DosSubUnSetMem.
  1657.  
  1658.  
  1659. ΓòÉΓòÉΓòÉ 10.19. RxSubAllocMem - Suballocate memory ΓòÉΓòÉΓòÉ
  1660.  
  1661. This function suballocates memory. 
  1662.  
  1663. Syntax:
  1664.  
  1665.   subarc = RxSubAllocMem(rexxvar, pointer [,memsize])
  1666.  
  1667. where
  1668.  
  1669.   rexxvar = name of a rexx variable in which block offset is returned
  1670.   pointer = valid 32-bit pointer to pool
  1671.   memsize = size of block to suballocate
  1672.   subarc  = return code from DosSubAllocMem()
  1673.  
  1674. for example:
  1675.  
  1676.   /* To suballocate some memory */
  1677.   subarc = RxSubAllocMem('block_offset', pointer, 4096)
  1678.  
  1679.  
  1680. ΓòÉΓòÉΓòÉ 10.20. RxSubFreeMem - Free suballocated memory ΓòÉΓòÉΓòÉ
  1681.  
  1682. This function frees suballocated memory. 
  1683.  
  1684. Syntax:
  1685.  
  1686.   freerc = RxSubFreeMem(pointer, boffset [,memsize])
  1687.  
  1688. where
  1689.  
  1690.   pointer = valid 32-bit pointer to pool
  1691.   boffset = block offset pointer
  1692.   memsize = size of block to free
  1693.  
  1694. for example:
  1695.  
  1696.   /* To free suballocated memory */
  1697.   freerc = RxSubFreeMem(pointer, boffset, 4096)
  1698.  
  1699. Note:
  1700.  
  1701.   Returned value is return code from DosSubFreeMem.
  1702.  
  1703.  
  1704. ΓòÉΓòÉΓòÉ 11. Semaphore handling ΓòÉΓòÉΓòÉ
  1705.  
  1706. These functions allow Rexx programs to make use of OS/2 semaphores for 
  1707. synchronization/serialization purposes. 
  1708.  
  1709. Note that for named semaphores (event, mutex, or mux) the semaphore name must 
  1710. begin with "\sem32\".  Thus, a valid semaphore name would be "\sem32\frank" 
  1711. whereas "\frank" would not be valid. 
  1712.  
  1713.  
  1714. ΓòÉΓòÉΓòÉ 11.1. RxCreateEventSem - Create an event semaphore ΓòÉΓòÉΓòÉ
  1715.  
  1716. This function creates a (named or un-named) event semaphore. 
  1717.  
  1718. Syntax:
  1719.  
  1720.   semrc = RxCreateEventSem(rexxvar [,type] [,name] [,state] )
  1721.  
  1722. where
  1723.  
  1724.   rexxvar = name of a rexx variable in which sem handle is returned
  1725.   type    = 'Shared' or 'Private' (default is Private)
  1726.   name    = semaphore name (default is un-named)
  1727.   state   = 'Reset' or 'Posted' (default is Reset)
  1728.   semrc   = return code from DosCreateEventSem()
  1729.  
  1730.  
  1731. ΓòÉΓòÉΓòÉ 11.2. RxOpenEventSem - Open an event semaphore ΓòÉΓòÉΓòÉ
  1732.  
  1733. This function opens an event semaphore for use by a process that did not create 
  1734. the semaphore. 
  1735.  
  1736. Syntax:
  1737.  
  1738.   semrc = RxOpenEventSem(rexxvar, semid)
  1739.  
  1740. where
  1741.  
  1742.   rexxvar = name of a rexx variable in which sem handle is returned
  1743.   semid   = either a semaphore handle, or a semaphore name
  1744.   semrc   = return code from DosOpenEventSem()
  1745.  
  1746. Note:
  1747.  
  1748.   A zero length string is returned if DosOpenEventSem fails.
  1749.  
  1750.  
  1751. ΓòÉΓòÉΓòÉ 11.3. RxPostEventSem - Post an event semaphore ΓòÉΓòÉΓòÉ
  1752.  
  1753. This function posts an event semaphore. 
  1754.  
  1755. Syntax:
  1756.  
  1757.   postrc = RxPostEventSem(hev)
  1758.  
  1759. where
  1760.  
  1761.   hev    = semaphore handle
  1762.   postrc = return code from DosPostEventSem
  1763.  
  1764.  
  1765. ΓòÉΓòÉΓòÉ 11.4. RxQueryEventSem - Query an event semaphore ΓòÉΓòÉΓòÉ
  1766.  
  1767. This function returns the post count for an event semaphore. 
  1768.  
  1769. Syntax:
  1770.  
  1771.   info = RxQueryEventSem(hev)
  1772.  
  1773. where
  1774.  
  1775.   hev    = semaphore handle
  1776.   info   = return code from DosQueryEventSem, followed by number of posts
  1777. Note:
  1778.  
  1779.   Word 1 of info is the return code from DosQueryEventSem
  1780.   Word 2 of info is the actual number of posts to the semaphore
  1781.  
  1782.  
  1783. ΓòÉΓòÉΓòÉ 11.5. RxResetEventSem - Reset an event semaphore ΓòÉΓòÉΓòÉ
  1784.  
  1785. This function resets an event semaphore, returning the number of postings for 
  1786. that semaphore. 
  1787.  
  1788. Syntax:
  1789.  
  1790.   info = RxResetEventSem(hev)
  1791.  
  1792. where
  1793.  
  1794.   hev    = semaphore handle
  1795.   info   = return code from DosResetEventSem, followed by number of posts
  1796.  
  1797. Note:
  1798.  
  1799.   Word 1 of info is the return code from DosResetEventSem
  1800.   Word 2 of info is the actual number of posts to the semaphore before
  1801.                     the Reset.
  1802.  
  1803.  
  1804. ΓòÉΓòÉΓòÉ 11.6. RxWaitEventSem - Wait on an event semaphore ΓòÉΓòÉΓòÉ
  1805.  
  1806. This function waits on the posting of an event semaphore. 
  1807.  
  1808. Syntax:
  1809.  
  1810.   semhandle /* A valid semaphore handle */
  1811.   time = 1000   /* in milliseconds */
  1812.  
  1813.   waitrc = RxWaitEventSem(hev [,time])
  1814.  
  1815. where
  1816.  
  1817.   hev    = semaphore handle
  1818.   time   = number of miliseconds to wait before returning, or the word
  1819.            'Indefinite'.  Default is 'Indefinite'.
  1820.   waitrc = return code from DosWaitEventSem
  1821.  
  1822.  
  1823. ΓòÉΓòÉΓòÉ 11.7. RxCloseEventSem - Close an event semaphore ΓòÉΓòÉΓòÉ
  1824.  
  1825. This function closes an event semaphore 
  1826.  
  1827. Syntax:
  1828.  
  1829.   closerc = RxCloseEventSem(hev)
  1830.  
  1831. where
  1832.  
  1833.   hev     = semaphore handle
  1834.   closerc = return code from DosCloseEventSem
  1835.  
  1836.  
  1837. ΓòÉΓòÉΓòÉ 11.8. RxCreateMutexSem - Create a Mutex Semaphore ΓòÉΓòÉΓòÉ
  1838.  
  1839. This function creates a mutex semaphore 
  1840.  
  1841. Syntax:
  1842.  
  1843.   semrc = RxCreateMutexSem(rexxvar [,type] [,name] [,state] )
  1844.  
  1845. where
  1846.  
  1847.   rexxvar = name of a rexx variable in which sem handle is returned
  1848.   type    = 'Shared' or 'Private' (default is 'Private')
  1849.   name    = semaphore name (default is un-named)
  1850.   state   = 'Owned' or 'Unowned' (default is un-owned)
  1851.   semrc   = return code from DosCreateMutexSem()
  1852.  
  1853.  
  1854. ΓòÉΓòÉΓòÉ 11.9. RxOpenMutexSem - Open a Mutex Semaphore ΓòÉΓòÉΓòÉ
  1855.  
  1856. This function opens a mutex semaphore 
  1857.  
  1858. Syntax:
  1859.  
  1860.   semrc = RxOpenMutexSem(rexxvar, semid )
  1861.  
  1862. where
  1863.  
  1864.   rexxvar = name of a rexx variable in which sem handle is returned
  1865.   semid   = either a semaphore name, or an existing mutex semaphore handle
  1866.   semrc   = return code from DosOpenMutexSem()
  1867.  
  1868.  
  1869. ΓòÉΓòÉΓòÉ 11.10. RxCloseMutexSem - Close a Mutex Semaphore ΓòÉΓòÉΓòÉ
  1870.  
  1871. This function closes a mutex semaphore 
  1872.  
  1873. Syntax:
  1874.  
  1875.   mtxrc = RxCloseMutexSem( hmtx )
  1876.  
  1877. where
  1878.  
  1879.   hmtx  = existing mutex semaphore handle
  1880.   mtxrc = return code from DosCloseMutexSem
  1881.  
  1882.  
  1883. ΓòÉΓòÉΓòÉ 11.11. RxQueryMutexSem - Query Mutex Semaphore ΓòÉΓòÉΓòÉ
  1884.  
  1885. This function queries a mutex semaphore's attributes 
  1886.  
  1887. Syntax:
  1888.  
  1889.   mtxinfo = RxQueryMutexSem( hmtx )
  1890.  
  1891. where
  1892.  
  1893.   hmtx    = existing mutex semaphore handle
  1894.   mtxinfo = four blank delimited tokens:
  1895.             1) return code from DosQueryMutexSem
  1896.             2) Process-Id of semaphore's current owner
  1897.             3) Thread-Id of semaphore's current owner
  1898.             4) A count of the number of calls to DosRequestMutexSem,
  1899.                minus the number of calls to DosReleaseMutexSem, that have
  1900.                been made for the semaphore by the owning thread.
  1901.                If the semaphore is unowned, this value will be zero.
  1902.                If the owning thread has ended, the value will be the
  1903.                request count for the ended owner.
  1904.  
  1905.  
  1906. ΓòÉΓòÉΓòÉ 11.12. RxReleaseMutexSem - Release Mutex Semaphore ΓòÉΓòÉΓòÉ
  1907.  
  1908. This function releases a mutex semaphore 
  1909.  
  1910. Syntax:
  1911.  
  1912.   mtxrc = RxReleaseMutexSem( hmtx )
  1913.  
  1914. where
  1915.  
  1916.   hmtx  = existing mutex semaphore handle
  1917.   mtxrc = return code from DosReleaseMutexSem
  1918.  
  1919.  
  1920. ΓòÉΓòÉΓòÉ 11.13. RxRequestMutexSem - Request Mutex Semaphore ΓòÉΓòÉΓòÉ
  1921.  
  1922. This function requests a mutex semaphore 
  1923.  
  1924. Syntax:
  1925.  
  1926.   mtxrc = RxRequestMutexSem( hmtx [, timeout] )
  1927.  
  1928. where
  1929.  
  1930.   hmtx    = existing mutex semaphore handle
  1931.   timeout = either a decimal integer (miliseconds to block), or the word
  1932.             'Indefinite'
  1933.   mtxrc   = return code from DosRequestMutexSem
  1934.  
  1935.  
  1936. ΓòÉΓòÉΓòÉ 11.14. RxCreateMuxWaitSem - Create a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  1937.  
  1938. This function creates a muxwait semaphore 
  1939.  
  1940. Syntax:
  1941.  
  1942.   semrc = RxCreateMuxWaitSem(rexxvar, stemname [,type] [,anyall]
  1943.                              [,name] )
  1944.  
  1945. where
  1946.  
  1947.   rexxvar  = name of a rexx variable in which sem handle is returned
  1948.   stemname = a Rexx stem name (ending in a period '.'), under which are
  1949.              supplied the semaphore handles which constitute this muxwait
  1950.              semaphore.  The expected structure of the stem is:
  1951.              1) stem.0   = a decimal integer indicating how many semaphores
  1952.                            are supplied
  1953.              2) stem.n.1 = handle of Nth semaphore
  1954.              3) stem.n.2 = decimal integer used as an Id for Nth semaphore
  1955.   type     = 'Shared' or 'Private' (default is 'Private')
  1956.   anyall   = 'anY' or 'alL' (default is 'All')
  1957.   name     = semaphore name (default is un-named)
  1958.   semrc    = return code from DosCreateMuxWaitSem()
  1959.  
  1960.  
  1961. ΓòÉΓòÉΓòÉ 11.15. RxOpenMuxWaitSem - Open a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  1962.  
  1963. This function opens a muxwait semaphore 
  1964.  
  1965. Syntax:
  1966.  
  1967.   semrc = RxOpenMuxWaitSem(rexxvar, semid )
  1968.  
  1969. where
  1970.  
  1971.   rexxvar = name of a rexx variable in which sem handle is returned
  1972.   semid   = either a semaphore name, or an existing muxwait
  1973.             semaphore handle
  1974.   semrc   = return code from DosOpenMuxWaitSem()
  1975.  
  1976.  
  1977. ΓòÉΓòÉΓòÉ 11.16. RxCloseMuxWaitSem - Close a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  1978.  
  1979. This function closes a muxwait semaphore 
  1980.  
  1981. Syntax:
  1982.  
  1983.   muxrc = RxCloseMuxWaitSem( hmux )
  1984.  
  1985. where
  1986.  
  1987.   hmux  = existing muxwait semaphore handle
  1988.   muxrc = return code from DosCloseMuxWaitSem
  1989.  
  1990.  
  1991. ΓòÉΓòÉΓòÉ 11.17. RxDeleteMuxWaitSem - Delete from a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  1992.  
  1993. This function deletes a semaphore from a muxwait semaphore list 
  1994.  
  1995. Syntax:
  1996.  
  1997.   muxrc = RxDeleteMuxWaitSem( hmux, hsem )
  1998.  
  1999. where
  2000.  
  2001.   hmux  = existing muxwait semaphore handle
  2002.   hsem  = handle of a semaphore in the muxwait semaphore list
  2003.   muxrc = return code from DosDeleteMuxWaitSem
  2004.  
  2005.  
  2006. ΓòÉΓòÉΓòÉ 11.18. RxAddMuxWaitSem - Add to a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  2007.  
  2008. This function adds a semaphore to a muxwait semaphore list 
  2009.  
  2010. Syntax:
  2011.  
  2012.   muxrc = RxAddMuxWaitSem( hmux, hsem, semid )
  2013.  
  2014. where
  2015.  
  2016.   hmux  = existing muxwait semaphore handle
  2017.   hsem  = handle of a semaphore to add to the muxwait semaphore list
  2018.   semid = decimal integer used as an Id for this semaphore
  2019.   muxrc = return code from DosAddMuxWaitSem
  2020.  
  2021.  
  2022. ΓòÉΓòÉΓòÉ 11.19. RxQueryMuxWaitSem - Query a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  2023.  
  2024. This function queries information about a muxwait semaphore 
  2025.  
  2026. Syntax:
  2027.  
  2028.   muxinfo = RxQueryMuxWaitSem( hmux, stemname )
  2029.  
  2030. where
  2031.  
  2032.   hmux     = existing muxwait semaphore handle
  2033.   stemname = a Rexx stem name (ending in a period '.'), under which is
  2034.              returned information about the muxwait semaphore.  The structure
  2035.              of the returned information is:
  2036.              1) stem.0   = a decimal integer indicating how many semaphores
  2037.                            are listed in this muxwait semaphore
  2038.              2) stem.n.1 = handle of Nth semaphore
  2039.              3) stem.n.2 = decimal integer Id of Nth semaphore
  2040.   muxinfo  = Two blank delimited tokens:
  2041.              1) return code from DosQueryMuxWaitSem
  2042.              2) a string of letters indicating this muxwait semaphore's
  2043.                 properties:
  2044.                 'S' if it's shared
  2045.                 'Y' if it's a wait ANY
  2046.                 'L' if it's a wait ALL
  2047.  
  2048.  
  2049. ΓòÉΓòÉΓòÉ 11.20. RxWaitMuxWaitSem - Wait on a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  2050.  
  2051. This function waits on a muxwait semaphore 
  2052.  
  2053. Syntax:
  2054.  
  2055.   muxinfo = RxWaitMuxWaitSem( hmux [,timeout] )
  2056.  
  2057. where
  2058.  
  2059.   hmux     = existing muxwait semaphore handle
  2060.   timeout  = either a decimal integer (miliseconds to block), or the word
  2061.             'Indefinite'
  2062.   muxinfo  = Two blank delimited tokens:
  2063.              1) return code from DosQueryMuxWaitSem
  2064.              2) semaphore-id of releaser of muxwait sem (for more info,
  2065.                 see details of DosWaitMuxWaitSem)
  2066.  
  2067.  
  2068. ΓòÉΓòÉΓòÉ 12. Rexx Macro Space Functions ΓòÉΓòÉΓòÉ
  2069.  
  2070. These functions allow Rexx programs to query and alter the Rexx MacroSpace. 
  2071.  
  2072.  
  2073. ΓòÉΓòÉΓòÉ 12.1. RxAddMacro - Add Entry to MacroSpace ΓòÉΓòÉΓòÉ
  2074.  
  2075. This function adds a Rexx program to the macrospace. 
  2076.  
  2077. Syntax:
  2078.  
  2079.   addrc = RxAddMacro(funcname, sourcefile [,order])
  2080.  
  2081. where
  2082.  
  2083.   funcname   = name for function in macrospace
  2084.   sourcefile = name of source file where Rexx source code exists
  2085.   order      = order in macrospace (Before or After)
  2086.  
  2087. Note:
  2088.  
  2089.   Returned value is return code from RexxAddMacro.
  2090.  
  2091.  
  2092. ΓòÉΓòÉΓòÉ 12.2. RxDropMacro - Drop Entry from MacroSpace ΓòÉΓòÉΓòÉ
  2093.  
  2094. This function drops a function from the macrospace. 
  2095.  
  2096. Syntax:
  2097.  
  2098.   droprc = RxDropMacro(funcname)
  2099.  
  2100. where
  2101.  
  2102.   funcname   = name of function in macrospace
  2103.  
  2104. Note:
  2105.  
  2106.   Returned value is return code from RexxDropMacro.
  2107.  
  2108.  
  2109. ΓòÉΓòÉΓòÉ 12.3. RxClearMacroSpace - Clear Entire MacroSpace ΓòÉΓòÉΓòÉ
  2110.  
  2111. This function clears all functions from the macro space.  Be careful when using 
  2112. this as it will affect all processes in the system. 
  2113.  
  2114. Syntax:
  2115.  
  2116.   clear_rc = RxClearMacroSpace()
  2117.  
  2118. Note:
  2119.  
  2120.   Returned value is return code from RexxClearMacroSpace.
  2121.  
  2122.  
  2123. ΓòÉΓòÉΓòÉ 12.4. RxSaveMacroSpace - Save Macro to File ΓòÉΓòÉΓòÉ
  2124.  
  2125. This function saves a macrospace function to a file. 
  2126.  
  2127. Syntax:
  2128.  
  2129.   saverc = RxSaveMacroSpace(funcname, macfile)
  2130.  
  2131. where
  2132.  
  2133.   funcname = name of function in macrospace
  2134.   macfile  = name of file in which to save macro
  2135.  
  2136. Note:
  2137.  
  2138.   Returned value is return code from RexxSaveMacroSpace.
  2139.  
  2140.  
  2141. ΓòÉΓòÉΓòÉ 12.5. RxLoadMacroSpace - Load a Macro from File ΓòÉΓòÉΓòÉ
  2142.  
  2143. This function loads a macrospace function from a file. 
  2144.  
  2145. Syntax:
  2146.  
  2147.   loadrc = RxLoadMacroSpace(funcname, macfile)
  2148.  
  2149. where
  2150.  
  2151.   funcname = name of function in macrospace
  2152.   macfile  = name of file in which to save macro
  2153.  
  2154. Note:
  2155.  
  2156.   Returned value is return code from RexxLoadMacroSpace.
  2157.  
  2158.  
  2159. ΓòÉΓòÉΓòÉ 12.6. RxQueryMacro - Query MacroSpace ΓòÉΓòÉΓòÉ
  2160.  
  2161. This function queries the existence/position of a macro in the macrospace. 
  2162.  
  2163. Syntax:
  2164.  
  2165.   qinfo = RxQueryMacro(funcname)
  2166.  
  2167. where
  2168.  
  2169.   funcname = name of function in macrospace
  2170.   qinfo    = blank-delimited tokens:
  2171.              1) return code from RexxQueryMacro
  2172.                 If #1 is zero, then:
  2173.                 2) Before/After/?
  2174.  
  2175. Note:
  2176.  
  2177.   If first token is not zero, no other information was returned.
  2178.  
  2179.  
  2180. ΓòÉΓòÉΓòÉ 12.7. RxReorderMacro - Reorder Macro Position ΓòÉΓòÉΓòÉ
  2181.  
  2182. This function reorders the position of a macro within the macrospace. 
  2183.  
  2184. Syntax:
  2185.  
  2186.   reorderrc = RxReorderMacro(funcname, position)
  2187.  
  2188. where
  2189.  
  2190.   funcname = name of function in macrospace
  2191.   position = relative position in macrospace (Before/After)
  2192.  
  2193. Note:
  2194.  
  2195.   Returned value is return code from RexxReorderMacro
  2196.  
  2197.  
  2198. ΓòÉΓòÉΓòÉ 13. Threads, Tasking, etc. ΓòÉΓòÉΓòÉ
  2199.  
  2200. These functions allow a Rexx program to start and control new threads and 
  2201. processes. 
  2202.  
  2203.  
  2204. ΓòÉΓòÉΓòÉ 13.1. RxWaitChild - Wait for child process(es) to end ΓòÉΓòÉΓòÉ
  2205.  
  2206. This function will wait for child process(es) to end 
  2207.  
  2208. Syntax:
  2209.  
  2210.   dosrc = RxWaitChild(childpid,actioncode,waitoption)
  2211.  
  2212. where
  2213.  
  2214.   childpid   = PID of child process (decimal number)
  2215.   actioncode = kill single process, or a process tree:
  2216.                P - single process
  2217.                T - process tree
  2218.   waitoption = whether or not to wait for child to end:
  2219.                W - wait
  2220.                N - no wait
  2221.   dosrc      = four blank-delimited tokens:
  2222.                1) return code from DosWaitChild
  2223.                if (1) is zero, then
  2224.                  2) returned PID
  2225.                  3) result code from terminating process
  2226.                  4) text indicating type of child termination:
  2227.                     - NormalExit
  2228.                     - HardError
  2229.                     - Trap
  2230.                     - KillProcess
  2231.                     - Exception
  2232.  
  2233.  
  2234. ΓòÉΓòÉΓòÉ 13.2. RxExecPgm - Execute a program ΓòÉΓòÉΓòÉ
  2235.  
  2236. This function starts another program in the same session. 
  2237.  
  2238. Syntax:
  2239.  
  2240.   exrc = RxExecPgm(pgmname [, mode [,argstring]])
  2241.  
  2242. where
  2243.  
  2244.   pgmname   = name of .EXE file to execute
  2245.   mode      = 'S'ync, 'A'sync, async'R'esult, 'T'race, 'B'ackground, 'L'oad,
  2246.               asyncresult'D'b.
  2247.               Default is 'S'ync.
  2248.   argstring = arg string to pass to program
  2249.               typically, to recreate the argument string 'C' programs expect from
  2250.               the command line, the arguments should have the form:
  2251.                 '00'x || argstring ||'0000'x
  2252.   exrc      = three blank-delimited tokens:
  2253.               1) return code from DosExecPgm
  2254.               2) termination code / process-id (for asynchronous)
  2255.               3) new program's return code
  2256.  
  2257.  
  2258. ΓòÉΓòÉΓòÉ 13.3. RxStartSession - Start Another Session ΓòÉΓòÉΓòÉ
  2259.  
  2260. This function starts a program in another OS/2 session. 
  2261.  
  2262. Syntax:
  2263.  
  2264.   strc = RxStartSession(pgmname [,args [,related [,fgbg [,title [,type
  2265.                         [,ctrl] ] ] ] ] ])
  2266.  
  2267. where
  2268.  
  2269.   pgmname   = name of .EXE file to execute
  2270.                 or
  2271.               32-bit pointer to populated STARTDATA structure used by DosStartSession
  2272.   args      = arg string to pass to program
  2273.   related   = Relation of started session to this session, can be:
  2274.               'I'ndependent or 'C'hild
  2275.   fgbg      = Foreground/Background option, can be:
  2276.               'F'oreground or 'B'ackground
  2277.   title     = Session title (defaults to program name)
  2278.   type      = Program type, can be:
  2279.               'D'efault, 'F'ullscreen, 'P'M, 'V'irtual-Dos,
  2280.               'W'indowed-Virtual-Dos, vi'O'-windowable
  2281.   ctrl      = Program control, can be:
  2282.               'V'isible, 'I'nvisible, ma'X'imized, mi'N'imized,
  2283.               no'A'utoclose
  2284.   strc      = if DosStartSession failed:
  2285.               - return code from DosStartSession followed by error info
  2286.               if DosStartSession got zero rc:
  2287.               - return code from DosStartSession Session-ID Process-ID
  2288.  
  2289.  
  2290. ΓòÉΓòÉΓòÉ 13.4. RxStartRexxSession - Start a Rexx program on another session ΓòÉΓòÉΓòÉ
  2291.  
  2292. This function starts a Rexx program in another OS/2 session. (The program 
  2293. "RXSRS.EXE" must be in your path in order to use this function) 
  2294.  
  2295. Syntax:
  2296.  
  2297.   strc = RxStartRexxSession(execname [,arg1] [,arg2] ... [,argn])
  2298.  
  2299. where
  2300.  
  2301.   execname = name of Rexx program to execute
  2302.                    or
  2303.              a '$' immediately preceding a source program string
  2304.                    or
  2305.              a '&' immediately preceding a tokenized program string
  2306.              (for more info about these, see "RxCallInStore" and
  2307.               "RxTokenize")
  2308.              a '+' immediately preceding the name of a program in the macrospace
  2309.   arg1     = arguments 1-n for target Rexx program
  2310.   ...
  2311.   argn
  2312.   strc     = if DosStartSession failed:
  2313.              - return code from DosStartSession followed by error info
  2314.              if DosStartSession worked:
  2315.              - return code from DosStartSession Session-ID Process-ID
  2316.  
  2317.  
  2318. ΓòÉΓòÉΓòÉ 13.5. RxDetachRexxPgm - Detach a Rexx program ΓòÉΓòÉΓòÉ
  2319.  
  2320. This function starts a Rexx program in the detached OS/2 session. (The program 
  2321. "RXSRS.EXE" must be in your path in order to use this function) 
  2322.  
  2323. Syntax:
  2324.  
  2325.   dtrc = RxDetachRexxPgm(execname [,arg1] [,arg2] ... [,argn])
  2326.  
  2327. where
  2328.  
  2329.   execname = name of Rexx program to execute
  2330.                    or
  2331.              a '$' immediately preceding a source program string
  2332.                    or
  2333.              a '&' immediately preceding a tokenized program string
  2334.              (for more info about these, see "RxCallInStore" and
  2335.               "RxTokenize")
  2336.              a '+' immediately preceding the name of a program in the macrospace
  2337.   arg1     = arguments 1-n for target Rexx program
  2338.   ...
  2339.   argn
  2340.   dtrc     = if DosExecPgm failed:
  2341.              - return code from DosExecPgm, followed by error info
  2342.              if DosExecPgm worked:
  2343.              - return code from DosExecPgm "codeTerminate" and "codeResult"
  2344.  
  2345.  
  2346. ΓòÉΓòÉΓòÉ 13.6. RxKillProcess - Kill an OS/2 Process ΓòÉΓòÉΓòÉ
  2347.  
  2348. This function kills an OS/2 process by process-id. 
  2349.  
  2350. Syntax:
  2351.  
  2352.   killrc = RxKillProcess(pid [, action])
  2353.  
  2354. where
  2355.  
  2356.   pid    = process-id (decimal integer)
  2357.   action = 'Process' or 'Tree' (default is 'Process')
  2358.   killrc = return code from DosKillProcess
  2359.  
  2360.  
  2361. ΓòÉΓòÉΓòÉ 13.7. RxCreateThread - Start new thread ΓòÉΓòÉΓòÉ
  2362.  
  2363. This function starts execution at a supplied entry point on a new thread. The 
  2364. entry point is any valid procedure address (e.g. obtained by a call to 
  2365. RxQueryProcAddr, etc.). 
  2366.  
  2367. Syntax:
  2368.  
  2369.   info = RxCreateThread(procaddr [,dataptr] [,linktype] [,stacksize] [,threadflag] )
  2370.  
  2371. where
  2372.  
  2373.   procaddr   = address of function to start on new thread
  2374.   dataptr    = optional, pointer to argument
  2375.   linktype   = optional, S = _System (default = _System)
  2376.                          O = _Optlink
  2377.   stacksize  = optional, stacksize for thread (default = 8k)
  2378.   threadflag = optional, I = Immediate (default = Immediate) (ignored for linktype = 'O')
  2379.                          S = Suspend
  2380.   info       = two blank delimited values:
  2381.                1) return code from DosCreateThread (linktype = 'S')
  2382.                                    _beginthread    (linktype = 'O')
  2383.                2) thread-id of newly created thread (if return code was zero)
  2384.  
  2385. Note:
  2386.   Pointer to argument is optional, but if supplied must be a valid pointer.
  2387.  
  2388.  
  2389. ΓòÉΓòÉΓòÉ 13.8. RxKillThread - Kill a thread ΓòÉΓòÉΓòÉ
  2390.  
  2391. This function kills a thread by thread-id. 
  2392.  
  2393. Syntax:
  2394.  
  2395.   killrc = RxKillThread(tid)
  2396.  
  2397. where
  2398.  
  2399.   tid    = thread-id
  2400.   killrc = return code from DosKillThread
  2401.  
  2402.  
  2403. ΓòÉΓòÉΓòÉ 13.9. RxSetPriority - Set the priority of processes or threads ΓòÉΓòÉΓòÉ
  2404.  
  2405. This function sets the priority of one or more process and/or threads. 
  2406.  
  2407. Syntax:
  2408.  
  2409.   setrc = RxSetPriority(scope,class,delta,id)
  2410.  
  2411. where
  2412.  
  2413.   scope = 'P'rocess (default)
  2414.           t'R'ee
  2415.           'T'hread
  2416.   class = 'N'ochange (default)
  2417.           'I'dletime
  2418.           'R'egular
  2419.           'T'imecritical
  2420.           foreground'S'erver
  2421.   delta = any integer from -31 to +31, or ma'X'imum, or mi'N'imum
  2422.   id    = a Process-Id, Thread-Id, or nothing, depending on value
  2423.           of "scope"
  2424.   setrc = return code from DosSetPriority
  2425.  
  2426.  
  2427. ΓòÉΓòÉΓòÉ 13.10. RxResumeThread - Resume thread execution ΓòÉΓòÉΓòÉ
  2428.  
  2429. This function causes a thread to resume execution 
  2430.  
  2431. Syntax:
  2432.  
  2433.   resrc = RxResumeThread(tid)
  2434.  
  2435. where
  2436.  
  2437.   tid   = thread-id
  2438.   resrc = return code from DosResumeThread
  2439.  
  2440.  
  2441. ΓòÉΓòÉΓòÉ 13.11. RxSuspendThread - Suspend thread execution ΓòÉΓòÉΓòÉ
  2442.  
  2443. This function causes a thread to suspend execution 
  2444.  
  2445. Syntax:
  2446.  
  2447.   susrc = RxSuspendThread(tid)
  2448.  
  2449. where
  2450.  
  2451.   tid   = thread-id
  2452.   susrc = return code from DosSuspendThread
  2453.  
  2454.  
  2455. ΓòÉΓòÉΓòÉ 13.12. RxCreateRexxThread - Rexx on another thread ΓòÉΓòÉΓòÉ
  2456.  
  2457. This function executes a Rexx program on another thread of the same process. 
  2458. The started Rexx program has a separate variable pool, and maintains its own 
  2459. "current Rexx queue", indpendently of the starting Rexx program.  But all other 
  2460. features of multi-threaded applications apply (i.e. shared file handles, etc.) 
  2461.  
  2462. Syntax:
  2463.  
  2464.   tid = RxCreateRexxThread(execname [,arg1 [,arg2 [, ...]]])
  2465.  
  2466. where
  2467.  
  2468.   execname = name of Rexx program to execute
  2469.                    or
  2470.              a '$' immediately preceding a source program string
  2471.                    or
  2472.              a '&' immediately preceding a tokenized program string
  2473.              (for more info about these, see "RxCallInStore" and
  2474.               "RxTokenize")
  2475.                    or
  2476.              a '+' immediately preceding the name of a program in the macrospace
  2477.   arg1     = arguments to Rexx program (up to 19 possible)
  2478.   arg2
  2479.   ...
  2480.   tid      = Thread-Id of new thread (Rexx integer)
  2481.  
  2482. Note:
  2483.  
  2484.   Example of executing a program string:
  2485.  
  2486.     crlf = '0d0a'x
  2487.     str = '/* Rexx */'crlf
  2488.     str = str 'Do i=1 To Arg()'crlf
  2489.     str = str '  Say "Arg#"i "= {"arg(i)"}"'crlf
  2490.     str = str 'End'crlf
  2491.     str = str||'1a'x       /* EOF marker */
  2492.     call rxcreaterexxthread '$'str, date(), time()
  2493.  
  2494.  
  2495. ΓòÉΓòÉΓòÉ 13.13. RxSetExceptionExit - Specify the address of exception exit ΓòÉΓòÉΓòÉ
  2496.  
  2497.              which is called when an OS/2 exception occurs on a 
  2498. thread started with "RxCreateRexxThread". 
  2499.  
  2500. This function specifies the address of a "_System" linkage function which is to 
  2501. be called when an OS/2 exception occurs on a thread which was started with 
  2502. "RxCreateRexxThread". 
  2503.  
  2504. Syntax:
  2505.  
  2506.   rslt = RxSetExceptionExit(pfn)
  2507.  
  2508. where
  2509.  
  2510.   pfn     = 32-bit pointer to a _System linkage exception (i.e. a four byte
  2511.             binary value)
  2512.   rslt    = empty string
  2513.  
  2514.  
  2515. ΓòÉΓòÉΓòÉ 14. NETBIOS information ΓòÉΓòÉΓòÉ
  2516.  
  2517. These functions allow a Rexx program to access certain NETBIOS information. 
  2518.  
  2519.  
  2520. ΓòÉΓòÉΓòÉ 14.1. RxNbSessionStatus - NetBios Session Status ΓòÉΓòÉΓòÉ
  2521.  
  2522. This function gets NetBios session status information. 
  2523.  
  2524. Syntax:
  2525.  
  2526.   nbname = 'S$SQLDBSERVR1#DB'
  2527.  
  2528.   nbrc =  RxNbSessionStatus(nbname,'s.','r')
  2529.  
  2530. Note:
  2531.  
  2532.   Return code is from NETBIOS api.  Second argument is name of a Rexx stem
  2533.   variable under which results are returned as such:
  2534.  
  2535.     stem.0 = number of sessions reported on
  2536.       stem.n.1 = Local session number
  2537.       stem.n.2 = Session state
  2538.       stem.n.3 = Local name
  2539.       stem.n.4 = Remote name
  2540.       stem.n.5 = Number of receive commands pending
  2541.       stem.n.6 = Number of send commands pending
  2542.  
  2543.   Third argument may be supplied to have a NETBIOS "Reset" done before and
  2544.   after obtaining session status.
  2545.  
  2546.  
  2547. ΓòÉΓòÉΓòÉ 15. DLL Handling ΓòÉΓòÉΓòÉ
  2548.  
  2549. These functions allow a Rexx program to load and execute procedures with- in 
  2550. DLL's.  Also, certain information about DLL's can be obtained. 
  2551.  
  2552.  
  2553. ΓòÉΓòÉΓòÉ 15.1. RxLoadModule - Load a DLL ΓòÉΓòÉΓòÉ
  2554.  
  2555. This function loads a DLL, returning a module handle (or an error code). 
  2556.  
  2557. Syntax:
  2558.  
  2559.   dosrc = RxLoadModule(rexxvar, dllname)
  2560.  
  2561. where:
  2562.  
  2563.   rexxvar = name of rexx variable in which module handle is returned
  2564.   dllname = name of DLL to load
  2565.   dosrc   = return code from DosLoadModule
  2566.  
  2567.  
  2568. ΓòÉΓòÉΓòÉ 15.2. RxFreeModule - Free a DLL ΓòÉΓòÉΓòÉ
  2569.  
  2570. This function frees the DLL whose module handle is supplied. 
  2571.  
  2572. Syntax:
  2573.  
  2574.   dosrc = RxFreeModule(hmod)
  2575.  
  2576. where:
  2577.  
  2578.   hmod    = module handle
  2579.   dosrc   = return code from DosFreeModule
  2580.  
  2581.  
  2582. ΓòÉΓòÉΓòÉ 15.3. RxQueryModuleName - Get Module Name ΓòÉΓòÉΓòÉ
  2583.  
  2584. This function returns the name of a module, given the module handle. 
  2585.  
  2586. Syntax:
  2587.  
  2588.   dosrc = RxQueryModuleName(rexxvar,hmod)
  2589.  
  2590. where:
  2591.  
  2592.   rexxvar = name of rexx variable in which module name is returned
  2593.   hmod    = module handle of DLL
  2594.   dosrc   = return code from DosQueryModuleName
  2595.  
  2596.  
  2597. ΓòÉΓòÉΓòÉ 15.4. RxQueryModuleHandle - Get Module Handle ΓòÉΓòÉΓòÉ
  2598.  
  2599. This function returns the handle of a module, given the module's name. 
  2600.  
  2601. Syntax:
  2602.  
  2603.   dosrc = RxQueryModuleHandle(rexxvar,modname)
  2604.  
  2605. where:
  2606.  
  2607.   rexxvar = name of rexx variable in which module handle is returned
  2608.   modname = name of DLL
  2609.   dosrc   = return code from DosQueryModuleHandle
  2610.  
  2611.  
  2612. ΓòÉΓòÉΓòÉ 15.5. RxQueryProcType - Query Procedure Type ΓòÉΓòÉΓòÉ
  2613.  
  2614. This function returns the addressing mode (16/32 bit) of a procedure of a DLL. 
  2615. The procedure can be identified either by name, or ordinal number. 
  2616.  
  2617. Syntax:
  2618.  
  2619.   entryname = 'SQLEXEC'
  2620.   ordinal = 3
  2621.  
  2622.   procinfo = RxQueryProcType(hmod,procid)
  2623.   amode = RxQueryProcType(hmod,entryname)
  2624.  
  2625. where:
  2626.  
  2627.   hmod     = module handle
  2628.   procid   = procedure-id (either an ordinal, or a procedure name)
  2629.   procinfo = Two blank-delimited tokens:
  2630.              1) return code from DosQueryProcType
  2631.              2) either "16" or "32", indicating 16 or 32 bit
  2632.  
  2633.  
  2634. ΓòÉΓòÉΓòÉ 15.6. RxQueryProcAddr - Query Procedure Address ΓòÉΓòÉΓòÉ
  2635.  
  2636. This function returns the address of an entry point in a DLL.  This entry point 
  2637. can then be used in RxCallEntryPoint to call an entry point in a Loaded DLL. 
  2638.  
  2639. Syntax:
  2640.  
  2641.   entryname = 'SQLEXEC' /* Entry name */
  2642.               3         /* Entry ordinal */
  2643.  
  2644.   dosrc = RxQueryProcAddr(rexxvar,hmod,procid)
  2645.  
  2646. where:
  2647.  
  2648.   rexxvar = name of rexx variable in which procedure address is returned
  2649.   hmod    = module handle of DLL
  2650.   procid  = procedure-id (either an ordinal, or a procedure name)
  2651.  
  2652.  
  2653. ΓòÉΓòÉΓòÉ 15.7. RxCallEntryPoint - Call an entry point ΓòÉΓòÉΓòÉ
  2654.  
  2655. This function "calls" the code which begins at the ProcAddress supplied. This 
  2656. ProcAddress could be the address obtained by RxQueryProcAddr for the entry 
  2657. point of a DLL.  But, it can be any "legal" entry point address of any routine. 
  2658.  
  2659. Syntax:
  2660.  
  2661.   procrc = RxCallEntryPoint(procaddr [,arg1 [, arg2 [,...]]] )
  2662.  
  2663. where
  2664.  
  2665.   procaddr = proc-address (could be obtained from RxQueryProcAddr, etc.)
  2666.   parg1
  2667.   ...
  2668.   parg19   = up to 19 arguments.  If an argument is a valid pointer, the
  2669.              pointer will be passed.  If not, a copy of the argument's value
  2670.              will be passed by reference.  Either way, the procedure must be
  2671.              expecting a pointer for each argument.
  2672.   procrc   = return code from the procedure
  2673.  
  2674. Note:
  2675.   Linkage to the proc-address is type _System.
  2676.  
  2677.  
  2678. ΓòÉΓòÉΓòÉ 16. OS/2 Pipes ΓòÉΓòÉΓòÉ
  2679.  
  2680. An assortment of OS/2 pipe-related functions (not complete). 
  2681.  
  2682.  
  2683. ΓòÉΓòÉΓòÉ 16.1. RxCreateNPipe - Create a named pipe ΓòÉΓòÉΓòÉ
  2684.  
  2685. This function creates an OS/2 named pipe. 
  2686.  
  2687. Syntax:
  2688.  
  2689.   dosrc = RxCreateNPipe( rexxvar, pipename, openmode, pipemode,
  2690.                          instance_count, outbufsize, inbufsize,
  2691.                          timeout)
  2692.  
  2693. where
  2694.  
  2695.    rexxvar  = name of Rexx variable into which read/write handle is placed
  2696.    pipename = name of pipe
  2697.  
  2698.    OpenMode Values
  2699.      W    = WriteBehind
  2700.      w    = NoWriteBehind
  2701.      I    = Inherit
  2702.      i    = NoInherit
  2703.      N(n) = Access Inbound
  2704.      O(o) = Access Outbound
  2705.      D(d) = Access Duplex
  2706.  
  2707.    PipeMode Values
  2708.      W    = Wait
  2709.      w    = NoWait
  2710.      T    = Pipe Type "Byte"
  2711.      t    = Pipe Type "Message"
  2712.      R    = Readmode "Byte"
  2713.      r    = Readmode "Message"
  2714.  
  2715.    Instance_Count
  2716.      Integer
  2717.  
  2718.    Outbuf Size
  2719.      Integer
  2720.  
  2721.    Inbuf Size
  2722.      Integer
  2723.  
  2724.    Timeout
  2725.      Integer
  2726.  
  2727.   dosrc   = return code from DosCreateNPipe()
  2728.  
  2729.  
  2730. ΓòÉΓòÉΓòÉ 16.2. RxSetNPHState - Set state of a named pipe ΓòÉΓòÉΓòÉ
  2731.  
  2732. This function sets the state of an OS/2 named pipe 
  2733.  
  2734. Syntax:
  2735.  
  2736.   dosrc = RxSetNPHState(pipehandle, stateflags)
  2737.  
  2738. where
  2739.  
  2740.   pipehandle = handle of pipe
  2741.   stateflags = string (case sensitive) consisting of a (valid) combination of:
  2742.                W - wait (blocking)
  2743.                w - no-wait (non-blocking)
  2744.                B - byte mode pipe
  2745.                M - message mode pipe
  2746.   dosrc   = return code from DosSetNPHState()
  2747.  
  2748.  
  2749. ΓòÉΓòÉΓòÉ 16.3. RxConnectNPipe - Connect to a named pipe ΓòÉΓòÉΓòÉ
  2750.  
  2751. This function connects to a named pipe 
  2752.  
  2753. Syntax:
  2754.  
  2755.   dosrc = RxConnectNPipe(hpipe)
  2756.  
  2757. where
  2758.  
  2759.    hpipe  = pipe handle
  2760.    dosrc  = return code from DosConnectNPipe()
  2761.  
  2762.  
  2763. ΓòÉΓòÉΓòÉ 16.4. RxDisConnectNPipe - Disconnect from a named pipe ΓòÉΓòÉΓòÉ
  2764.  
  2765. This function disconnects from a named pipe 
  2766.  
  2767. Syntax:
  2768.  
  2769.   dosrc = RxDisConnectNPipe(hpipe)
  2770.  
  2771. where
  2772.  
  2773.    hpipe  = pipe handle
  2774.    dosrc  = return code from DosDisConnectNPipe()
  2775.  
  2776.  
  2777. ΓòÉΓòÉΓòÉ 16.5. RxCreatePipe - Create an un-named pipe ΓòÉΓòÉΓòÉ
  2778.  
  2779. This function creates an OS/2 un-named pipe 
  2780.  
  2781. Syntax:
  2782.  
  2783.   dosrc = RxCreatePipe(rexxstem [,pipesize])
  2784.  
  2785. where
  2786.  
  2787.    rexxstem = name of Rexx stem variable under which read handle,
  2788.               write handle, and pipe size are returned as such:
  2789.               stem.1 = read handle
  2790.               stem.2 = write handle
  2791.               stem.3 = pipe size
  2792.    dosrc  = return code from DosCreatePipe()
  2793.  
  2794.  
  2795. ΓòÉΓòÉΓòÉ 16.6. RxDestroyPipe - Destroy an un-named pipe ΓòÉΓòÉΓòÉ
  2796.  
  2797. This function destroys an OS/2 un-named pipe 
  2798.  
  2799. Syntax:
  2800.  
  2801.   dosrc = RxDestroyPipe(hread,hwrite)
  2802.  
  2803. where
  2804.  
  2805.    hread  = read handle
  2806.    hwrite = write handle
  2807.    dosrc  = return codes from DosClose()
  2808.  
  2809.  
  2810. ΓòÉΓòÉΓòÉ 17. OS/2 Queues ΓòÉΓòÉΓòÉ
  2811.  
  2812. Most of the OS/2 queue APIs are implemented here. 
  2813.  
  2814.  
  2815. ΓòÉΓòÉΓòÉ 17.1. RxCreateQueue - Create an OS/2 queue. ΓòÉΓòÉΓòÉ
  2816.  
  2817. This function creates an OS/2 queue. 
  2818.  
  2819. Syntax:
  2820.  
  2821.   dosrc = RxCreateQueue(rexxvar, qname, qflags)
  2822.  
  2823. where
  2824.  
  2825.    rexxvar  = name of Rexx variable into which queue handle is placed
  2826.    qname    = name of OS/2 queue
  2827.    qflags   = flags for queue creation:
  2828.               F - Fifo
  2829.               L - Lifo
  2830.               P - Priority
  2831.               C - Convert Address
  2832.               N - No-convert Address
  2833.   dosrc   = return code from DosCreateQueue()
  2834.  
  2835.  
  2836. ΓòÉΓòÉΓòÉ 17.2. RxOpenQueue - Open an OS/2 queue ΓòÉΓòÉΓòÉ
  2837.  
  2838. This function opens an OS/2 queue 
  2839.  
  2840. Syntax:
  2841.  
  2842.   dosrc = RxOpenQueue(rexxstem,qname)
  2843.  
  2844. where
  2845.  
  2846.    rexxstem = name of Rexx stem, under which info is returned:
  2847.               stem.1 = queue-owner-pid (integer)
  2848.               stem.2 = queue handle
  2849.    qname    = name of queue to open
  2850.    dosrc    = return code from DosOpenQueue()
  2851.  
  2852.  
  2853. ΓòÉΓòÉΓòÉ 17.3. RxPeekQueue - Peek at an OS/2 queue ΓòÉΓòÉΓòÉ
  2854.  
  2855. This function peeks at an OS/2 queue without reading it 
  2856.  
  2857. Syntax:
  2858.  
  2859.   dosrc = RxPeekQueue(rexxstem,qhandle,elemcode,waitcode,semhandle)
  2860.  
  2861. where
  2862.  
  2863.    rexxstem  = name of Rexx stem, under which info is returned:
  2864.                stem.1 = data pointer (e.g. for use with RxStorage)
  2865.                stem.2 = data length (of that pointed to by stem.1)
  2866.                stem.3 = PID of process which enqueued element
  2867.                stem.4 = event code (RequestData.ulData)
  2868.                stem.5 = element code
  2869.                stem.6 = element priority
  2870.    qhandle   = handle to queue
  2871.    elemcode  = element code (integer)
  2872.    waitcode  = whether to wait for data in queue
  2873.                W = Wait
  2874.                N = Nowait
  2875.    semhandle = handle of semaphore
  2876.    dosrc     = return code from DosPeekQueue()
  2877.  
  2878.  
  2879. ΓòÉΓòÉΓòÉ 17.4. RxReadQueue - Read an OS/2 queue ΓòÉΓòÉΓòÉ
  2880.  
  2881. This function reads an element off an OS/2 
  2882.  
  2883. Syntax:
  2884.  
  2885.   dosrc = RxReadQueue(rexxstem,qhandle,elemcode,waitcode,semhandle)
  2886.  
  2887. where
  2888.  
  2889.    rexxstem  = name of Rexx stem, under which info is returned:
  2890.                stem.1 = data pointer (e.g. for use with RxStorage)
  2891.                stem.2 = data length (of that pointed to by stem.1)
  2892.                stem.3 = PID of process which enqueued element
  2893.                stem.4 = event code (RequestData.ulData)
  2894.                stem.5 = element priority
  2895.    qhandle   = handle to queue
  2896.    elemcode  = element code (integer)
  2897.    waitcode  = whether to wait for data in queue
  2898.                W = Wait
  2899.                N = Nowait
  2900.    semhandle = handle of semaphore
  2901.    dosrc     = return code from DosReadQueue()
  2902.  
  2903.  
  2904. ΓòÉΓòÉΓòÉ 17.5. RxWriteQueue - Write to an OS/2 queue ΓòÉΓòÉΓòÉ
  2905.  
  2906. This function writes an element to an OS/2 
  2907.  
  2908. Syntax:
  2909.  
  2910.   dosrc = RxWriteQueue(qhandle,pointer,length,reqdata,elemprty)
  2911.  
  2912. where
  2913.  
  2914.    qhandle   = handle to queue
  2915.    pointer   = whatever 32 bits you want to put on queue
  2916.    length    = integer length associated with "pointer"
  2917.    reqdata   = integer request data
  2918.    elemprtry = element priority, if this is a priority queue
  2919.    dosrc     = return code from DosWriteQueue()
  2920.  
  2921.  
  2922. ΓòÉΓòÉΓòÉ 17.6. RxPurgeQueue - Purge elements from OS/2 queue ΓòÉΓòÉΓòÉ
  2923.  
  2924. This function purges elements from an OS/2 queue 
  2925.  
  2926. Syntax:
  2927.  
  2928.   dosrc = RxPurgeQueue(qhandle)
  2929.  
  2930. where
  2931.  
  2932.    qhandle   = handle to queue
  2933.    dosrc     = return code from DosPurgeQueue()
  2934.  
  2935.  
  2936. ΓòÉΓòÉΓòÉ 17.7. RxQueryQueue - Query info about OS/2 queue ΓòÉΓòÉΓòÉ
  2937.  
  2938. This function returns information about an OS/2 queue 
  2939.  
  2940. Syntax:
  2941.  
  2942.   info = RxQueryQueue(qhandle)
  2943.  
  2944. where
  2945.  
  2946.    qhandle   = handle to queue
  2947.    info      = two blank delimited tokens:
  2948.                1) return code from DosQueryQueue()
  2949.                2) number of elements on queue (if (1) is zero)
  2950.  
  2951.  
  2952. ΓòÉΓòÉΓòÉ 17.8. RxCloseQueue - Close an OS/2 queue ΓòÉΓòÉΓòÉ
  2953.  
  2954. This function closes an OS/2 queue 
  2955.  
  2956. Syntax:
  2957.  
  2958.   dosrc = RxCloseQueue(qhandle)
  2959.  
  2960. where
  2961.  
  2962.    qhandle   = handle to queue
  2963.    dosrc     = return code from DosCloseQueue()
  2964.  
  2965.  
  2966. ΓòÉΓòÉΓòÉ 17.9. RxReadQueueStr - Read data from OS/2 queue ΓòÉΓòÉΓòÉ
  2967.  
  2968. This function returns the de-referenced contents of an OS/2 queue element. 
  2969. That is, it dequeues an element and returns the data pointed to by the dequeued 
  2970. element as the function result.  It first does a DosOpenQueue, then a 
  2971. DosReadQueue(wait), but does NOT do a DosCloseQueue. 
  2972.  
  2973. Syntax:
  2974.  
  2975.   datastr = RxReadQueueStr(qid)
  2976.  
  2977. where
  2978.  
  2979.    qid       = name of queue to read, or handle of already-opened queue
  2980.    datastr   = data pointed to by dequeued pointer
  2981.  
  2982.  
  2983. ΓòÉΓòÉΓòÉ 18. I/O Related ΓòÉΓòÉΓòÉ
  2984.  
  2985. Miscellaneous functions related to I/O operations. 
  2986.  
  2987.  
  2988. ΓòÉΓòÉΓòÉ 18.1. RxOpen - Open a file ΓòÉΓòÉΓòÉ
  2989.  
  2990. This function opens a file. 
  2991.  
  2992. Syntax:
  2993.  
  2994.   dosrc = RxOpen(rexxstem, filename, openflag, openmode [,attr] [,size])
  2995.  
  2996. where
  2997.  
  2998.   rexxstem  = name of Rexx stem variable under which info is returned:
  2999.               stem.1 = file handle
  3000.               stem.2 = action taken:
  3001.                        Existed
  3002.                        Created
  3003.                        Truncated
  3004.   filename  = name of file/pipe/stream to open
  3005.   openflag  = flag indicating what to do if file exists:
  3006.               (case does not matter)
  3007.               N - fail if New
  3008.               C - Create if new
  3009.               E - fail if Exists
  3010.               O - Open if exists
  3011.               R - Replace if exists
  3012.   openmode  = how to open file, valid combinations of:
  3013.               (case DOES matter)
  3014.               D - Dasd
  3015.               T - write Through
  3016.               F - Fail on error
  3017.               C - no Cache
  3018.               S - Sequential
  3019.               R - Random
  3020.               M - random/sequential (Mixed)
  3021.               H - no inHerit
  3022.               b - (sharemode) deny read/write (both)
  3023.               w - (sharemode) deny write
  3024.               r - (sharemode) deny read
  3025.               n - (sharemode) deny none
  3026.               R - (accessmode) Read only
  3027.               W - (accessmode) Write only
  3028.               B - (accessmode) readwrite (Both)
  3029.   attr      = file attribute, valid combinations of:
  3030.               (only if open creates file)
  3031.               A - Archived
  3032.               D - Directory
  3033.               S - System
  3034.               H - Hidden
  3035.               R - Readonly
  3036.               N - Normal (default)
  3037.   size      = file size (only if open creates file)
  3038.   dosrc     = return code from DosOpen()
  3039.  
  3040.  
  3041. ΓòÉΓòÉΓòÉ 18.2. RxDosRead - Read from File Handle (alias for RxRead) ΓòÉΓòÉΓòÉ
  3042.  
  3043. This alias for "RxRead()" is provided to allow RXU to be used along with other 
  3044. Rexx function packages (such as RXUTILS, etc.) which already use the function 
  3045. name "RxRead". 
  3046.  
  3047.  
  3048. ΓòÉΓòÉΓòÉ 18.3. RxRead - Read from File Handle ΓòÉΓòÉΓòÉ
  3049.  
  3050. This function reads a character stream in from a file handle, rather than from 
  3051. a file name. 
  3052.  
  3053. Syntax:
  3054.  
  3055.   dosrc = RxRead( rexxvar, hfile [,length] )
  3056.  
  3057. where
  3058.  
  3059.   rexxvar = name of Rexx variable into which read data is placed
  3060.   hfile   = handle of file to be read from
  3061.   length  = number of bytes to read (defaults to zero)
  3062.   dosrc   = two blank-delimited words:
  3063.             1) return code from DosRead
  3064.             2) if (1) is zero, an integer indicating number of bytes
  3065.                read (should be same as length of rexx variable's
  3066.                value)
  3067.  
  3068.  
  3069. ΓòÉΓòÉΓòÉ 18.4. RxDosWrite - Write to File Handle (alias for RxWrite) ΓòÉΓòÉΓòÉ
  3070.  
  3071. This alias for "RxWrite()" is provided to allow RXU to be used along with other 
  3072. Rexx function packages (such as RXUTILS, etc.) which already use the function 
  3073. name "RxWrite". 
  3074.  
  3075.  
  3076. ΓòÉΓòÉΓòÉ 18.5. RxWrite - Write to File Handle ΓòÉΓòÉΓòÉ
  3077.  
  3078. This function writes a character stream out to a file handle, rather than from 
  3079. a file name. 
  3080.  
  3081. Syntax:
  3082.  
  3083.   dosrc = RxWrite( hfile , data )
  3084.  
  3085. where
  3086.  
  3087.   hfile = handle of file to be written to
  3088.   data  = data to be written to file
  3089.   dosrc   = two blank-delimited words:
  3090.             1) return code from DosWrite
  3091.             2) if (1) is zero, an integer indicating number of bytes
  3092.                written (may not be same as length of data supplied)
  3093.  
  3094.  
  3095. ΓòÉΓòÉΓòÉ 18.6. RxCloseH - Close a File Handle ΓòÉΓòÉΓòÉ
  3096.  
  3097. This function closes a file handle. 
  3098.  
  3099. Syntax:
  3100.  
  3101.   closerc = RxCloseH(hfile)
  3102.  
  3103. where
  3104.  
  3105.   hfile   = handle of file to be closed
  3106.   closerc = return code from DosClose()
  3107.  
  3108.  
  3109. ΓòÉΓòÉΓòÉ 18.7. RxSoSe2H - Redirect StdOut/StdErr to a file (by file handle) ΓòÉΓòÉΓòÉ
  3110.  
  3111. This function redirects StdOut/StdErr to a file whose handle you supply. 
  3112.  
  3113. Syntax:
  3114.  
  3115.   dosrc = RxSoSe2H(hfile)
  3116.  
  3117. where
  3118.  
  3119.   hfile   = handle of file
  3120.   dosrc   = return code from DosDupHandle()
  3121.  
  3122.  
  3123. ΓòÉΓòÉΓòÉ 18.8. RxSi2H - Redirect StdIn from a file (by file handle) ΓòÉΓòÉΓòÉ
  3124.  
  3125. This function redirects StdIn from a file whose handle you supply. 
  3126.  
  3127. Syntax:
  3128.  
  3129.   dosrc = RxSi2H(hfile)
  3130.  
  3131. where
  3132.  
  3133.   hfile   = handle of file
  3134.   dosrc   = return code from DosDupHandle()
  3135.  
  3136.  
  3137. ΓòÉΓòÉΓòÉ 18.9. RxRSi2F - Redirect StdIn from a file (by file name) ΓòÉΓòÉΓòÉ
  3138.  
  3139. This function redirects StdIn from a file whose name you supply. 
  3140.  
  3141. Syntax:
  3142.  
  3143.   dosrc = RxRSi2F(filename)
  3144.  
  3145. where
  3146.  
  3147.   filename = name of file
  3148.   dosrc    = return code from DosOpen() or DosDupHandle()
  3149.  
  3150.  
  3151. ΓòÉΓòÉΓòÉ 18.10. RxExecI - Read data into a Rexx queue or stem from a file ΓòÉΓòÉΓòÉ
  3152.  
  3153. This function reads (text) data into a Rexx queue or stem variable from a file. 
  3154. It is meant to be like EXECIO in TSO and VM, and can be used in a similar 
  3155. fashion for file input. 
  3156.  
  3157. Syntax:
  3158.  
  3159.   info = RxExecI([fname], [qtype], [name], [type])
  3160.  
  3161. where:
  3162.  
  3163.   fname  = name of file to be read from (default reads from stdin)
  3164.   qtype  = 'Lifo' or 'Fifo' (default is 'Fifo')
  3165.            determines how lines are read onto queue
  3166.            (ignored for stems)
  3167.   name   = name of Rexx queue from into which data is read (default uses
  3168.            current queue)
  3169.                or
  3170.            name of a Rexx stem variable under which data is to be mapped as
  3171.              stem.0 = number of lines (stem.1 - stem.n)
  3172.              stem.1
  3173.              stem.2
  3174.              ...
  3175.              stem.n
  3176.   type   = 'Queue' or 'Stem' (default is 'Queue')
  3177.            this tells whether arg 3 is a Rexx Queue name or a stem
  3178.            variable name
  3179.   info   = two blank delimited numbers:
  3180.            1) number of lines read
  3181.            2) total number of bytes read
  3182.  
  3183. Example:
  3184.  
  3185.   /* Read a text file into the Rexx stem 's.' */
  3186.   info = rxexeci('c:\config.sys',,'s.','s')
  3187.   parse var info lines bytes
  3188.   Say lines 'lines were read'
  3189.   Say bytes 'bytes were read'
  3190.  
  3191.  
  3192. ΓòÉΓòÉΓòÉ 18.11. RxExecO - Write data from a Rexx queue or stem to a file ΓòÉΓòÉΓòÉ
  3193.  
  3194. This function writes data from a Rexx queue or stem variable to a file.  It is 
  3195. meant to be like EXECIO in TSO and VM, and can be used in a similar fashion for 
  3196. file output. 
  3197.  
  3198. Syntax:
  3199.  
  3200.   info = RxExecO([fname], [action], [name], [type])
  3201.  
  3202. where:
  3203.  
  3204.   fname  = name of file to be written to (default sends to stdout)
  3205.   action = Replace or Append (default is 'Replace')
  3206.            replaces or appends to 'fname'
  3207.   name   = name of Rexx queue from which to get data (default uses
  3208.            current queue)
  3209.                or
  3210.            name of a Rexx stem variable under which data is mapped as
  3211.              stem.1
  3212.              stem.2
  3213.              ...
  3214.              stem.n
  3215.            Once an uninitialized value for 'stem.n' is encountered,
  3216.            i/o stops.
  3217.   type   = 'Queue' or 'Stem' (default is 'Queue')
  3218.            this tells whether arg 3 is a Rexx Queue name or a stem
  3219.            variable name
  3220.   info   = two blank delimited numbers:
  3221.            1) number of lines written
  3222.            2) total number of bytes written
  3223.  
  3224. Example:
  3225.  
  3226.   /* Write 100 lines from current queue to c:\junk.dat (replace file) */
  3227.   Do 100
  3228.     Queue i time('l')
  3229.   End
  3230.   info = rxexeco('c:\junk.dat','r')
  3231.   parse var info lines bytes
  3232.   Say lines 'lines were written'
  3233.   Say bytes 'bytes were written'
  3234.  
  3235.  
  3236. ΓòÉΓòÉΓòÉ 18.12. RxVioPopUp - Start a VioPopUp display screen ΓòÉΓòÉΓòÉ
  3237.  
  3238. This function starts a VioPopUp display screen. 
  3239.  
  3240. Syntax:
  3241.  
  3242.   viorc = RxVioPopUp(wait,opaque)
  3243.  
  3244. where:
  3245.  
  3246.   wait   = Wait   - wait if a pop-up screen already exists
  3247.          = Nowait - return with error if a pop-up screen already exists
  3248.   opaque = Opaque or Transparent
  3249.   viorc  = return code from VioPopUp()
  3250.  
  3251.  
  3252. ΓòÉΓòÉΓòÉ 18.13. RxVioEndPopUp - Close a VioPopUp display screen ΓòÉΓòÉΓòÉ
  3253.  
  3254. This function closes a VioPopUp display screen. 
  3255.  
  3256. Syntax:
  3257.  
  3258.   viorc = RxVioEndPopUp()
  3259.  
  3260. where:
  3261.  
  3262.   viorc  = return code from VioEndPopUp()
  3263.  
  3264.  
  3265. ΓòÉΓòÉΓòÉ 18.14. RxVioWrtCharStrAtt - Write characters to a VioPopUp display screen ΓòÉΓòÉΓòÉ
  3266.  
  3267. This function writes characters to a VioPopUp display screen. 
  3268.  
  3269. Syntax:
  3270.  
  3271.   viorc = RxWrtCharStrAtt(string,rowx,coly,attr)
  3272.  
  3273. where:
  3274.  
  3275.   string = data to write
  3276.   rowx   = row number
  3277.   coly   = column number
  3278.   attr   = attribute bit string
  3279.   viorc  = return code from VioWrtCharStrAtt()
  3280.  
  3281.  
  3282. ΓòÉΓòÉΓòÉ 18.15. RxKbCharIn - Get a character from a VioPopUp display screen ΓòÉΓòÉΓòÉ
  3283.  
  3284. This function gets a character from a VioPopUp display screen 
  3285.  
  3286. Syntax:
  3287.  
  3288.   info = RxKbdCharIn(wait)
  3289.  
  3290. where:
  3291.  
  3292.   wait   = Wait   - wait for character
  3293.            Nowait - no wait for character
  3294.   info   = return code from KbdCharIn(), and, if zero, followed by these
  3295.            blank delimited values:
  3296.            1) Character
  3297.            2) Scan Code (hex)
  3298.            3) NLS state (hex)
  3299.            4) NLS shift (hex)
  3300.            5) Shift Key state (hex)
  3301.            6) Millisecond timestamp of keystroke
  3302.  
  3303.  
  3304. ΓòÉΓòÉΓòÉ 18.16. Rxrsoe2f - Redirect Std-Out/Err to File ΓòÉΓòÉΓòÉ
  3305.  
  3306. This function redirects Standard Out and Standard Error to a named file (or 
  3307. device name, such as "CON"). 
  3308.  
  3309. Syntax:
  3310.  
  3311.   Call Rxrsoe2f stream,opt
  3312.  
  3313. where:
  3314.  
  3315.   stream = name of file or device (e.g. 'con', 'nul', 'kbd', etc.)
  3316.            to which standard-out and standard-error are re-directed.
  3317.   opt    = either 'Append' or 'Replace' file/device
  3318.  
  3319.  
  3320. ΓòÉΓòÉΓòÉ 18.17. Rxrsoe2q - Redirect Std-Out/Err to Rexx Queue ΓòÉΓòÉΓòÉ
  3321.  
  3322. This function redirects Standard Out and Standard Error to a named queue. 
  3323.  
  3324. Syntax:
  3325.  
  3326.   token = rxrsoe2q(opt,value)
  3327.  
  3328. where:
  3329.  
  3330.   opt    = either 'Enable' or 'Disable'
  3331.   value  = queue name - (when opt=Enable)  (created if it doesn't exist)
  3332.            token      - (when opt=Disable)
  3333.   token  = binary token returned when opt=Enable, subsequently supplied as a parameter
  3334.            when opt=Disable
  3335.  
  3336.  
  3337. ΓòÉΓòÉΓòÉ 18.18. RxDupHandle - Do a "DosDupHandle()" ΓòÉΓòÉΓòÉ
  3338.  
  3339. This function allows you to do a "DosDupHandle()" 
  3340.  
  3341. Syntax:
  3342.  
  3343.   dosrc = RxDupHandle(rexxvar,hfile1,hfile2)
  3344.  
  3345. where:
  3346.  
  3347.   rexxvar = name of Rexx variable in which is return duplicated handle
  3348.             (value returned in arg2 by DosDupHandle)
  3349.   hfile1  = arg1 to DosDupHandle
  3350.   hfile2  = arg2 to DosDupHandle
  3351.   dosrc   = return code from DosDupHandle()
  3352.  
  3353.  
  3354. ΓòÉΓòÉΓòÉ 18.19. RxSetFHState - Set file handle state ΓòÉΓòÉΓòÉ
  3355.  
  3356. This function allows you to set a file handle's state 
  3357.  
  3358. Syntax:
  3359.  
  3360.   dosrc = RxSetFHState(hfile,flags)
  3361.  
  3362. where:
  3363.  
  3364.   hfile  = file handle whose state you want to set
  3365.   flags  = valid combinations of:
  3366.            (case DOES matter)
  3367.            D - Dasd
  3368.            T - write Through
  3369.            F - Fail on error
  3370.            C - no Cache
  3371.            S - Sequential
  3372.            R - Random
  3373.            M - random/sequential (Mixed)
  3374.            H - no inHerit
  3375.            b - (sharemode) deny read/write (both)
  3376.            w - (sharemode) deny write
  3377.            r - (sharemode) deny read
  3378.            n - (sharemode) deny none
  3379.            R - (accessmode) Read only
  3380.            W - (accessmode) Write only
  3381.            B - (accessmode) readwrite (Both)
  3382.   dosrc  = return code from DosSetFHState()
  3383.  
  3384.  
  3385. ΓòÉΓòÉΓòÉ 18.20. RxSetMaxFH - Set maximum file handles for process ΓòÉΓòÉΓòÉ
  3386.  
  3387. This function allows you to set the maximum number of file handles for the 
  3388. calling process. 
  3389.  
  3390. Syntax:
  3391.  
  3392.   dosrc = RxSetMaxFH(numhandles)
  3393.  
  3394. where:
  3395.  
  3396.   numhandles = maximum number of file handles for calling process
  3397.   dosrc      = return code from DosSetMaxFH
  3398.  
  3399.  
  3400. ΓòÉΓòÉΓòÉ 18.21. RxSetRelMaxFH - Set max file handles for process (relative to current value) ΓòÉΓòÉΓòÉ
  3401.  
  3402. This function allows you to set the maximum number of file handles (relative to 
  3403. the current number) for the calling process. 
  3404.  
  3405. Syntax:
  3406.  
  3407.   info = RxSetRelMaxFH(numhandles)
  3408.  
  3409. where:
  3410.  
  3411.   numhandles = maximum number of file handles for calling process
  3412.   info       = two blank delimited integers:
  3413.                1) return code from DosSetMaxFH
  3414.                2) new total number of allocated file handles
  3415.  
  3416.  
  3417. ΓòÉΓòÉΓòÉ 18.22. RxQueryFHState - Query file handle state ΓòÉΓòÉΓòÉ
  3418.  
  3419. This function allows you to query a file handle's state 
  3420.  
  3421. Syntax:
  3422.  
  3423.   info = RxQueryFHState(hfile)
  3424.  
  3425. where:
  3426.  
  3427.   hfile  = file handle whose state you want to query
  3428.   info   = two blank delimited tokens:
  3429.            1) return code from DosQueryFHState(),
  3430.            2) if (1) is zero, then a string of flags indicating state
  3431.               of file, flag values are (case is important):
  3432.               D - OPEN_FLAGS_DASD
  3433.               T - OPEN_FLAGS_WRITE_THROUGH
  3434.               F - OPEN_FLAGS_FAIL_ON_ERROR
  3435.               C - OPEN_FLAGS_NO_CACHE
  3436.               H - OPEN_FLAGS_NOINHERIT
  3437.               b - OPEN_SHARE_DENYREADWRITE
  3438.               w - OPEN_SHARE_DENYWRITE
  3439.               r - OPEN_SHARE_DENYREAD
  3440.               n - OPEN_SHARE_DENYNONE
  3441.               R - OPEN_ACCESS_READONLY
  3442.               W - OPEN_ACCESS_WRITEONLY
  3443.               B - OPEN_ACCESS_READWRITE
  3444.  
  3445.  
  3446. ΓòÉΓòÉΓòÉ 19. System-Info related ΓòÉΓòÉΓòÉ
  3447.  
  3448. Functions returning OS/2 system information. 
  3449.  
  3450.  
  3451. ΓòÉΓòÉΓòÉ 19.1. RxSetExtLibPath - Set extended LIBPATH for current process ΓòÉΓòÉΓòÉ
  3452.  
  3453. This function uses the DosSetExtLIBPATH API to set an extension to the LIBPATH 
  3454. for the current process.  This allows you to dynamically alter LIBPATH per 
  3455. process. 
  3456.  
  3457.  
  3458. Syntax:
  3459.  
  3460.   dosrc = RxSetExtLibPath( pathstring [,flag] )
  3461.  
  3462. Where:
  3463.  
  3464.   pathstring = semicolon delimited list of directories to be prepended/appended
  3465.                to existing system-wide LIBPATH for this process
  3466.   flag       = 'B' indicating that "pathstring" is to be prepended to LIBPATH
  3467.                'A' indicating that "pathstring" is to be appended to LIBPATH
  3468.   dosrc      = return code from DosSetExtLIBPATH
  3469.  
  3470.  
  3471. ΓòÉΓòÉΓòÉ 19.2. RxQueryExtLibPath - Query extended LIBPATH for current process ΓòÉΓòÉΓòÉ
  3472.  
  3473. This function uses the DosQueryExtLIBPATH API to query the extension to the 
  3474. LIBPATH for the current process. 
  3475.  
  3476.  
  3477. Syntax:
  3478.  
  3479.   dosrc = RxQueryExtLibPath( rexxvar, flag )
  3480.  
  3481. Where:
  3482.  
  3483.   flag       = 'B' to query LIBPATH extension that was prepended to system-wide LIBPATH
  3484.                'A' to query LIBPATH extension that was appended to system-wide LIBPATH
  3485.   rexxvar    = name of rexx variable in which LIBPATH extension string is returned
  3486.   dosrc      = return code from DosQueryExtLIBPATH
  3487.  
  3488.  
  3489. ΓòÉΓòÉΓòÉ 19.3. RxQProcstatus - Get Process Status Information ΓòÉΓòÉΓòÉ
  3490.  
  3491. This function returns process status information (like PSTAT).  In this version 
  3492. of RXU (v1.5), Library, Shared-Memory and 16-Bit Semaphore information is 
  3493. stored differently than in the previous release (v1.4). In the previous 
  3494. version, if you wanted the name of a module used by a process, for instance, 
  3495. you would have to search through the Library array to match the module index 
  3496. value "stem.0p.n.0l.m", to get the module name "stem.0l.n.2".  In this version, 
  3497. you simply get the module name by indexing into the Library array using the 
  3498. index value in "stem.0p.n.0l.m". 
  3499.  
  3500.  
  3501. Syntax:
  3502.  
  3503.   dosrc = RxQProcStatus(stemname [,flags])
  3504.  
  3505. where:
  3506.  
  3507.   stemname = a Rexx stem variable name under which results are
  3508.              mapped as such:
  3509.  
  3510.                // System Global Information
  3511.                stem.0G.1 = total number of threads in system
  3512.                stem.0G.2 = undocumented value 1
  3513.                stem.0G.3 = undocumented value 2
  3514.  
  3515.                // Process Information
  3516.                stem.0P.0 = number of processes
  3517.                stem.0P.n.1 = process-id (hex)
  3518.                stem.0P.n.2 = parent process-id (hex)
  3519.                stem.0P.n.3 = process type (hex)
  3520.                stem.0P.n.4 = process status (hex, followed by blank, followed
  3521.                              by text description)
  3522.                stem.0P.n.5 = process screen-group/session-id (hex)
  3523.                stem.0P.n.6 = process module name (value of "SYSINIT" may
  3524.                              indicate a DOS "process")
  3525.                stem.0P.n.0S.0 = number of 16-bit semaphores used by process
  3526.                stem.0P.n.0S.n = 16-bit semaphore index value (use to "hash"
  3527.                                 into list of "stem.0S.index" values)
  3528.                stem.0P.n.0L.0 = number of libraries statically linked by process
  3529.                stem.0P.n.0L.n = linked library index value (use to "hash"
  3530.                                 into list of "stem.0L.index" values)
  3531.                stem.0P.n.0M.0 = number of shared memory objects used by process
  3532.                stem.0P.n.0M.n = shared memory index value (use to "hash"
  3533.                                 into list of "stem.0M.index" values)
  3534.                stem.0P.n.0T.0 = number of threads in this process
  3535.                stem.0P.n.0T.m.1 = thread-id within process (hex)
  3536.                stem.0P.n.0T.m.2 = unique thread slot number (hex, system wide)
  3537.                stem.0P.n.0T.m.3 = sleep-id thread is sleeping on (hex)
  3538.                stem.0P.n.0T.m.4 = thread priority (hex)
  3539.                stem.0P.n.0T.m.5 = system time (# ring 0 time slices)
  3540.                stem.0P.n.0T.m.6 = user time (# ring 3 time slices)
  3541.                stem.0P.n.0T.m.7 = thread state (hex followed by text string)
  3542.  
  3543.                // 16-Bit Semaphore Information
  3544.                stem.0S.0 = number of 16-bit semaphore records
  3545.                stem.0S.0.1 = index of first semaphore (hex)
  3546.                stem.0S.n = semaphore index (hex, hash into using "stem.0P.n.0S.n")
  3547.                stem.0S.index.1 = owning slot-id (hex)
  3548.                stem.0S.index.3 = semaphore flag
  3549.                stem.0S.index.4 = reference count
  3550.                stem.0S.index.5 = request count
  3551.                stem.0S.index.6 = semaphore name
  3552.  
  3553.                // Shared Memory Object Information
  3554.                stem.0M.0 = number of shared memory objects
  3555.                stem.0M.n = memory handle (hex, hash into using "stem.0P.n.0M.n")
  3556.                stem.0M.index.1 = memory selector (hex)
  3557.                stem.0M.index.2 = reference count
  3558.                stem.0M.index.3 = memory name
  3559.  
  3560.                // Statically Linked Library Information
  3561.                stem.0L.0 = number of statically linked libraries/modules
  3562.                stem.0L.n = module handle (hex, hash into using "stem.0P.n.0L.n")
  3563.                stem.0L.index.1 = library name
  3564.                stem.0L.index.0I.0 = number of imported modules
  3565.                stem.0L.index.0I.n = imported module handle (hex, use to "hash"
  3566.                                     into list of "stem.0L.index" values)
  3567.  
  3568.   flags    = flags indicating what kind of information to return, may be
  3569.              any combination of:
  3570.                M - shared memory information
  3571.                S - 16-bit semaphore information
  3572.                L - linked library information
  3573.  
  3574.   dosrc    = return code from DosQProcStatus()
  3575.  
  3576. Example:
  3577.  
  3578.   /* rexx */
  3579.   /* Find out what modules each process has statically linked (1st level) */
  3580.  
  3581.   dosrc = rxqprocstatus('q.','l')
  3582.  
  3583.   Say 'There are' q.0p.0 'processes ('q.0g.1 'threads) running right now'
  3584.   do j=1 to q.0p.0
  3585.     say;say 'Process ('q.0p.j.1')'q.0p.j.6 'statically links the following libraries:'
  3586.     do r=1 to q.0p.j.0l.0
  3587.       idx = q.0p.j.0l.r
  3588.       say '   ' q.0l.idx.1
  3589.     end
  3590.   end
  3591.  
  3592.   exit
  3593.  
  3594. Note:
  3595.  
  3596.   Process/Thread information is always returned, whether or not semaphore,
  3597.   library or shared-memory information is requested.
  3598.  
  3599.   The reason such odd compound variable index values were chosen (such as "0P",
  3600.   "0S", etc.) is because too long a constant index value (such as "PROC")
  3601.   tended to increase processing time for the function call (actual size of
  3602.   variable name pool is larger).  The alternative, to use brief constant index
  3603.   values (such as "M") turned out to cause problems when I happened to be using
  3604.   one of these for a variable.  The solution was to choose a constant index name
  3605.   which begins with a digit ("0" - i.e. zero), which is an invalid variable name,
  3606.   thus ensuring that no variable could have the same name as the constant index.
  3607.   This made relatively brief names (e.g. - "0M") possible and prevents "collision"
  3608.   with variable names your program may be using.
  3609.  
  3610.  
  3611. ΓòÉΓòÉΓòÉ 19.4. RxSetError - Set DosError settings ΓòÉΓòÉΓòÉ
  3612.  
  3613. This function allows you to turn HardError and Exception popup on or off.  This 
  3614. change takes effect for the process in which it is issued, no matter what the 
  3615. previous setting was, by whom, or on what thread. Presently, there is no way 
  3616. (that I know of) to query or "reset" these error settings. 
  3617.  
  3618. Syntax:
  3619.  
  3620.   dosrc = RxSetError(flag)
  3621.  
  3622. where:
  3623.  
  3624.   flag  = any combination of:
  3625.           'h' to disable HardError popup
  3626.           'H' to enable  HardError popup
  3627.           'e' to disable Exception popup
  3628.           'E' to enable  Exception popup
  3629.   dosrc = return code from DosError()
  3630.  
  3631. Example:
  3632.  
  3633.   Call rxseterror 'eh'  /* would suppress popups from both harderror */
  3634.                         /* and exception conditions */
  3635.  
  3636.  
  3637. ΓòÉΓòÉΓòÉ 19.5. RxReplaceModule - Replace an active .DLL or .EXE ΓòÉΓòÉΓòÉ
  3638.  
  3639. This function uses the OS/2 "DosReplaceModule()" API to replace an active .DLL 
  3640. or .EXE (i.e. such a module that is locked because it is currently in use). 
  3641.  
  3642. Syntax:
  3643.  
  3644.   dosrc = RxReplaceModule(oldmodname, newmodname, backupmodname)
  3645.  
  3646. where:
  3647.  
  3648.   oldmodname    = name of locked module
  3649.   newmodname    = name of new module to replace old one
  3650.   backupmodname = name of backup module for recoverability
  3651.   dosrc         = return code from DosReplaceModule()
  3652.  
  3653.  
  3654. ΓòÉΓòÉΓòÉ 19.6. RxExitList - Use DosExitList ΓòÉΓòÉΓòÉ
  3655.  
  3656. This function uses the OS/2 "DosExitList()" API to work with OS/2 Exit-Handlers 
  3657. (i.e. add/remove/exit).  For more information on this function, see the OS/2 
  3658. developer's reference for "DosExitList()". 
  3659.  
  3660. Syntax:
  3661.  
  3662.   dosrc = RxExitList(funcaddr [,action] [,order] )
  3663.  
  3664. where:
  3665.  
  3666.   funcaddr  = function pointer (e.g. obtained by RxQueryProcAddr())
  3667.   action    = Add, Remove, Exit
  3668.   order     = 1 byte value (0x00-0xff) indicating order for "Add"
  3669.   dosrc     = return code from DosExitList()
  3670.  
  3671.  
  3672. ΓòÉΓòÉΓòÉ 19.7. RxProcId - Get process' own PID and TID information ΓòÉΓòÉΓòÉ
  3673.  
  3674. This function returns the process-id, parent process-id, and thread-id of the 
  3675. current thread of the current process. 
  3676.  
  3677. Syntax:
  3678.  
  3679.   procinfo = rxprocid()
  3680.  
  3681. where:
  3682.  
  3683.   procinfo = three blank delimited integers:
  3684.              1) process-id
  3685.              2) parent process-id
  3686.              3) thread-id
  3687.  
  3688.  
  3689. ΓòÉΓòÉΓòÉ 19.8. RxGetInfoBlocks - Get information about current process/thread ΓòÉΓòÉΓòÉ
  3690.  
  3691. This function returns the various pieces of information which the 
  3692. DosGetInfoBlocks() function returns. 
  3693.  
  3694. Syntax:
  3695.  
  3696.   dosrc = RxGetInfoBlocks(rexxstem)
  3697.  
  3698. where:
  3699.  
  3700.   rexxstem = name of rexx stem under which information is returned as
  3701.              such:
  3702.  
  3703.              stem.P.1  = process-id
  3704.              stem.P.2  = parent process-id
  3705.              stem.P.3  = our .EXE's module handle
  3706.              stem.P.4  = pointer to command line string
  3707.              stem.P.5  = pointer to environment string
  3708.              stem.P.6  = process status bits
  3709.              stem.P.7  = process type code
  3710.  
  3711.              stem.T.1  = thread-id
  3712.              stem.T.2  = thread priority
  3713.              stem.T.3  = tib2 version
  3714.              stem.T.4  = MustComplete count
  3715.              stem.T.5  = MustComplete Force Flag
  3716.              stem.T.6  = tib version
  3717.              stem.T.7  = thread ordinal
  3718.              stem.T.8  = pointer to head of exception handler chain
  3719.              stem.T.9  = pointer to base of stack
  3720.              stem.T.10 = pointer to end of stack
  3721.  
  3722.   dosrc    = return code from DosGetInfoBlocks()
  3723.  
  3724. Note:
  3725.  
  3726.   for stem.P.4, stem.P.5, stem.T.9, and stem.T.10, you could use
  3727.   RxStorage() to get to the values at these addresses.
  3728.  
  3729.  
  3730. ΓòÉΓòÉΓòÉ 19.9. RxQueryAppType - Get information about an executable file ΓòÉΓòÉΓòÉ
  3731.  
  3732. This function returns information about the type of an executable file as 
  3733. indicated in that file's header. 
  3734.  
  3735. Syntax:
  3736.  
  3737.   info = RxQueryAppType(filename)
  3738.  
  3739. where:
  3740.  
  3741.   filename = name of executable file whose type you want to know
  3742.              (either fully qualified, or just name and will search
  3743.               path)
  3744.   info     = return code from DosQueryAppType, and if zero, followed
  3745.              by any combination of:
  3746.  
  3747.              N - NotSpecified
  3748.              w - NotWindowCompat
  3749.              W - WindowCompat
  3750.              A - WindowApi
  3751.              B - Bound
  3752.              L - DLL
  3753.              D - DOS
  3754.              Y - Physical Device Driver
  3755.              V - Virtual Device Driver
  3756.              P - Protected Memory DLL
  3757.              3 - 32 Bit
  3758.  
  3759.  
  3760. ΓòÉΓòÉΓòÉ 19.10. RxTmrQueryFreq - Query frequency of IRQ0 high-resolution timer ΓòÉΓòÉΓòÉ
  3761.  
  3762. This function returns the frequency of the IRQ0 high-resolution (8254) timer 
  3763. via the DosTmrQueryFreq() API. 
  3764.  
  3765. Syntax:
  3766.  
  3767.   info = RxTmrQueryFreq()
  3768.  
  3769. where
  3770.  
  3771.   info     = two blank delimited values:
  3772.              1) return code from DosTmrQueryFreq()
  3773.                 and if return code is zero:
  3774.              2) frequency of high-resolution timer in hertz (timer units/sec).
  3775.  
  3776.  
  3777. ΓòÉΓòÉΓòÉ 19.11. RxTmrQueryTime - Query snapshot of IRQ0 high-resolution timer value ΓòÉΓòÉΓòÉ
  3778.  
  3779. This function returns a snapshot of the value from the IRQ0 high-resolution 
  3780. (8254) timer via the DosTmrQueryTime() API. 
  3781.  
  3782. Syntax:
  3783.  
  3784.   info = RxTmrQueryTime()
  3785.  
  3786. where
  3787.  
  3788.   info     = two blank delimited values:
  3789.              1) return code from DosTmrQueryTime()
  3790.                 and if return code is zero:
  3791.              2) two period-delimited integers indicating high-order and low-order
  3792.                 portions of timer value, as such:
  3793.                   high-order.low-order
  3794.  
  3795.  
  3796. ΓòÉΓòÉΓòÉ 19.12. RxQuerySysInfo - Query OS/2 SysInfo ΓòÉΓòÉΓòÉ
  3797.  
  3798. This function returns live system information about OS/2 via the 
  3799. DosQuerySysInfo API. 
  3800.  
  3801. Syntax:
  3802.  
  3803.   dosrc = RxQuerySysInfo( stemname [,startidx [,endidx]])
  3804.  
  3805. where
  3806.  
  3807.   stemname = Rexx stem name, under which results are returned.  Each
  3808.              DosQuerySysInfo item is returned under the appropriate stem.n
  3809.              For instance, the call "call rxquerysysinfo('s.',3,5)" would
  3810.              set the rexx variables "s.3", "s.4", and "s.5".
  3811.   dosrc    = return code from DosQuerySysInfo()
  3812.   startidx = Default is 1
  3813.   endidx   = Default is 26
  3814.  
  3815.   Index values:
  3816.  
  3817.   1. Maximum length, in bytes, of a path name.
  3818.   2. Maximum number of text sessions.
  3819.   3. Maximum number of PM sessions.
  3820.   4. Maximum number of DOS sessions.
  3821.   5. Drive from which the system was started (1 means drive A,
  3822.      2 means drive B, and so on).
  3823.   6. Dynamic priority variation flag (0 means absolute priority,
  3824.      1 means dynamic priority).
  3825.   7. Maximum wait in seconds.
  3826.   8. Minimum time slice in milliseconds.
  3827.   9. Maximum time slice in milliseconds.
  3828.  10. Memory page size in bytes.  This value is 4096 for the 80386
  3829.      processor.
  3830.  11. Major version number.
  3831.  12. Minor version number.
  3832.  13. Revision letter.
  3833.  14. Value of a 32-bit, free-running millisecond counter.  This value
  3834.      is zero when the system is started.
  3835.  15. Low-order 32 bits of the time in seconds since January 1, 1970
  3836.      at 0:00:00.
  3837.  16. High-order 32 bits of the time in seconds since January 1, 1970
  3838.      at 0:00:00.
  3839.  17. Total number of pages of physical memory in the system.
  3840.      One page is 4KB.
  3841.  18. Total number of pages of resident memory in the system.
  3842.  19. Maximum number of pages of memory that can be allocated by all
  3843.      processes in the system.  This number is advisory and is not
  3844.      guaranteed, since system conditions change constantly.
  3845.  20. Maximum number of bytes of memory that this process can allocate
  3846.      in its private arena.  This number is advisory and is not
  3847.      guaranteed, since system conditions change constantly.
  3848.  21. Maximum number of bytes of memory that a process can allocate in
  3849.      the shared arena.  This number is advisory and is not guaranteed,
  3850.      since system conditions change constantly.
  3851.  22. Timer interval in tenths of a millisecond.
  3852.  23. Maximum length, in bytes, of one component in a path name.
  3853.  24. Session ID of the current foreground full-screen session (full screen
  3854.      sessions only; PM session has sessid=1)
  3855.  25. Process ID of current (i.e. one making this call) foreground process
  3856.  26. Number of processors on machine
  3857.  
  3858.  
  3859. ΓòÉΓòÉΓòÉ 19.13. RxPhysicalDisk - Query information about partitionable disks ΓòÉΓòÉΓòÉ
  3860.  
  3861. This function returns information about physical disks via the 
  3862. DosPhysicalDisk() API. 
  3863.  
  3864. Syntax:
  3865.  
  3866.   dosrc = RxDevConfig(function, rexxvar ,retlen [,parm])
  3867.  
  3868. where
  3869.  
  3870.   function = function code (1,2,3)
  3871.   rexxvar  = Rexx variable name, in which physical disk information is returned
  3872.   retlen   = return buffer length
  3873.   parm     = (optional) parameter to be passed to API
  3874.   dosrc    = return code from DosPhysicalDisk()
  3875.  
  3876.  
  3877. ΓòÉΓòÉΓòÉ 19.14. RxDevConfig - Obtain device configuration information ΓòÉΓòÉΓòÉ
  3878.  
  3879. This function returns device configuration information using the DosDevConfig() 
  3880. API. 
  3881.  
  3882. Syntax:
  3883.  
  3884.   dosrc = RxDevConfig(rexxvar ,devtype [,infolen])
  3885.  
  3886. where
  3887.  
  3888.   rexxvar  = Rexx variable name, in which device information is returned
  3889.   devtype  = integer (currently 0-6) indicating which device to get info on
  3890.   infolen  = if devtype > 6, length of buffer necessary to hold devinfo
  3891.   dosrc    = return code from DosDevConfig()
  3892.  
  3893.  
  3894. ΓòÉΓòÉΓòÉ 19.15. RxDevIOCtl - Do DosDevIOCtl calls (to talk to character devices directly) ΓòÉΓòÉΓòÉ
  3895.  
  3896. This function allows direct communication with character devices using the 
  3897. DosDevIOCtl() API. 
  3898.  
  3899. Syntax:
  3900.  
  3901.   dosrc = RxDevIOCtl(rexxstem, devhandle, category, function,
  3902.                      parmlist, retparmlen, data, retdatalen)
  3903.  
  3904. where
  3905.  
  3906.   rexxstem   = Rexx stem name, under which data is returned as such:
  3907.                stem.1 = parmlist returned
  3908.                stem.2 = dataarea returned
  3909.   devhandle  = device handle (binary) obtained from DosOpen()
  3910.   category   = integer indicating category
  3911.   function   = integer indicating function
  3912.   parmlist   = parmlist data (if zero length or "empty" string, no parmlist is
  3913.                passed to DosDevIOCtl())
  3914.   retparmlen = length of expected parmlist returned
  3915.   data       = dataarea data (if zero length or "empty" string, no dataarea is
  3916.                passed to DosDevIOCtl())
  3917.   retdatalen = length of expected dataarea returned
  3918.   dosrc      = return code from DosDevIOCtl()
  3919.  
  3920.  
  3921. ΓòÉΓòÉΓòÉ 20. PM / Wp related functions ΓòÉΓòÉΓòÉ
  3922.  
  3923. Functions related to PM or Workplace Shell Objects 
  3924.  
  3925.  
  3926. ΓòÉΓòÉΓòÉ 20.1. RxWinQueryObject - Query WP-Shell Object Handle ΓòÉΓòÉΓòÉ
  3927.  
  3928. This function returns the object handle of a WorkPlace Shell object. 
  3929.  
  3930. Syntax:
  3931.  
  3932.   hobj = RxWinQueryObject(objname)
  3933.  
  3934. where
  3935.  
  3936.   objname = name of WorkPlace Shell object
  3937.   hobj    = handle to object (or null string if not successful)
  3938.  
  3939.  
  3940. ΓòÉΓòÉΓòÉ 20.2. RxWinDestroyObject - Destroy a WP-Shell Object ΓòÉΓòÉΓòÉ
  3941.  
  3942. This function destroys a WorkPlace Shell object by object handle. 
  3943.  
  3944. Syntax:
  3945.  
  3946.   yorn = RxWinDestroyObject(hobj)
  3947.  
  3948. where
  3949.  
  3950.   hobj    = handle to object
  3951.   yorn    = "1" if it worked, "0" if it didn't
  3952.