home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1993 #2 / Image.iso / os2 / rxu11.zip / YDBAUTIL.INF (.txt) < prev   
OS/2 Help File  |  1993-06-22  |  62KB  |  2,415 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. About YDBAUTIL ΓòÉΓòÉΓòÉ
  3.  
  4. YDBAUTIL is a package of diverse OS/2 Rexx External Functions. Some functions 
  5. in this package work with features of Extended Services (ES), although you do 
  6. not need to have ES installed to use the non-ES functions. Almost all the 
  7. functions in this package are in use in many of my own programs and are fairly 
  8. well de-bugged.  Please let me know of any problems you encounter in using the 
  9. functions, or of any suggestions for enhancements to existing functions, or 
  10. ideas for new ones. 
  11.  
  12.  
  13.   With the functions in the YDBAUTIL function package, you can make
  14.   use of some of OS/2's most powerful facilities, such as multi-threading,
  15.   processes, sessions, semaphores, shared memory, OS/2 queues, etc.
  16.   Some of these features are not only useful in pure Rexx applications,
  17.   but they allow you to write Rexx programs which can talk to compiled
  18.   programs on their level (i.e. reference memory by address, use
  19.   semaphores, etc.).
  20.  
  21.   Another benefit is the ability to quickly prototype real OS/2 programs
  22.   using real OS/2 APIs so that you can cheaply 'prove' techniques
  23.   before committing them to 'C' code.
  24.  
  25.   The capabilities provided to Rexx programs by this package, in
  26.   conjunction with those provided by other Rexx function packages
  27.   (database access, APPC, etc.) and the base language itself allow
  28.   you to prototype or build Rexx applications with much of the
  29.   functional sophistication (and complexity, unfortunately) of "real"
  30.   OS/2 applications.
  31.  
  32.   In addition to the many OS/2 API "passthrough" functions, there are
  33.   some Rexx-specific enhancements and additions.
  34.  
  35.  
  36.   Author:        Dave Boll
  37.                  (CompuServe = 74170,2016)
  38.                  IBMMAIL(USFMCFKF)
  39.   Release Date:  21 June, 1993
  40.   Version:       1.1
  41.  
  42.  
  43. ΓòÉΓòÉΓòÉ 2. Release Notes ΓòÉΓòÉΓòÉ
  44.  
  45. This release contains fixes for some minor problems and includes help 
  46. information for OS/2 queue functions (which were there for v.10 but I forgot to 
  47. document).  I have tried this on OS/2 v2.1 GA code and it seems to work just 
  48. fine.  This function package will only work on OS/2 2.x as it is 32-bit code. 
  49.  
  50.  
  51. ΓòÉΓòÉΓòÉ 3. How to Use It ΓòÉΓòÉΓòÉ
  52.  
  53. How to register the functions: 
  54.  
  55. In order to use the functions, you have to register them with Rexx like this:
  56.  
  57.   call rxfuncadd 'rxydbautilinit','ydbautil','rxydbautilinit'
  58.   call rxydbautilinit
  59.  
  60. The .DLL "ydbautil.dll" must be in your libpath.
  61. The program "RXSRS.EXE" must be in your path in order to use the functions
  62. "RxStartRexxSession" and "RxDetachRexxPgm".
  63.  
  64.  
  65. ΓòÉΓòÉΓòÉ 4. Available External Functions ΓòÉΓòÉΓòÉ
  66.  
  67. The available functions are: 
  68.  
  69.  
  70.   Function Package utility functions
  71.   ----------------------------------
  72.   RxYdbaUtilInit        - Register all YDBAUTIL Rexx functions
  73.   RxYdbaUtilTerm        - De-Register all YDBAUTIL Rexx functions
  74.   RxYdbaUtilQuery       - Query available external function entry point names
  75.  
  76.   UPM Related
  77.   -----------
  78.   RxUpm                 - Rexx interface to UPM
  79.   RxNet                 - Rexx interface to certain NET calls
  80.                           (also some UPM-related calls)
  81.  
  82.   System-Info related
  83.   -------------------
  84.   RxProcId              - Get process' own PID and TID information
  85.   RxQuerySysInfo        - Invoke DosQuerySysInfo
  86.   RxPStat               - Obtain Process Status Information (like PSTAT)
  87.   RxSetError            - Set DosError settings (enable/disable HardError
  88.                           and Exception popups)
  89.  
  90.   Rexx programming and debugging functions
  91.   ----------------------------------------
  92.   RxVlist               - List, manipulate Rexx variable pool
  93.   RxScount              - Count strings (needle) in another string (haystack)
  94.   RxPmPrintf            - Write lines to a PMPrintf Monitor
  95.   RxCallInStore         - Execute a string as a program
  96.   RxTokenize            - Tokenize ("Compile") a program string
  97.   RxPullQueue           - Pull items from any Rexx data queue
  98.   RxAddQueue            - Add items to any Rexx data queue
  99.   RxQueued              - Query number of items on any Rexx data queue
  100.   RxQExists             - Query existence of a Rexx Queue
  101.  
  102.   I/O related
  103.   -----------
  104.   RxRsoe2f              - Redirect StdOut/StdErr to a file (by file name)
  105.   RxSoSe2H              - Redirect StdOut/StdErr to a file (by file handle)
  106.   RxSi2H                - Redirect StdIn from a file (by file handle)
  107.   RxRSi2F               - Redirect StdIn from a file (by file name)
  108.   RxRead                - Read data from a file handle
  109.   RxWrite               - Write data to a file handle
  110.   RxCloseH              - Close a file handle
  111.   RxExecI               - Read data into a Rexx queue or stem from a file
  112.   RxExecO               - Write data from a Rexx queue or stem to a file
  113.  
  114.   OS/2 Pipes
  115.   ----------
  116.   RxCreateNPipe         - Create a named pipe
  117.   RxConnectNPipe        - Connect to a named pipe
  118.   RxDisConnectNPipe     - Disconnect from a named pipe
  119.   RxCreatePipe          - Create an un-named pipe
  120.   RxDestroyPipe         - Destroy a pipe
  121.  
  122.   OS/2 Queues
  123.   ----------
  124.   RxCreateQueue         - DosCreateQueue
  125.   RxOpenQueue           - DosOpenQueue
  126.   RxPeekQueue           - DosPeekQueue
  127.   RxReadQueue           - DosReadQueue
  128.   RxWriteQueue          - DosWriteQueue
  129.   RxPurgeQueue          - DosPurgeQueue
  130.   RxQueryQueue          - DosQueryQueue
  131.   RxCloseQueue          - DosCloseQueue
  132.   RxReadQueueStr        - Returns data from de-referenced queue pointer
  133.  
  134.   NetBios information
  135.   -------------------
  136.   RxNbSessionStatus     - Obtain NETBIOS session status information
  137.  
  138.   Tasking, threads, etc.
  139.   ----------------------
  140.   RxSetPriority         - Set the priority of processes or threads
  141.             Process - Related
  142.   RxKillProcess         - Kill an OS/2 process by process-id
  143.   RxExecPgm             - Execute a program using DosExecPgm
  144.   RxStartSession        - Start a program in another session (DosStartSession)
  145.   RxStartRexxSession    - Start a Rexx program in another session
  146.   RxDetachRexxPgm       - Detach a Rexx program
  147.             Thread - Related
  148.   RxCreateRexxThread    - Execute a Rexx program on another thread
  149.   RxCreateThread        - Call a procedure address on another thread
  150.   RxKillThread          - Kill a thread by thread-id
  151.   RxResumeThread        - Resume thread execution by thread-id
  152.   RxSuspendThread       - Suspend thread execution by thread-id
  153.   RxCallEntryPoint      - Call a (non-Rexx) routine by entry point address
  154.  
  155.   OS/2 Memory managment
  156.   ---------------------
  157.   RxStorage             - Query/Alter storage by address
  158.   RxAdd2Ptr             - Pointer Arithmetic (Add/Subtract)
  159.   RxAllocMem            - Allocate Memory
  160.   RxFreeMem             - Free Memory
  161.   RxAllocSharedMem      - Allocated Shared memory (named or un-named)
  162.   RxGetSharedMem        - Get (gettable) shared memory
  163.   RxGiveSharedMem       - Give (giveable) shared memory
  164.   RxGetNamedSharedMem   - Get named shared memory
  165.   RxSetMem              - Set memory attributes
  166.   RxQueryMem            - Query memory attributes
  167.   RxSubAllocMem         - Suballocate memory
  168.   RxSubFreeMem          - Free suballocated memory
  169.   RxSubSetMem           - Set memory for suballocation
  170.   RxSubUnsetMem         - Unset previously "SubSet" memory
  171.  
  172.   OS/2 Semaphores
  173.   ---------------
  174.              Event Semaphore
  175.   RxCreateEventSem      - Create an event semaphore
  176.   RxCloseEventSem       - Close an event semaphore
  177.   RxOpenEventSem        - Open an event semaphore
  178.   RxPostEventSem        - Post an event semaphore
  179.   RxQueryEventSem       - Query an event semaphore
  180.   RxResetEventSem       - Reset an event semaphore
  181.   RxWaitEventSem        - Wait on an event semaphore
  182.              Mutex Semaphore
  183.   RxCreateMutexSem      - Create a Mutex semaphore
  184.   RxOpenMutexSem        - Invoke DosOpenMutexSem
  185.   RxCloseMutexSem       - Invoke DosCloseMutexSem
  186.   RxQueryMutexSem       - Invoke DosQueryMutexSem
  187.   RxReleaseMutexSem     - Invoke DosReleaseMutexSem
  188.   RxRequestMutexSem     - Invoke DosRequestMutexSem
  189.              MuxWait Semaphore
  190.   RxCreateMuxWaitSem    - Invoke DosCreateMuxWaitSem
  191.   RxCloseMuxWaitSem     - Invoke DosCloseMuxWaitSem
  192.   RxOpenMuxWaitSem      - Invoke DosOpenMuxWaitSem
  193.   RxWaitMuxWaitSem      - Invoke DosWaitMuxWaitSem
  194.   RxAddMuxWaitSem       - Invoke DosAddMuxWaitSem
  195.   RxDeleteMuxWaitSem    - Invoke DosDeleteMuxWaitSem
  196.   RxQueryMuxWaitSem     - Invoke DosQueryMuxWaitSem
  197.  
  198.   DLL Handling
  199.   ------------
  200.   RxLoadModule          - Load a DLL
  201.   RxFreeModule          - Free a DLL
  202.   RxQueryModuleName     - Query the fully qualified name of a DLL (by handle)
  203.   RxQueryModuleHandle   - Query the module handle of a DLL (by name)
  204.   RxQueryProcType       - Query the addressing mode of an entry point in a DLL
  205.   RxQueryProcAddr       - Query the procedure address of an entry point in a DLL
  206.  
  207.   Rexx Macro Space Handling
  208.   -------------------------
  209.   RxAddMacro            - Add a particular Macro Space function
  210.   RxDropMacro           - Drop a particular Macro Space function
  211.   RxClearMacroSpace     - Clear the Rexx Macro Space
  212.   RxSaveMacroSpace      - Save a particular Macro Space function to a file
  213.   RxLoadMacroSpace      - Load a particular Macro Space function from a file
  214.   RxQueryMacro          - Query the position of a particular Macro Space function
  215.   RxReorderMacro        - Reorder a function's position in a Macro Space
  216.  
  217.   PM / Wp related functions
  218.   -------------------------
  219.   RxWinQueryObject      - Query object handle of a WP object
  220.   RxWinDestroyObject    - Destroy a WP object
  221.  
  222.  
  223. ΓòÉΓòÉΓòÉ 5. UPM Related Functions ΓòÉΓòÉΓòÉ
  224.  
  225. Functions which allow certain UPM activities to be performed. 
  226.  
  227.  
  228. ΓòÉΓòÉΓòÉ 5.1. RxUpm - Rexx/UPM Interface ΓòÉΓòÉΓòÉ
  229.  
  230. This function allows you to make most UPM calls from a Rexx program. 
  231.  
  232. Syntax:
  233.  
  234.   func  = 'Logon'     For Process level logon, only usable by that process */
  235.           'Logonp'
  236.         = 'Logonu'    For "User" logon, usable by all processes
  237.         = 'Logoff'    For Process level logoff, undoes a "LOGONP"
  238.           'Logoffp'
  239.         = 'Logoffu'   For "User" logoff, undoes a "LOGONU"
  240.         = 'LogonList' Gets list of current active logons
  241.   uid   = 'Userid'    Userid to be logged on/off
  242.         = 'stemname'  Name of Rexx stem variable under which results
  243.                       of "LogonList" are mapped as such:
  244.                       stem.0    - Number of logons reported on
  245.                       stem.n.1  - Userid
  246.                       stem.n.2  - Node/Domain name
  247.                       stem.n.3  - Session-Id
  248.                       stem.n.4  - Logon type (Local/Node/Domain)
  249.   pw    = 'Password'  Password to be used with 'Userid' (for logon)
  250.   type  = 'Local'     Logs you on/off UPM locally (default is LOCAL if
  251.                       no value supplied)
  252.         = 'Node'      Logs you on/off a node
  253.         = 'Domain'    Logs you on/off a LAN domain
  254.         = 'dataBase'  Logs you on/off the correct node for a database
  255.   name  = 'Name'      The name of the node/domain/database, depending on
  256.                       what "TYPE" was chosen
  257.   check = 'Admin'     Checks to see if userid has Admin authority
  258.         = 'User'      Checks to see if userid has User authority
  259.         = 'Config'    Checks to see if logon was done from Config.Sys
  260.  
  261.   upmrc = RxUpm(func, uid, pw, type, name, check)
  262.  
  263.  
  264. ΓòÉΓòÉΓòÉ 5.2. RxNet - Rexx/NET Interface ΓòÉΓòÉΓòÉ
  265.  
  266. This function allows you to make certain NetApi calls from Rexx.  This enables 
  267. you to do such things as changing passwords, adding and deleting userids, 
  268. validating a userid/pw, listing users and logons. 
  269.  
  270. Syntax:
  271.  
  272. /* General syntax */
  273.   netrc = RxNet(func, server, arg3, arg4, arg5, arg6)
  274.  
  275. where:
  276.  
  277.   func   = 'UserPwSet' /* Change a user's password */
  278.          = 'UserAdd'   /* Add a user to UPM */
  279.          = 'UserDel'   /* Delete a user from UPM */
  280.          = 'UserVal'   /* Validate a userid/password without logging on */
  281.          = 'UserEnum'  /* List users in UPM */
  282.          = 'LogonEnum' /* List active logons */
  283.          = 'FileEnum'  /* File usage on the LAN */
  284.   server = name of server, or '00'x for local
  285.   netrc  = return code from NetApi call. If netrc < 2100, then it's probably
  286.            a base OS/2 return code, otherwise, it's defined in NETCONS.H
  287.  
  288. /* Specific calls */
  289.   netrc = RxNet('UserPwSet', server, userid, oldpw, newpw)
  290.  
  291.   netrc = RxNet('UserAdd', server, userid, password, type, comment)
  292.           type = 'User', 'Guest', or 'Admin'
  293.  
  294.   netrc = RxNet('UserDel', server, userid)
  295.  
  296.   netrc = RxNet('UserVal', server, userid, password)
  297.  
  298.   netrc = RxNet('UserEnum',server, rexxstem)
  299.           rexxstem = Rexx stem name, under which results are mapped as:
  300.                      stem.0 = number of users
  301.                      stem.n.1 = userid
  302.                      stem.n.2 = privilege level (Guest, User, Admin, ?)
  303.                      stem.n.3 = password age (in seconds)
  304.                      stem.n.4 = comment
  305.  
  306.   netrc = RxNet('LogonEnum',server, rexxstem)
  307.           rexxstem = Rexx stem name, under which results are mapped as:
  308.                      stem.0 = number of users
  309.                      stem.n.1 = userid
  310.  
  311.   netrc = RxNet('FileEnum',server, basepath, username, rexxstem)
  312.           basepath = file path/name qualifier
  313.           username = username qualifier
  314.           rexxstem = Rexx stem name, under which results are mapped as:
  315.                      stem.0 = number of entries
  316.                      stem.n.1 = file-id
  317.                      stem.n.2 = permissions
  318.                      stem.n.3 = numlocks
  319.                      stem.n.4 = pathname
  320.                      stem.n.5 = username
  321.  
  322.  
  323. ΓòÉΓòÉΓòÉ 6. Rexx Programming/Debugging ΓòÉΓòÉΓòÉ
  324.  
  325. Tools for developing Rexx programs. 
  326.  
  327.  
  328. ΓòÉΓòÉΓòÉ 6.1. RxSCount - Count instances of a string ΓòÉΓòÉΓòÉ
  329.  
  330. This function returns a count of the number of instances of a string "needle" 
  331. in a string "haystack", optionally ignoring case. 
  332.  
  333. Syntax:
  334.  
  335.   numitem = rxscount(needle,haystack[,case])
  336.  
  337. where:
  338.  
  339.   needle   = string you want to count instances of
  340.   haystack = string in which you want to count instances of "needle"
  341.   case     = any character to indicate that case (upper/lower) is to
  342.              be ignored
  343.   numitem  = number of times "needle" is found in "haystack"
  344.  
  345.  
  346. ΓòÉΓòÉΓòÉ 6.2. RxPmPrintf - Write lines to a PMPrintf Monitor ΓòÉΓòÉΓòÉ
  347.  
  348. This function writes data lines to a PMPrintf "Monitor" program. 
  349.  
  350. Syntax:
  351.  
  352.   bytes = RxPmPrintf(qname, [data1 [,data2 [,data3 [...]]]] )
  353.  
  354. where:
  355.  
  356.   qname    = name of PMPrintf queue
  357.              If blank, uses default PMPrintf Queue (PRINTF32).
  358.   data1    = data to be written to PMPrintf
  359.   ...        Each argument is written as a separate line
  360.   datan
  361.  
  362.   bytes    = number of bytes written in this operation
  363.  
  364. Notes:
  365.  
  366.   The PMPrintf tool can be downloaded from the OS/2 Bulletin Board.
  367.   This Rexx function does work with PMPrintf v2.5, but may not work
  368.   with earlier versions.  You can start the PMPrintf program with
  369.   a command line argument specifying an alternate queue name for it
  370.   to use.  This queue name can be supplied as the first argument of
  371.   RxPmPrintf to direct the data to a specific running instance of
  372.   PMPrintf.
  373.  
  374.   If only the queue name is supplied (i.e. args 2-n are not supplied),
  375.   nothing at all is written to queue.  If an argument has zero length,
  376.   no data will be written to the queue for that argument (i.e. you
  377.   must supply at least one byte to be written to queue).
  378.  
  379.  
  380. ΓòÉΓòÉΓòÉ 6.3. RxCallInStore - Execute a string as a program ΓòÉΓòÉΓòÉ
  381.  
  382. This function allows the Rexx program developer to execute a string as though 
  383. it were a Rexx program.  This allows you to build the equivalent of a Rexx 
  384. program's text in a variable, and then execute it from the string.  Actually, 
  385. the Rexx program text can come from anywhere -- a file, over a communications 
  386. link, from a database. For repeated execution of a program, use "RxTokenize" to 
  387. "compile" the program, then call "RxCallInStore" with "&" to re-use the 
  388. tokenized program. 
  389.  
  390. Syntax:
  391.  
  392.   result = RxCallInStore strtext, arg1, arg2, ..., arg19
  393.  
  394. where:
  395.  
  396.   strtext  = text of a Rexx program, complete with crlf and eof markers
  397.                   or
  398.              a '$' immediately preceding a source program string
  399.                   or
  400.              a '&' immediately preceding a tokenized program string
  401.   arg1     = arguments to the called program
  402.   ...
  403.   arg19
  404.  
  405. Note:
  406.  
  407.   Example of executing a program string:
  408.  
  409.     crlf = '0d0a'x
  410.     str = '/* Rexx */'crlf
  411.     str = str 'Do i=1 To Arg()'crlf
  412.     str = str '  Say "Arg#"i "= {"arg(i)"}"'crlf
  413.     str = str 'End'crlf
  414.     str = str||'1a'x       /* EOF marker */
  415.     call rxcallinstore str, date(), time()
  416.                ( or )
  417.     call rxcallinstore '$'str, date(), time()
  418.                ( or )
  419.     tstr = rxtokenize(str)
  420.     call rxcallinstore '&'tstr, date(), time()
  421.  
  422.  
  423. ΓòÉΓòÉΓòÉ 6.4. RxTokenize - Tokenize a program source string ΓòÉΓòÉΓòÉ
  424.  
  425. This function in effect "compiles" a program source string for re-use with 
  426. subsequent "RxCallInstore" or "RxCreateRexxThread" calls. This provides better 
  427. performance when a program string is repeatedly called. 
  428.  
  429. Syntax:
  430.  
  431.   tokenstr = RxTokenize(progstr)
  432.  
  433. where:
  434.  
  435.   progstr  = actual Rexx program source string
  436.   tokenstr = tokenized ("compiled") result of "progstr"
  437.  
  438. Note:
  439.  
  440.   This function, in conjunction with the "RxCallInstore" and/or
  441.   "RxCreateRexxThread" functions, can be used to achieve the same
  442.   effect as the Rexx Macrospace, except that this technique is local
  443.   to the program using it (whereas the Macrospace is system global).
  444.  
  445.  
  446. ΓòÉΓòÉΓòÉ 6.5. RxVlist - Display/Process Rexx Variables ΓòÉΓòÉΓòÉ
  447.  
  448. This function allows the Rexx program developer to view portions of the Rexx 
  449. variable pool.  It also allows you to effectively "pass" variable pools (or 
  450. subsets thereof) between execs across Rexx queues. 
  451.  
  452. Syntax:
  453.  
  454.   numvar = RxVlist( [vnamepat] [,func] [,qname] )
  455.  
  456. where:
  457.  
  458.   func     = 'V'  /* Puts variable name/value pairs on a queue */
  459.            = 'N'  /* Puts variable names on a queue */
  460.            = 'G'  /* Gets variable name/value pairs off a queue */
  461.                   /* and incorporates them into the current variable pool */
  462.            = 'D'  /* display variables and their values (default) */
  463.   vnamepat = variable name prefix (every variable whose name begins with this
  464.              value is processed according to the specified function)
  465.              (default is all variables)
  466.   qname    = name of a Rexx queue to use (default is the current queue)
  467.  
  468.  
  469. ΓòÉΓòÉΓòÉ 6.6. RxPullQueue - Pull items off any Rexx queue ΓòÉΓòÉΓòÉ
  470.  
  471. This function does what the Rexx "Pull" instruction and "LineIn" functions do, 
  472. except this function allows you to specify the queue name as part of the call, 
  473. regardless of what the current queue may be. 
  474.  
  475. Syntax:
  476.  
  477.   data = RxPullQueue( [qname] [,type] [,rexxvar] )
  478.  
  479. where:
  480.  
  481.   qname   = name of Rexx queue to pull from (default is current queue)
  482.   type    = 'Wait' or 'Nowait' (default is 'Wait')
  483.   rexxvar = name of a Rexx variable into which is put the queue-insertion-
  484.             timestamp for the retreived element
  485.   data    = data obtained from queue
  486.  
  487.  
  488. ΓòÉΓòÉΓòÉ 6.7. RxAddQueue - Add items to any Rexx queue ΓòÉΓòÉΓòÉ
  489.  
  490. This function does what the Rexx "Queue" and "Push" instructions, and the 
  491. "LineOut" function do, except this function allows you to specify the queue 
  492. name as part of the call, regardless of what the current queue may be. 
  493.  
  494. Syntax:
  495.  
  496.   qrc = RxAddQueue( data [,qname] [,type] )
  497.  
  498. where:
  499.  
  500.   data  = data to be placed on queue
  501.   qname = name of Rexx queue to add to (default is current queue)
  502.   type  = 'Queue' or 'Push' (default is 'Queue')
  503.  
  504.  
  505. ΓòÉΓòÉΓòÉ 6.8. RxQueued - Query number of items on any Rexx queue ΓòÉΓòÉΓòÉ
  506.  
  507. This function does what the Rexx "Queued" function does, except this function 
  508. allows you to specify the queue name as part of the call, regardless of what 
  509. the current queue may be. 
  510.  
  511. Syntax:
  512.  
  513.   numq = RxQueued( [qname] )
  514.  
  515. where:
  516.  
  517.   qname = name of Rexx queue to report on (default is current queue)
  518.  
  519.  
  520. ΓòÉΓòÉΓòÉ 6.9. RxQExists - Query existence of a Rexx Queue ΓòÉΓòÉΓòÉ
  521.  
  522. This function returns "1" or "0", indicating the existence of the Rexx Queue 
  523. whose name you supply as an argument. 
  524.  
  525. Syntax:
  526.  
  527.   bool = RxQExists( [qname] )
  528.  
  529. where:
  530.  
  531.   qname = name of Rexx queue to check for existence of
  532.   bool  = truth value of queue's existence
  533.  
  534.  
  535. ΓòÉΓòÉΓòÉ 7. Memory Management/Access ΓòÉΓòÉΓòÉ
  536.  
  537. These functions allow Rexx programs to create, access, and manage OS/2 memory 
  538. objects by address.  This includes objects such as shared memory (named and 
  539. un-named). 
  540.  
  541.  
  542. ΓòÉΓòÉΓòÉ 7.1. RxStorage - Access/Alter memory by address ΓòÉΓòÉΓòÉ
  543.  
  544. This function allows a Rexx program to access and/or alter storage by address. 
  545. This could be used to process data passed to it by a program.  This could also 
  546. be used to "Pass By Reference" among Rexx programs when using the RxAllocMem 
  547. and RxFreeMem functions. 
  548.  
  549. Syntax:
  550.  
  551.   outdata = RxStorage( pointer [, length] [, indata] )
  552.  
  553. where
  554.  
  555.   pointer  = 32-bit pointer (address)
  556.   length   = Length of storage to be queried (defaults to 1)
  557.   indata   = Data to place at address "pointer" for the length of the data
  558.              (regardless of "length" value)
  559.   outdata  = Data at address "pointer" for length "length" (truncated if
  560.              "length" takes you beyond allowed storage)
  561.  
  562. Note:
  563.  
  564.   A request to query memory out-of-bounds returns a string up to the bound-
  565.   ary.  A request to set memory out-of-bounds, sets memory up to the bound-
  566.   ary.  All memory is allocated in 4k chunks.  Therefore, some query or set
  567.   operations will access memory up to the next 4k boundary.
  568.  
  569.  
  570. ΓòÉΓòÉΓòÉ 7.2. RxAdd2Ptr - Pointer Arithmetic (Add/Subtract) ΓòÉΓòÉΓòÉ
  571.  
  572. This function allows a Rexx program to add or subtract from an OS/2 32-bit 
  573. linear address. 
  574.  
  575. Syntax:
  576.  
  577.   newptr = RxAdd2Ptr( pointer , [number] )
  578.  
  579. where:
  580.  
  581.   pointer  = 32-bit pointer (address)
  582.   number   = amount by which "pointer" is to be incremented/decremented
  583.              in bytes.  Default is zero.
  584.   newptr   = result of addition/subtraction
  585.  
  586.  
  587. ΓòÉΓòÉΓòÉ 7.3. RxAllocMem - Allocate memory (using DosAllocMem) ΓòÉΓòÉΓòÉ
  588.  
  589. This function allows a Rexx program to allocate memory.  This memory can then 
  590. be accessed using RxStorage. 
  591.  
  592. Syntax:
  593.  
  594.   allocrc = RxAllocMem(rexxvar, length, flags)
  595.  
  596. where
  597.  
  598.   rexxvar = name of a rexx variable in which pointer is returned
  599.   length  = a decimal integer indicating amount of storage (in bytes) to
  600.             allocate
  601.   flags   = any combination of:
  602.             C - Pag_Commit
  603.             T - Obj_Tile
  604.             X - Pag_Execute
  605.             R - Pag_Read
  606.             W - Pag_Write
  607.             G - Pag_Guard
  608.   allocrc = return code from DosAllocMem()
  609.  
  610. for example:
  611.             /* Following would get 4k committed read/write */
  612.   allocrc = RxAllocMem('pointer', 4096, 'crw')
  613.  
  614. Note:
  615.  
  616.   All memory is allocated in 4k chunks.  Therefore, even if you allocate 200
  617.   bytes, you will get access to 4096 bytes.
  618.  
  619.  
  620. ΓòÉΓòÉΓòÉ 7.4. RxFreeMem - Free memory allocated by RxAllocMem ΓòÉΓòÉΓòÉ
  621.  
  622. This function allows a Rexx program to free memory allocated by RxAllocMem. 
  623.  
  624. Syntax:
  625.  
  626.   freerc = RxFreeMem(pointer)
  627.  
  628. where
  629.  
  630.   pointer - A valid 32 bit pointer.
  631.  
  632. Note:
  633.  
  634.   Returned value is return code from DosFreeMem
  635.  
  636.  
  637. ΓòÉΓòÉΓòÉ 7.5. RxAllocSharedMem - Allocate shared memory ΓòÉΓòÉΓòÉ
  638.  
  639. This function allocates shared (named or un-named) memory.  Other processes can 
  640. access this memory with either RxGetSharedMem (un-named), or 
  641. RxGetNamedSharedMem (named), or if it is "Given", followed by calls to 
  642. RxStorage. 
  643.  
  644. Syntax:
  645.  
  646.   allocrc = RxAllocSharedMem(rexxvar, length, flags [,memname] )
  647.  
  648. where
  649.  
  650.   rexxvar = name of a rexx variable in which pointer is returned
  651.   length  = a decimal integer indicating amount of storage (in bytes) to
  652.             allocate
  653.   flags   = any combination of:
  654.             C - Pag_Commit
  655.             T - Obj_Tile
  656.             I - Obj_Giveable
  657.             E - Obj_Gettable (sic)
  658.             X - Pag_Execute
  659.             R - Pag_Read
  660.             W - Pag_Write
  661.             G - Pag_Guard
  662.   memname = name of shared memory object, if this is to be named shared
  663.             memory
  664.   allocrc = return code from DosAllocSharedMem()
  665.  
  666. for example:
  667.  
  668.   /* To allocate an un-named, gettable object */
  669.   allocrc = RxAllocSharedMem('pointer', 4096, 'cerw')
  670.  
  671.   /* To allocate a named object */
  672.   allocrc = RxAllocSharedMem('pointer', 4096, 'crw','\SHAREMEM\TEST.MEM')
  673.  
  674. Note:
  675.  
  676.   All memory is allocated in 4k chunks.  Therefore, even if you allocate 200
  677.   bytes, you will get access to 4096 bytes.
  678.  
  679.  
  680. ΓòÉΓòÉΓòÉ 7.6. RxGiveSharedMem - Give access to shared memory ΓòÉΓòÉΓòÉ
  681.  
  682. This function gives access to shared, un-named memory to a process-id 
  683.  
  684. Syntax:
  685.  
  686.   giverc = RxGiveSharedMem(pointer, pid [,flags])
  687.  
  688. where
  689.  
  690.   pointer = valid 32-bit pointer
  691.   pid     = valid process-id (as a decimal integer)
  692.   flags   = any combination of:
  693.             X - Pag_Execute
  694.             R - Pag_Read
  695.             W - Pag_Write
  696.             G - Pag_Guard
  697.  
  698. for example:
  699.  
  700.   /* To give shared memory */
  701.   giverc = RxGiveSharedMem(pointer, 23, 'rw')
  702.  
  703. Note:
  704.  
  705.   A valid pointer must be supplied.  This is obtained from the process which
  706.   allocated the shared un-named memory via RxAllocSharedMem.  The process-id
  707.   supplied must be valid (i.e. must currently exist).
  708.  
  709.  
  710. ΓòÉΓòÉΓòÉ 7.7. RxGetSharedMem - Get access to shared memory ΓòÉΓòÉΓòÉ
  711.  
  712. This function gets access to shared, un-named, gettable memory. 
  713.  
  714. Syntax:
  715.  
  716.   getrc = RxGetSharedMem(pointer, flags)
  717.  
  718. where
  719.  
  720.   pointer = valid 32-bit pointer
  721.   flags   = any combination of:
  722.             X - Pag_Execute
  723.             R - Pag_Read
  724.             W - Pag_Write
  725.             G - Pag_Guard
  726.  
  727. for example:
  728.  
  729.   /* To get shared memory */
  730.   getrc = RxGetSharedMem(pointer, 'rw')
  731.  
  732. Note:
  733.  
  734.   A valid pointer must be supplied.  This is obtained from the process which
  735.   allocated the shared un-named memory via RxAllocSharedMem.
  736.  
  737.  
  738. ΓòÉΓòÉΓòÉ 7.8. RxGetNamedSharedMem - Get access to named shared memory ΓòÉΓòÉΓòÉ
  739.  
  740. This function gets access to shared, named memory. 
  741.  
  742. Syntax:
  743.  
  744.   getrc = RxGetNamedSharedMem(rexxvar, memname, flags)
  745.  
  746. where
  747.  
  748.   rexxvar = name of a rexx variable in which pointer is returned
  749.   memname = valid name of a shared memory object
  750.   flags   = any combination of:
  751.             X - Pag_Execute
  752.             R - Pag_Read
  753.             W - Pag_Write
  754.             G - Pag_Guard
  755.   getrc   = return code from DosGetNamedSharedMem()
  756.  
  757. for example:
  758.  
  759.   /* To get named shared memory */
  760.   getrc = RxGetNamedSharedMem('pointer', '\SHAREMEM\TEST.MEM', 'rw')
  761.  
  762.  
  763. ΓòÉΓòÉΓòÉ 7.9. RxSetMem - Set memory attributes ΓòÉΓòÉΓòÉ
  764.  
  765. This function sets memory attributes using DosSetMem 
  766.  
  767. Syntax:
  768.  
  769.   setrc = RxSetMem(pointer [,memsize [,flags]])
  770.  
  771. where
  772.  
  773.   pointer = valid 32-bit pointer
  774.   memsize = size of memory block to set
  775.   flags   = any combination of:
  776.             C - Pag_Commit
  777.             D - Pag_Decommit
  778.             F - Pag_Default
  779.             X - Pag_Execute
  780.             R - Pag_Read
  781.             W - Pag_Write
  782.             G - Pag_Guard
  783.  
  784. for example:
  785.  
  786.   /* To set memory attributes */
  787.   setrc = RxSetMem(pointer, 4096, 'crw')
  788.  
  789. Note:
  790.  
  791.   Returned value is return code from DosSetMem.
  792.  
  793.  
  794. ΓòÉΓòÉΓòÉ 7.10. RxQueryMem - Query memory attributes ΓòÉΓòÉΓòÉ
  795.  
  796. This function queries memory attributes using DosQueryMem 
  797.  
  798. Syntax:
  799.  
  800.   qinfo = RxQueryMem(pointer [,memsize])
  801.  
  802. where
  803.  
  804.   pointer = valid 32-bit pointer
  805.   memsize = size of memory block to query
  806.   qinfo   = either one or three blank-delimited tokens:
  807.             1) return code from DosQueryMem
  808.                If #1 is zero:
  809.                  2) actual memory size
  810.                  3) memory attribute flags, which can be any combination of:
  811.                     C - Pag_Commit
  812.                     F - Pag_Free
  813.                     S - Pag_Shared
  814.                     B - Pag_Base
  815.                     X - Pag_Execute
  816.                     R - Pag_Read
  817.                     W - Pag_Write
  818.                     G - Pag_Guard
  819.  
  820. for example:
  821.  
  822.   /* To query memory attributes */
  823.   qinfo = RxQueryMem(pointer, 4096)
  824.   /* "Say qinfo" might say -> "0 4096 CSRW" for instance */
  825.  
  826. Note:
  827.  
  828.   If first token is not zero, no other information was returned.
  829.  
  830.  
  831. ΓòÉΓòÉΓòÉ 7.11. RxSubSetMem - Set memory for suballocation ΓòÉΓòÉΓòÉ
  832.  
  833. This function sets memory for suballocation using DosSubSetMem 
  834.  
  835. Syntax:
  836.  
  837.   subsetrc = RxSubSetMem(pointer [,memsize [,flags]])
  838.  
  839. where
  840.  
  841.   pointer = valid 32-bit pointer to pool
  842.   memsize = size of memory block to subset
  843.   flags   = any combination of:
  844.             I - DosSub_Init
  845.             G - DosSub_Grow
  846.             S - DosSub_Sparse
  847.             R - DosSub_Serialize
  848.  
  849. for example:
  850.  
  851.   /* To subset some memory */
  852.   subsetrc = RxSubSetMem(pointer, 4096, 'i')
  853.  
  854. Note:
  855.  
  856.   Returned value is return code from DosSubSetMem.
  857.  
  858.  
  859. ΓòÉΓòÉΓòÉ 7.12. RxSubUnSetMem - UnSet memory from suballocation ΓòÉΓòÉΓòÉ
  860.  
  861. This function unsets memory from suballocation using DosSubUnSetMem 
  862.  
  863. Syntax:
  864.  
  865.   subunsetrc = RxSubUnSetMem(pointer)
  866.  
  867. where
  868.  
  869.   pointer = valid 32-bit pointer to pool
  870.  
  871. for example:
  872.  
  873.   /* To subunset some memory */
  874.   subunsetrc = RxSubUnSetMem(pointer)
  875.  
  876. Note:
  877.  
  878.   Returned value is return code from DosSubUnSetMem.
  879.  
  880.  
  881. ΓòÉΓòÉΓòÉ 7.13. RxSubAllocMem - Suballocate memory ΓòÉΓòÉΓòÉ
  882.  
  883. This function suballocates memory. 
  884.  
  885. Syntax:
  886.  
  887.   subarc = RxSubAllocMem(rexxvar, pointer [,memsize])
  888.  
  889. where
  890.  
  891.   rexxvar = name of a rexx variable in which block offset is returned
  892.   pointer = valid 32-bit pointer to pool
  893.   memsize = size of block to suballocate
  894.   subarc  = return code from DosSubAllocMem()
  895.  
  896. for example:
  897.  
  898.   /* To suballocate some memory */
  899.   subarc = RxSubAllocMem('block_offset', pointer, 4096)
  900.  
  901.  
  902. ΓòÉΓòÉΓòÉ 7.14. RxSubFreeMem - Free suballocated memory ΓòÉΓòÉΓòÉ
  903.  
  904. This function frees suballocated memory. 
  905.  
  906. Syntax:
  907.  
  908.   freerc = RxSubFreeMem(pointer, boffset [,memsize])
  909.  
  910. where
  911.  
  912.   pointer = valid 32-bit pointer to pool
  913.   boffset = block offset pointer
  914.   memsize = size of block to free
  915.  
  916. for example:
  917.  
  918.   /* To free suballocated memory */
  919.   freerc = RxSubFreeMem(pointer, boffset, 4096)
  920.  
  921. Note:
  922.  
  923.   Returned value is return code from DosSubFreeMem.
  924.  
  925.  
  926. ΓòÉΓòÉΓòÉ 8. Sempahore handling ΓòÉΓòÉΓòÉ
  927.  
  928. These functions allow Rexx programs to make use of OS/2 semaphores for 
  929. synchronization/serialization purposes. 
  930.  
  931.  
  932. ΓòÉΓòÉΓòÉ 8.1. RxCreateEventSem - Create an event semaphore ΓòÉΓòÉΓòÉ
  933.  
  934. This function creates a (named or un-named) event semaphore. 
  935.  
  936. Syntax:
  937.  
  938.   semrc = RxCreateEventSem(rexxvar [,type] [,name] [,state] )
  939.  
  940. where
  941.  
  942.   rexxvar = name of a rexx variable in which sem handle is returned
  943.   type    = 'Shared' or 'Private' (default is Private)
  944.   name    = semaphore name (default is un-named)
  945.   state   = 'Reset' or 'Posted' (default is Reset)
  946.   semrc   = return code from DosCreateEventSem()
  947.  
  948.  
  949. ΓòÉΓòÉΓòÉ 8.2. RxOpenEventSem - Open an event semaphore ΓòÉΓòÉΓòÉ
  950.  
  951. This function opens an event semaphore for use by a process that did not create 
  952. the semaphore. 
  953.  
  954. Syntax:
  955.  
  956.   semrc = RxOpenEventSem(rexxvar, semid)
  957.  
  958. where
  959.  
  960.   rexxvar = name of a rexx variable in which sem handle is returned
  961.   semid   = either a semaphore handle, or a semaphore name
  962.   semrc   = return code from DosOpenEventSem()
  963.  
  964. Note:
  965.  
  966.   A zero length string is returned if DosOpenEventSem fails.
  967.  
  968.  
  969. ΓòÉΓòÉΓòÉ 8.3. RxPostEventSem - Post an event semaphore ΓòÉΓòÉΓòÉ
  970.  
  971. This function posts an event semaphore. 
  972.  
  973. Syntax:
  974.  
  975.   postrc = RxPostEventSem(hev)
  976.  
  977. where
  978.  
  979.   hev    = semaphore handle
  980.   postrc = return code from DosPostEventSem
  981.  
  982.  
  983. ΓòÉΓòÉΓòÉ 8.4. RxQueryEventSem - Query an event semaphore ΓòÉΓòÉΓòÉ
  984.  
  985. This function returns the post count for an event semaphore. 
  986.  
  987. Syntax:
  988.  
  989.   info = RxQueryEventSem(hev)
  990.  
  991. where
  992.  
  993.   hev    = semaphore handle
  994.   info   = return code from DosQueryEventSem, followed by number of posts
  995. Note:
  996.  
  997.   Word 1 of info is the return code from DosQueryEventSem
  998.   Word 2 of info is the actual number of posts to the semaphore
  999.  
  1000.  
  1001. ΓòÉΓòÉΓòÉ 8.5. RxResetEventSem - Reset an event semaphore ΓòÉΓòÉΓòÉ
  1002.  
  1003. This function resets an event semaphore, returning the number of postings for 
  1004. that semaphore. 
  1005.  
  1006. Syntax:
  1007.  
  1008.   info = RxResetEventSem(hev)
  1009.  
  1010. where
  1011.  
  1012.   hev    = semaphore handle
  1013.   info   = return code from DosResetEventSem, followed by number of posts
  1014.  
  1015. Note:
  1016.  
  1017.   Word 1 of info is the return code from DosResetEventSem
  1018.   Word 2 of info is the actual number of posts to the semaphore before
  1019.                     the Reset.
  1020.  
  1021.  
  1022. ΓòÉΓòÉΓòÉ 8.6. RxWaitEventSem - Wait on an event semaphore ΓòÉΓòÉΓòÉ
  1023.  
  1024. This function waits on the posting of an event semaphore. 
  1025.  
  1026. Syntax:
  1027.  
  1028.   semhandle /* A valid semaphore handle */
  1029.   time = 1000   /* in milliseconds */
  1030.  
  1031.   waitrc = RxWaitEventSem(hev [,time])
  1032.  
  1033. where
  1034.  
  1035.   hev    = semaphore handle
  1036.   time   = number of miliseconds to wait before returning, or the word
  1037.            'Indefinite'.  Default is 'Indefinite'.
  1038.   waitrc = return code from DosWaitEventSem
  1039.  
  1040.  
  1041. ΓòÉΓòÉΓòÉ 8.7. RxCloseEventSem - Close an event semaphore ΓòÉΓòÉΓòÉ
  1042.  
  1043. This function closes an event semaphore 
  1044.  
  1045. Syntax:
  1046.  
  1047.   closerc = RxCloseEventSem(hev)
  1048.  
  1049. where
  1050.  
  1051.   hev     = semaphore handle
  1052.   closerc = return code from DosCloseEventSem
  1053.  
  1054.  
  1055. ΓòÉΓòÉΓòÉ 8.8. RxCreateMutexSem - Create a Mutex Semaphore ΓòÉΓòÉΓòÉ
  1056.  
  1057. This function creates a mutex semaphore 
  1058.  
  1059. Syntax:
  1060.  
  1061.   semrc = RxCreateMutexSem(rexxvar [,type] [,name] [,state] )
  1062.  
  1063. where
  1064.  
  1065.   rexxvar = name of a rexx variable in which sem handle is returned
  1066.   type    = 'Shared' or 'Private' (default is 'Private')
  1067.   name    = semaphore name (default is un-named)
  1068.   state   = 'Owned' or 'Unowned' (default is un-owned)
  1069.   semrc   = return code from DosCreateMutexSem()
  1070.  
  1071.  
  1072. ΓòÉΓòÉΓòÉ 8.9. RxOpenMutexSem - Open a Mutex Semaphore ΓòÉΓòÉΓòÉ
  1073.  
  1074. This function opens a mutex semaphore 
  1075.  
  1076. Syntax:
  1077.  
  1078.   semrc = RxOpenMutexSem(rexxvar, semid )
  1079.  
  1080. where
  1081.  
  1082.   rexxvar = name of a rexx variable in which sem handle is returned
  1083.   semid   = either a semaphore name, or an existing mutex semaphore handle
  1084.   semrc   = return code from DosOpenMutexSem()
  1085.  
  1086.  
  1087. ΓòÉΓòÉΓòÉ 8.10. RxCloseMutexSem - Close a Mutex Semaphore ΓòÉΓòÉΓòÉ
  1088.  
  1089. This function closes a mutex semaphore 
  1090.  
  1091. Syntax:
  1092.  
  1093.   mtxrc = RxCloseMutexSem( hmtx )
  1094.  
  1095. where
  1096.  
  1097.   hmtx  = existing mutex semaphore handle
  1098.   mtxrc = return code from DosCloseMutexSem
  1099.  
  1100.  
  1101. ΓòÉΓòÉΓòÉ 8.11. RxQueryMutexSem - Query Mutex Semaphore ΓòÉΓòÉΓòÉ
  1102.  
  1103. This function queries a mutex semaphore's attributes 
  1104.  
  1105. Syntax:
  1106.  
  1107.   mtxinfo = RxQueryMutexSem( hmtx )
  1108.  
  1109. where
  1110.  
  1111.   hmtx    = existing mutex semaphore handle
  1112.   mtxinfo = four blank delimited tokens:
  1113.             1) return code from DosQueryMutexSem
  1114.             2) Process-Id of semaphore's current owner
  1115.             3) Thread-Id of semaphore's current owner
  1116.             4) A count of the number of calls to DosRequestMutexSem,
  1117.                minus the number of calls to DosReleaseMutexSem, that have
  1118.                been made for the semaphore by the owning thread.
  1119.                If the semaphore is unowned, this value will be zero.
  1120.                If the owning thread has ended, the value will be the
  1121.                request count for the ended owner.
  1122.  
  1123.  
  1124. ΓòÉΓòÉΓòÉ 8.12. RxReleaseMutexSem - Release Mutex Semaphore ΓòÉΓòÉΓòÉ
  1125.  
  1126. This function releases a mutex semaphore 
  1127.  
  1128. Syntax:
  1129.  
  1130.   mtxrc = RxReleaseMutexSem( hmtx )
  1131.  
  1132. where
  1133.  
  1134.   hmtx  = existing mutex semaphore handle
  1135.   mtxrc = return code from DosReleaseMutexSem
  1136.  
  1137.  
  1138. ΓòÉΓòÉΓòÉ 8.13. RxRequestMutexSem - Request Mutex Semaphore ΓòÉΓòÉΓòÉ
  1139.  
  1140. This function requests a mutex semaphore 
  1141.  
  1142. Syntax:
  1143.  
  1144.   mtxrc = RxRequestMutexSem( hmtx [, timeout] )
  1145.  
  1146. where
  1147.  
  1148.   hmtx    = existing mutex semaphore handle
  1149.   timeout = either a decimal integer (miliseconds to block), or the word
  1150.             'Indefinite'
  1151.   mtxrc   = return code from DosRequestMutexSem
  1152.  
  1153.  
  1154. ΓòÉΓòÉΓòÉ 8.14. RxCreateMuxWaitSem - Create a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  1155.  
  1156. This function creates a muxwait semaphore 
  1157.  
  1158. Syntax:
  1159.  
  1160.   semrc = RxCreateMuxWaitSem(rexxvar, stemname [,type] [,anyall]
  1161.                              [,name] )
  1162.  
  1163. where
  1164.  
  1165.   rexxvar  = name of a rexx variable in which sem handle is returned
  1166.   stemname = a Rexx stem name (ending in a period '.'), under which are
  1167.              supplied the semaphore handles which constitute this muxwait
  1168.              semaphore.  The expected structure of the stem is:
  1169.              1) stem.0   = a decimal integer indicating how many semaphores
  1170.                            are supplied
  1171.              2) stem.n.1 = handle of Nth semaphore
  1172.              3) stem.n.2 = decimal integer used as an Id for Nth semaphore
  1173.   type     = 'Shared' or 'Private' (default is 'Private')
  1174.   anyall   = 'Any' or 'All' (default is 'All')
  1175.   name     = semaphore name (default is un-named)
  1176.   semrc    = return code from DosCreateMuxWaitSem()
  1177.  
  1178.  
  1179. ΓòÉΓòÉΓòÉ 8.15. RxOpenMuxWaitSem - Open a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  1180.  
  1181. This function opens a muxwait semaphore 
  1182.  
  1183. Syntax:
  1184.  
  1185.   semrc = RxOpenMuxWaitSem(rexxvar, semid )
  1186.  
  1187. where
  1188.  
  1189.   rexxvar = name of a rexx variable in which sem handle is returned
  1190.   semid   = either a semaphore name, or an existing muxwait
  1191.             semaphore handle
  1192.   semrc   = return code from DosOpenMuxWaitSem()
  1193.  
  1194.  
  1195. ΓòÉΓòÉΓòÉ 8.16. RxCloseMuxWaitSem - Close a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  1196.  
  1197. This function closes a muxwait semaphore 
  1198.  
  1199. Syntax:
  1200.  
  1201.   muxrc = RxCloseMuxWaitSem( hmux )
  1202.  
  1203. where
  1204.  
  1205.   hmux  = existing muxwait semaphore handle
  1206.   muxrc = return code from DosCloseMuxWaitSem
  1207.  
  1208.  
  1209. ΓòÉΓòÉΓòÉ 8.17. RxDeleteMuxWaitSem - Delete from a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  1210.  
  1211. This function deletes a semaphore from a muxwait semaphore list 
  1212.  
  1213. Syntax:
  1214.  
  1215.   muxrc = RxDeleteMuxWaitSem( hmux, hsem )
  1216.  
  1217. where
  1218.  
  1219.   hmux  = existing muxwait semaphore handle
  1220.   hsem  = handle of a semaphore in the muxwait semaphore list
  1221.   muxrc = return code from DosDeleteMuxWaitSem
  1222.  
  1223.  
  1224. ΓòÉΓòÉΓòÉ 8.18. RxAddMuxWaitSem - Add to a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  1225.  
  1226. This function adds a semaphore to a muxwait semaphore list 
  1227.  
  1228. Syntax:
  1229.  
  1230.   muxrc = RxAddMuxWaitSem( hmux, hsem, semid )
  1231.  
  1232. where
  1233.  
  1234.   hmux  = existing muxwait semaphore handle
  1235.   hsem  = handle of a semaphore to add to the muxwait semaphore list
  1236.   semid = decimal integer used as an Id for this semaphore
  1237.   muxrc = return code from DosAddMuxWaitSem
  1238.  
  1239.  
  1240. ΓòÉΓòÉΓòÉ 8.19. RxQueryMuxWaitSem - Query a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  1241.  
  1242. This function queries information about a muxwait semaphore 
  1243.  
  1244. Syntax:
  1245.  
  1246.   muxinfo = RxQueryMuxWaitSem( hmux, stemname )
  1247.  
  1248. where
  1249.  
  1250.   hmux     = existing muxwait semaphore handle
  1251.   stemname = a Rexx stem name (ending in a period '.'), under which is
  1252.              returned information about the muxwait semaphore.  The structure
  1253.              of the returned information is:
  1254.              1) stem.0   = a decimal integer indicating how many semaphores
  1255.                            are listed in this muxwait semaphore
  1256.              2) stem.n.1 = handle of Nth semaphore
  1257.              3) stem.n.2 = decimal integer Id of Nth semaphore
  1258.   muxinfo  = Two blank delimited tokens:
  1259.              1) return code from DosQueryMuxWaitSem
  1260.              2) a string of letters indicating this muxwait semaphore's
  1261.                 properties:
  1262.                 'S' if it's shared
  1263.                 'Y' if it's a wait ANY
  1264.                 'L' if it's a wait ALL
  1265.  
  1266.  
  1267. ΓòÉΓòÉΓòÉ 8.20. RxWaitMuxWaitSem - Wait on a MuxWait Semaphore ΓòÉΓòÉΓòÉ
  1268.  
  1269. This function waits on a muxwait semaphore 
  1270.  
  1271. Syntax:
  1272.  
  1273.   muxinfo = RxWaitMuxWaitSem( hmux [,timeout] )
  1274.  
  1275. where
  1276.  
  1277.   hmux     = existing muxwait semaphore handle
  1278.   timeout  = either a decimal integer (miliseconds to block), or the word
  1279.             'Indefinite'
  1280.   muxinfo  = Two blank delimited tokens:
  1281.              1) return code from DosQueryMuxWaitSem
  1282.              2) semaphore-id of releaser of muxwait sem (for more info,
  1283.                 see details of DosWaitMuxWaitSem)
  1284.  
  1285.  
  1286. ΓòÉΓòÉΓòÉ 9. Rexx Macro Space Functions ΓòÉΓòÉΓòÉ
  1287.  
  1288. These functions allow Rexx programs to query and alter the Rexx MacroSpace. 
  1289.  
  1290.  
  1291. ΓòÉΓòÉΓòÉ 9.1. RxAddMacro - Add Entry to MacroSpace ΓòÉΓòÉΓòÉ
  1292.  
  1293. This function adds a Rexx program to the macrospace. 
  1294.  
  1295. Syntax:
  1296.  
  1297.   addrc = RxAddMacro(funcname, sourcefile [,order])
  1298.  
  1299. where
  1300.  
  1301.   funcname   = name for function in macrospace
  1302.   sourcefile = name of source file where Rexx source code exists
  1303.   order      = order in macrospace (Before or After)
  1304.  
  1305. Note:
  1306.  
  1307.   Returned value is return code from RexxAddMacro.
  1308.  
  1309.  
  1310. ΓòÉΓòÉΓòÉ 9.2. RxDropMacro - Drop Entry from MacroSpace ΓòÉΓòÉΓòÉ
  1311.  
  1312. This function drops a function from the macrospace. 
  1313.  
  1314. Syntax:
  1315.  
  1316.   droprc = RxDropMacro(funcname)
  1317.  
  1318. where
  1319.  
  1320.   funcname   = name of function in macrospace
  1321.  
  1322. Note:
  1323.  
  1324.   Returned value is return code from RexxDropMacro.
  1325.  
  1326.  
  1327. ΓòÉΓòÉΓòÉ 9.3. RxClearMacroSpace - Clear Entire MacroSpace ΓòÉΓòÉΓòÉ
  1328.  
  1329. This function clears all functions from the macro space.  Be careful when using 
  1330. this as it will affect all processes in the system. 
  1331.  
  1332. Syntax:
  1333.  
  1334.   clear_rc = RxClearMacroSpace()
  1335.  
  1336. Note:
  1337.  
  1338.   Returned value is return code from RexxClearMacroSpace.
  1339.  
  1340.  
  1341. ΓòÉΓòÉΓòÉ 9.4. RxSaveMacroSpace - Save Macro to File ΓòÉΓòÉΓòÉ
  1342.  
  1343. This function saves a macrospace function to a file. 
  1344.  
  1345. Syntax:
  1346.  
  1347.   saverc = RxSaveMacroSpace(funcname, macfile)
  1348.  
  1349. where
  1350.  
  1351.   funcname = name of function in macrospace
  1352.   macfile  = name of file in which to save macro
  1353.  
  1354. Note:
  1355.  
  1356.   Returned value is return code from RexxSaveMacroSpace.
  1357.  
  1358.  
  1359. ΓòÉΓòÉΓòÉ 9.5. RxLoadMacroSpace - Load a Macro from File ΓòÉΓòÉΓòÉ
  1360.  
  1361. This function loads a macrospace function from a file. 
  1362.  
  1363. Syntax:
  1364.  
  1365.   loadrc = RxLoadMacroSpace(funcname, macfile)
  1366.  
  1367. where
  1368.  
  1369.   funcname = name of function in macrospace
  1370.   macfile  = name of file in which to save macro
  1371.  
  1372. Note:
  1373.  
  1374.   Returned value is return code from RexxLoadMacroSpace.
  1375.  
  1376.  
  1377. ΓòÉΓòÉΓòÉ 9.6. RxQueryMacro - Query MacroSpace ΓòÉΓòÉΓòÉ
  1378.  
  1379. This function queries the existence/position of a macro in the macrospace. 
  1380.  
  1381. Syntax:
  1382.  
  1383.   qinfo = RxQueryMacro(funcname)
  1384.  
  1385. where
  1386.  
  1387.   funcname = name of function in macrospace
  1388.   qinfo    = blank-delimited tokens:
  1389.              1) return code from RexxQueryMacro
  1390.                 If #1 is zero, then:
  1391.                 2) Before/After/?
  1392.  
  1393. Note:
  1394.  
  1395.   If first token is not zero, no other information was returned.
  1396.  
  1397.  
  1398. ΓòÉΓòÉΓòÉ 9.7. RxReorderMacro - Reorder Macro Position ΓòÉΓòÉΓòÉ
  1399.  
  1400. This function reorders the position of a macro within the macrospace. 
  1401.  
  1402. Syntax:
  1403.  
  1404.   reorderrc = RxReorderMacro(funcname, position)
  1405.  
  1406. where
  1407.  
  1408.   funcname = name of function in macrospace
  1409.   position = relative position in macrospace (Before/After)
  1410.  
  1411. Note:
  1412.  
  1413.   Returned value is return code from RexxReorderMacro
  1414.  
  1415.  
  1416. ΓòÉΓòÉΓòÉ 10. Threads, Tasking, etc. ΓòÉΓòÉΓòÉ
  1417.  
  1418. These functions allow a Rexx program to start and control new threads and 
  1419. processes. 
  1420.  
  1421.  
  1422. ΓòÉΓòÉΓòÉ 10.1. RxExecPgm - Execute a program ΓòÉΓòÉΓòÉ
  1423.  
  1424. This function starts another program in the same session. 
  1425.  
  1426. Syntax:
  1427.  
  1428.   exrc = RxExecPgm(pgmname [, mode [,argstring]])
  1429.  
  1430. where
  1431.  
  1432.   pgmname   = name of .EXE file to execute
  1433.   mode      = 'S'ync, 'A'sync, async'R'esult, 'T'race, 'B'ackground, 'L'oad,
  1434.               asyncresult'D'b.
  1435.               Default is 'S'ync.
  1436.   argstring = arg string to pass to program
  1437.   exrc      = three blank-delimited tokens:
  1438.               1) return code from DosExecPgm
  1439.               2) termination code / process-id (for asynchronous)
  1440.               3) new program's return code
  1441.  
  1442.  
  1443. ΓòÉΓòÉΓòÉ 10.2. RxStartSession - Start Another Session ΓòÉΓòÉΓòÉ
  1444.  
  1445. This function starts a program in another OS/2 session. 
  1446.  
  1447. Syntax:
  1448.  
  1449.   strc = RxStartSession(pgmname [,args [,related [,fgbg [,title [,type
  1450.                         [,ctrl] ] ] ] ] ])
  1451.  
  1452. where
  1453.  
  1454.   pgmname   = name of .EXE file to execute
  1455.   args      = arg string to pass to program
  1456.   related   = Relation of started session to this session, can be:
  1457.               'I'ndependent or 'C'hild
  1458.   fgbg      = Foreground/Background option, can be:
  1459.               'F'oreground or 'B'ackground
  1460.   title     = Session title (defaults to program name)
  1461.   type      = Program type, can be:
  1462.               'D'efault, 'F'ullscreen, 'P'M, 'V'irtual-Dos,
  1463.               'W'indowed-Virtual-Dos, vi'O'-windowable
  1464.   ctrl      = Program control, can be:
  1465.               'V'isible, 'I'nvisible, ma'X'imized, mi'N'imized,
  1466.               no'A'utoclose
  1467.   strc      = if DosStartSession failed:
  1468.               - return code from DosStartSession followed by error info
  1469.               if DosStartSession got zero rc:
  1470.               - return code from DosStartSession Session-ID Process-ID
  1471.  
  1472.  
  1473. ΓòÉΓòÉΓòÉ 10.3. RxStartRexxSession - Start a Rexx program on another session ΓòÉΓòÉΓòÉ
  1474.  
  1475. This function starts a Rexx program in another OS/2 session. (The program 
  1476. "RXSRS.EXE" must be in your path in order to use this function) 
  1477.  
  1478. Syntax:
  1479.  
  1480.   strc = RxStartRexxSession(execname [,arg1] [,arg2] ... [,argn])
  1481.  
  1482. where
  1483.  
  1484.   execname = name of Rexx program to execute
  1485.                    or
  1486.              a '$' immediately preceding a source program string
  1487.                    or
  1488.              a '&' immediately preceding a tokenized program string
  1489.              (for more info about these, see "RxCallInStore" and
  1490.               "RxTokenize")
  1491.   arg1     = arguments 1-n for target Rexx program
  1492.   ...
  1493.   argn
  1494.   strc     = if DosStartSession failed:
  1495.              - return code from DosStartSession followed by error info
  1496.              if DosStartSession worked:
  1497.              - return code from DosStartSession Session-ID Process-ID
  1498.  
  1499.  
  1500. ΓòÉΓòÉΓòÉ 10.4. RxDetachRexxPgm - Detach a Rexx program ΓòÉΓòÉΓòÉ
  1501.  
  1502. This function starts a Rexx program in the detached OS/2 session. (The program 
  1503. "RXSRS.EXE" must be in your path in order to use this function) 
  1504.  
  1505. Syntax:
  1506.  
  1507.   dtrc = RxDetachRexxPgm(execname [,arg1] [,arg2] ... [,argn])
  1508.  
  1509. where
  1510.  
  1511.   execname = name of Rexx program to execute
  1512.                    or
  1513.              a '$' immediately preceding a source program string
  1514.                    or
  1515.              a '&' immediately preceding a tokenized program string
  1516.              (for more info about these, see "RxCallInStore" and
  1517.               "RxTokenize")
  1518.   arg1     = arguments 1-n for target Rexx program
  1519.   ...
  1520.   argn
  1521.   dtrc     = if DosExecPgm failed:
  1522.              - return code from DosExecPgm, followed by error info
  1523.              if DosExecPgm worked:
  1524.              - return code from DosExecPgm "codeTerminate" and "codeResult"
  1525.  
  1526.  
  1527. ΓòÉΓòÉΓòÉ 10.5. RxKillProcess - Kill an OS/2 Process ΓòÉΓòÉΓòÉ
  1528.  
  1529. This function kills an OS/2 process by process-id. 
  1530.  
  1531. Syntax:
  1532.  
  1533.   killrc = RxKillProcess(pid [, action])
  1534.  
  1535. where
  1536.  
  1537.   pid    = process-id (decimal integer)
  1538.   action = 'Process' or 'Tree' (default is 'Process')
  1539.   killrc = return code from DosKillProcess
  1540.  
  1541.  
  1542. ΓòÉΓòÉΓòÉ 10.6. RxCreateThread - Start new thread ΓòÉΓòÉΓòÉ
  1543.  
  1544. This function starts execution at a supplied entry point on a new thread. The 
  1545. entry point is any valid procedure address (e.g. obtained by a call to 
  1546. RxQueryProcAddr, etc.). 
  1547.  
  1548. Syntax:
  1549.  
  1550.   tid = RxCreateThread(procaddr [, dataptr [, linktype [, stacksize
  1551.                                 [, threadflag]]]])
  1552.  
  1553. where
  1554.  
  1555.   procaddr     = Procedure Address
  1556.   dataptr      = pointer to arguments
  1557.   linktype     = 'System' or 'Optlink'
  1558.                  If linktype is 'System', then args 4 and 5 are:
  1559.     stacksize  = stacksize for thread (default is 8192)
  1560.     threadflag = 'Immediate' or 'Suspend'
  1561.   tid          = thread-id of new thread
  1562.  
  1563. Note:
  1564.   Pointer to arguments is optional, but if supplied must be a valid pointer.
  1565.  
  1566.  
  1567. ΓòÉΓòÉΓòÉ 10.7. RxKillThread - Kill a thread ΓòÉΓòÉΓòÉ
  1568.  
  1569. This function kills a thread by thread-id. 
  1570.  
  1571. Syntax:
  1572.  
  1573.   killrc = RxKillThread(tid)
  1574.  
  1575. where
  1576.  
  1577.   tid    = thread-id
  1578.   killrc = return code from DosKillThread
  1579.  
  1580.  
  1581. ΓòÉΓòÉΓòÉ 10.8. RxSetPriority - Set the priority of processes or threads ΓòÉΓòÉΓòÉ
  1582.  
  1583. This function sets the priority of one or more process and/or threads. 
  1584.  
  1585. Syntax:
  1586.  
  1587.   setrc = RxSetPriority(scope,class,delta,id)
  1588.  
  1589. where
  1590.  
  1591.   scope = 'P'rocess (default)
  1592.           t'R'ee
  1593.           'T'hread
  1594.   class = 'N'ochange (default)
  1595.           'I'dletime
  1596.           'R'egular
  1597.           'T'imecritical
  1598.           foreground'S'erver
  1599.   delta = any integer from -31 to +31, or ma'X'imum, or mi'N'imum
  1600.   id    = a Process-Id, Thread-Id, or nothing, depending on value
  1601.           of "scope"
  1602.   setrc = return code from DosSetPriority
  1603.  
  1604.  
  1605. ΓòÉΓòÉΓòÉ 10.9. RxResumeThread - Resume thread execution ΓòÉΓòÉΓòÉ
  1606.  
  1607. This function causes a thread to resume execution 
  1608.  
  1609. Syntax:
  1610.  
  1611.   resrc = RxResumeThread(tid)
  1612.  
  1613. where
  1614.  
  1615.   tid   = thread-id
  1616.   resrc = return code from DosResumeThread
  1617.  
  1618.  
  1619. ΓòÉΓòÉΓòÉ 10.10. RxSuspendThread - Suspend thread execution ΓòÉΓòÉΓòÉ
  1620.  
  1621. This function causes a thread to suspend execution 
  1622.  
  1623. Syntax:
  1624.  
  1625.   susrc = RxSuspendThread(tid)
  1626.  
  1627. where
  1628.  
  1629.   tid   = thread-id
  1630.   susrc = return code from DosSuspendThread
  1631.  
  1632.  
  1633. ΓòÉΓòÉΓòÉ 10.11. RxCreateRexxThread - Rexx on another thread ΓòÉΓòÉΓòÉ
  1634.  
  1635. This function executes a Rexx program on another thread of the same process. 
  1636. The started Rexx program has a separate variable pool, and maintains its own 
  1637. "current Rexx queue", indpendently of the starting Rexx program.  But all other 
  1638. features of multi-threaded applications apply (i.e. shared file handles, etc.) 
  1639.  
  1640. Syntax:
  1641.  
  1642.   tid = RxCreateRexxThread(execname [,arg1 [,arg2 [, ...]]])
  1643.  
  1644. where
  1645.  
  1646.   execname = name of Rexx program to execute
  1647.                    or
  1648.              a '$' immediately preceding a source program string
  1649.                    or
  1650.              a '&' immediately preceding a tokenized program string
  1651.              (for more info about these, see "RxCallInStore" and
  1652.               "RxTokenize")
  1653.   arg1     = arguments to Rexx program (up to 19 possible)
  1654.   arg2
  1655.   ...
  1656.   tid      = Thread-Id of new thread
  1657.  
  1658. Note:
  1659.  
  1660.   Example of executing a program string:
  1661.  
  1662.     crlf = '0d0a'x
  1663.     str = '/* Rexx */'crlf
  1664.     str = str 'Do i=1 To Arg()'crlf
  1665.     str = str '  Say "Arg#"i "= {"arg(i)"}"'crlf
  1666.     str = str 'End'crlf
  1667.     str = str||'1a'x       /* EOF marker */
  1668.     call rxcreaterexxthread '$'str, date(), time()
  1669.  
  1670.  
  1671. ΓòÉΓòÉΓòÉ 11. NETBIOS information ΓòÉΓòÉΓòÉ
  1672.  
  1673. These functions allow a Rexx program to access certain NETBIOS information. 
  1674.  
  1675.  
  1676. ΓòÉΓòÉΓòÉ 11.1. RxNbSessionStatus - NetBios Session Status ΓòÉΓòÉΓòÉ
  1677.  
  1678. This function gets NetBios session status information. 
  1679.  
  1680. Syntax:
  1681.  
  1682.   nbname = 'S$SQLDBSERVR1#DB'
  1683.  
  1684.   nbrc =  RxNbSessionStatus(nbname,'s.','r')
  1685.  
  1686. Note:
  1687.  
  1688.   Return code is from NETBIOS api.  Second argument is name of a Rexx stem
  1689.   variable under which results are returned as such:
  1690.  
  1691.     stem.0 = number of sessions reported on
  1692.       stem.n.1 = Local session number
  1693.       stem.n.2 = Session state
  1694.       stem.n.3 = Local name
  1695.       stem.n.4 = Remote name
  1696.       stem.n.5 = Number of receive commands pending
  1697.       stem.n.6 = Number of send commands pending
  1698.  
  1699.   Third argument may be supplied to have a NETBIOS "Reset" done before and
  1700.   after obtaining session status.
  1701.  
  1702.  
  1703. ΓòÉΓòÉΓòÉ 12. DLL Handling ΓòÉΓòÉΓòÉ
  1704.  
  1705. These functions allow a Rexx program to load and execute procedures with- in 
  1706. DLL's.  Also, certain information about DLL's can be obtained. 
  1707.  
  1708.  
  1709. ΓòÉΓòÉΓòÉ 12.1. RxLoadModule - Load a DLL ΓòÉΓòÉΓòÉ
  1710.  
  1711. This function loads a DLL, returning a module handle (or an error code). 
  1712.  
  1713. Syntax:
  1714.  
  1715.   dosrc = RxLoadModule(rexxvar, dllname)
  1716.  
  1717. where:
  1718.  
  1719.   rexxvar = name of rexx variable in which module handle is returned
  1720.   dllname = name of DLL to load
  1721.   dosrc   = return code from DosLoadModule
  1722.  
  1723.  
  1724. ΓòÉΓòÉΓòÉ 12.2. RxFreeModule - Free a DLL ΓòÉΓòÉΓòÉ
  1725.  
  1726. This function frees the DLL whose module handle is supplied. 
  1727.  
  1728. Syntax:
  1729.  
  1730.   dosrc = RxFreeModule(hmod)
  1731.  
  1732. where:
  1733.  
  1734.   hmod    = module handle
  1735.   dosrc   = return code from DosFreeModule
  1736.  
  1737.  
  1738. ΓòÉΓòÉΓòÉ 12.3. RxQueryModuleName - Get Module Name ΓòÉΓòÉΓòÉ
  1739.  
  1740. This function returns the name of a module, given the module handle. 
  1741.  
  1742. Syntax:
  1743.  
  1744.   dosrc = RxQueryModuleName(rexxvar,hmod)
  1745.  
  1746. where:
  1747.  
  1748.   rexxvar = name of rexx variable in which module name is returned
  1749.   hmod    = module handle of DLL
  1750.   dosrc   = return code from DosQueryModuleName
  1751.  
  1752.  
  1753. ΓòÉΓòÉΓòÉ 12.4. RxQueryModuleHandle - Get Module Handle ΓòÉΓòÉΓòÉ
  1754.  
  1755. This function returns the handle of a module, given the module's name. 
  1756.  
  1757. Syntax:
  1758.  
  1759.   dosrc = RxQueryModuleHandle(rexxvar,modname)
  1760.  
  1761. where:
  1762.  
  1763.   rexxvar = name of rexx variable in which module handle is returned
  1764.   modname = name of DLL
  1765.   dosrc   = return code from DosQueryModuleHandle
  1766.  
  1767.  
  1768. ΓòÉΓòÉΓòÉ 12.5. RxQueryProcType - Query Procedure Type ΓòÉΓòÉΓòÉ
  1769.  
  1770. This function returns the addressing mode (16/32 bit) of a procedure of a DLL. 
  1771. The procedure can be identified either by name, or ordinal number. 
  1772.  
  1773. Syntax:
  1774.  
  1775.   entryname = 'SQLEXEC'
  1776.   ordinal = 3
  1777.  
  1778.   procinfo = RxQueryProcType(hmod,procid)
  1779.   amode = RxQueryProcType(hmod,entryname)
  1780.  
  1781. where:
  1782.  
  1783.   hmod     = module handle
  1784.   procid   = procedure-id (either an ordinal, or a procedure name)
  1785.   procinfo = Two blank-delimited tokens:
  1786.              1) return code from DosQueryProcType
  1787.              2) either "16" or "32", indicating 16 or 32 bit
  1788.  
  1789.  
  1790. ΓòÉΓòÉΓòÉ 12.6. RxQueryProcAddr - Query Procedure Address ΓòÉΓòÉΓòÉ
  1791.  
  1792. This function returns the address of an entry point in a DLL.  This entry point 
  1793. can then be used in RxCallEntryPoint to call an entry point in a Loaded DLL. 
  1794.  
  1795. Syntax:
  1796.  
  1797.   entryname = 'SQLEXEC' /* Entry name */
  1798.               3         /* Entry ordinal */
  1799.  
  1800.   dosrc = RxQueryProcAddr(rexxvar,hmod,procid)
  1801.  
  1802. where:
  1803.  
  1804.   rexxvar = name of rexx variable in which procedure address is returned
  1805.   hmod    = module handle of DLL
  1806.   procid  = procedure-id (either an ordinal, or a procedure name)
  1807.  
  1808.  
  1809. ΓòÉΓòÉΓòÉ 12.7. RxCallEntryPoint - Call an entry point ΓòÉΓòÉΓòÉ
  1810.  
  1811. This function "calls" the code which begins at the ProcAddress supplied. This 
  1812. ProcAddress could be the address obtained by RxQueryProcAddr for the entry 
  1813. point of a DLL.  But, it can be any "legal" entry point address of any routine. 
  1814.  
  1815. Syntax:
  1816.  
  1817.   procrc = RxCallEntryPoint(procaddr [,arg1 [, arg2 [,...]]] )
  1818.  
  1819. where
  1820.  
  1821.   procaddr = proc-address (could be obtained from RxQueryProcAddr, etc.)
  1822.   parg1
  1823.   ...
  1824.   parg19   = up to 19 arguments.  If an argument is a valid pointer, the
  1825.              pointer will be passed.  If not, a copy of the argument's value
  1826.              will be passed by reference.  Either way, the procedure must be
  1827.              expecting a pointer for each argument.
  1828.   procrc   = return code from the procedure
  1829.  
  1830. Note:
  1831.   Linkage to the proc-address is type _System.
  1832.  
  1833.  
  1834. ΓòÉΓòÉΓòÉ 13. OS/2 Pipes ΓòÉΓòÉΓòÉ
  1835.  
  1836. An assortment of OS/2 pipe-related functions (not complete). 
  1837.  
  1838.  
  1839. ΓòÉΓòÉΓòÉ 13.1. RxCreateNPipe - Create a named pipe ΓòÉΓòÉΓòÉ
  1840.  
  1841. This function creates an OS/2 named pipe. 
  1842.  
  1843. Syntax:
  1844.  
  1845.   dosrc = RxCreateNPipe( rexxvar, pipename, openmode, pipemode,
  1846.                          instance_count, outbufsize, inbufsize,
  1847.                          timeout)
  1848.  
  1849. where
  1850.  
  1851.    rexxvar  = name of Rexx variable into which read/write handle is placed
  1852.    pipename = name of pipe
  1853.  
  1854.    OpenMode Values
  1855.      W    = WriteBehind
  1856.      w    = NoWriteBehind
  1857.      I    = Inherit
  1858.      i    = NoInherit
  1859.      N(n) = Access Inbound
  1860.      O(o) = Access Outbound
  1861.      D(d) = Access Duplex
  1862.  
  1863.    PipeMode Values
  1864.      W    = Wait
  1865.      w    = NoWait
  1866.      T    = Pipe Type "Byte"
  1867.      t    = Pipe Type "Message"
  1868.      R    = Readmode "Byte"
  1869.      r    = Readmode "Message"
  1870.  
  1871.    Instance_Count
  1872.      Integer
  1873.  
  1874.    Outbuf Size
  1875.      Integer
  1876.  
  1877.    Inbuf Size
  1878.      Integer
  1879.  
  1880.    Timeout
  1881.      Integer
  1882.  
  1883.   dosrc   = return code from DosCreateNPipe()
  1884.  
  1885.  
  1886. ΓòÉΓòÉΓòÉ 13.2. RxConnectNPipe - Connect to a named pipe ΓòÉΓòÉΓòÉ
  1887.  
  1888. This function connects to a named pipe 
  1889.  
  1890. Syntax:
  1891.  
  1892.   dosrc = RxConnectNPipe(hpipe)
  1893.  
  1894. where
  1895.  
  1896.    hpipe  = pipe handle
  1897.    dosrc  = return code from DosConnectNPipe()
  1898.  
  1899.  
  1900. ΓòÉΓòÉΓòÉ 13.3. RxDisConnectNPipe - Disconnect from a named pipe ΓòÉΓòÉΓòÉ
  1901.  
  1902. This function disconnects from a named pipe 
  1903.  
  1904. Syntax:
  1905.  
  1906.   dosrc = RxDisConnectNPipe(hpipe)
  1907.  
  1908. where
  1909.  
  1910.    hpipe  = pipe handle
  1911.    dosrc  = return code from DosDisConnectNPipe()
  1912.  
  1913.  
  1914. ΓòÉΓòÉΓòÉ 13.4. RxCreatePipe - Create an un-named pipe ΓòÉΓòÉΓòÉ
  1915.  
  1916. This function creates an OS/2 un-named pipe 
  1917.  
  1918. Syntax:
  1919.  
  1920.   dosrc = RxCreatePipe(rexxstem [,pipesize])
  1921.  
  1922. where
  1923.  
  1924.    rexxstem = name of Rexx stem variable under which read handle,
  1925.               write handle, and pipe size are returned as such:
  1926.               stem.1 = read handle
  1927.               stem.2 = write handle
  1928.               stem.3 = pipe size
  1929.    dosrc  = return code from DosCreatePipe()
  1930.  
  1931.  
  1932. ΓòÉΓòÉΓòÉ 13.5. RxDestroyPipe - Destroy an un-named pipe ΓòÉΓòÉΓòÉ
  1933.  
  1934. This function destroys an OS/2 un-named pipe 
  1935.  
  1936. Syntax:
  1937.  
  1938.   dosrc = RxDestroyPipe(hread,hwrite)
  1939.  
  1940. where
  1941.  
  1942.    hread  = read handle
  1943.    hwrite = write handle
  1944.    dosrc  = return codes from DosClose()
  1945.  
  1946.  
  1947. ΓòÉΓòÉΓòÉ 14. OS/2 Queues ΓòÉΓòÉΓòÉ
  1948.  
  1949. Most of the OS/2 queue APIs are implemented here. 
  1950.  
  1951.  
  1952. ΓòÉΓòÉΓòÉ 14.1. RxCreateQueue - Create an OS/2 queue. ΓòÉΓòÉΓòÉ
  1953.  
  1954. This function creates an OS/2 queue. 
  1955.  
  1956. Syntax:
  1957.  
  1958.   dosrc = RxCreateQueue(rexxvar, qname, qflags)
  1959.  
  1960. where
  1961.  
  1962.    rexxvar  = name of Rexx variable into which queue handle is placed
  1963.    qname    = name of OS/2 queue
  1964.    qflags   = flags for queue creation:
  1965.               F - Fifo
  1966.               L - Lifo
  1967.               P - Priority
  1968.               C - Convert Address
  1969.               N - No-convert Address
  1970.   dosrc   = return code from DosCreateQueue()
  1971.  
  1972.  
  1973. ΓòÉΓòÉΓòÉ 14.2. RxOpenQueue - Open an OS/2 queue ΓòÉΓòÉΓòÉ
  1974.  
  1975. This function opens an OS/2 queue 
  1976.  
  1977. Syntax:
  1978.  
  1979.   dosrc = RxOpenQueue(rexxstem,qname)
  1980.  
  1981. where
  1982.  
  1983.    rexxstem = name of Rexx stem, under which info is returned:
  1984.               stem.1 = queue-owner-pid (integer)
  1985.               stem.2 = queue handle
  1986.    qname    = name of queue to open
  1987.    dosrc    = return code from DosOpenQueue()
  1988.  
  1989.  
  1990. ΓòÉΓòÉΓòÉ 14.3. RxPeekQueue - Peek at an OS/2 queue ΓòÉΓòÉΓòÉ
  1991.  
  1992. This function peeks at an OS/2 queue without reading it 
  1993.  
  1994. Syntax:
  1995.  
  1996.   dosrc = RxPeekQueue(rexxstem,qhandle,elemcode,waitcode,semhandle)
  1997.  
  1998. where
  1999.  
  2000.    rexxstem  = name of Rexx stem, under which info is returned:
  2001.                stem.1 = data pointer (e.g. for use with RxStorage)
  2002.                stem.2 = data length (of that pointed to by stem.1)
  2003.                stem.3 = PID of process which enqueued element
  2004.                stem.4 = event code (RequestData.ulData)
  2005.                stem.5 = element code
  2006.                stem.6 = element priority
  2007.    qhandle   = handle to queue
  2008.    elemcode  = element code (integer)
  2009.    waitcode  = whether to wait for data in queue
  2010.                W = Wait
  2011.                N = Nowait
  2012.    semhandle = handle of semaphore
  2013.    dosrc     = return code from DosPeekQueue()
  2014.  
  2015.  
  2016. ΓòÉΓòÉΓòÉ 14.4. RxReadQueue - Read an OS/2 queue ΓòÉΓòÉΓòÉ
  2017.  
  2018. This function reads an element off an OS/2 
  2019.  
  2020. Syntax:
  2021.  
  2022.   dosrc = RxReadQueue(rexxstem,qhandle,elemcode,waitcode,semhandle)
  2023.  
  2024. where
  2025.  
  2026.    rexxstem  = name of Rexx stem, under which info is returned:
  2027.                stem.1 = data pointer (e.g. for use with RxStorage)
  2028.                stem.2 = data length (of that pointed to by stem.1)
  2029.                stem.3 = PID of process which enqueued element
  2030.                stem.4 = event code (RequestData.ulData)
  2031.                stem.5 = element priority
  2032.    qhandle   = handle to queue
  2033.    elemcode  = element code (integer)
  2034.    waitcode  = whether to wait for data in queue
  2035.                W = Wait
  2036.                N = Nowait
  2037.    semhandle = handle of semaphore
  2038.    dosrc     = return code from DosReadQueue()
  2039.  
  2040.  
  2041. ΓòÉΓòÉΓòÉ 14.5. RxWriteQueue - Write to an OS/2 queue ΓòÉΓòÉΓòÉ
  2042.  
  2043. This function writes an element to an OS/2 
  2044.  
  2045. Syntax:
  2046.  
  2047.   dosrc = RxWriteQueue(qhandle,pointer,length,reqdata,elemprty)
  2048.  
  2049. where
  2050.  
  2051.    qhandle   = handle to queue
  2052.    pointer   = whatever 32 bits you want to put on queue
  2053.    length    = integer length associated with "pointer"
  2054.    reqdata   = integer request data
  2055.    elemprtry = element priority, if this is a priority queue
  2056.    dosrc     = return code from DosWriteQueue()
  2057.  
  2058.  
  2059. ΓòÉΓòÉΓòÉ 14.6. RxPurgeQueue - Purge elements from OS/2 queue ΓòÉΓòÉΓòÉ
  2060.  
  2061. This function purges elements from an OS/2 queue 
  2062.  
  2063. Syntax:
  2064.  
  2065.   dosrc = RxPurgeQueue(qhandle)
  2066.  
  2067. where
  2068.  
  2069.    qhandle   = handle to queue
  2070.    dosrc     = return code from DosPurgeQueue()
  2071.  
  2072.  
  2073. ΓòÉΓòÉΓòÉ 14.7. RxQueryQueue - Query info about OS/2 queue ΓòÉΓòÉΓòÉ
  2074.  
  2075. This function returns information about an OS/2 queue 
  2076.  
  2077. Syntax:
  2078.  
  2079.   info = RxQueryQueue(qhandle)
  2080.  
  2081. where
  2082.  
  2083.    qhandle   = handle to queue
  2084.    info      = two blank delimited tokens:
  2085.                1) return code from DosQueryQueue()
  2086.                2) number of elements on queue (if (1) is zero)
  2087.  
  2088.  
  2089. ΓòÉΓòÉΓòÉ 14.8. RxCloseQueue - Close an OS/2 queue ΓòÉΓòÉΓòÉ
  2090.  
  2091. This function closes an OS/2 queue 
  2092.  
  2093. Syntax:
  2094.  
  2095.   dosrc = RxCloseQueue(qhandle)
  2096.  
  2097. where
  2098.  
  2099.    qhandle   = handle to queue
  2100.    dosrc     = return code from DosCloseQueue()
  2101.  
  2102.  
  2103. ΓòÉΓòÉΓòÉ 14.9. RxReadQueueStr - Read data from OS/2 queue ΓòÉΓòÉΓòÉ
  2104.  
  2105. This function returns the de-referenced contents of an OS/2 queue element. 
  2106. That is, it dequeues an element and returns the data pointed to by the dequeued 
  2107. element as the function result.  It first does a DosOpenQueue, then a 
  2108. DosReadQueue(wait), but does NOT do a DosCloseQueue. 
  2109.  
  2110. Syntax:
  2111.  
  2112.   datastr = RxReadQueueStr(qname)
  2113.  
  2114. where
  2115.  
  2116.    qname     = name of queue to read
  2117.    datastr   = data pointed to by dequeued pointer
  2118.  
  2119.  
  2120. ΓòÉΓòÉΓòÉ 15. I/O Related ΓòÉΓòÉΓòÉ
  2121.  
  2122. Miscellaneous functions related to I/O operations. 
  2123.  
  2124.  
  2125. ΓòÉΓòÉΓòÉ 15.1. RxRead - Read from File Handle ΓòÉΓòÉΓòÉ
  2126.  
  2127. This function reads a character stream in from a file handle, rather than from 
  2128. a file name. 
  2129.  
  2130. Syntax:
  2131.  
  2132.   dosrc = RxRead( rexxvar, hfile [,length] )
  2133.  
  2134. where
  2135.  
  2136.   rexxvar = name of Rexx variable into which read data is placed
  2137.   hfile   = handle of file to be read from
  2138.   length  = number of bytes to read (defaults to zero)
  2139.   dosrc   = two blank-delimited words:
  2140.             1) return code from DosRead
  2141.             2) if (1) is zero, an integer indicating number of bytes
  2142.                read (should be same as length of rexx variable's
  2143.                value)
  2144.  
  2145.  
  2146. ΓòÉΓòÉΓòÉ 15.2. RxWrite - Write to File Handle ΓòÉΓòÉΓòÉ
  2147.  
  2148. This function writes a character stream out to a file handle, rather than from 
  2149. a file name. 
  2150.  
  2151. Syntax:
  2152.  
  2153.   dosrc = RxWrite( hfile , data )
  2154.  
  2155. where
  2156.  
  2157.   hfile = handle of file to be written to
  2158.   data  = data to be written to file
  2159.   dosrc   = two blank-delimited words:
  2160.             1) return code from DosWrite
  2161.             2) if (1) is zero, an integer indicating number of bytes
  2162.                written (may not be same as length of data supplied)
  2163.  
  2164.  
  2165. ΓòÉΓòÉΓòÉ 15.3. RxCloseH - Close a File Handle ΓòÉΓòÉΓòÉ
  2166.  
  2167. This function closes a file handle. 
  2168.  
  2169. Syntax:
  2170.  
  2171.   closerc = RxCloseH(hfile)
  2172.  
  2173. where
  2174.  
  2175.   hfile   = handle of file to be closed
  2176.   closerc = return code from DosClose
  2177.  
  2178.  
  2179. ΓòÉΓòÉΓòÉ 15.4. RxExecI - Read data into a Rexx queue or stem from a file ΓòÉΓòÉΓòÉ
  2180.  
  2181. This function reads (text) data into a Rexx queue or stem variable from a file. 
  2182. It is meant to be like EXECIO in TSO and VM, and can be used in a similar 
  2183. fashion for file input. 
  2184.  
  2185. Syntax:
  2186.  
  2187.   info = RxExecI([fname], [qtype], [name], [type])
  2188.  
  2189. where:
  2190.  
  2191.   fname  = name of file to be read from (default reads from stdin)
  2192.   qtype  = 'Lifo' or 'Fifo' (default is 'Fifo')
  2193.            determines how lines are read onto queue
  2194.            (ignored for stems)
  2195.   name   = name of Rexx queue from into which data is read (default uses
  2196.            current queue)
  2197.                or
  2198.            name of a Rexx stem variable under which data is to be mapped as
  2199.              stem.0 = number of lines (stem.1 - stem.n)
  2200.              stem.1
  2201.              stem.2
  2202.              ...
  2203.              stem.n
  2204.   type   = 'Queue' or 'Stem' (default is 'Queue')
  2205.            this tells whether arg 3 is a Rexx Queue name or a stem
  2206.            variable name
  2207.   info   = two blank delimited numbers:
  2208.            1) number of lines read
  2209.            2) total number of bytes read
  2210.  
  2211. Example:
  2212.  
  2213.   /* Read a text file into the Rexx stem 's.' */
  2214.   info = rxexeci('c:\config.sys',,'s.','s')
  2215.   parse var info lines bytes
  2216.   Say lines 'lines were read'
  2217.   Say bytes 'bytes were read'
  2218.  
  2219.  
  2220. ΓòÉΓòÉΓòÉ 15.5. RxExecO - Write data from a Rexx queue or stem to a file ΓòÉΓòÉΓòÉ
  2221.  
  2222. This function writes data from a Rexx queue or stem variable to a file.  It is 
  2223. meant to be like EXECIO in TSO and VM, and can be used in a similar fashion for 
  2224. file output. 
  2225.  
  2226. Syntax:
  2227.  
  2228.   info = RxExecO([fname], [action], [name], [type])
  2229.  
  2230. where:
  2231.  
  2232.   fname  = name of file to be written to (default sends to stdout)
  2233.   action = Replace or Append (default is 'Replace')
  2234.            replaces or appends to 'fname'
  2235.   name   = name of Rexx queue from which to get data (default uses
  2236.            current queue)
  2237.                or
  2238.            name of a Rexx stem variable under which data is mapped as
  2239.              stem.1
  2240.              stem.2
  2241.              ...
  2242.              stem.n
  2243.            Once an uninitialized value for 'stem.n' is encountered,
  2244.            i/o stops.
  2245.   type   = 'Queue' or 'Stem' (default is 'Queue')
  2246.            this tells whether arg 3 is a Rexx Queue name or a stem
  2247.            variable name
  2248.   info   = two blank delimited numbers:
  2249.            1) number of lines written
  2250.            2) total number of bytes written
  2251.  
  2252. Example:
  2253.  
  2254.   /* Write 100 lines from current queue to c:\junk.dat (replace file) */
  2255.   Do 100
  2256.     Queue i time('l')
  2257.   End
  2258.   info = rxexeco('c:\junk.dat','r')
  2259.   parse var info lines bytes
  2260.   Say lines 'lines were written'
  2261.   Say bytes 'bytes were written'
  2262.  
  2263.  
  2264. ΓòÉΓòÉΓòÉ 15.6. Rxrsoe2f - Redirect Std-Out/Err to File ΓòÉΓòÉΓòÉ
  2265.  
  2266. This function redirects Standard Out and Standard Error to a named file (or 
  2267. device name, such as "CON"). 
  2268.  
  2269. Syntax:
  2270.  
  2271.   Call Rxrsoe2f stream,opt
  2272.  
  2273. where:
  2274.  
  2275.   stream = name of file or device (e.g. 'con', 'nul', 'kbd', etc.)
  2276.            to which standard-out and standard-error are re-directed.
  2277.   opt    = either 'Append' or 'Replace' file/device
  2278.  
  2279.  
  2280. ΓòÉΓòÉΓòÉ 16. System-Info related ΓòÉΓòÉΓòÉ
  2281.  
  2282. Functions returning OS/2 system information. 
  2283.  
  2284.  
  2285. ΓòÉΓòÉΓòÉ 16.1. RxPstat - Get Process Status Information ΓòÉΓòÉΓòÉ
  2286.  
  2287. This function returns process status information (like PSTAT). 
  2288.  
  2289. Syntax:
  2290.  
  2291.   procrc = RxPStat(stemname)
  2292.  
  2293. where:
  2294.  
  2295.   stemname = a Rexx stem variable name under which results are
  2296.              mapped as such:
  2297.  
  2298.                stem.P.0 = number of processes
  2299.                stem.P.n.1 = process-id
  2300.                stem.P.n.2 = parent process-id
  2301.                stem.P.n.3 = process type
  2302.                stem.P.n.4 = process status
  2303.                stem.P.n.5 = process session-id
  2304.                stem.P.n.6 = process module name
  2305.                stem.P.n.T = process thread count
  2306.                stem.P.n.T.m.1 = thread-id within process
  2307.                stem.P.n.T.m.2 = unique thread slot number
  2308.                stem.P.n.T.m.3 = sleep-id thread is sleeping on
  2309.                stem.P.n.T.m.4 = thread priority
  2310.                stem.P.n.T.m.5 = thread state
  2311.                stem.P.n.T.m.6 = thread system time
  2312.                stem.P.n.T.m.7 = thread user time
  2313.   procrc   = return code from DosQProcStatus
  2314.  
  2315. Example:
  2316.  
  2317.   prc = rxpstat('s.')
  2318.   Say 'There are' s.p.0 'processes running right now'
  2319.  
  2320.  
  2321. ΓòÉΓòÉΓòÉ 16.2. RxSetError - Set DosError settings ΓòÉΓòÉΓòÉ
  2322.  
  2323. This function allows you to turn HardError and Exception popup on or off.  This 
  2324. change takes effect for the process in which it is issued, no matter what the 
  2325. previous setting was, by whom, or on what thread. Presently, there is no way 
  2326. (that I know of) to query or "reset" these error settings. 
  2327.  
  2328. Syntax:
  2329.  
  2330.   dosrc = RxSetError(flag)
  2331.  
  2332. where:
  2333.  
  2334.   flag  = any combination of:
  2335.           'h' to disable HardError popup
  2336.           'H' to enable  HardError popup
  2337.           'e' to disable Exception popup
  2338.           'E' to enable  Exception popup
  2339.   dosrc = return code from DosError()
  2340.  
  2341. Example:
  2342.  
  2343.   Call rxseterror 'eh'  /* would suppress popups from both harderror */
  2344.                         /* and exception conditions */
  2345.  
  2346.  
  2347. ΓòÉΓòÉΓòÉ 16.3. RxProcId - Get process' own PID and TID information ΓòÉΓòÉΓòÉ
  2348.  
  2349. This function returns the process-id, parent process-id, and thread-id of the 
  2350. current thread of the current process. 
  2351.  
  2352. Syntax:
  2353.  
  2354.   procinfo = rxprocid()
  2355.  
  2356. where:
  2357.  
  2358.   procinfo = three blank delimited integers:
  2359.              1) process-id
  2360.              2) parent process-id
  2361.              3) thread-id
  2362.  
  2363.  
  2364. ΓòÉΓòÉΓòÉ 16.4. RxQuerySysInfo - Query OS/2 SysInfo ΓòÉΓòÉΓòÉ
  2365.  
  2366. This function returns live system information about OS/2 via the 
  2367. DosQuerySysInfo API. 
  2368.  
  2369. Syntax:
  2370.  
  2371.   rc = RxQuerySysInfo( stemname [,startidx [,endidx]])
  2372.  
  2373. where
  2374.  
  2375.   stemname = Rexx stem name, under which results are returned.  Each
  2376.              DosQuerySysInfo item is returned under the appropriate stem.n
  2377.              For instance, the call "call rxquerysysinfo('s.',3,5)" would
  2378.              set the rexx variables "s.3", "s.4", and "s.5".
  2379.   startidx = (see programming info for DosQuerySysInfo) Default is 1
  2380.   endidx   = (see programming info for DosQuerySysInfo) Default is 23
  2381.   rc       = return code from DosQuerySysInfo
  2382.  
  2383.  
  2384. ΓòÉΓòÉΓòÉ 17. PM / Wp related functions ΓòÉΓòÉΓòÉ
  2385.  
  2386. Functions related to PM or Workplace Shell Objects 
  2387.  
  2388.  
  2389. ΓòÉΓòÉΓòÉ 17.1. RxWinQueryObject - Query WP-Shell Object Handle ΓòÉΓòÉΓòÉ
  2390.  
  2391. This function returns the object handle of a WorkPlace Shell object. 
  2392.  
  2393. Syntax:
  2394.  
  2395.   hobj = RxWinQueryObject(objname)
  2396.  
  2397. where
  2398.  
  2399.   objname = name of WorkPlace Shell object
  2400.   hobj    = handle to object (or null string if not successful)
  2401.  
  2402.  
  2403. ΓòÉΓòÉΓòÉ 17.2. RxWinDestroyObject - Destroy a WP-Shell Object ΓòÉΓòÉΓòÉ
  2404.  
  2405. This function destroys a WorkPlace Shell object by object handle. 
  2406.  
  2407. Syntax:
  2408.  
  2409.   yorn = RxWinDestroyObject(hobj)
  2410.  
  2411. where
  2412.  
  2413.   hobj    = handle to object
  2414.   yorn    = "1" if it worked, "0" if it didn't
  2415.