<!--#########################################################################
#
# Description: Open Object Rexx: Reference SGML file.
#
# Copyright (c) 2005-2009, Rexx Language Association. All rights reserved.
# Portions Copyright (c) 2004, IBM Corporation. All rights reserved.
#
# This program and the accompanying materials are made available under
# the terms of the Common Public License v1.0 which accompanies this
# distribution. A copy is also available at the following address:
# http://www.oorexx.org/license.html
#
# Redistribution and use in source and binary forms, with or
# without modification, are permitted provided that the following
# conditions are met:
#
# Redistributions of source code must retain the above copyright
# notice, this list of conditions and the following disclaimer.
# Redistributions in binary form must reproduce the above copyright
# notice, this list of conditions and the following disclaimer in
# the documentation and/or other materials provided with the distribution.
#
# Neither the name of Rexx Language Association nor the names
# of its contributors may be used to endorse or promote products
# derived from this software without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
# TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
# OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
# OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#
# Author(s):
# W. David Ashley <dashley@us.ibm.com>
#
#########################################################################
-->
<chapter id="rexutil"><title>Rexx Utilities (RexxUtil)</title>
<indexterm><primary>dynamic link library (RexxUtil)</primary></indexterm>
<indexterm><primary>shared library (RexxUtil)</primary></indexterm>
<indexterm><primary>dllfunctions</primary></indexterm>
<para>RexxUtil is a Dynamic Link Library (DLL) package for Windows and *nix
platforms; the package contains external Rexx functions. These functions:</para>
<itemizedlist>
<listitem><para>Manipulate operating system files and directories</para>
</listitem>
<listitem><para>Manipulate Windows classes and objects</para></listitem>
<listitem><para>Perform text screen input and output</para></listitem>
</itemizedlist>
<para>All of the RexxUtil functions are registered by the ooRexx interpreter on
startup so there is no need to register the functions either individually or
via the SysLoadFuncs function.</para>
<section id="systemerrorcodes"><title>A Note on Error Codes</title>
<indexterm><primary>Windows OS Error Codes</primary></indexterm>
<para>On Windows, some of the REXXUTIL functions return operating system error
codes on failure. The <link linkend="utlSysgeterrortext">SysGetErrorText()</link>
function can be used retrieve a description of system error code. In addition,
the meaning of these error return codes can be looked up in the Windows
Operating System documentation provided by Microsoft.
</para>
<para>The documentation is called the MSDN Library. The library is provided
online for anyone to access. Plus, since May 2006, Microsoft has also provided
the ISO images for the library free of charge. Anyone can download the ISOs,
burn them to a CD, and install the library locally on their system.
</para>
<para>The information below is provided to help the Rexx programmer locate the
MSDN Library. All things on the Internet change. The
URLs listed here are accurate at the time of this writing.
</para>
<para>The online MSDN Library is currently located at:</para>
<para>http://msdn2.microsoft.com/en-us/library/default.aspx.</para>
<para>A direct link to the section on the System Error codes is:</para>
<para>http://msdn.microsoft.com/en-us/library/ms681381.aspx</para>
<para>A Google search of <computeroutput>MSDN Library</computeroutput> will turn
up the link to the online MSDN Library. A Google search of <computeroutput>MSDN
"System Error Codes"</computeroutput> will turn up the section on the error
codes.
</para>
<para>Directions to the downloadable ISO images of the MSDN Library have been
posted on this blog entry:</para>
<para>http://blogs.msdn.com/robcaron/archive/2006/07/26/678897.aspx</para>
<para>A Google search using: <computeroutput>"Rob Caron" General Downloads MSDN
Library</computeroutput> should also turn up the blog entry.
</para>
</section>
<section id="utilfuncttable"><title>List of Rexx Utility Functions</title>
<indexterm><primary>rexxutil functions</primary></indexterm>
<para>The following table lists all of the REXXUTIL functions and the
platforms on which they are available.</para>
<table id="functtable" frame="all" pgwide="1"><title>Rexx Utility Library Functions</title>
<tgroup cols ="4">
<colspec colname="c1" colwidth="2*">
<colspec colname="c2">
<colspec colname="c3">
<colspec colname="c4">
<thead>
<row>
<entry morerows="1">Function Name</entry>
<entry namest="c2" nameend="c3" align="center">Exists on Platform</entry>
<entry morerows="1">Remarks</entry>
</row>
<row>
<entry align="center">Windows</entry>
<entry align="center">Unix</entry>
</row>
</thead>
<tbody>
<row>
<entry><link linkend="utlRxmessagebox">RxMessageBox</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlRxwinexec">RxWinExec</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysaddrexxmacro">SysAddRexxMacro</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysbootdrive">SysBootDrive</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysclearrexxmacrospace">SysClearRexxMacroSpace</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSyscloseeventsem">SysCloseEventSem</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysclosemutexsem">SysCloseMutexSem</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSyscls">SysCls</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSyscreateeventsem">SysCreateEventSem</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSyscreatemutexsem">SysCreateMutexSem</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSyscreatepipe">SysCreatePipe</link></entry><entry>NO</entry><entry>Yes</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSyscurpos">SysCurPos</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSyscurstate">SysCurState</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysdriveinfo">SysDriveInfo</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysdrivemap">SysDriveMap</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysdropfuncs">SysDropFuncs</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysdroprexxmacro">SysDropRexxMacro</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysdumpvariables">SysDumpVariables</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysfilecopy">SysFileCopy</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysfiledelete">SysFileDelete</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysFileExists">SysFileExists</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysfilemove">SysFileMove</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysfilesearch">SysFileSearch</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysfilesystemtype">SysFileSystemType</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysfiletree">SysFileTree</link></entry><entry>YES</entry><entry>YES</entry>
<entry>Works differently</entry>
</row>
<row>
<entry><link linkend="utlSysfork">SysFork</link></entry><entry>NO</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysfromunicode">SysFromUnicode</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysgeterrortext">SysGetErrortext</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysgetfiledatetime">SysGetFileDateTime</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysgetkey">SysGetKey</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysgetmessage">SysGetMessage</link></entry><entry>NO</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysgetmessagex">SysGetMessageX</link></entry><entry>NO</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysini">SysIni</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysisfile">SysIsFile</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysisfilecompressed">SysIsFileCompressed</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysisfiledirectory">SysIsFileDirectory</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysisfileencrypted">SysIsFileEncrypted</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysisfilelink">SysIsFileLink</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysisfilenotcontentindexed">SysIsFileNotContentIndexed</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysisfileoffline">SysIsFileOffline</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysisfilesparse">SysIsFileSparse</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysisfiletemporary">SysIsFileTemporary</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSyslinver">SysLinVer</link></entry><entry>NO</entry><entry>NO*</entry>
<entry>Linux only*</entry>
</row>
<row>
<entry><link linkend="utlSysloadfuncs">SysLoadFuncs</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysloadrexxmacrospace">SysLoadRexxMacroSpace</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysmkdir">SysMkDir</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysopeneventsem">SysOpenEventSem</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysopenmutexsem">SysOpenMutexSem</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysposteventsem">SysPostEventSem</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSyspulseeventsem">SysPulseEventSem</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysqueryprocess">SysQueryProcess</link></entry><entry>YES</entry><entry>YES</entry>
<entry>Works differently</entry>
</row>
<row>
<entry><link linkend="utlSysqueryrexxmacro">SysQueryRexxMacro</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysreleasemutexsem">SysReleaseMutexSem</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysreorderrexxmacro">SysReorderRexxMacro</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysrequestmutexsem">SysRequestMutexSem</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysreseteventsem">SysResetEventSem</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysrmdir">SysRmDir</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSyssaverexxmacrospace">SysSaveRexxMacroSpace</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSyssearchpath">SysSearchPath</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSyssetfiledatetime">SysSetFileDateTime</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSyssetpriority">SysSetPriority</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysshutdownsystem">SysShutdownSystem</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSyssleep">SysSleep</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysstemcopy">SysStemCopy</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysstemdelete">SysStemDelete</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSyssteminsert">SysStemInsert</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysstemsort">SysStemSort</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysswitchsession">SysSwitchSession</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSyssystemdirectory">SysSystemDirectory</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSystempfilename">SysTempFileName</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSystextscreenread">SysTextScreenRead</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSystextscreensize">SysTextScreenSize</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSystounicode">SysToUnicode</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysutilversion">SysUtilVersion</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysversion">SysVersion</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSysvolumelabel">SysVolumeLabel</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSyswait">SysWait</link></entry><entry>NO</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSyswaiteventsem">SysWaitEventSem</link></entry><entry>YES</entry><entry>YES</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSyswaitnamedpipe">SysWaitNamedPipe</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSyswindecryptfile">SysWinDecryptFile</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSyswinencryptfile">SysWinEncryptFile</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSyswinver">SysWinVer</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSyswingetprinters">SysWinGetPrinters</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSyswingetdefaultprinter">SysWinGetDefaultPrinter</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="utlSyswinsetdefaultprinter">SysWinSetDefaultPrinter</link></entry><entry>YES</entry><entry>NO</entry>
<entry></entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section id="utlRxmessagebox"><title>RxMessageBox (Windows only)</title>
<indexterm><primary>RxMessageBox</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>RxMessageBox</secondary></indexterm>
<programlisting>
<![CDATA[
>>-RxMessageBox(text-------------------------------------------->
>--+--------------------------------------------+--)-----------><
+-,--+-------+--+--------------------------+-+
+-title-+ +-,--+--------+--+-------+-+
+-button-+ +-,icon-+
]]>
</programlisting>
<para>Displays a Windows message box.</para>
<para>RxMessageBox returns the selected message box push button. Possible values
are: </para>
<variablelist>
<varlistentry><term>1</term>
<listitem><para>The OK push button was pressed
</para></listitem></varlistentry>
<varlistentry><term>2</term>
<listitem><para>The CANCEL push button was pressed
</para></listitem></varlistentry>
<varlistentry><term>3</term>
<listitem><para>The ABORT push button was pressed
</para></listitem></varlistentry>
<varlistentry><term>4</term>
<listitem><para>The RETRY push button was pressed
</para></listitem></varlistentry>
<varlistentry><term>5</term>
<listitem><para>The IGNORE push button was pressed
</para></listitem></varlistentry>
<varlistentry><term>6</term>
<listitem><para>The YES push button was pressed
</para></listitem></varlistentry>
<varlistentry><term>7</term>
<listitem><para>The NO push button was pressed
</para></listitem></varlistentry>
</variablelist>
<para>If a message box has a "CANCEL" button, the function returns the
2 value if either the ESC key is pressed or the "CANCEL" button is
selected. If the message box has no "CANCEL" button, pressing ESC
has no effect.</para>
<variablelist>
<varlistentry><term><emphasis role="italic">text</emphasis></term>
<listitem><para>The message box text.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">title</emphasis></term>
<listitem><para>The message box title. The default title is "Error!".
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">button</emphasis></term>
<listitem><para>The message box push button style. The allowed styles are:
<variablelist>
<varlistentry><term>"OK"</term>
<listitem><para>A single OK push button.
</para></listitem></varlistentry>
<varlistentry><term>"OKCANCEL"</term>
<listitem><para>An OK push button and a CANCEL push button.
</para></listitem></varlistentry>
<varlistentry><term>"RETRYCANCEL"</term>
<listitem><para>A RETRY push button and a CANCEL push button.
</para></listitem></varlistentry>
<varlistentry><term>"ABORTRETRYIGNORE"</term>
<listitem><para>An ABORT push button, a RETRY push button and an IGNORE push
button.</para></listitem></varlistentry>
<varlistentry><term>"YESNO"</term>
<listitem><para>A YES push button and a NO push button.
</para></listitem></varlistentry>
<varlistentry><term>"YESNOCANCEL"</term>
<listitem><para>A YES push button, a NO push button and a CANCEL push button.
</para></listitem></varlistentry>
</variablelist>
The default push button style is OK.</para>
</listitem></varlistentry>
<varlistentry><term><emphasis role="italic">icon</emphasis></term>
<listitem><para>The message box icon style. The allowed styles are:
<variablelist>
<varlistentry><term>"NONE"</term>
<listitem><para>No icon is displayed.
</para></listitem></varlistentry>
<varlistentry><term>"HAND"</term>
<listitem><para>A hand icon is displayed.
</para></listitem></varlistentry>
<varlistentry><term>"QUESTION"</term>
<listitem><para>A question mark icon is displayed.
</para></listitem></varlistentry>
<varlistentry><term>"EXCLAMATION"</term>
<listitem><para>An exclamation point icon is displayed.
</para></listitem></varlistentry>
<varlistentry><term>"ASTERISK"</term>
<listitem><para>An asterisk icon is displayed.
</para></listitem></varlistentry>
<varlistentry><term>"INFORMATION"</term>
<listitem><para>An information icon is displayed.
</para></listitem></varlistentry>
<varlistentry><term>"STOP"</term>
<listitem><para>A stop icon is displayed.
</para></listitem></varlistentry>
<varlistentry><term>"QUERY"</term>
<listitem><para>A query icon is displayed.
</para></listitem></varlistentry>
<varlistentry><term>"WARNING"</term>
<listitem><para>A warning icon is displayed.
</para></listitem></varlistentry>
<varlistentry><term>"ERROR"</term>
<listitem><para>An error icon is displayed.
</para></listitem></varlistentry>
</variablelist>
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>RxMessageBox</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>RxMessageBox</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>RxMessageBox</secondary></indexterm>
<programlisting>
/* Give option to quit */
if RxMessageBox("Shall we continue", , "YesNo", "Question") = 7
Then Exit /* quit option given, exit */
</programlisting>
</section>
<section id="utlRxwinexec"><title>RxWinExec (Windows only)</title>
<indexterm><primary>RxWinExec</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>RxWinExec</secondary></indexterm>
<programlisting>
<![CDATA[
>>-RxWinExec(-cmdline--+------------+--)-----------------------><
+-,--cmdshow-+
]]>
</programlisting>
<para>Starts (executes) the application as specified in
<emphasis role="italic">cmdline</emphasis>.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">cmdline</emphasis></term>
<listitem><para>A string containing a file name and optional parameters for the
application to be executed. If the name of the executable file in
<emphasis role="italic">cmdline</emphasis> does
not contain a directory path, RxWinExec searches for the executable file in
this sequence:
<variablelist>
<varlistentry><term>1</term>
<listitem><para>The directory from which Object Rexx was loaded.
</para></listitem></varlistentry>
<varlistentry><term>2</term>
<listitem><para>The current directory.
</para></listitem></varlistentry>
<varlistentry><term>3</term>
<listitem><para>The Windows system directory.
</para></listitem></varlistentry>
<varlistentry><term>4</term>
<listitem><para>The Windows directory.
</para></listitem></varlistentry>
<varlistentry><term>5</term>
<listitem><para>The directories listed in the PATH environment variable.
</para></listitem></varlistentry>
</variablelist>
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">cmdshow</emphasis></term>
<listitem><para>Specifies how a Windows-based application window is to be shown.
For a non-Windows-based application, the PIF file, if any, for the application
determines the window state.
<variablelist>
<varlistentry><term>SHOWNORMAL</term>
<listitem><para>Activates and displays a window.
</para></listitem></varlistentry>
<varlistentry><term>SHOWNOACTIVATE</term>
<listitem><para>Displays the window while the current active window remains
active.</para></listitem></varlistentry>
<varlistentry><term>SHOWMINNOACTIVE</term>
<listitem><para>Displays the window as a minimized window, the current active
window remains active.
</para></listitem></varlistentry>
<varlistentry><term>SHOWMINIMIZED</term>
<listitem><para>Activates the window and displays it as a minimized window.
</para></listitem></varlistentry>
<varlistentry><term>SHOWMAXIMIZED</term>
<listitem><para>Activates the window and displays it as a maximized window.
</para></listitem></varlistentry>
<varlistentry><term>HIDE</term>
<listitem><para>Hides the window and activates another window.
</para></listitem></varlistentry>
<varlistentry><term>MINIMIZE</term>
<listitem><para>Minimizes the specified window and activates the next top-level
window in the Z order.
</para></listitem></varlistentry>
</variablelist>
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<para>If the application is started successfully, the process id (PID) is
returned. If an error occurs the returned value is less than 32.</para>
<para>Error return codes correspond to a <link linkend="systemerrorcodes">
Windows System Error code</link>. If the Windows system error code is greater
than 32 it is negated. This is to prevent confusion between a legitimate error
code and a PID.</para>
<para>Some common error returns for this function are as follows.</para>
<variablelist>
<varlistentry><term>2</term>
<listitem><para>The specified file was not found.
</para></listitem></varlistentry>
<varlistentry><term>3</term>
<listitem><para>The specified path was not found.
</para></listitem></varlistentry>
<varlistentry><term>11</term>
<listitem><para>The EXE file is invalid.
</para></listitem></varlistentry>
<varlistentry><term>-53</term>
<listitem><para>The network path is invalid.
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSysaddrexxmacro"><title>SysAddRexxMacro</title>
<indexterm><primary>SysAddRexxMacro</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysAddRexxMacro</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysAddRexxMacro(name,file-+--------+-)----------------------><
+-,order-+
]]>
</programlisting>
<para>Adds a routine to the Rexx macrospace. SysAddRexxMacro returns the
RexxAddMacro return code.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">name</emphasis></term>
<listitem><para>The name of the function added to the macrospace.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">file</emphasis></term>
<listitem><para>The file containing the Rexx program.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">order</emphasis></term>
<listitem><para>The macrospace search order. The order can be "B" (Before) or
"A" (After).
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSysbootdrive"><title>SysBootDrive (Windows only)</title>
<indexterm><primary>SysAddBootDrive</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysBootDrive</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysBootDrive--(--)------------------------------------------><
]]>
</programlisting>
<para>Returns the drive used to boot Windows, for example, "C:".</para>
</section>
<section id="utlSysclearrexxmacrospace"><title>SysClearRexxMacroSpace</title>
<indexterm><primary>SysClearRexxMacroSpace</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysClearRexxMacroSpace</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysClearRexxMacroSpace()------------------------------------><
]]>
</programlisting>
<para>Clears the Rexx macrospace. SysClearRexxMacroSpace returns the
RexxClearMacroSpace return code.</para>
</section>
<section id="utlSyscloseeventsem"><title>SysCloseEventSem</title>
<indexterm><primary>SysCloseEventSem</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysCloseEventSem</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysCloseEventSem(handle)------------------------------------><
]]>
</programlisting>
<para>Closes an event semaphore.</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">handle</emphasis></term>
<listitem><para>A handle returned from a previous SysCreateEventSem or
SysOpenEventSem call.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>No errors.
</para></listitem></varlistentry>
<varlistentry><term>Other</term>
<listitem><para>An error occurred. On Windows, a <link linkend="systemerrorcodes">Windows System Error
code</link> is returned. This may be one of the following, but could be others.
</para></listitem></varlistentry>
<varlistentry><term>6</term>
<listitem><para>Invalid handle.
</para></listitem></varlistentry>
<varlistentry><term>102</term>
<listitem><para>Error semaphore busy.
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSysclosemutexsem"><title>SysCloseMutexSem</title>
<indexterm><primary>SysCloseMutexSem</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysCloseMutexSem</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysCloseMutexSem(handle)------------------------------------><
]]>
</programlisting>
<para>Closes a mutex semaphore.</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">handle</emphasis></term>
<listitem><para>A handle returned from a previous SysCreateMutexSem call.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>No errors.
</para></listitem></varlistentry>
<varlistentry><term>Other</term>
<listitem><para>An error occurred. On Windows, a <link linkend="systemerrorcodes">Windows System Error
code</link> is returned. This may be one of the following, but could be others.
</para></listitem></varlistentry>
<varlistentry><term>6</term>
<listitem><para>Invalid handle.
</para></listitem></varlistentry>
<varlistentry><term>102</term>
<listitem><para>Error semaphore busy.
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSyscls"><title>SysCls</title>
<indexterm><primary>SysCls</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysCls</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysCls()----------------------------------------------------><
]]>
</programlisting>
<para>Clears the screen.</para>
<para><emphasis role="bold">Example:</emphasis></para>
<programlisting>
/* Code */
call SysCls
</programlisting>
</section>
<section id="utlSyscreateeventsem"><title>SysCreateEventSem</title>
<indexterm><primary>SysCreateEventSem</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysCreateEventSem</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysCreateEventSem(-+------+--+--------------+-)-------------><
+-name-+ +-manual_reset-+
]]>
</programlisting>
<para>Creates or opens an event semaphore. It returns an event semaphore
handle that can be used with SysCloseEventSem, SysOpenEventSem,
SysResetEventSem, SysPostEventSem, and SysWaitEventSem. SysCreateEventSem
returns a null string ("") if the semaphore cannot be created or
opened.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">name</emphasis></term>
<listitem><para>The optional event semaphore name. If you omit
<emphasis role="italic">name</emphasis>,
SysCreateEventSem creates an unnamed, shared event semaphore. If you specify
<emphasis role="italic">name</emphasis>, SysCreateEventSem opens the semaphore
if the semaphore has already
been created. A semaphore name can be MAX_PATH long, and
can contain any character except the backslash (\) path-separator character.
Semaphore names are case-sensitive.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">manual_reset</emphasis></term>
<listitem><para>A flag to indicate that the event semaphore must be reset
manually by SysResetEventSem. If this parameter is omitted, the event
semaphore is reset automatically by SysWaitEventSem.
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSyscreatemutexsem"><title>SysCreateMutexSem</title>
<indexterm><primary>SysCreateMutexSem</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysCreateMutexSem</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysCreateMutexSem(-+------+-)-------------------------------><
+-name-+
]]>
</programlisting>
<para>Creates or opens a mutex semaphore. Returns a mutex semaphore handle that
can be used with SysCloseMutexSem, SysRequestMutexSem, and SysReleaseMutexSem.
SysCreateMutexSem returns a null string ("") if the semaphore cannot
be created or opened.</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">name</emphasis></term>
<listitem><para>The optional mutex semaphore name. If you omit
<emphasis role="italic">name</emphasis>, SysCreateMutexSem
creates an unnamed, shared mutex semaphore. If you specify
<emphasis role="italic">name</emphasis>,
SysCreateMutexSem opens the semaphore if the mutex has already been created.
The semaphore names cannot be longer than 63 characters. Semaphore names are
case-sensitive.
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSyscreatepipe"><title>SysCreatePipe (Unix only)</title>
<indexterm><primary>SysCreatePipe</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysCreatePipe</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysCreatePipe()---------------------------------------------><
]]>
</programlisting>
<para>Creates an unnamed pipe.</para>
<para><emphasis role="bold">Returns:</emphasis></para>
<para>Returns a string like <computeroutput>"handle handle"</computeroutput>
where the first handle is for read and the second handle for write.</para>
</section>
<section id="utlSyscurpos"><title>SysCurPos (Windows only)</title>
<indexterm><primary>SysCurPos</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysCurPos</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysCurPos(-+------------+-)---------------------------------><
+-row,column-+
]]>
</programlisting>
<para>Returns the cursor position in the form
<computeroutput>row col</computeroutput> and optionally
moves the cursor to a new location.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">row</emphasis></term>
<listitem><para>The row to move to.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">col</emphasis></term>
<listitem><para>The column to move to.
</para></listitem></varlistentry>
</variablelist>
<note><title>Note</title>
<para>Position (0,0) is the upper left corner.</para></note>
<para>You can call SysCurPos without a column and row position to obtain the
cursor position without moving the cursor.</para>
<para><emphasis role="bold">Example:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysCurPos</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysCurPos</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysCurPos</secondary></indexterm>
<programlisting>
/* Code */
call SysCls
parse value SysCurPos() with row col
say "Cursor position is "row", "col
/* Output */
Cursor position is 0, 0
</programlisting>
</section>
<section id="utlSyscurstate"><title>SysCurState (Windows only)</title>
<indexterm><primary>SysCurState</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysCurState</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysCurState(state)------------------------------------------><
]]>
</programlisting>
<para>Hides or displays the cursor.</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">state</emphasis></term>
<listitem><para>The new cursor state. Allowed states are:
<variablelist>
<varlistentry><term>"ON"</term>
<listitem><para>Display the cursor
</para></listitem></varlistentry>
<varlistentry><term>"OFF"</term>
<listitem><para>Hide the cursor
</para></listitem></varlistentry>
</variablelist>
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSysdriveinfo"><title>SysDriveInfo (Windows only)</title>
<indexterm><primary>SysDriveInfo</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysDriveInfo</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysDriveInfo(drive)-----------------------------------------><
]]>
</programlisting>
<para>Returns drive information in the form:
<computeroutput>drive: free total label</computeroutput>.</para>
<variablelist>
<varlistentry><term>drive:</term>
<listitem><para>is the drive letter identifier.
</para></listitem></varlistentry>
<varlistentry><term>free</term>
<listitem><para>is the drive unused space.
</para></listitem></varlistentry>
<varlistentry><term>total</term>
<listitem><para>is the total size of the drive.
</para></listitem></varlistentry>
<varlistentry><term>label</term>
<listitem><para>is the drive label.
</para></listitem></varlistentry>
</variablelist>
<para>If the drive is not accessible, then SysDriveInfo returns "".</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">drive</emphasis></term>
<listitem><para>The drive of interest, "C:".
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysDriveInfo</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysDriveInfo</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysDriveInfo</secondary></indexterm>
<programlisting>
/* Code */
say "Disk="SysDriveInfo("C:")
/* Output */
Disk=C: 33392640 83687424 TRIGGER_C
</programlisting>
</section>
<section id="utlSysdrivemap"><title>SysDriveMap (Windows only)</title>
<indexterm><primary>SysDriveMap</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysDriveMap</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysDriveMap(-+-------+-+------+-)---------------------------><
+-drive-+ +-,opt-+
]]>
</programlisting>
<para>Returns a string listing accessible drives (separated by blanks) in the
form: <computeroutput>C: D: ...</computeroutput>.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">drive</emphasis></term>
<listitem><para>The first drive letter of the drive map. The default is "C:".
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">opt</emphasis></term>
<listitem><para>The drivemap option. This can be:
<variablelist>
<varlistentry><term>"USED"</term>
<listitem><para>returns the drives that are accessible or in use, including
all local and remote drives. This is the default.
</para></listitem></varlistentry>
<varlistentry><term>"FREE"</term>
<listitem><para>returns drives that are free or not in use.
</para></listitem></varlistentry>
<varlistentry><term>"LOCAL"</term>
<listitem><para>returns only local drives.
</para></listitem></varlistentry>
<varlistentry><term>"REMOTE"</term>
<listitem><para>returns only remote drives, such as redirected LAN resources
or installable file system (IFS) attached drives.
</para></listitem></varlistentry>
<varlistentry><term>"REMOVABLE"</term>
<listitem><para>returns removable drives.
</para></listitem></varlistentry>
<varlistentry><term>"CDROM"</term>
<listitem><para>returns CD-ROM drives.
</para></listitem></varlistentry>
<varlistentry><term>"RAMDISK"</term>
<listitem><para>returns drives assigned from RAM.
</para></listitem></varlistentry>
</variablelist>
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysDriveMap</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysDriveMap</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysDriveMap</secondary></indexterm>
<programlisting>
/* Code */
say "Used drives include:"
say SysDriveMap("C:", "USED")
/* Output */
Used drives include:
C: D: E: F: W:
</programlisting>
</section>
<section id="utlSysdropfuncs"><title>SysDropFuncs</title>
<indexterm><primary>SysDropFuncs</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysDropFuncs</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysDropFuncs------------------------------------------------><
]]>
</programlisting>
<para>
From ooRexx 4.0.0 and on this function does nothing.
</para>
</section>
<section id="utlSysdroprexxmacro"><title>SysDropRexxMacro</title>
<indexterm><primary>SysDropRexxMacro</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysDropRexxMacro</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysDropRexxMacro(name)--------------------------------------><
]]>
</programlisting>
<para>Removes a routine from the Rexx macrospace. SysDropRexxMacro returns the
RexxDropMacro return code.</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">name</emphasis></term>
<listitem><para>The name of the function removed from the macrospace.
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSysdumpvariables"><title>SysDumpVariables</title>
<indexterm><primary>SysDumpVariables</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysDumpVariables</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysDumpVariables-+------------+-----------------------------><
+-(--name--)-+
]]>
</programlisting>
<para>Dumps all variables in the current scope either to the specified file
<emphasis role="italic">filename</emphasis> (new data is appended) or to
STDOUT if you omit <emphasis role="italic">filename</emphasis>. The format of
the data is, with one variable per line:</para>
<para><computeroutput>Name=MYVAR, Value="This is the content of MYVAR"</computeroutput>
</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">filename</emphasis></term>
<listitem><para>The name of the file to which variables are appended. The dump is
written to STDOUT if you omit this parameter.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>Dump completed successfully.
</para></listitem></varlistentry>
<varlistentry><term>-1</term>
<listitem><para>Dump failed.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysDumpVariables</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysDumpVariables</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysDumpVariables</secondary></indexterm>
<programlisting>
Call SysDumpVariables "MyVars.Lst" /* append vars to file */
Call SysDumpVariables /* list vars on STDOUT */
</programlisting>
</section>
<section id="utlSysfilecopy"><title>SysFileCopy (Windows only)</title>
<indexterm><primary>SysFileCopy</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysFileCopy</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysFileCopy(source, target)---------------------------------><
]]>
</programlisting>
<para>Copies a file from one location to another. Wildcard file
specifications are not allowed.</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">source</emphasis></term>
<listitem><para>The path/name of the file to be copied.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">target</emphasis></term>
<listitem><para>The path/name of the target location where the file is to be
copied.</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>File copied successfully.
</para></listitem></varlistentry>
<varlistentry><term>Other</term>
<listitem><para>A <link linkend="systemerrorcodes"> Windows System Error
code</link>.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysFileCopy</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysFileCopy</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysFileCopy</secondary></indexterm>
<programlisting>
/* Code */
call SysFileCopy "c:\temp\myfile.txt", "d:\myfolder\myCopy.txt"
</programlisting>
</section>
<section id="utlSysfiledelete"><title>SysFileDelete</title>
<indexterm><primary>SysFileDelete</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysFileDelete</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysFileDelete(file)-----------------------------------------><
]]>
</programlisting>
<para>Deletes a file. SysFileDelete does not support wildcard file
specifications.</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">file</emphasis></term>
<listitem><para>The name of the file to be deleted.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>File deleted successfully.
</para></listitem></varlistentry>
<varlistentry><term>Other</term>
<listitem><para>An error occurred. On Windows, a <link linkend="systemerrorcodes">Windows System Error
code</link> is returned. This may be one of the following, but could be others.
</para></listitem></varlistentry>
<varlistentry><term>2</term>
<listitem><para>File not found.
</para></listitem></varlistentry>
<varlistentry><term>3</term>
<listitem><para>Path not found.
</para></listitem></varlistentry>
<varlistentry><term>5</term>
<listitem><para>Access denied or busy.
</para></listitem></varlistentry>
<varlistentry><term>26</term>
<listitem><para>Not DOS disk.
</para></listitem></varlistentry>
<varlistentry><term>32</term>
<listitem><para>Sharing violation.
</para></listitem></varlistentry>
<varlistentry><term>36</term>
<listitem><para>Sharing buffer exceeded.
</para></listitem></varlistentry>
<varlistentry><term>87</term>
<listitem><para>Does not exist.
</para></listitem></varlistentry>
<varlistentry><term>206</term>
<listitem><para>File name exceeds range error.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysFileDelete</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysFileDelete</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysFileDelete</secondary></indexterm>
<programlisting>
/* Code */
parse arg InputFile OutputFile
call SysFileDelete OutputFile /* unconditionally erase output file */
</programlisting>
</section>
<section id="utlSysFileExists"><title>SysFileExists</title>
<indexterm><primary>SysFileExists</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysFileExists</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysFileExists(filename)-----------------------------------------><
]]>
</programlisting>
<para>Checks for the existence of a file. This function does not support
wildcard specifications. Returns true if any file system entity with the
given name exists. In particular, this will return true for both regular
files and directories.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">filename</emphasis></term>
<listitem><para>The name of the file to check for the existence of.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Returns:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>The file does not exist.
</para></listitem></varlistentry>
<varlistentry><term>1</term>
<listitem><para>The file exists.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<programlisting>
if SysFileExists(InputFile) then say "File Exists!"
else say "File does not exist."
</programlisting>
</section>
<section id="utlSysfilemove"><title>SysFileMove (Windows only)</title>
<indexterm><primary>SysFileMove</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysFileMove</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysFileMove(source, target)---------------------------------><
]]>
</programlisting>
<para>Moves a file from one location to another. Wildcard file
specifications are not allowed.</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">source</emphasis></term>
<listitem><para>The path/name of the file to be moved.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">target</emphasis></term>
<listitem><para>The path of the target location where the file is to be
moved. The <emphasis role="italic">target</emphasis> must contain a path
component.</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>File copied successfully.
</para></listitem></varlistentry>
<varlistentry><term>Other</term>
<listitem><para>On failure, a <link linkend="systemerrorcodes">
Windows System Error code</link> is returned.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysFileMove</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysFileMove</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysFileMove</secondary></indexterm>
<programlisting>
/* Code */
call SysFileMove "c:\temp\myfile.txt", "d:\myfolder"
</programlisting>
</section>
<section id="utlSysfilesearch"><title>SysFileSearch</title>
<indexterm><primary>SysFileSearch</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysFileSearch</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysFileSearch(target,file,stem--+----------+--)-------------><
+-,options-+
]]>
</programlisting>
<para>Finds all file lines containing the target string and returns the file
lines in a Rexx stem variable collection.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">target</emphasis></term>
<listitem><para>The target search string.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">file</emphasis></term>
<listitem><para>The searched file.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">stem</emphasis></term>
<listitem><para>The result stem variable name. SysFileSearch sets Rexx variable
<emphasis role="italic">stem.0</emphasis> to the number of lines returned and
stores the individual lines in variables
<emphasis role="italic">stem.1</emphasis> to
<emphasis role="italic">stem.n</emphasis>.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">options</emphasis></term>
<listitem><para>Any combination of the following one-character options:
<variablelist>
<varlistentry><term>"C"</term>
<listitem><para>Conducts a case-sensitive search.
</para></listitem></varlistentry>
<varlistentry><term>"N"</term>
<listitem><para>Returns the file line numbers.
</para></listitem></varlistentry>
</variablelist>
The default is a case-insensitive search without line numbers.</para>
</listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>Successful.
</para></listitem></varlistentry>
<varlistentry><term>2</term>
<listitem><para>Not enough memory.
</para></listitem></varlistentry>
<varlistentry><term>3</term>
<listitem><para>Error opening file.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysFileSearch</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysFileSearch</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysFileSearch</secondary></indexterm>
<programlisting>
/* Find DEVICE statements in CONFIG.SYS */
call SysFileSearch "DEVICE", "C:\CONFIG.SYS", "file."
do i=1 to file.0
say file.i
end
/* Output */
DEVICE=C:\SB16\DRV\CTSB16.SYS /UNIT=0 /BLASTER=A:240 I:5 D:1 H:5
DEVICE=C:\SB16\DRV\CTMMSYS.SYS
rem **** DOS SCSI CDROM device drivers ***
DEVICE=C:\SCSI\ASPI8DOS.SYS /D
DEVICE=C:\SCSI\ASPICD.SYS /D:ASPICD0
rem **** IDE CDROM device drivers
DEVICE=C:\DOS\HIMEM.SYS
DEVICE=C:\SBCD\DRV\SBIDE.SYS /V /D:MSCD001 /P:1f0,14
DEVICE=C:\DOS\SETVER.EXE
DEVICE=C:\WINDOWS\SMARTDRV.EXE /DOUBLE_BUFFER
DEVICE=C:\WINDOWS\IFSHLP.SYS
/* Find DEVICE statements in CONFIG.SYS (along with */
/* line numbers) */
call SysFileSearch "DEVICE", "C:\CONFIG.SYS", "file.", "N"
do i=1 to file.0
say file.i
end
/* Output */
1 DEVICE=C:\SB16\DRV\CTSB16.SYS /UNIT=0 /BLASTER=A:240 I:5 D:1
H:5
2 DEVICE=C:\SB16\DRV\CTMMSYS.SYS
4 rem **** DOS SCSI CDROM device drivers ***
5 DEVICE=C:\SCSI\ASPI8DOS.SYS /D
6 DEVICE=C:\SCSI\ASPICD.SYS /D:ASPICD0
8 rem **** IDE CDROM device drivers
9 DEVICE=C:\DOS\HIMEM.SYS
10 DEVICE=C:\SBCD\DRV\SBIDE.SYS /V /D:MSCD001 /P:1f0,14
13 DEVICE=C:\DOS\SETVER.EXE
16 DEVICE=C:\WINDOWS\SMARTDRV.EXE /DOUBLE_BUFFER
17 DEVICE=C:\WINDOWS\IFSHLP.SYS
</programlisting>
</section>
<section id="utlSysfilesystemtype"><title>SysFileSystemType (Windows only)</title>
<indexterm><primary>SysFileSystemType</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysFileSystemType</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysFileSystemType(drive)------------------------------------><
]]>
</programlisting>
<para>Returns the name of the file system used for a drive. If the drive is not
accessible, it returns a null string ("").</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">drive</emphasis></term>
<listitem><para>The drive of interest, for example "C:".
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysFileSystemType</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysFileSystemType</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysFileSystemType</secondary></indexterm>
<programlisting>
/* Code */
say "File System="SysFileSystemType("C:")
/* Output */
File System=NTFS
</programlisting>
</section>
<section id="utlSysfiletree"><title>SysFileTree</title>
<indexterm><primary>SysFileTree</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysFileTree</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysFileTree(filespec,stem------------------------------------>
>--+-------------------------------------------------------+---->
+-,--+---------+--+-----------------------------------+-+
+-options-+ +-,--+---------+--+---------------+-+
+-tattrib-+ +-,-+---------+-+
+-nattrib-+
>--)-----------------------------------------------------------><
]]>
</programlisting>
<para>Finds all files that match a file specification. SysFileTree returns the
file descriptions (date, time, size, attributes, and file specification) space delimited in
a Rexx stem variable collection. The default format for date and time is platform specific.</para>
<para>
<emphasis role="italic">SysFileTree</emphasis> uses operating system APIs to find the files. The found files are
placed in the returned stem in the order they are found by the operating system. This documentation does not attempt
to define what that order might be.
</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">filespec [required]</emphasis></term>
<listitem><para>The search file specification. This can not be the empty string. On Unix-like systems, <emphasis
role="italic">filespec</emphasis> must be less than or equal to 255 characters in length.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">stem [required]</emphasis></term>
<listitem><para>The name of a stem variable to be used for storing results.
SysFileTree sets Rexx variable <emphasis role="italic">stem.0</emphasis>
to the number of files and directories found and stores individual
file descriptions into variables <emphasis role="italic">stem.1</emphasis> to
<emphasis role="italic">stem.n</emphasis>.
Note: <emphasis role="italic">stem</emphasis> can be specified as
<emphasis role="italic">stem</emphasis> or <emphasis role="italic">stem.</emphasis>
(with or without the trailing period)
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">options [optional]</emphasis></term>
<listitem><para>A string with any combination of the following. If this argument is omitted, it defaults to <emphasis
role="italic">B</emphasis>.</para>
<variablelist>
<varlistentry><term>"F"</term>
<listitem><para>Search only for files.
</para></listitem></varlistentry>
<varlistentry><term>"D"</term>
<listitem><para>Search only for directories.
</para></listitem></varlistentry>
<varlistentry><term>"B"</term>
<listitem><para>Search for both files and directories. This is the default.
</para></listitem></varlistentry>
<varlistentry><term>"S"</term>
<listitem><para>Search subdirectories recursively.
</para></listitem></varlistentry>
<varlistentry><term>"T"</term>
<listitem><para>Return the time and date in the form YY/MM/DD/HH/MM. If the "L" option is also specified
then this option will be ignored.
</para></listitem></varlistentry>
<varlistentry><term>"L"</term>
<listitem><para>Return the time and date in the form YYYY-MM-DD HH:MM:SS.
</para></listitem></varlistentry>
<varlistentry><term>"I"</term>
<listitem><para>Perform a case-insensitive search for file names/directories.
This option is only used on system that support case-sensitive file names and
is ignored on systems like Windows where the file system is case-insensitive
by default.
</para></listitem></varlistentry>
<varlistentry><term>"O"</term>
<listitem><para>Return only the fully-qualified file name.</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">tattrib [optional] [Windows only]</emphasis></term>
<listitem><para>The target attribute mask for file specification matches. Only
files that match the target mask are returned. The default mask is "*****".
This returns all files regardless of the settings (clear or set) of the Archive,
Directory, Hidden, Read-Only, and System attributes. The target mask attributes
must appear in the order "ADHRS". This argument is Windows only. It is allowed but ignored on Unix-like operating
systems.</para></listitem></varlistentry>
</variablelist>
<para>Target Mask
Options </para>
<variablelist>
<varlistentry><term>*</term>
<listitem><para>The file attribute may be any state.
</para></listitem></varlistentry>
<varlistentry><term>+</term>
<listitem><para>The file attribute must be set.
</para></listitem></varlistentry>
<varlistentry><term>-</term>
<listitem><para>The file attribute must be cleared.
</para></listitem></varlistentry>
</variablelist>
<para>Target Mask Examples </para>
<variablelist>
<varlistentry><term>"***+*"</term>
<listitem><para>Find all files with the Read-Only attribute set.
</para></listitem></varlistentry>
<varlistentry><term>"+**+*"</term>
<listitem><para>Find all files with the Read-Only and Archive attributes set.
</para></listitem></varlistentry>
<varlistentry><term>"*++**"</term>
<listitem><para>Find all hidden subdirectories.
</para></listitem></varlistentry>
<varlistentry><term>"---+-"</term>
<listitem><para>Find all files with only the Read-Only attribute set.
</para></listitem></varlistentry>
</variablelist>
</listitem></varlistentry>
<varlistentry><term><emphasis role="italic">nattrib [optional] [Windows only]</emphasis></term>
<listitem><para>The new attribute mask for setting the attributes of each
matching file. The default mask is "*****". This means not to change the
Archive, Directory, Hidden, Read-Only, and System attributes. The target mask
attributes must appear in the order "ADHRS". This argument is Windows only. It is allowed but ignored on Unix-like
operating systems.</para>
<para>New Attribute
Mask Options </para>
<variablelist>
<varlistentry><term>*</term>
<listitem><para>Do not change the file attribute.
</para></listitem></varlistentry>
<varlistentry><term>+</term>
<listitem><para>Set the file attribute.
</para></listitem></varlistentry>
<varlistentry><term>-</term>
<listitem><para>Clear the file attribute.
</para></listitem></varlistentry>
</variablelist>
<para>New Attribute Mask Examples</para>
<variablelist>
<varlistentry><term>"***+*"</term>
<listitem><para>Set the Read-Only attribute on all files.
</para></listitem></varlistentry>
<varlistentry><term>"-**+*"</term>
<listitem><para>Set the Read-Only attribute and clear the Archive attribute
of each file.</para></listitem></varlistentry>
<varlistentry><term>"+*+++"</term>
<listitem><para>Set all file attributes, except the directory attribute.
</para></listitem></varlistentry>
<varlistentry><term>"-----"</term>
<listitem><para>Clear all attributes on all files.
<note><title>Note</title>
<para>You cannot set the
directory attribute on non-directory files. SysFileTree
returns the file attribute settings after the new attribute mask has been
applied.</para></note>
</para></listitem></varlistentry>
</variablelist>
</listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>Successful.
</para></listitem></varlistentry>
<varlistentry><term>2</term>
<listitem><para>Not enough memory.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Examples:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysFileTree</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysFileTree</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysFileTree</secondary></indexterm>
<programlisting>
/* Find all subdirectories on C: */
call SysFileTree "c:\*.*", "file", "SD"
/* Find all Read-Only files */
call SysFileTree "c:\*.*", "file", "S", "***+*"
/* Clear Archive and Read-Only attributes of files that have them set */
call SysFileTree "c:\*.*", "file", "S", "+**+*", "-**-*"
/****<< Sample Code and Output Example.>>********/
/* Code */
call SysFileTree "c:\win*.", "file", "B"
do i=1 to file.0
say file.i
end
/* Actual Output */
5:24:95 4:59p 0 -D--- C:\WINDOWS
</programlisting>
</section>
<section id="utlSysfork"><title>SysFork (Unix only)</title>
<indexterm><primary>SysFork</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysFork</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysFork()---------------------------------------------------><
]]>
</programlisting>
<para><emphasis role="bold">Returns</emphasis></para>
<para>Returns the process id to the parent process.</para>
<para>Returns <computeroutput>0</computeroutput> to the spawned process.</para>
<para><emphasis role="bold">Example:</emphasis></para>
<para>
This is a complete working example. It can be cut and pasted into a file and executed on a Unix system.
<programlisting>
<![CDATA[
/* Example Unix SysFork() and SysWait() */
pid = SysFork()
if pid == 0 then do
say "I am the child."
code = executeChild()
say "Child : done with execution, will exit with" code
exit code
end
else do
say 'I am the parent, child pid is:' pid
code = executeParent()
say 'Parent: going to wait for child.'
code = SysWait()
say 'Parent: back from waiting. Child exit code:' code
end
say 'Operating system version:' SysVersion()
::routine executeChild
say 'Child : will sleep 1 second.'
j = SysSleep(1)
say 'Child : done sleeping 1. Will do some calculations.'
total = 0
do 786
total += 3
end
say 'Child : 3 * 786 is:' total
say 'Child : will sleep 2 seconds.'
j = SysSleep(2)
say 'Child : done sleeping 2. Will do some calculations.'
total = 0
do 1865
total += 7
end
say 'Child : 7 * 1865 is:' total
say 'Child : will sleep 2 seconds.'
j = SysSleep(2)
say 'Child : done sleeping 2.'
say 'Child : done executing, will return 0.'
return 0
::routine executeParent
say 'Parent: 3 * 786 is:' (3 * 786)
j = SysSleep(2)
say 'Parent: 7 * 1865 is:' (7 * 1865)
return 0
]]>
</programlisting>
</para>
</section>
<section id="utlSysfromunicode"><title>SysFromUnicode (Windows only)</title>
<indexterm><primary>SysFromUnicode</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysFromUnicode</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysFromUnicode--(--string, codepage, mappingflags,----------->
>--, defaultchar, outstem--)-----------------------------------><
]]>
</programlisting>
<para>Maps a UNICODE character string to an ASCII character string. The new character
string and additional information is returned in the outstem.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">string</emphasis></term>
<listitem><para>A string containing the UNICODE characters to be mapped.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">codepage</emphasis></term>
<listitem><para>Specifies the code page used to perform the conversion.
This parameter
can be the value of any code page that is installed or available in the system.
The default is the current original equipment manufacturer (OEM) code-page
identifier for the system.</para>
<para>You can also
specify one of the following values:</para>
<variablelist>
<varlistentry><term>ACP</term>
<listitem><para>ANSI code page.
</para></listitem></varlistentry>
<varlistentry><term>OEMCP</term>
<listitem><para>OEM code page.
</para></listitem></varlistentry>
<varlistentry><term>SYMBOL</term>
<listitem><para>Windows 2000: symbol code page.
</para></listitem></varlistentry>
<varlistentry><term>THREAD_ACP
<indexterm><primary>thread</primary></indexterm>
</term>
<listitem><para>Windows 2000: current thread's ANSI code page.
</para></listitem></varlistentry>
<varlistentry><term>UTF7</term>
<listitem><para>Windows NT 4.0 and Windows 2000: translate using UTF-7.
</para></listitem></varlistentry>
<varlistentry><term>UTF8</term>
<listitem><para>Windows NT 4.0 and Windows 2000: translate using UTF-8. When
this is set, <computeroutput>mappingflags</computeroutput> must be set.
</para></listitem></varlistentry>
</variablelist>
</listitem></varlistentry>
<varlistentry><term><emphasis role="italic">mappingflags</emphasis></term>
<listitem><para>Specifies the handling of unmapped characters. The function
performs more quickly when none of these flags is set.</para>
<para>The following flags can be
used:</para>
<variablelist>
<varlistentry><term>COMPOSITECHECK</term>
<listitem><para>Converts composite characters to precomposed characters.
</para></listitem></varlistentry>
<varlistentry><term>SEPCHARS</term>
<listitem><para>Generates separate characters during conversion. This is the
default conversion behavior.
</para></listitem></varlistentry>
<varlistentry><term>DISCARDNS</term>
<listitem><para>Discards nonspacing characters during conversion.
</para></listitem></varlistentry>
<varlistentry><term>DEFAULTCHAR</term>
<listitem><para>Replaces non-convertible characters with the default character
during conversion.
</para></listitem></varlistentry>
</variablelist>
<para>When <computeroutput>compositecheck</computeroutput> is specified,
the function converts composite characters to precomposed characters.
A composite character consists of a base character and a nonspacing character,
each having different character
values. A precomposed character has a single character value for a combination
of a base and a nonspacing character. In the character è, the "e" is the
base character, and the "grave" accent mark is the nonspacing character.</para>
<para>When <computeroutput>compositecheck</computeroutput> is specified, it can
use the last three flags in this list
(<computeroutput>discardns, sepchars</computeroutput>, and
<computeroutput>defaultchar</computeroutput>)
to customize the conversion to precomposed characters. These flags determine
the function's behavior when there is no precomposed mapping for a combination
of a base and a nonspace character in a Unicode character string. These last
three flags can be used only if the
<computeroutput>compositecheck</computeroutput> flag is set.
The function's default behavior is to generate separate characters
(<computeroutput>sepchars</computeroutput>) for unmapped composite characters.
</para>
</listitem></varlistentry>
<varlistentry><term><emphasis role="italic">defaultchar</emphasis></term>
<listitem><para>Character to be used if a Unicode character cannot be
represented in the specified code page. If this parameter is NULL, a
system default value is used. The function is faster when
<computeroutput>defaultchar</computeroutput> is not used.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">outstem</emphasis></term>
<listitem><para>The name of the stem variable that will contain the converted
result. If the conversion was successful the stem will be composed of
the following value(s):
</para>
<variablelist>
<varlistentry><term>outstem.!USEDDEFAULTchar</term>
<listitem><para>This variable will be set to "1" if the
<emphasis role="italic">defaultchar</emphasis> was used
during the conversion and "0" if it was not.</para></listitem></varlistentry>
<varlistentry><term>outstem.!TEXT</term>
<listitem><para>This variable will contain the converted string.
</para></listitem></varlistentry>
</variablelist>
</listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>No errors.
</para></listitem></varlistentry>
<varlistentry><term>Other</term>
<listitem><para>An error occurred. A <link linkend="systemerrorcodes">Windows
System Error code</link> is returned. This may be one of the following, but
could be others.
</para></listitem></varlistentry>
<varlistentry><term>87</term>
<listitem><para>Incorrect code page or
<computeroutput>codepage</computeroutput> value.
</para></listitem></varlistentry>
<varlistentry><term>1004</term>
<listitem><para>Invalid mapping flags.
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSysgeterrortext"><title>SysGetErrortext</title>
<indexterm><primary>SysGetErrortext</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysGetErrortext</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysGetErrortext(errornumber)--------------------------------><
]]>
</programlisting>
<para>Obtains a string describing the system error identified by the error
number.</para>
<para>Returns a string with the description of the error, or an empty string
if no description is available.</para>
<para><emphasis role="bold">Windows Example:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysGetErrortext</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysGetErrortext</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysGetErrortext</secondary></indexterm>
<programlisting>
err=SysMkDir("c:\temp")
if err \= 0 then
say "Error" err":"SysGetErrortext(err)</programlisting>
<para><emphasis role="bold">Unix Example:</emphasis></para>
<programlisting>
err=SysMkDir("/home/NotKnown/temp")
if err \= 0 then
say "Error" err":"SysGetErrortext(err)
</programlisting>
</section>
<section id="utlSysgetfiledatetime"><title>SysGetFileDateTime</title>
<indexterm><primary>SysGetFileDateTime</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysGetFileDateTime</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysGetFileDateTime(filename-+------------+-)----------------><
+-,--timesel-+
]]>
</programlisting>
<para>Returns the selected data and time attribute of the file
<emphasis role="italic">filename</emphasis> provided
that this is supported by the operating and file system. FAT, for example,
does not support Create/Access. The selector for the time to be returned can
be abbreviated to the first character.</para>
<para>The <emphasis role="italic">filename</emphasis> can
also be a directory name.</para>
<para>The file that you want to query must not be opened by another process or
must at least allow shared writes to query the time stamp.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">filename</emphasis></term>
<listitem><para>The name of the file to be queried.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">timesel</emphasis></term>
<listitem><para>The file time to be queried, namely CREATE, ACCESS, WRITE.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<para>The date and time in the format YYYY-MM-DD HH:MM:SS, or -1 to indicate
that the file date and time query failed</para>
<para><emphasis role="bold">Example:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysGetFileDateTime</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysGetFileDateTime</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysGetFileDateTime</secondary></indexterm>
<programlisting>
Say "File creation time:" SysGetFileDateTime("MyFile.Log", "C")
Say "File last access time:" SysGetFileDateTime("MyFile.Log", "A")
Say "File last update time:" SysGetFileDateTime("MyFile.Log", "W")
Say "Directory creation time:" SysGetFileDateTime("C:\MyDir", "C")
/* in Windows NT */
</programlisting>
</section>
<section id="utlSysgetkey"><title>SysGetKey</title>
<indexterm><primary>SysGetKey</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysGetKey</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysGetKey(-+-----+-)----------------------------------------><
+-opt-+
]]>
</programlisting>
<para>Reads and returns the next key from the keyboard buffer. If the keyboard
buffer is empty, SysGetKey waits until a key is pressed. Unlike the CHARIN
built-in function, SysGetKey does not wait until the Enter key is pressed.
</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">opt</emphasis></term>
<listitem><para>An option controlling screen echoing. Allowed values are:
<variablelist>
<varlistentry><term>"ECHO"</term>
<listitem><para>Echo the pressed key to the screen. This is the default.
</para></listitem></varlistentry>
<varlistentry><term>"NOECHO"</term>
<listitem><para>Do not echo the pressed key.
</para></listitem></varlistentry>
</variablelist>
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSysgetmessage"><title>SysGetMessage (Unix only)</title>
<indexterm><primary>SysGetMessage</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysGetMessage</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysGetMessage(num--+---------------------------------+--)-----><
+--,--filename--+---------------+-+
| | +---------+ | |
| | V | | |
| +----,--str--+--+ |
| +---------+ |
| V | |
+-----,--str-+--------------------+
]]>
</programlisting>
<para>Retrieves a message from a catalog file and replaces the placeholder
<computeroutput>%s</computeroutput> with the text you specify. SysGetMessage
can replace up to 9 placeholders.</para>
<para>This utility is implemented for Unix only.</para>
<para>To create catalog files, consult your system documentation.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">num</emphasis></term>
<listitem><para>The message number.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">filename</emphasis></term>
<listitem><para>The name of the catalog file containing the message. The
default message catalog is <emphasis role="bold">rexx.cat</emphasis>.
SysGetMessage searches along the NLSPATH or uses the absolute path name.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">str</emphasis></term>
<listitem><para>The test for a placeholder (%) in the message. The message can
contain up to 9 placeholders. You must specify as many strings as there are
placeholders in the message.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysGetMessage</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysGetMessage</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysGetMessage</secondary></indexterm>
<programlisting>
<![CDATA[
/* sample code segment using SysGetMessage */
msg = SysGetMessage(485, "rexx.cat", foo)
say msg
/*** Output ***/
Class "foo" not found.
]]>
</programlisting>
</section>
<section id="utlSysgetmessagex"><title>SysGetMessageX (Unix only)</title>
<indexterm><primary>SysGetMessageX</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysGetMessageX</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysGetMessageX(set,num--+---------------------------------+--)-><
+--,--filename--+---------------+-+
| | +---------+ | |
| | V | | |
| +----,--str--+--+ |
| +---------+ |
| V | |
+-----,--str--+-------------------+
]]>
</programlisting>
<para>Retrieves a message from a specific set of
Unix catalog file and replaces the placeholder
<computeroutput>%s</computeroutput> with the text you specify. SysGetMessageX
can replace up to 9 placeholders.</para>
<para>This utility is implemented for Unix only. Do not use it for
platform-independent programs.</para>
<para>To create catalog files, consult your system documentation.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">set</emphasis></term>
<listitem><para>The message set.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">num</emphasis></term>
<listitem><para>The message number.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">filename</emphasis></term>
<listitem><para>The name of the catalog file containing the message. The
default message catalog is <emphasis role="bold">rexx.cat</emphasis>.
SysGetMessageX searches along the NLSPATH or uses the absolute path name.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">str</emphasis></term>
<listitem><para>The test for a placeholder (%) in the message. The message can
contain up to 9 placeholders. You must specify as many strings as there are
placeholders in the message.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysGetMessageX</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysGetMessageX</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysGetMessageX</secondary></indexterm>
<programlisting>
<![CDATA[
/* sample code segment using SysGetMessage */
msg = SysGetMessageX(1, 485, "rexx.cat", foo)
say msg
/*** Output ***/
Class "foo" not found.
]]>
</programlisting>
</section>
<section id="utlSysini"><title>SysIni (Windows only)</title>
<indexterm><primary>SysIni</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysIni</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysIni(-+---------+-,app,key,val,stem-)---------------------><
+-inifile-+
]]>
</programlisting>
<para>Allows limited access to INI file variables. Variables are stored in the
INI file under Application Names and their associated key names or keywords.
You can use SysIni to share variables between applications or as a way of
implementing GLOBALV in the Windows operating system. Be careful when
changing application profile information.</para>
<note><title>Note</title>
<para>SysIni works on all types of data stored in an INI file (text,
numeric, or binary).</para></note>
<para>When SysIni successfully sets or deletes key values, it returns "".
For a successful query, it returns the value of the specified application
keyword.</para>
<para>SysIni may return the string <computeroutput>ERROR:</computeroutput>
when an error occurs. Possible error conditions include:</para>
<itemizedlist>
<listitem><para>An attempt was made to query or delete an application/key pair
that does not exist.</para></listitem>
<listitem><para>An error opening the profile file occurred. You may have
specified the current user or system INI file with a relative file
specification. Make sure to use the full file specification
(specify drive, path, and file name).</para></listitem>
</itemizedlist>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">inifile</emphasis></term>
<listitem><para>The name of the INI file with which you would like to work. The
default is WIN.INI.
<note><title>Note</title>
<para>If this argument does not contain a fully qualified file name, the Windows
operating system searches for the file in the Windows directory. Therefore to
work with a file outside of the Windows directory, specify the full path name of
the file.
</para></note>
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">app</emphasis></term>
<listitem><para>The application name or some other meaningful value with which
you want to store keywords (some sort of data).
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">key</emphasis></term>
<listitem><para>The name of a keyword to hold data.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">val</emphasis></term>
<listitem><para>The value to associate with the keyword of the specified
application. This can be <computeroutput>"DELETE:"</computeroutput> or
<computeroutput>"ALL:"</computeroutput>.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">stem</emphasis></term>
<listitem><para>The name of a Rexx stem variable collection in which to store
the resultant information. SysIni sets Rexx variable
<emphasis role="italic">stem.0</emphasis> to the number of elements
returned and stores these elements in
<emphasis role="italic">stem.1</emphasis> to
<emphasis role="italic">stem.n</emphasis>.
</para></listitem></varlistentry>
</variablelist>
<para>Sysini has six modes. The modes and the syntax variations are as follows:
</para>
<programlisting>
<![CDATA[
>>-SysIni(-+---------+-,app,key,val)---------------------------><
+-inifile-+
]]>
</programlisting>
<para>Sets a single key value.</para>
<programlisting>
<![CDATA[
>>-SysIni(-+---------+-,app,key)-------------------------------><
+-inifile-+
]]>
</programlisting>
<para>Queries a single key value.</para>
<programlisting>
<![CDATA[
>>-SysIni(-+---------+-,app,key--,"DELETE:"-)------------------><
+-inifile-+
]]>
</programlisting>
<para>Deletes a single key.</para>
<programlisting>
<![CDATA[
>>-SysIni(-+---------+-,app-+------------+-)-------------------><
+-inifile-+ +-,"DELETE:"-+
]]>
</programlisting>
<para>Deletes an application and all associated keys.</para>
<programlisting>
<![CDATA[
>>-SysIni(-+---------+-,app--,"ALL:"--,"stem"-)----------------><
+-inifile-+
]]>
</programlisting>
<para>Queries names of all keys associated with a certain application.</para>
<programlisting>
<![CDATA[
>>-SysIni(-+---------+-,"ALL:"--,"stem"-)----------------------><
+-inifile-+
]]>
</programlisting>
<para>Queries the names of all applications.</para>
<para><emphasis role="bold">Examples:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysIni</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysIni</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysIni</secondary></indexterm>
<programlisting>
/* Sample code segments */
</programlisting>
<para></para>
<programlisting>
/*** Save the user entered name under the key "NAME" of *****
**** the application "MYAPP". ****/
pull name .
call SysIni , "MYAPP", "NAME", name /* Save the value */
say SysIni(, "MYAPP", "NAME") /* Query the value */
call SysIni , "MYAPP" /* Delete all MYAPP info */
exit
</programlisting>
<para></para>
<programlisting>
/**** Type all WIN.INI file information to the screen *****/
call SysIni "WIN.INI", "All:", "Apps."
if Result \= "ERROR:" then
do i = 1 to Apps.0
call SysIni "WIN.INI", Apps.i, "All:", "Keys"
if Result \= "ERROR:" then
do j=1 to Keys.0
val = SysIni("WIN.INI", Apps.i, Keys.j)
say left(Apps.i, 20) left(Keys.j, 20),
"Len=x"Left(d2x(length(val)),4) left(val, 20)
end
end
exit
</programlisting>
</section>
<section id="utlSysisfile"><title>SysIsFile</title>
<indexterm><primary>SysIsFile</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysIsFile</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysIsFile(filename)-----------------------------------------><
]]>
</programlisting>
<para>Checks for the existence of a file. This function does not support
wildcard specifications.</para>
<para>On Linux/Unix block devices are also considered to be regular files
by this function.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">filename</emphasis></term>
<listitem><para>The name of the file to check for the existence of.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Returns:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>The file does not exist.
</para></listitem></varlistentry>
<varlistentry><term>1</term>
<listitem><para>The file exists.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<programlisting>
if SysIsFile(InputFile) then say "File Exists!"
else say "File does not exist."
</programlisting>
</section>
<section id="utlSysisfilecompressed"><title>SysIsFileCompressed (Windows only)</title>
<indexterm><primary>SysIsFileCompressed</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysIsFileCompressed</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysIsFileCompressed(filename)-------------------------------><
]]>
</programlisting>
<para>Checks if a file is compressed. This function does not support
wildcard specifications.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">filename</emphasis></term>
<listitem><para>The name of the file to check.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Returns:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>The file is not compressed or does not exist.
</para></listitem></varlistentry>
<varlistentry><term>1</term>
<listitem><para>The file is compressed.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<programlisting>
if SysIsFileCompressed(InputFile) then say "File is compressed!"
else say "File is not compressed or does not exist."
</programlisting>
</section>
<section id="utlSysisfiledirectory"><title>SysIsFileDirectory</title>
<indexterm><primary>SysIsFileDirectory</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysIsFileDirectory</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysIsFileDirectory(dirname)---------------------------------><
]]>
</programlisting>
<para>Checks for the existence of a subdirectory. This function does not support
wildcard specifications.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">dirname</emphasis></term>
<listitem><para>The name of the subdirectory to check for the existence of.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Returns:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>The subdirectory does not exist.
</para></listitem></varlistentry>
<varlistentry><term>1</term>
<listitem><para>The subdirectory exists.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<programlisting>
if SysIsFileDirectory(InputFile) then say "Subdirectory Exists!"
else say "Subdirectory does not exist."
</programlisting>
</section>
<section id="utlSysisfileencrypted"><title>SysIsFileEncrypted (Windows only)</title>
<indexterm><primary>SysIsFileEncrypted</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysIsFileEncrypted</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysIsFileEncrypted(filename)--------------------------------><
]]>
</programlisting>
<para>Checks if a file is encrypted. This function does not support
wildcard specifications.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">filename</emphasis></term>
<listitem><para>The name of the file to check.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Returns:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>The file is not encrypted or does not exist.
</para></listitem></varlistentry>
<varlistentry><term>1</term>
<listitem><para>The file is encrypted.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<programlisting>
if SysIsFileEncrypted(InputFile) then say "File is encrypted!"
else say "File is not encrypted or does not exist."
</programlisting>
</section>
<section id="utlSysisfilelink"><title>SysIsFileLink</title>
<indexterm><primary>SysIsFileLink</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysIsFileLink</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysIsFileLink(linkname)-------------------------------------><
]]>
</programlisting>
<para>Checks for the existence of a link. This function does not support
wildcard specifications.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">linkname</emphasis></term>
<listitem><para>The name of the link to check for the existence of.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Returns:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>The link does not exist or it is not a link.
</para></listitem></varlistentry>
<varlistentry><term>1</term>
<listitem><para>The link exists.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<programlisting>
if SysIsFileLink(InputFile) then say "Link Exists!"
else say "Link does not exist."
</programlisting>
</section>
<section id="utlSysisfilenotcontentindexed">
<title>SysIsFileNotContentIndexed (Windows only)</title>
<indexterm><primary>SysIsFileNotContentIndexed</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysIsFileNotContentIndexed</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysIsFileNotContentIndexed(filename)------------------------><
]]>
</programlisting>
<para>Checks if a file is flagged to be indexed by the Index Service.
This function does not support wildcard specifications.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">filename</emphasis></term>
<listitem><para>The name of the file to check.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Returns:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>The file is not flagged to be Indexed or does not exist.
</para></listitem></varlistentry>
<varlistentry><term>1</term>
<listitem><para>The file is flagged to be Indexed.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<programlisting>
if SysIsFileNotContentIndexed(InputFile) then say "File is flagged to be Indexed!"
else say "File is not flagged to be Indexed."
</programlisting>
</section>
<section id="utlSysisfileoffline"><title>SysIsFileOffline (Windows only)</title>
<indexterm><primary>SysIsFileOffline</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysIsFileOffline</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysIsFileOffline(filename)----------------------------------><
]]>
</programlisting>
<para>Checks if a file is flagged as Offline.
This function does not support wildcard specifications.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">filename</emphasis></term>
<listitem><para>The name of the file to check.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Returns:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>The file is not flagged as Offline or does not exist.
</para></listitem></varlistentry>
<varlistentry><term>1</term>
<listitem><para>The file is flagged as Offline.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<programlisting>
if SysIsFileOffline(InputFile) then say "File is flagged as Offline!"
else say "File is not flagged as Offline."
</programlisting>
</section>
<section id="utlSysisfilesparse"><title>SysIsFileSparse (Windows only)</title>
<indexterm><primary>SysIsFileSparse</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysIsFileSparse</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysIsFileSparse(filename)-----------------------------------><
]]>
</programlisting>
<para>Checks if a file is flagged as Sparse.
This function does not support wildcard specifications.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">filename</emphasis></term>
<listitem><para>The name of the file, subdirectory or link to check.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Returns:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>The file is not flagged as Sparse or does not exist.
</para></listitem></varlistentry>
<varlistentry><term>1</term>
<listitem><para>The file is flagged as Sparse.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<programlisting>
if SysIsFileSparse(InputFile) then say "File is Sparse!"
else say "File is not Sparse."
</programlisting>
</section>
<section id="utlSysisfiletemporary"><title>SysIsFileTemporary (Windows only)</title>
<indexterm><primary>SysIsFileTemporary</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysIsFileTemporary</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysIsFileTemporary(filename)--------------------------------><
]]>
</programlisting>
<para>Checks if a file is flagged as Temporary.
This function does not support wildcard specifications.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">filename</emphasis></term>
<listitem><para>The name of the file, subdirectory or link to check.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Returns:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>The file is not flagged as Temporary or does not exist.
</para></listitem></varlistentry>
<varlistentry><term>1</term>
<listitem><para>The file is flagged as Temporary.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<programlisting>
if SysIsFileTemporary(InputFile) then say "File is Temporary!"
else say "File is not Temporary."
</programlisting>
</section>
<section id="utlSyslinver"><title>SysLinVer (Linux Only)</title>
<indexterm><primary>SysLinVer</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysLinVer</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysLinVer()-------------------------------------------------><
]]>
</programlisting>
<para>
Returns a string identifying the Linux system version. The first word of the returned string is Linux
and the second word in the string identifies the kernel version. A possible output for a Linux system
might be:
</para>
<programlisting>
Say SysLinVer() -> "Linux 2006.2.6.18-1.2798.fc6"
</programlisting>
</section>
<section id="utlSysloadfuncs"><title>SysLoadFuncs</title>
<indexterm><primary>SysLoadFuncs</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysLoadFuncs</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysLoadFuncs------------------------------------------------><
]]>
</programlisting>
<para>
From ooRexx 4.0.0 and on this function does nothing.
</para>
</section>
<section id="utlSysloadrexxmacrospace"><title>SysLoadRexxMacroSpace</title>
<indexterm><primary>SysLoadRexxMacroSpace</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysLoadRexxMacroSpace</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysLoadRexxMacroSpace(file)---------------------------------><
]]>
</programlisting>
<para>Loads functions from a saved macrospace file. SysLoadRexxMacroSpace
returns the RexxLoadMacroSpace return code.</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">file</emphasis></term>
<listitem><para>The file used to load functions into the Rexx macrospace.
SysSaveRexxMacroSpace must have created the file.
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSysmkdir"><title>SysMkDir</title>
<indexterm><primary>SysMkDir</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysMkDir</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysMkDir(dirspec)-------------------------------------------><
]]>
</programlisting>
<para>Creates a specified directory.</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">dirspec</emphasis></term>
<listitem><para>The directory to be created.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>Directory creation was successful.
</para></listitem></varlistentry>
<varlistentry><term>Other</term>
<listitem><para>An error occurred. On Windows, a <link linkend="systemerrorcodes">Windows System Error
code</link> is returned. This may be one of the following, but could be others.
</para></listitem></varlistentry>
<varlistentry><term>2</term>
<listitem><para>File not found.
</para></listitem></varlistentry>
<varlistentry><term>3</term>
<listitem><para>Path not found.
</para></listitem></varlistentry>
<varlistentry><term>5</term>
<listitem><para>Access denied.
</para></listitem></varlistentry>
<varlistentry><term>26</term>
<listitem><para>Not a DOS disk.
</para></listitem></varlistentry>
<varlistentry><term>87</term>
<listitem><para>Invalid parameter.
</para></listitem></varlistentry>
<varlistentry><term>108</term>
<listitem><para>Drive locked.
</para></listitem></varlistentry>
<varlistentry><term>183</term>
<listitem><para>Directory already exists.
</para></listitem></varlistentry>
<varlistentry><term>206</term>
<listitem><para>File name exceeds range.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysMkDir</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysMkDir</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysMkDir</secondary></indexterm>
<programlisting>
/* Code */
call SysMkDir "rexx"
</programlisting>
</section>
<section id="utlSysopeneventsem"><title>SysOpenEventSem</title>
<indexterm><primary>SysOpenEventSem</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysOpenEventSem</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysOpenEventSem(name)---------------------------------------><
]]>
</programlisting>
<para>Opens an event semaphore. SysOpenEventSem
returns a handle to the semaphore, or zero if an error occurred.</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">name</emphasis></term>
<listitem><para>The name of the event semaphore created by SysCreateEventSem.
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSysopenmutexsem"><title>SysOpenMutexSem</title>
<indexterm><primary>SysOpenMutexSem</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysOpenMutexSem</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysOpenMutexSem(name)---------------------------------------><
]]>
</programlisting>
<para>Opens a mutex semaphore. SysOpenMutexSem
returns a handle to the semaphore, or zero if an error occurred.</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">name</emphasis></term>
<listitem><para>The name of the mutex semaphore created by SysCreateMutexSem.
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSysposteventsem"><title>SysPostEventSem</title>
<indexterm><primary>SysPostEventSem</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysPostEventSem</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysPostEventSem(handle)-------------------------------------><
]]>
</programlisting>
<para>Posts an event semaphore.</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">handle</emphasis></term>
<listitem><para>A handle returned from a previous SysCreateEventSem call.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>No errors.
</para></listitem></varlistentry>
<varlistentry><term>Other</term>
<listitem><para>An error occurred. On Windows, a <link linkend="systemerrorcodes">Windows System Error
code</link> is returned. This may be one of the following, but could be others.
</para></listitem></varlistentry>
<varlistentry><term>6</term>
<listitem><para>Invalid handle.
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSyspulseeventsem"><title>SysPulseEventSem (Windows only)</title>
<indexterm><primary>SysPulseEventSem</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysPulseEventSem</secondary></indexterm>
<indexterm><primary>thread</primary></indexterm>
<programlisting>
<![CDATA[
>>-SysPulseEventSem(handle)------------------------------------><
]]>
</programlisting>
<para>Posts and immediately resets an event
semaphore. It sets the state of the event to signaled (available), releases
any waiting threads, and resets it to nonsignaled (unavailable) automatically.
If the event is manual, all waiting threads are released, the event is set
to nonsignaled, and PulseEvent returns. If the event is automatic, a single
thread is released, the event is set to nonsignaled, and PulseEvent returns.
If no threads are waiting, or no threads can be released immediately, PulseEvent
sets the state of the event to nonsignaled and returns.</para>
<para>SysPulseEventSem returns 0 on success and a
<link linkend="systemerrorcodes">Windows System Error code</link> is returned on
error.
.</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">handle</emphasis></term>
<listitem><para>The handle of an event semaphore previously created
by SysCreateEventSem.
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSysqueryprocess"><title>SysQueryProcess</title>
<indexterm><primary>SysQueryProcess</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysQueryProcess</secondary></indexterm>
<para><emphasis role="bold">Windows</emphasis></para>
<indexterm><primary>thread</primary></indexterm>
<programlisting>
<![CDATA[
+-PID---+
>>-SysQueryProcess(" -+-TID---+- ")----------------------------><
+-PPRIO-+
+-TPRIO-+
+-PTIME-+
+-TTIME-+
]]>
</programlisting>
<para><emphasis role="bold">Unix</emphasis></para>
<programlisting>
<![CDATA[
+-PID------+
>>-SysQueryProcess(" -+----------+- ")-------------------------><
+-PPID-----+
+-PPRIO----+
+-PTIME----+
+-PMEM-----+
+-PSWAPS---+
+-PRCVDSIG-+
]]>
</programlisting>
<para>Retrieves information about the current
process or Windows thread.</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">info</emphasis></term>
<listitem><para>The kind of information requested:
<variablelist>
<varlistentry><term>PID</term>
<listitem><para>Returns the process ID of the current process.
</para></listitem></varlistentry>
<varlistentry><term>PPID</term>
<listitem><para>Returns the parent process ID of the current process.
</para></listitem></varlistentry>
<varlistentry><term>TID</term>
<listitem><para>Returns the thread ID of the current thread.
</para></listitem></varlistentry>
<varlistentry><term>PPRIO</term>
<listitem><para>Returns the priority class of the current process.
</para></listitem></varlistentry>
<varlistentry><term>TPRIO</term>
<listitem><para>Returns the relative priority of the current thread.
</para></listitem></varlistentry>
<varlistentry><term>PTIME</term>
<listitem><para>Returns time information on the current process.
</para></listitem></varlistentry>
<varlistentry><term>TTIME</term>
<listitem><para>Returns time information on the current thread.
</para></listitem></varlistentry>
<varlistentry><term>PMEM</term>
<listitem><para>Returns the maximum memory (RSS) used by the current
process.</para></listitem></varlistentry>
<varlistentry><term>PRCVDSIG</term>
<listitem><para>Returns the number of signals that have been received by
the process.
</para></listitem></varlistentry>
</variablelist>
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<itemizedlist>
<listitem><para>For PID, PPID or TID: an ID</para></listitem>
<listitem><para>For Windows PPRIO: "IDLE", "NORMAL",
"HIGH", "REALTIME",
or "UNKNOWN"</para></listitem>
<listitem><para>For Unix PPRIO: a number from -20 to +20.
</para></listitem>
<listitem><para>For TPRIO: "IDLE", "LOWEST",
"BELOW_NORMAL", "NORMAL", "ABOVE_NORMAL",
"HIGHEST", "TIME_CRITICAL",
or "UNKNOWN"</para></listitem>
<listitem><para>For Windows PTIME or TTIME: the creation date and time, the
amount of time that the process executed in kernel mode, and the amount of time
that the process executed in user mode</para></listitem>
<listitem><para>For Unix PTIME: the summary and the duration that the process
executed in kernel mode, and the duration that the process executed in
user mode</para></listitem></itemizedlist>
</section>
<section id="utlSysqueryrexxmacro"><title>SysQueryRexxMacro</title>
<indexterm><primary>SysQueryRexxMacro</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysQueryRexxMacro</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysQueryRexxMacro(name)-------------------------------------><
]]>
</programlisting>
<para>Queries the existence of a macrospace function. SysQueryRexxMacro returns
the placement order of the macrospace function or a null string ("")
if the function does not exist in the macrospace.</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">name</emphasis></term>
<listitem><para>The name of a function in the Rexx macrospace.
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSysreleasemutexsem"><title>SysReleaseMutexSem</title>
<indexterm><primary>SysReleaseMutexSem</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysReleaseMutexSem</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysReleaseMutexSem(handle)----------------------------------><
]]>
</programlisting>
<para>Releases a mutex semaphore.</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">handle</emphasis></term>
<listitem><para>A handle returned from a previous SysCreateMutexSem call.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>No errors.
</para></listitem></varlistentry>
<varlistentry><term>Other</term>
<listitem><para>An error occurred. On Windows, a <link linkend="systemerrorcodes">Windows System Error
code</link> is returned. This may be one of the following, but could be others.
</para></listitem></varlistentry>
<varlistentry><term>6</term>
<listitem><para>Invalid handle.
</para></listitem></varlistentry>
<varlistentry><term>105</term>
<listitem><para>Owner died.
</para></listitem></varlistentry>
<varlistentry><term>288</term>
<listitem><para>Not owner.
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSysreorderrexxmacro"><title>SysReorderRexxMacro</title>
<indexterm><primary>SysReorderRexxmacro</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysReorderRexxMacro</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysReorderRexxMacro(name,order)-----------------------------><
]]>
</programlisting>
<para>Reorders a routine loaded in the Rexx macrospace. SysReorderRexxMacro
returns the RexxReorderMacro return code.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">name</emphasis></term>
<listitem><para>The name of a function in the macrospace.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">order</emphasis></term>
<listitem><para>The new macro search order. The order can be "B" (Before) or "A"
(After).
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSysrequestmutexsem"><title>SysRequestMutexSem</title>
<indexterm><primary>SysRequestMutexSem</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysRequestMutexSem</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysRequestMutexSem(handle-+----------+-)--------------------><
+-,timeout-+
]]>
</programlisting>
<para>Requests a mutex semaphore. SysRequestMutexSem
returns the WaitForSingleObject return code.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">handle</emphasis></term>
<listitem><para>A handle returned from a previous SysCreateMutexSem call.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">timeout</emphasis></term>
<listitem><para>The time, in milliseconds, to wait on the semaphore.
The default <emphasis role="italic">timeout</emphasis> is an infinite wait.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>No errors.
</para></listitem></varlistentry>
<varlistentry><term>Other</term>
<listitem><para>An error occurred. On Windows, a <link linkend="systemerrorcodes">Windows System Error
code</link> is returned. This may be one of the following, but could be others.
</para></listitem></varlistentry>
<varlistentry><term>6</term>
<listitem><para>Invalid handle.
</para></listitem></varlistentry>
<varlistentry><term>103</term>
<listitem><para>Too many requests.
</para></listitem></varlistentry>
<varlistentry><term>121</term>
<listitem><para>Error timeout.
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSysreseteventsem"><title>SysResetEventSem</title>
<indexterm><primary>SysResetEventSem</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysResetEventSem</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysResetEventSem(handle)------------------------------------><
]]>
</programlisting>
<para>Resets an event semaphore..</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">handle</emphasis></term>
<listitem><para>A handle returned from a previous SysCreateEventSem call.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>No errors.
</para></listitem></varlistentry>
<varlistentry><term>Other</term>
<listitem><para>An error occurred. On Windows, a <link linkend="systemerrorcodes">Windows System Error
code</link> is returned. This may be one of the following, but could be others.
</para></listitem></varlistentry>
<varlistentry><term>6</term>
<listitem><para>Invalid handle.
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSysrmdir"><title>SysRmDir</title>
<indexterm><primary>SysRmDir</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysRmDir</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysRmDir(dirspec)-------------------------------------------><
]]>
</programlisting>
<para>Deletes a specified file directory without your confirmation. </para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">dirspec</emphasis></term>
<listitem><para>The directory that should be deleted.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>Directory removal was successful.
</para></listitem></varlistentry>
<varlistentry><term>Other</term>
<listitem><para>An error occurred. On Windows, a <link linkend="systemerrorcodes">Windows System Error
code</link> is returned. This may be one of the following, but could be others.
</para></listitem></varlistentry>
<varlistentry><term>2</term>
<listitem><para>File not found.
</para></listitem></varlistentry>
<varlistentry><term>3</term>
<listitem><para>Path not found.
</para></listitem></varlistentry>
<varlistentry><term>5</term>
<listitem><para>Access denied or busy.
</para></listitem></varlistentry>
<varlistentry><term>16</term>
<listitem><para>Current directory.
</para></listitem></varlistentry>
<varlistentry><term>26</term>
<listitem><para>Not a DOS disk.
</para></listitem></varlistentry>
<varlistentry><term>32</term>
<listitem><para>Sharing violation.
</para></listitem></varlistentry>
<varlistentry><term>108</term>
<listitem><para>Drive locked.
</para></listitem></varlistentry>
<varlistentry><term>123</term>
<listitem><para>Invalid name.
</para></listitem></varlistentry>
<varlistentry><term>145</term>
<listitem><para>Directory not empty.
</para></listitem></varlistentry>
<varlistentry><term>146</term>
<listitem><para>Is Subst Path.
</para></listitem></varlistentry>
<varlistentry><term>147</term>
<listitem><para>Is Join Path.
</para></listitem></varlistentry>
<varlistentry><term>206</term>
<listitem><para>File name exceeds range.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysRmDir</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysRmDir</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysRmDir</secondary></indexterm>
<programlisting>
/* Code */
call SysRmDir "c:\rexx"
</programlisting>
</section>
<section id="utlSyssaverexxmacrospace"><title>SysSaveRexxMacroSpace</title>
<indexterm><primary>SysSaveRexxMacroSpace</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysSaveRexxMacroSpace</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysSaveRexxMacroSpace(file)---------------------------------><
]]>
</programlisting>
<para>Saves the Rexx macrospace. SysSaveRexxMacroSpace returns the RexxSaveMacroSpace
return code.</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">file</emphasis></term>
<listitem><para>The file used to save the functions in the Rexx macrospace.
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSyssearchpath"><title>SysSearchPath</title>
<indexterm><primary>SysSearchPath</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysSearchPath</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysSearchPath(path,filename-+-----------+-)-----------------><
+-,--option-+
]]>
</programlisting>
<para>Searches the specified file path for the specified file. If the file is
found, the search returns the full file specification of the first file found
within the path, and then stops searching. If the file is not found, the search
returns a null string.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">path</emphasis></term>
<listitem><para>An environment variable name. The environment variable must
contain a list of file directories. Examples are "PATH" or "DPATH".
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">filename</emphasis></term>
<listitem><para>The file for which the path is to be searched.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">option</emphasis></term>
<listitem><para>Specifies where the search starts.
<variablelist>
<varlistentry><term>"C"</term>
<listitem><para>Starts the search at the current directory and then along the
specified path. This is the default.
</para></listitem></varlistentry>
<varlistentry><term>"N"</term>
<listitem><para>Starts the search at the path, not at the current directory.
</para></listitem></varlistentry>
</variablelist>
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysSearchPath</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysSearchPath</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysSearchPath</secondary></indexterm>
<programlisting>
/* Code */
fspec = SysSearchPath("PATH", "CMD.EXE")
say "CMD.EXE is located at" fspec
/* Output */
CMD.EXE is located at C:\WIN\CMD.EXE
</programlisting>
</section>
<section id="utlSyssetfiledatetime"><title>SysSetFileDateTime</title>
<indexterm><primary>SysSetFileDateTime</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysSetFileDateTime</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysSetFileDateTime(filename-+--------------------------------+-)-><
+-,--+---------+--+------------+-+
+-newdate-+ +-,--newtime-+
]]>
</programlisting>
<para>Modifies the "Last Modified" date and time of file
<emphasis role="italic">filename</emphasis>. If no new date or time is
specified the file date or time is set to the current time (TOUCH).
If only the date is omitted, the "Last Modified"
date remains unchanged. If only the time is omitted, the "Last
Modified" time remains unchanged.</para>
<para>The <emphasis role="italic">filename</emphasis> can
also be a directory name.</para>
<para>The file that you want to change must not be opened by another process
or must at least allow shared writes to update the time stamp.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">filename</emphasis></term>
<listitem><para>The name of the file to be updated.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">newdate</emphasis></term>
<listitem><para>The new date for the file, to be specified in the format
YYYY-MM-DD, where YYYY > 1800.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">newtime</emphasis></term>
<listitem><para>The new time for the file, to be specified in the format
HH:MM:SS (24-hour format).
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>The file date and time were updated correctly.
</para></listitem></varlistentry>
<varlistentry><term>-1</term>
<listitem><para>The update of the file date or time failed.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysSetFileDateTime</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysSetFileDateTime</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysSetFileDateTime</secondary></indexterm>
<programlisting>
Call SysSetFileDateTime "MyFile.Log" /* touch file */
Call SysSetFileDateTime "MyFile.Log", "1998-12-17"
Call SysSetFileDateTime "MyFile.Log", , "16:37:21"
Call SysSetFileDateTime "MyFile.Log", "1998-12-17", "16:37:21"
Call SysSetFileDateTime "C:\MyDir" /* touch dir on Windows NT */
</programlisting>
</section>
<section id="utlSyssetpriority"><title>SysSetPriority</title>
<indexterm><primary>SysSetPriority</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysSetPriority</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysSetPriority(class,delta)---------------------------------><
]]>
</programlisting>
<para>Changes the priority of the current process. A return code
of 0 indicates no error.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">class</emphasis></term>
<listitem><para>The new process priority class. The allowed classes are:
<variablelist>
<varlistentry><term>0 or "IDLE"</term>
<listitem><para>Idle time priority
</para></listitem></varlistentry>
<varlistentry><term>1 or "NORMAL"</term>
<listitem><para>Regular priority
</para></listitem></varlistentry>
<varlistentry><term>2 or "HIGH"</term>
<listitem><para>High or time-critical priority
</para></listitem></varlistentry>
<varlistentry><term>3 or "REALTIME"</term>
<listitem><para>Real-time priority
</para></listitem></varlistentry>
</variablelist>
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">delta</emphasis></term>
<listitem><para>The change applied to the process priority level.
<emphasis role="italic">delta</emphasis> must be in the range -15 to +15.
It can also be a symbolic name:
<itemizedlist>
<listitem><para>"IDLE" for -15</para></listitem>
<listitem><para>"LOWEST" for -2</para></listitem>
<listitem><para>"BELOW_NORMAL" for -1</para></listitem>
<listitem><para>"NORMAL" for 0</para></listitem>
<listitem><para>"ABOVE_NORMAL" for 1</para></listitem>
<listitem><para>"HIGHEST" for 2</para></listitem>
<listitem><para>"TIME_CRITICAL" for 15</para></listitem>
</itemizedlist>
</para></listitem></varlistentry>
</variablelist>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>No errors.
</para></listitem></varlistentry>
<varlistentry><term>Other</term>
<listitem><para>An error occurred. A <link linkend="systemerrorcodes">Windows
System Error code</link> is returned. This may be one of the following, but
could be others.
</para></listitem></varlistentry>
<varlistentry><term>307</term>
<listitem><para>Invalid priority class.
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSysshutdownsystem"><title>SysShutdownSystem (Windows only)</title>
<indexterm><primary>SysShutdownSystem</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysShutdownSystem</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysShutdownSystem(-+----------+-+----------+-+----------+-+--------+-+---------+-)---><
+-computer-+ +-,message-+ +-,timeout-+ +-,force-+ +-,reboot-+
]]>
</programlisting>
<para>
Provides an interface to the <computeroutput>InitiateSystemShutdown()</computeroutput> API on Windows.
If the user has sufficient privileges, this function can be used to shut down the local machine or a
remote system. In general all users have sufficient privileges to shut down the local machine and only
Administrators have sufficient privileges to shut down remote machines.
</para>
<para>
The user of this function is <emphasis role="bold">strongly</emphasis> encouraged to read the Microsoft
documentation for <computeroutput>InitiateSystemShutdown()</computeroutput> to understand the finer
points to using this function. The documentation is freely available online. A Google search
using <emphasis role="italic">InitiateSystemShutdown MSDN</emphasis> will provide a link to the
documentation. In particular, this function can be used to force a shut down of a system while users
are logged on and applications have unsaved data.
</para>
<para>
If the <emphasis role="italic">timeout</emphasis> argument is not 0, a shut down dialog is displayed on
the machine being shut down, naming the user who initiated the shut down, a timer counting down the
seconds until the machine is shut down, and prompting the user to log off. This dialog can be moved but
it can not be closed and remains on top of all other windows on the system.
</para>
<para>
If any open application has unsaved data, the operating system gives the application a chance to prompt
the user to save and close the application. If the <emphasis role="italic">force</emphasis> argument is
false, the shut down will be delayed until the user responds, and ultimately the user could cancel the
shut down. If the <emphasis role="italic">force</emphasis> argument is true the system will force the
application closed whether the data gets saved or not. The application is still given a chance to
prompt the user to save the data, but the user only has a few seconds to respond before the system
forcibly closing the application.
</para>
<para>
The implications of the preceding two paragraphs are this, if the <emphasis
role="italic">timeout</emphasis> argument is 0 and the <emphasis role="italic">force</emphasis>
argument is true, the system immediately shuts down and any unsaved data is forever lost. This is why
the user of this function is encouraged to fully understand this function before using it.
</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis>computer</emphasis></term>
<listitem>
<para>
Indicates which system to shut down. If omitted or the empty string, the local machine is shut down.
Otherwise this should be the network name of the remote machine.
</para></listitem></varlistentry>
<varlistentry><term><emphasis>message</emphasis></term>
<listitem><para>
An additional message that is added to the shut down dialog. If omitted, no additional message is
added.
</para></listitem></varlistentry>
<varlistentry><term><emphasis>timeout</emphasis></term>
<listitem><para>
The time, in seconds, before the system is shut down. If this value is 0, the system is immediately
shut down and no shut down dialog is displayed. The shut down can not be aborted. If omitted the
default time out is 30 seconds.
</para></listitem></varlistentry>
<varlistentry><term><emphasis>force</emphasis></term>
<listitem>
<para>
If this argument is true, applications with unsaved data will be forced close by the system whether the
data is saved or not. If false, the shut down is delayed until applications with unsaved data responds.
If an application does not respond, the user will be prompted by the system to end the application. At
this point, if the user chooses not to forcibly end the application, the shut down will be aborted.
</para>
<para>
Please <emphasis role="bold">note</emphasis> some consequences of this argument as described by
Microsoft. If this argument is false, i.e. applications are not forced to close, and an application
with unsaved changes is running on the console session, the shutdown will remain in progress until the
user logged into the console session aborts the shutdown, saves changes, closes the application, or
forces the application to close. During this period, the shutdown <emphasis role="italic">may not
be</emphasis> aborted except by the console user, and another shutdown <emphasis role="italic">may not
be</emphasis> initiated. Using true for this argument prevents that situation. But, using true can also
result in unsaved data being lost.
</para></listitem></varlistentry>
<varlistentry><term><emphasis>reboot</emphasis></term>
<listitem><para>
If this argument is true, the system is rebooted after the shut down. If it is false, the system is
shut down. The default if omitted is false.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Returns:</emphasis></para>
<para>
Returns <computeroutput>0</computeroutput> for success or a <link linkend="systemerrorcodes">Windows
System Error code</link> for failure. For instance a return of 1300 would indicate the user does not
have sufficient privileges to shut down the named system. Use <link
linkend="utlSysgeterrortext">SysGetErrorText</link>() to get a generic text description for any Windows
System Error code. For example, the description for error code 1300 is <emphasis role="italic">Not all
privileges referenced are assigned to the caller.</emphasis>
</para>
</section>
<section id="utlSyssleep"><title>SysSleep</title>
<indexterm><primary>SysSleep</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysSleep</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysSleep(secs)----------------------------------------------><
]]>
</programlisting>
<para>Pauses a Rexx program for a specified time interval.</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">secs</emphasis></term>
<listitem><para>The number of seconds for which the program is to be paused.
You can specify up to seven decimal places in the number.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysSleep</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysSleep</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysSleep</secondary></indexterm>
<programlisting>
Say "Now paused for 2 seconds ..."
Call SysSleep 2
Say "Now paused for 0.1234567 seconds ..."
Call SysSleep 0.1234567
Call SysSleep 0.12345678 -- Error 40: Incorrect call to routine
</programlisting>
</section>
<section id="utlSysstemcopy"><title>SysStemCopy</title>
<indexterm><primary>SysStemCopy</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysStemCopy</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysStemCopy--(--fromstem--,--tostem-------------------------->
>--+------------------------------------------------------------------+--)-><
+-,--+------+--+-------------------------------------------------+-+
+-from-+ +-,--+----+--+----------------------------------+-+
+-to-+ +-,--+-------+--+----------------+-+
+-count-+ +-,--"--+-I-+--"-+
+-O-+
]]>
</programlisting>
<para>Copies items from the source stem to the target stem. Items in the source
stem are copied starting at the
<emphasis role="italic">from</emphasis> index (default is 1) into the
target stem beginning at the <emphasis role="italic">to </emphasis>
index (default is 1). The number
of items to be copied to the target stem can be specified with the count.
The default is to copy all items in the source stem.</para>
<para>You can also specify that the items are to be inserted into the target
stem at the position and the existing items are shifted to the end.</para>
<para>This function operates only on stem arrays that specify the number of
items in stem.0 and all items must be numbered from 1 to n without omitting
an index.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">fromstem</emphasis></term>
<listitem><para>The name of the source stem.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">tostem</emphasis></term>
<listitem><para>The name of the target stem.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">from</emphasis></term>
<listitem><para>The first index in the source stem to be copied.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">to</emphasis></term>
<listitem><para>The position at which the items are to be inserted in the
target stem.</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">count</emphasis></term>
<listitem><para>The number of items to be copied or inserted.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">insert</emphasis></term>
<listitem><para>Either of the following values:
<variablelist>
<varlistentry><term>I</term>
<listitem><para>Insert items.
</para></listitem></varlistentry>
<varlistentry><term>O</term>
<listitem><para>Overwrite items.
</para></listitem></varlistentry>
</variablelist>
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>The stem was copied successfully.
</para></listitem></varlistentry>
<varlistentry><term>-1</term>
<listitem><para>Copying the stem failed.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysStemCopy</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysStemCopy</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysStemCopy</secondary></indexterm>
<programlisting>
Source.0 = 3
Source.1 = "Hello"
Source.2 = "from"
Source.3 = "Rexx"
Call SysStemCopy "Source.", "Target."
Call SysStemCopy "Source.", "Target.", 1, 5, 2, "I"
</programlisting>
</section>
<section id="utlSysstemdelete"><title>SysStemDelete</title>
<indexterm><primary>SysStemDelete</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysStemDelete</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysStemDelete(stem,startitem-+--------------+-)-------------><
+-,--itemcount-+
]]>
</programlisting>
<para>Deletes the specified item at the index
<emphasis role="italic">startitem</emphasis> in the stem.
If more than one item is to be deleted the
<emphasis role="italic">itemcount</emphasis> must be specified.
After deleting the requested items the stem is compacted, which means that
items following the deleted items are moved to the vacant positions.</para>
<para>This function operates only on stem arrays that specify the number of
items in stem.0 and all items must be numbered from 1 to n without omitting
an index.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">stem</emphasis></term>
<listitem><para>The name of the stem from which the item is to be deleted.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">startitem</emphasis></term>
<listitem><para>The index of the item to be deleted.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">itemcount</emphasis></term>
<listitem><para>The number of items to be deleted if more than one.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>Deleting was successful.
</para></listitem></varlistentry>
<varlistentry><term>-1</term>
<listitem><para>Deleting failed.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysStemDelete</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysStemDelete</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysStemDelete</secondary></indexterm>
<programlisting>
Call SysStemDelete "MyStem.", 5
Call SysStemDelete "MyStem.", 5, 4
</programlisting>
</section>
<section id="utlSyssteminsert"><title>SysStemInsert</title>
<indexterm><primary>SysStemInsert</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysStemInsert</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysStemInsert(stem,position,value)--------------------------><
]]>
</programlisting>
<para>Inserts a new item at <emphasis role="italic">position</emphasis>
in the stem. All items in the stem
following this position are shifted down by one position.</para>
<para>This function operates only on stem arrays that specify the number of
items in stem.0 and all items must be numbered from 1 to n without omitting
an index.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">stem</emphasis></term>
<listitem><para>The name of the stem in which an item is to be inserted.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">position</emphasis></term>
<listitem><para>The index at which the new item is to be inserted.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">value</emphasis></term>
<listitem><para>The value of the new item.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>Inserting was successful.
</para></listitem></varlistentry>
<varlistentry><term>-1</term>
<listitem><para>Inserting failed.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<programlisting>
Call SysStemInsert "MyStem.", 5, "New value for item 5"
</programlisting>
</section>
<section id="utlSysstemsort"><title>SysStemSort</title>
<indexterm><primary>SysStemSort</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysStemSort</secondary></indexterm>
<programlisting>
<![CDATA[
+-A-+ +-C-+ +-1-----+
>>-SysStemSort--(--stem--,--"--+-D-+--"--,--"--+-I-+--"--,--+-start-+-->
+-1--------+
>--,--end--,--+-firstcol-+--,--lastcol--)-----------------------------><
]]>
</programlisting>
<para>Sorts all or the specified items in the stem. The items can
be sorted in ascending or descending order and the case of the strings being
compared can be respected or ignored. Sorting can be further narrowed by
specifying the first and last item to be sorted or the columns used as sort
keys. Because the sort uses a quick-sort algorithm, the order of sorted items
according to the sort key is undetermined.</para>
<para>This function operates only on stems that specify the number
of items in stem.0 and all items must be numbered from 1 to n without omitting
an index. A value of 0 in stem.0 is also valid but no sort will be performed.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">stem</emphasis></term>
<listitem><para>The name of the stem to be sorted.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">order</emphasis></term>
<listitem><para>Either "A" for ascending or "D" for
descending. The default is "A".
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">type</emphasis></term>
<listitem><para>The type of comparison: either "C" for case or
"I" for ignore. The default is "C".
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">start</emphasis></term>
<listitem><para>The index at which the sort is to start. The default is 1.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">end</emphasis></term>
<listitem><para>The index at which the sort is to end. The default is the
last item.</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">firstcol</emphasis></term>
<listitem><para>The first column to be used as sort key. The default is 1.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">lastcol</emphasis></term>
<listitem><para>The last column to be used as sort key. The default is the
last column.</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>The sort was successful.
</para></listitem></varlistentry>
<varlistentry><term>-1</term>
<listitem><para>The sort failed.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysStemSort</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysStemSort</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysStemSort</secondary></indexterm>
<programlisting>
/* sort all elements descending, use cols 5 to 10 as key */
Call SysStemSort "MyStem.", "D", , , ,5, 10
/* sort all elements ascending, ignore the case */
Call SysStemSort "MyStem.", "A", "I"
/* sort elements 10 to 20 ascending, use cols 1 to 10 as key */
Call SysStemSort "MyStem.", , ,10, 20, 1, 10
</programlisting>
</section>
<section id="utlSysswitchsession"><title>SysSwitchSession (Windows only)</title>
<indexterm><primary>SysSwitchSession</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysSwitchSession</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysSwitchSession(name)--------------------------------------><
]]>
</programlisting>
<para>
Brings the named window to the foreground. Modern versions of Windows do not always allow a window to
be brought to the foreground programmatically. Instead, the icon for the window on the task bar is set
to flashing.
</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">name</emphasis></term>
<listitem><para>
The name of the window you want to be the foreground window. The name of the window must exactly match
the title of the window, but is not case sensitive. The title of a window is the text displayed in its
title bar.
</para></listitem></varlistentry>
</variablelist>
<para>
O is returned on success and a <link linkend="systemerrorcodes">Windows System Error code </link> on
failure.
</para>
</section>
<section id="utlSyssystemdirectory"><title>SysSystemDirectory (Windows only)</title>
<indexterm><primary>SysSystemDirectory</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysSystemDirectory</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysSystemDirectory()----------------------------------------><
]]>
</programlisting>
<para>Returns the Windows system directory.</para>
</section>
<section id="utlSystempfilename"><title>SysTempFileName</title>
<indexterm><primary>SysTempFileName</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysTempFileName</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysTempFileName(template-+---------+-)----------------------><
+-,filter-+
]]>
</programlisting>
<para>Returns a unique name for a file or directory that does not currently
exist. If an error occurs or SysTempFileName cannot create a unique name from
the template, it returns a null string (""). SysTempFileName is useful
when a program requires a temporary file.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">template</emphasis></term>
<listitem><para>The location and base form of the temporary file or directory
name. The <emphasis role="italic">template</emphasis> is a valid file or
directory specification with up to five filter characters.
</para>
<para>
SysTempFileName generates the filter character replacements with a random number algorithm. If the
resulting file or directory already exists, SysTempFileName increments the replacement value until all
possibilities have been exhausted.
</para>
<para>
There are slight differences in how the template works on Windows and Unix/Linux.
</para>
<para>
On Windows: The file name part of the template can be any length. However, the template must contain at
least 1 filter character or the empty string is returned. The unique name is created solely by
substituting random numbers for the filter character(s). If there is a directory name part of the
template in addition to the file name part, and the directory name part contains a non-existent
directory, the function will succeed. However, the temporary file will not be writable unless the user
first creates the non-existent directory, or directories. When the function succeeds, the result is
always the same length as the template.
</para>
<para>
On Unix/Linux: Only the first five characters of the file name part of the template are used. Any
characters after the first five in the file name part are ignored. The unique name is generated by the
operating system adding a random string of characaters to the end of the template. The template does
not have to include any filter characters. If the template does include filter characters, then ooRexx
replaces those filter characters with random numbers. Because the operating system adds a random string
to the end of the template, the result will always be longer than the template. In general, if the
template does not contain a directory part, or if the directory part is not writable by the user, a
writable directory part is added by the operating system (most likely /tmp.) This last behavior may
vary depending on the exact version of the Unix/Linux operating system.
</para>
</listitem></varlistentry>
<varlistentry><term><emphasis role="italic">filter</emphasis></term>
<listitem><para>The filter character used in
<emphasis role="italic">template</emphasis>. SysTempFileName replaces
each filter character in <emphasis role="italic">template</emphasis>
with a numeric value. The resulting string represents a file or directory that
does not exist. The default filter character is ?.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Examples:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysTempFileName</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysTempFileName</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysTempFileName</secondary></indexterm>
<programlisting>
/* Windows Code */
say SysTempFileName("C:\TEMP\MYEXEC.???")
say SysTempFileName("C:\TEMP\MYEXEC.tmp") -- produces the empty string.
say SysTempFileName("C:\TEMP\??MYEXEC.???")
say SysTempFileName("C:\MYEXEC@.@@@", "@")
/* Output */
C:\TEMP\MYEXEC.251
C:\TEMP\10MYEXEC.392
C:\MYEXEC6.019
/* Unix/Linux Code. mydir is an existing directory. */
say SysTempFileName("/mydir/MYEXEC.???") -- filter characters are ignored
say SysTempFileName("/mydir/MYEXEC.tmp") -- produces a unique name
say SysTempFileName("/mydir/??MYEXEC.???")
say SysTempFileName("/bogusdir/??MYEXEC.???")
say SysTempFileName("MYEXEC@.@@@", "@")
/* Output */
/mydir/MYEXEYqY2Hd
/mydir/MYEXET4dwdz
/mydir/77MYELnI0IU
/tmp/77MYEzjoweg
/tmp/MYEXEJNj3JB
</programlisting>
</section>
<section id="utlSystextscreenread"><title>SysTextScreenRead (Windows
only)</title>
<indexterm><primary>SysTextScreenRead</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysTextScreenRead</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysTextScreenRead(-row,column--+------+--)------------------><
+-,len-+
]]>
</programlisting>
<para>Reads characters from a specified screen location. These include any
carriage return and linefeed characters if the number of character reads spans
multiple lines.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">row</emphasis></term>
<listitem><para>The row from which to start reading.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">col</emphasis></term>
<listitem><para>The column from which to start reading.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">len</emphasis></term>
<listitem><para>The number of characters to read. The default is to read to the
end of the screen.
</para></listitem></varlistentry>
</variablelist>
<para>Note that, on error, a <link linkend="systemerrorcodes">Windows System
Error code</link> is returned.</para>
<para>Limitations: This function reads in only screen characters
and does not consider the color attributes of each character read. When
restoring a character string to the screen with SAY or the CHAROUT built-in
function, the previous color settings are lost.</para>
<para><emphasis role="bold">Examples:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysTextScreenRead</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysTextScreenRead</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysTextScreenRead</secondary></indexterm>
<programlisting>
/* Reading the entire screen */
screen = SysTextScreenRead(0, 0)
/* Reading one line */
line = SysTextScreenRead(2, 0, 80)
</programlisting>
</section>
<section id="utlSystextscreensize"><title>SysTextScreenSize (Windows
only)</title>
<indexterm><primary>SysTextScreenSize</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysTextScreenSize</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysTextScreenSize()-----------------------------------------><
]]>
</programlisting>
<para>Returns the size of the screen in the format:
<computeroutput>row col</computeroutput>.</para>
<para><emphasis role="bold">Example:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysTextScreenSize</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysTextScreenSize</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysTextScreenSize</secondary></indexterm>
<programlisting>
/* Code */
call RxFuncAdd "SysTextScreenSize", "RexxUtil", "SysTextScreenSize"
parse value SysTextScreenSize() with row col
say "Rows="row", Columns="col
</programlisting>
</section>
<section id="utlSystounicode"><title>SysToUnicode (Windows only)</title>
<indexterm><primary>SysToUnicode</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysToUnicode</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysToUnicode--(--string, codepage, translateflags, outstem--)-><
]]>
</programlisting>
<para>Maps a character string to a UNICODE string.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">string</emphasis></term>
<listitem><para>A string containing the UNICODE characters to be mapped.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">codepage</emphasis></term>
<listitem><para>Specifies the code page used to perform the conversion.
This parameter can be the value of any code page that is installed or available
in the system. The default is the current original equipment manufacturer
(OEM) code-page identifier for the system.</para>
<para>You can also
specify one of the following values:</para>
<variablelist>
<varlistentry><term>ACP</term>
<listitem><para>ANSI code page.
</para></listitem></varlistentry>
<varlistentry><term>OEMCP</term>
<listitem><para>OEM code page.
</para></listitem></varlistentry>
<varlistentry><term>SYMBOL</term>
<listitem><para>Windows 2000: symbol code page.
</para></listitem></varlistentry>
<varlistentry><term>THREAD_ACP
<indexterm><primary>thread</primary></indexterm>
</term>
<listitem><para>Windows 2000: current thread's ANSI code page.
</para></listitem></varlistentry>
<varlistentry><term>UTF7</term>
<listitem><para>Windows NT 4.0 and Windows 2000: translate using UTF-7.
</para></listitem></varlistentry>
<varlistentry><term>UTF8</term>
<listitem><para>Windows NT 4.0 and Windows 2000: translate using UTF-8. When
this is set, <computeroutput>translateflags</computeroutput> must be set.
</para></listitem></varlistentry>
</variablelist>
</listitem></varlistentry>
<varlistentry><term><emphasis role="italic">translateflags</emphasis></term>
<listitem><para>Indicates whether to translate to precomposed or composite-wide
characters (if a composite form exists), whether to use glyph characters in
place of control characters, and how to deal with invalid characters.</para>
<para>You can specify
a combination of the following flags:</para>
<variablelist>
<varlistentry><term>PRECOMPOSED</term>
<listitem><para>Always use precomposed characters, that is, characters in which
a base character and a nonspacing character have a single character value. This
is the default translation option. Cannot be used with COMPOSITE.
</para></listitem></varlistentry>
<varlistentry><term>COMPOSITE</term>
<listitem><para>Always use composite characters, that is, characters in which a
base character and a nonspacing character have different character values.
Cannot be used with PRECOMPOSED.
</para></listitem></varlistentry>
<varlistentry><term>ERR_INVALID_CHARS</term>
<listitem><para>If the function encounters an invalid input character, it fails
and returns "1113".
</para></listitem></varlistentry>
<varlistentry><term>USEGLYPHCHARS</term>
<listitem><para>Use glyph characters instead of control characters.
</para></listitem></varlistentry>
</variablelist>
<para>A composite character consists of a base character and a nonspacing
character, each having different character values. A precomposed character
has a single character value for a base-nonspacing character combination.
In the character è, the "e" is the base character and the "grave" accent
mark is the nonspacing character. The function's default behavior is to
translate to the precomposed form. If a precomposed form does not exist, the
function attempts to translate to a composite form.</para>
<para>The flags PRECOMPOSED and
COMPOSITE are mutually exclusive. The USEGLYPHCHARS flag and the
ERR_INVALID_CHARS can be set regardless of the state of the other flags.</para>
</listitem></varlistentry>
<varlistentry><term><emphasis role="italic">outstem</emphasis></term>
<listitem><para>The name of the stem variable that will contain the converted
result. If the conversion was successful the stem will be composed of
the following value(s):
</para>
<variablelist>
<varlistentry><term>outstem.!TEXT</term>
<listitem><para>This variable will contain the converted string.
</para></listitem></varlistentry>
</variablelist>
</listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>No errors.
</para></listitem></varlistentry>
<varlistentry><term>Other</term>
<listitem><para>An error occurred. A <link linkend="systemerrorcodes">Windows
System Error code</link> is returned. This may be one of the following, but
could be others.
</para></listitem></varlistentry>
<varlistentry><term>87</term>
<listitem><para>Incorrect code page or
<computeroutput>codepage</computeroutput> value.
</para></listitem></varlistentry>
<varlistentry><term>1004</term>
<listitem><para>Invalid translate flags.
</para></listitem></varlistentry>
<varlistentry><term>1113</term>
<listitem><para>No mapping for the Unicode character exists in the target code
page.</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSysutilversion"><title>SysUtilVersion</title>
<indexterm><primary>SysUtilVersion</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysUtilVersion</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysUtilVersion()--------------------------------------------><
]]>
</programlisting>
<para>Returns a version number that identifies the current level of the Rexx
Utilities package. It can be used to verify the availability of certain
functions.</para>
<para>Return code: The REXXUTIL version number in the format
<computeroutput>n.mm</computeroutput>.</para>
<para><emphasis role="bold">Examples:</emphasis></para>
<para>Because this function was not part of the original packaging, a sample
logic to check for a certain level of RexxUTIL can look as follows:</para>
<programlisting>
If RxFuncQuery("SysUtilVersion") = 1 |,
SysUtilVersion() < "2.00" Then
Say "Your RexxUTIL.DLL is not at the current level"
</programlisting>
<para>If a specific function should be used that was added at a later REXXUTIL
level a similar check can be performed by querying this function as follows:
</para>
<programlisting>
If RxFuncQuery("SysSetFileDateTime") = 1 Then
Say "Your REXXUTIL.DLL is not at the current level"
</programlisting>
</section>
<section id="utlSysversion"><title>SysVersion</title>
<indexterm><primary>SysVersion</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysVersion</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysVersion()------------------------------------------------><
]]>
</programlisting>
<para>
Returns a string to identify the operating system and version. The first word of the returned string
contains the identifier for the operating system and the rest of the string contains a operating
specific version string. Something like: <computeroutput>WindowsNT x</computeroutput> or
<computeroutput>Linux x</computeroutput>.
</para>
<para>
Some possible output for operating systems supported by ooRexx might be:
</para>
<programlisting>
Say SysVersion() -> "Linux #1 SMP Mon Oct 16 14:54:20 EDT 2006.2.6.18-1.2798.fc6"
Say SysVersion() -> "WindowsNT 6.01" /* Windows 7 */
</programlisting>
<note><title>Note</title><para>
This function can be used to replace the operating-system-specific functions SysWinVer(), and
SysLinVer().
</para></note>
</section>
<section id="utlSysvolumelabel"><title>SysVolumeLabel (Windows only)</title>
<indexterm><primary>SysVolumeLabel</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysVolumeLabel</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysVolumeLabel(--+-------------+--)------------------------------><
+-driveLetter-+
]]>
</programlisting>
<para>Returns the volume label for the specified drive.</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">driveLetter</emphasis></term>
<listitem><para>A drive letter in the form 'X:'. If the drive letter
is omitted than the current drive is used.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>Encryption was successful.
</para></listitem></varlistentry>
<varlistentry><term>2</term>
<listitem><para>File not found.
</para></listitem></varlistentry>
<varlistentry><term>4</term>
<listitem><para>Cannot open file.
</para></listitem></varlistentry>
<varlistentry><term>5</term>
<listitem><para>Access denied.
</para></listitem></varlistentry>
<varlistentry><term>82</term>
<listitem><para>Cannot encrypt.
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSyswait"><title>SysWait (Unix only)</title>
<indexterm><primary>SysWait</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysWait</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysWait()---------------------------------------------------><
]]>
</programlisting>
<para>Waits for all child processes to end.</para>
<para><emphasis role="bold">Returns:</emphasis></para>
<para>The exit code from the child process.</para>
<para><emphasis role="bold">Example:</emphasis></para>
<para>
<link linkend="utlSysfork">SysFork</link>() has an example that uses
<computeroutput>wait()</computeroutput>.</para>
</section>
<section id="utlSyswaiteventsem"><title>SysWaitEventSem</title>
<indexterm><primary>SysWaitEventSem</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysWaitEventSem</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysWaitEventSem(handle-+----------+-)-----------------------><
+-,timeout-+
]]>
</programlisting>
<para>Waits on an event semaphore. SysWaitEventSem
returns the WaitForSingleObject return code.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">handle</emphasis></term>
<listitem><para>A handle returned from a previous SysCreateEventSem call.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">timeout</emphasis></term>
<listitem><para>The time, in milliseconds, to wait on the semaphore. The
default <emphasis role="italic">timeout</emphasis> is an infinite wait.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>No errors.
</para></listitem></varlistentry>
<varlistentry><term>Other</term>
<listitem><para>An error occurred. On Windows, a <link linkend="systemerrorcodes">Windows System Error
code</link> is returned. This may be one of the following, but could be others.
</para></listitem></varlistentry>
<varlistentry><term>6</term>
<listitem><para>Invalid handle.
</para></listitem></varlistentry>
<varlistentry><term>258</term>
<listitem><para>Timeout.
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSyswaitnamedpipe"><title>SysWaitNamedPipe (Windows only)</title>
<indexterm><primary>SysWaitNamedPipe</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysWaitNamedPipe</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysWaitNamedPipe(name-+----------+-)------------------------><
+-,timeout-+
]]>
</programlisting>
<para>Performs a timed wait on a named pipe and returns the WaitNamedPipe
return code.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">name</emphasis></term>
<listitem><para>The name of the pipe in the form
"\\servername\pipe\pipename."
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">timeout</emphasis></term>
<listitem><para>The number of microseconds to be waited. If you omit
<emphasis role="italic">timeout</emphasis> or
specify 0, SysWaitNamedPipe uses the default timeout value. To wait until
the pipe is no longer busy, you can use a value of -1.
</para></listitem></varlistentry>
</variablelist>
<para>Returns 0 on success. A <link linkend="systemerrorcodes">Windows System
Error code</link> is returned on error.
</para>
</section>
<section id="utlSyswindecryptfile"><title>SysWinDecryptFile (Windows
only)</title>
<indexterm><primary>SysWinDecryptFile</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysWinDecryptFile</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysWinDecryptFile(filename)---------------------------------><
]]>
</programlisting>
<para>Decrypts a given file (Windows 2000 only).</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">filename</emphasis></term>
<listitem><para>The file to be decrypted.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>Decryption was successful.
</para></listitem></varlistentry>
<varlistentry><term>Other</term>
<listitem><para>A <link linkend="systemerrorcodes">Windows System Error code
</link>. This may be one of the following, but could be others.
</para></listitem></varlistentry>
<varlistentry><term>2</term>
<listitem><para>File not found.
</para></listitem></varlistentry>
<varlistentry><term>4</term>
<listitem><para>Cannot open file.
</para></listitem></varlistentry>
<varlistentry><term>5</term>
<listitem><para>Access denied.
</para></listitem></varlistentry>
<varlistentry><term>82</term>
<listitem><para>Cannot decrypt.
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSyswinencryptfile"><title>SysWinEncryptFile (Windows
only)</title>
<indexterm><primary>SysWinEncryptFile</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysWinEncryptFile</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysWinEncryptFile(filename)---------------------------------><
]]>
</programlisting>
<para>Encrypts a given file (Windows 2000 only).</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">filename</emphasis></term>
<listitem><para>The file to be encrypted.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>Encryption was successful.
</para></listitem></varlistentry>
<varlistentry><term>Other</term>
<listitem><para>A <link linkend="systemerrorcodes">Windows System Error code
</link>. This may be one of the following, but could be others.
</para></listitem></varlistentry>
<varlistentry><term>2</term>
<listitem><para>File not found.
</para></listitem></varlistentry>
<varlistentry><term>4</term>
<listitem><para>Cannot open file.
</para></listitem></varlistentry>
<varlistentry><term>5</term>
<listitem><para>Access denied.
</para></listitem></varlistentry>
<varlistentry><term>82</term>
<listitem><para>Cannot encrypt.
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSyswingetdefaultprinter"><title>SysWinGetDefaultPrinter (Windows
only)</title>
<indexterm><primary>SysWinGetDefaultPrinter</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysWinGetDefaultPrinter</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysWinGetDefaultPrinter-------------------------------------><
]]>
</programlisting>
<para>Returns the current default printer in the form
"Printername,Drivername,Portname".</para>
</section>
<section id="utlSyswingetprinters"><title>SysWinGetPrinters (Windows
only)</title>
<indexterm><primary>SysWinGetPrinters</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysWinGetPrinters</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysWinGetPrinters(stem.)------------------------------------><
]]>
</programlisting>
<para>Fills a stem with the available printer descriptions.</para>
<para><emphasis role="bold">Parameters:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">stem.0</emphasis></term>
<listitem><para>The number of entries
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="italic">stem.i</emphasis></term>
<listitem><para>Entry
</para></listitem></varlistentry>
</variablelist>
<para>Each entry is of the form "Printername,Drivername,Portname".</para>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>Success
</para></listitem></varlistentry>
<varlistentry><term>1</term>
<listitem><para>Failure
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="utlSyswinsetdefaultprinter"><title>SysWinSetDefaultPrinter (Windows
only)</title>
<indexterm><primary>SysWinSetDefaultPrinter</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysWinSetDefaultPrinter</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysWinSetDefaultPrinter(description)------------------------><
]]>
</programlisting>
<para>Sets the default printer.</para>
<para><emphasis role="bold">Parameter:</emphasis></para>
<variablelist>
<varlistentry><term><emphasis role="italic">description</emphasis></term>
<listitem><para>A string identifying the printer. On Windows 2000 or later this
string can be just the printer name. For earlier versions of Windows, the
string must have the form "Printername,Drivername,Portname".
<note><title>Note</title><para>
For Windows 2000 or later either form of the description string is accepted.
However, using just the printer name is the preferred method. Using the
"Printername,Drivername,Portname" form will invoke an outdated Windows API
that Microsoft has deprecated.
</para></note>
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Return codes:</emphasis></para>
<variablelist>
<varlistentry><term>0</term>
<listitem><para>Success
</para></listitem></varlistentry>
<varlistentry><term>non-zero</term>
<listitem><para>A <link linkend="systemerrorcodes">Windows System Error
code</link>. You can use SysGetErrortext() to get a description of the error.
</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="bold">Example:</emphasis></para>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysWinSetDefaultPrinter</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysWinSetDefaultPrinter</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysSetDefaultPrinter</secondary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysWinGetDefaultPrinter</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysWinGetDefaultPrinter</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysGetDefaultPrinter</secondary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysWinGetPrinters</secondary>
<tertiary>example</tertiary></indexterm>
<indexterm><primary>SysWinGetPrinters</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SysGetPrinters</secondary></indexterm>
<programlisting>
<![CDATA[
/* set default printer */
default = SysWinGetDefaultPrinter()
parse var default default",".
say 'The Default printer is:' default
say
if SysWinGetPrinters(list.) == 0 then do
say "List of available printers (* = default):"
do i=1 to list.0
parse var list.i pname",".
if pname == default then
say i list.i "*"
else
say i list.i
end
say
say "Please enter number of new default printer (0 = keep default)"
pull i
numberOk = .false
if i~datatype('W') then do
if 0 <= i & i <= list.0 then do
numberOK = .true
if i > 0 then do
/* Assumes we are on Windows 2000 or later. */
parse var list.i pname",".
ret = SysWinSetDefaultPrinter(pname)
if ret <> 0 then do
say "Error setting default printer ("ret"):" SysGetErrorText(ret)
end
else do
say "The new default printer is:" pname
end
end
end
end
if \ numberOk then do
say "You did not enter a valid printer number."
end
end
else do
say "Failed to get a list of the available printers."
end
]]>
</programlisting>
</section>
<section id="utlSyswinver"><title>SysWinVer (Windows only)</title>
<indexterm><primary>SysWinVer</primary></indexterm>
<indexterm><primary>rexxutil functions</primary>
<secondary>SysWinVer</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SysWinVer()-------------------------------------------------><
]]>
</programlisting>
<para>Returns a string specifying the Windows operating system version
information in the form <computeroutput>x.xx</computeroutput>.</para>
</section>
</chapter>