New REXXUTIL Functions

Автор: Richard K. Goran

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

1 File System Functions

2 Semaphore Functions

3 Process Control Functions

4 National Language Functions

5 Macrospace Functions

6 Function Library Routines

Much to my surprise, IBM has chosen to add new functions to REXXUTIL. I had previously said here in this column that I thought that REXXUTIL was probably at its evolutionary end. While the new functions that are planned are not of the earth-shaking variety nor do they provide any functions that have not previously been available via third-party Application Program Interfaces (APIs), a couple of the general-use functions will be welcomed by most REXX programmers. All of these new functions are just pass-throughs to the corresponding system functions that are referenceable in C only.

The advance information that I have obtained on these functions is preliminary and there is no guarantee that all of the these functions will make it into the next official release of REXXUTIL nor can I be certain that there might not be some additional functions included in the next version of REXXUTIL. Anticipated availability of this new version is the next release of Warp. My guess is that the release date will coincide will fall COMDEX in November.

The new functions are grouped into seven categories: File System Functions, Mutually Exclusive Semaphore Functions, Even Semaphore Functions, Process Control Functions, national Language Functions, Macrospace Functions, and Function Library Routines. Table 1 summarizes the functions within these categories.

File System Functions

The SysAddFileHandle() and SysSetFileHandle() functions were implemented to overcome a "fix" made to Warp that I previously wrote about ([9504.htm 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() simply returns the letter of the boot drive (which I prefer to call the Initial Program Load or IPL drive) followed by a colon. The need for this function is obvious and the function existed in the IBM internal version of REXXUTIL (rxutil.dll) yet never made it into the released version.

SysFileSystemType() returns the name of the file system used on the specified drive. It will return FAT, HPFS or presumably CDFS 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 editting a source file name with a wildcard mask. The editting 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. Semaphores are defined by the system and reside in an internal memory buffer. 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. 

SysSwitchSession(name) results in the focus being changed to the named session.

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 following quoted is from the IBM-supplied REXX information: "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. It is recommended that only the most frequently used functions be placed in the macrospace."

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.

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.

SysElapsedTime() reports an elapsed time using the OS/2 high-frequency timer services. The high-frequency timer services have a higher timer resolution than the timer services used by the TIME() built-in function. SysElapsedTime() maintains a single, process-wide time stamp for measuring elapsed time. In contrast with the TIME() built-in function, the time stamp is not saved and restored on subroutine calls and multiple calls to SysElapsedTime() in a single instruction will use different versions of the time stamp.

Table 1