REXX on OS/2 Warp Version 4

Автор: Richard K. Goran

Дата: December, 1996

Источник: EDM/2

If 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 [9509.htm 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 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 [../rrsh-4/welcome.htm 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 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

SysDropLibrary( DLL[, drop_routine] )

Returns 0 after successfully calling the drop_routine in DLL to terminate and deregister all of the functions in DLL; otherwise, returns 1. If drop_routine is not specified, SysDropLibrary() will call ordinal routine #2 in the DLL.

SysLoadLibrary( DLL[, load_routine] )

Returns 0 if load_routine was successful; otherwise, 1. DLL is the name of the library module. Load_routine is the name of the function loader routine in the DLL. If load_routine is not specified, SysLoadLibrary() will call ordinal routine #1 in the DLL.

SysQuerySwitchList( stem )

Returns 0 after sequentially assigning the contents of the switch list to stem. Stem.0 will contain the number of entries in the switch list.

SysSwitchSession( session_name )

Returns 0 after attempting to switch the focus to session_name; otherwise, returns a non-zero value. Session_name must contain the session name as it appears in the window list and can be retrieved with the SysQuerySwitchList() function.

Note: If session_name contains a non-switchable session, focus may be switched to the Window List.

File System Functions

The SysAddFileHandle() and SysSetFileHandle() functions were implemented to overcome a "fix" made to Warp that I [9504.htm previously wrote about (April, 1995 - page 54)]. Since Warp reduced the default number of file handles per session to 20 (with only 15 of the 20 being available to a user program), these functions were added to allow the number of file handles to be adjusted for the current session.

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 Functions

Semaphores 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:

• Event semaphores enable a thread to notify waiting threads that an event has occurred.
• Mutual exclusion (mutex) semaphores enable threads to serialize their access to shared resources.
• Multiple Wait (muxwait) semaphores enable threads to wait either for multiple events to occur, or for multiple resources to become available.

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 Functions

This 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 Functions

The 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 Functions

The 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 Routines

The 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 line

There 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 (https://, 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 [../pub/welcome.htm#rxtt REXX Tips & Tricks].

Resources

• REXX Reference Summary Handbook
• REXX Tips & Tricks