|
The REXX Column December, 1996 by Dick Goran |
Index of articles |
| Disclaimer: This material is reprinted here, as it was submitted to OS/2 Magazine, as a service to the OS/2 user community. Only minor editing has been done to accomodate the change to HTML format. Some of the information which was valid at the time the original column was written may now be obsolete. No assurance is implied as to its accuracy or completeness. |
REXX on OS/2 Warp Version 4If my E-mail is a valid indicator, there is a great deal of confusion about REXX on OS/2 Warp Version 4 which was released by IBM on September 25, 1996. In last month's column I described the presence of the traditional or "classic" REXX interpreter along with the new Object REXX interpreter. This is the first official release of Object REXX. All prior releases were betas that were only available to subscribers of the IBM Developer Connection CD-ROM. In my September 1995 column I described all of the new functions that were supposed to be included in REXXUTIL. Well, there is good news and bad news. The 38 new functions shown in Table 1 are included in REXXUTIL, but only for the version which is used with Object REXX. The version of REXXUTIL which is installed by default along with classic REXX when you install Warp 4 does not contain any of these new functions.True to form, IBM did not do a very good job of documenting many of the new functions and, did not document some of the functions at all. Error-indicating return codes are the primary weakness of the functions that were included in the rexx.inf documentation. The rexx.inf for both classic REXX and Object REXX make reference to return codes passed back by the underlying Application Programming Interface (API) calls. Unfortunately, these return codes are only available from IBM in OS/2 developer documentation. The other source for this documentation for REXX programmers is in the REXX Reference Summary Handbook. Since there are 38 functions included in the Object REXX version of REXXUTIL that do not appear in its classic REXX counterpart, space prohibits me from including them all here. Table 2 contains four functions from the Handbook that are not documented in the rexx.inf file that accompanies Object REXX on Warp 4. The new functions fall into one of the following groups: Event / Mutual Exclusion (mutex) Semaphores, File System functions, Function Library routines, Macrospace functions, and National Language functions. Table 1 - New REXXUTIL Functions
Table 2 - Undocumented REXXUTIL Functions
Note: If session_name contains a non-switchable session, focus may be switched to the
Window List.
SysBootDrive() returns the uppercase letter of the boot drive followed by a colon. SysFileSystemType() returns the name of the file system used on the specified drive. It will return FAT, HPFS, CDFS, or LAN for valid drive designations otherwise it returns a null string. SysQueryEAList() allows you to retrieve a list of all of the extended attributes associated with a file or directory. You can then retrieve the specific EA data using the pre-existing SysGetEA() function. The list of EA names is placed in a compound variable. SysWildCard() returns the result from editing a source file name with a wildcard mask. The editing is performed using DosEditName(). Semaphore FunctionsSemaphores signal the beginning and ending of an operation and provide mutually exclusive ownership of resources. Typically, semaphores are used to prevent more than one process or thread within a process from accessing a resource. Semaphore names are validated by the file system and must include the prefix '\SEM32\'. Semaphores are divided into three types, according to the functionality they provide:
The new Mutex and Event semaphores share the SysCreate...(), SysOpen...(), and SysClose...() function calls. Mutex handling is also permitted with SysReleaseMutexSem() and SysRequestMutexSem() whereas the additional Event semaphore functions include SysPostEventSem(), SysResetEventSem(), and SysWaitEventSem(). Process Control FunctionsThis group of functions include the often-requested ability to shutdown the OS/2 system from a REXX program. That task can now be accomplished with the SysShutDownSystem() function. Session priority can be changed with SysSetPriority(class, delta) where class indicates the new process priority class with the allowed classes being:0 No change, leave as is. 1 Idle time priority 2 Regular priority 3 Time critical priority 4 Foreground server priority Delta is the change applied to the process's priority level. The delta value must be in the range -31 to +31. SysProcessType() returns one of the following values indicating the type of process the REXX program is running in: 0 Full screen protect mode session. 1 Requires real mode. 2 VIO windowable protect mode session. 3 Presentation Manager protect mode session. 4 Detached protect mode process. SysQuerySwitchList( name ) and SysSwitchSession( name ) permit the system switch list to be interrogated and focus to be changed to the named session, respectively. SysElapsedTime( option ) minimally uses the first letter of the following strings: Elapsed - returns the number of seconds and microseconds since the elapsed time clock was started or reset (see below). This is the default. Reset - returns the number of seconds and microseconds since the elapsed time close was started or reset and also simultaneously resets the elapsed time clock to zero. The value returned will be in the same format as the TIME( 'E' ) built-in function - 'sssssssss.uuuuuu'. The number will have no leading zeros or blanks. The fractional part will always have six digits. National Language FunctionsThe national language functions control the OS/2 code page settings and perform national language sensitive operations such as uppercasing and comparisons. The functions include: SysGetCollate(), SysMapCase(), SysNationalLanguageCompare(), SysQueryProcessCodePage(), and SysSetProcessCodePage().Macrospace FunctionsThe macrospace can improve the performance of REXX procedures by maintaining REXX procedure images in memory for immediate load and execution. This is useful for frequently used procedures and functions such as editor macros. Programs loaded and registered in the REXX macrospace are available to all processes. They can be called as functions or subroutines from other REXX programs just as other REXX external functions are called. However, the macrospace REXX procedures can be placed at the front or at the end of the external function search order - SysAddRexxMacro( name, file, [order] ). REXX procedures in the macrospace can be saved to a disk file - SysSaveRexxMacroSpace(file). A saved macrospace file can be reloaded with the SysLoadRexxMacroSpace(file) function. An application, such as an editor, can create a library of frequently-used functions and load the library into the macrospace for fast access. Multiple macrospace libraries can be created and loaded. The other macrospace functions include: SysClearRexxMacroSpace(), SysDropRexxMacro(), SysQueryRexxMacro(), and SysReorderRexxMacro().The REXX macrospace is placed in shared memory. The size of the macrospace is only limited by the amount of memory and swap space available to the system. However, as the macrospace grows, it limits the memory available to other processes in the system. Allowing the macrospace to grow too large might degrade overall system performance due to increased system swap file access. Function Library RoutinesThe function library routines include SysLoadLibrary() and SysDropLibrary() and are intended as an assist in the loading and dropping of REXX external function libraries. They have extended flexibility over the built-in functions RxFuncAdd() and RxFuncDrop() because they include the ability to reference ordinal routines within a .dll. If a load routine is not specified, SysLoadLibrary() will call ordinal routine #1 in the DLL. Similarly, if the name of the routine to be dropped is not specified, SysDropLibrary() will call ordinal routine #2 in the DLL.URLs from the command lineThere has been a persistent bug with classic REXX which has been reported to IBM repeatedly since OS/2 2.1 where you could not pass a parameter which contained two or more concatenated slashes to a REXX program. With OS/2 2.1 this problem effected a very small audience; however, beginning with Warp Version 3 and the increased awareness and use of Internet URLs this became more than a minor annoyance. Two of the common Internet protocols (http://, file://) cannot be passed to a classic REXX program. IBM fixed the problem in Object REXX but ignored it in classic REXX. The problem stems from the ability to indicate to the REXX interpreter that it is to only tokenize the code in a program when the command line parameter of //t is specified and not execute the program. The //t option still functions for Object REXX but other command line parameters containing a double slash are passed to the program. There is a work around for classic REXX included in Bernd Schemmer's REXX Tips & Tricks.Resources | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||