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