Menu
▾
▴
[Oorexx-svn] SF.net SVN: oorexx:[5730] docs/trunk/rexxpg
|
From: <wda...@us...> - 2010-03-22 21:48:05
|
Revision: 5730
http://oorexx.svn.sourceforge.net/oorexx/?rev=5730&view=rev
Author: wdashley
Date: 2010-03-22 21:47:57 +0000 (Mon, 22 Mar 2010)
Log Message:
-----------
Rename all rexxpg sgml files to xml.
Modified Paths:
--------------
docs/trunk/rexxpg/Makefile
Added Paths:
-----------
docs/trunk/rexxpg/api.xml
docs/trunk/rexxpg/classes.xml
docs/trunk/rexxpg/classicapi.xml
docs/trunk/rexxpg/command.xml
docs/trunk/rexxpg/concept.xml
docs/trunk/rexxpg/meet.xml
docs/trunk/rexxpg/preface.xml
docs/trunk/rexxpg/provide.xml
docs/trunk/rexxpg/rexio.xml
docs/trunk/rexxpg/rexxpg.xml
docs/trunk/rexxpg/rxruntime.xml
docs/trunk/rexxpg/samples.xml
docs/trunk/rexxpg/tour.xml
Removed Paths:
-------------
docs/trunk/rexxpg/api.sgml
docs/trunk/rexxpg/classes.sgml
docs/trunk/rexxpg/classicapi.sgml
docs/trunk/rexxpg/command.sgml
docs/trunk/rexxpg/concept.sgml
docs/trunk/rexxpg/meet.sgml
docs/trunk/rexxpg/preface.sgml
docs/trunk/rexxpg/provide.sgml
docs/trunk/rexxpg/rexio.sgml
docs/trunk/rexxpg/rexxpg.sgml
docs/trunk/rexxpg/rxruntime.sgml
docs/trunk/rexxpg/samples.sgml
docs/trunk/rexxpg/tour.sgml
Modified: docs/trunk/rexxpg/Makefile
===================================================================
--- docs/trunk/rexxpg/Makefile 2010-03-22 21:41:17 UTC (rev 5729)
+++ docs/trunk/rexxpg/Makefile 2010-03-22 21:47:57 UTC (rev 5730)
@@ -2,7 +2,7 @@
#
# Description: Makefile for the Object Rexx Programming Guide Documents.
#
-# Copyright (c) 2005-2007, Rexx Language Association. All rights reserved.
+# Copyright (c) 2005-2010, Rexx Language Association. 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
@@ -47,23 +47,23 @@
../shared/oorexx.html.dsl
-SGML_FILES = classes.sgml \
- api.sgml \
- classicapi.sgml \
- command.sgml \
- concept.sgml \
- meet.sgml \
- preface.sgml \
- provide.sgml \
- rexio.sgml \
- rexxpg.sgml \
- rxruntime.sgml \
- samples.sgml \
- tour.sgml \
- ../shared/notices.sgml \
- ../shared/legalstuff.sgml \
- ../shared/gethelp.sgml \
- ../shared/CPLv1.0.sgml
+xml_FILES = classes.xml \
+ api.xml \
+ classicapi.xml \
+ command.xml \
+ concept.xml \
+ meet.xml \
+ preface.xml \
+ provide.xml \
+ rexio.xml \
+ rexxpg.xml \
+ rxruntime.xml \
+ samples.xml \
+ tour.xml \
+ ../shared/notices.xml \
+ ../shared/legalstuff.xml \
+ ../shared/gethelp.xml \
+ ../shared/CPLv1.0.xml
HTML_IMAGE_FILES = ReportObject.png \
BallObject.png \
@@ -138,11 +138,11 @@
html: rexxpg-html.zip
-rexxpg.pdf: $(PDF_IMAGE_FILES) $(STYLESHEET) $(JADETEXFMT) genindex.sgml svnrev.tmp
- docbook2pdf -d ../shared/oorexx.print.dsl rexxpg.sgml
+rexxpg.pdf: $(PDF_IMAGE_FILES) $(STYLESHEET) $(JADETEXFMT) genindex.xml svnrev.tmp
+ docbook2pdf -d ../shared/oorexx.print.dsl rexxpg.xml
-book1.htm: $(HTML_IMAGE_FILES) $(HTML_STYLESHEET) genindex.sgml svnrev.tmp
- docbook2html -d ../shared/oorexx.html.dsl rexxpg.sgml
+book1.htm: $(HTML_IMAGE_FILES) $(HTML_STYLESHEET) genindex.xml svnrev.tmp
+ docbook2html -d ../shared/oorexx.html.dsl rexxpg.xml
rexxpg-html.zip: book1.htm
zip rexxpg-html *.htm *.jpg *.png
@@ -150,11 +150,11 @@
$(JADETEXFMT): $(HYPERREFCFG)
pdftex -ini \&pdflatex pdfjadetex.ini
-genindex.sgml: $(HTML_STYLESHEET) $(SGML_FILES) svnrev.tmp
- collateindex.pl -N -o genindex.sgml
- jade -t sgml -d ../shared/oorexx.html.dsl -V html-index rexxpg.sgml
+genindex.xml: $(HTML_STYLESHEET) $(xml_FILES) svnrev.tmp
+ collateindex.pl -N -o genindex.xml
+ jade -t xml -d ../shared/oorexx.html.dsl -V html-index rexxpg.xml
rm *.htm
- collateindex.pl -p -g -o genindex.sgml HTML.index
+ collateindex.pl -p -g -o genindex.xml HTML.index
svnrev.tmp:
svnversion > svnrev.tmp
@@ -163,6 +163,6 @@
clean:
- rm -f *.log *.aux *.out *.fmt rexxpg.pdf genindex.sgml *.htm *.zip \
+ rm -f *.log *.aux *.out *.fmt rexxpg.pdf genindex.xml *.htm *.zip \
HTML.index *.tmp
Deleted: docs/trunk/rexxpg/api.sgml
===================================================================
--- docs/trunk/rexxpg/api.sgml 2010-03-22 21:41:17 UTC (rev 5729)
+++ docs/trunk/rexxpg/api.sgml 2010-03-22 21:47:57 UTC (rev 5730)
@@ -1,11202 +0,0 @@
-<!--#########################################################################
- #
- # Description: Open Object Rexx: Programming Guide 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 <da...@us...>
- #
- #########################################################################
--->
-<chapter id="api4x">
-<title>Rexx C++ Application Programming Interfaces</title>
-<para>This chapter describes how to interface applications to Rexx or extend
-the Rexx language by using Rexx C++ application programming interfaces (APIs).
-As used here, the term application refers to programs
-written in C++.
-</para>
-<para>The features described here let a C++ application extend many parts of the
-Rexx language or extend an application with Rexx. This includes creating handlers
-for Rexx methods, external functions, and system exits.</para>
-<variablelist>
-<varlistentry><term>Rexx methods</term>
-<listitem><para>are methods for Rexx classes written in C++. The methods reside in dynamically
-loaded external shared libraries.
-</para></listitem></varlistentry>
-<varlistentry><term>Functions</term>
-<listitem><para>are function extensions of the Rexx language written in C++. Like the native
-methods, functions are packaged in external libraries.
-Functions can be general-purpose
-extensions or specific to an application.
-</para></listitem></varlistentry>
-<varlistentry><term>Command Handlers</term>
-<listitem><para>are programmer-defined handlers for named command environments.
-The application programmer can tailor the Rexx interpreter behavior by
-creating named command environments to interfacing with
-application environments.
-</para></listitem></varlistentry>
-<varlistentry><term>System exits</term>
-<listitem><para>are programmer-defined variations of the interpreter.
-The application programmer can tailor the Rexx interpreter behavior by
-using the defined exit points to control Rexx resources.
-</para></listitem></varlistentry>
-</variablelist>
-<para>Methods, functions, system exit handlers, and command handlers have similar coding,
-compilation, and packaging characteristics.
-</para>
-<para>In addition, applications can call methods defined of Rexx objects and
-execute them from externally defined methods and functions.</para>
-
-<section id="intertreterapi"><title>Rexx Interpreter API</title>
-<para>Rexx programs run in an environment controlled by an interpreter instance.
-An interpreter instance environment is created with an enable set of exit handlers and
-a customized environment. An instance may have multiple active threads
-and each interpreter instance has a unique version of the .local environment
-directory, allowing programs to run with some degree of isolation.
-</para>
-<para>If you use the older <link linkend="rexxstartfu">RexxStart()</link> API to run
-a Rexx program, the Rexx environment initializes, runs a single program, and the
-environment is terminated. With the RexxCreateInterpreter() API, you have fine grain
-control over how the environment is used. You are able to create a tailored environment, perform
-multiple operations (potentially, on multiple threads), create objects that persist for longer
-than the life of a single program, etc. An application can create an interpreter instance once, and
-reuse it to run multiple programs.
-</para>
-<para>Interpreter environments are created using the
-<link linkend="createinterpreter">RexxCreateInterpreter()</link> API:</para>
-<programlisting>
-RexxInstance *instance;
-RexxThreadContext *threadContext;
-RexxOption options[25];
-
-if (RexxCreateInterpreter(&instance, &threadContext, options)) {
-…
-}
-</programlisting>
-<para>Once you've created an interpreter instance, you can use the APIs provided by the
-RexxInstance or RexxThreadContext interface to perform operations
-like running programs, loading class packages, etc. For example, the following
-code will run a program using a created instance, checking for syntax errors upon completion:</para>
-<programlisting>
-<![CDATA[
- // create an Array object to hold the program arguments
- RexxArrayObject args = threadContext->NewArray(instanceInfo->argCount);
- // we're passing a variable number of arguments, so we need to create
- // String objects and insert them into the array
- for (size_t i = 0; i < argCount; i++)
- {
- if (arguments[i] != NULL)
- {
- // add the argument to the array, if specified. Note that ArrayPut() requires an
- // index that is origin-1, unlike C arrays which are origin-0.
- threadContext->ArrayPut(args, threadContext->String(arguments[i]), i + 1);
- }
- }
-
- // call our program, using the provided arguments.
- RexxObjectPtr result = threadContext->CallProgram("myprogram.rex", args);
- // if an error occurred, get the decoded exception information
- if (threadContext->CheckCondition())
- {
- RexxCondition condition;
-
- // retrieve the error information and get it into a decoded form
- RexxDirectoryObject cond = threadContext->GetConditionInfo();
- threadContext->DecodeConditionInfo(cond, &condition);
- // display the errors
- printf("error %d: %s\n%s\n", condition.code, threadContext->CString(condition.errortext),
- threadContext->CString(condition.message));
- }
- else
- {
- // Copy any return value as a string
- if (result != NULLOBJECT)
- {
- CSTRING resultString = threadContext->CString(result);
- strncpy(returnResult, resultString, sizeof(returnResult));
- }
- }
- // make sure we terminate this first
- instance->Terminate();
-]]>
-</programlisting>
-<para>The example above creates a Rexx String object for each program argument
-stores them in a Rexx array. It then uses
-<link linkend="mthCallProgram">CallProgram()</link> to call "myprogram.rex", passing the array object
-as the program arguments. On return, if the program terminated with a Rexx SYNTAX error, it
-displays the error message to the console. Finally, if the program
-exited normally and returned a value, the ASCII-Z value of that result is copied to a buffer. As
-a final step, the interpreter instance is destroyed once we're finished using it.</para>
-<section id="createinterpreter"><title>RexxCreateInterpreter</title>
-<indexterm><primary>application programming interfaces</primary>
-<secondary>RexxCreateInterpreter</secondary></indexterm>
-<indexterm><primary>RexxCreateInterpreter</primary></indexterm>
-<para>RexxCreateInterpreter creates an interpreter instance and an associated
-thread context interface for the current thread.</para>
-<programlisting>
-RexxInstance *instance;
-RexxThreadContext *threadContext;
-RexxOption options[25];
-
-if (RexxCreateInterpreter(&instance, &threadContext, options)) {
-…
-}
-</programlisting>
-<para><emphasis role="bold">Arguments</emphasis></para>
-<informaltable frame="none" colsep="0" rowsep="0"><tgroup cols="2"><colspec colnum="1" colwidth="1*"><colspec colnum="2" colwidth="5*"><tbody>
- <row><entry><emphasis role="italic">instance</emphasis></entry>
- <entry><para>The returned RexxInstance interface vector. The interface
- vector provides access to APIs that apply to the global interpreter environment.</para></entry>
- </row>
- <row><entry><emphasis role="italic">threadContext</emphasis></entry>
- <entry><para>The returned RexxThreadContext interface vector for the thread that creates the
- interpreter instance. The thread context vector provides access to thread-specific services.
- </para></entry>
- </row>
- <row><entry><emphasis role="italic">options</emphasis></entry>
- <entry><para>An array of RexxOption structures that control the interpreter
- instance initialization. See <link linkend="instanceoptions">Interpreter Instance Options</link> for details on
- the available options.
- </para></entry>
- </row>
-</tbody></tgroup></informaltable>
-<para><emphasis role="bold">Returns</emphasis></para>
-<para>1 (TRUE) if the interpreter instance was successfully created, 0 (FALSE) for any
-failure to create the interpreter.</para>
-</section>
-
-<section id="instanceoptions"><title>Interpreter Instance Options</title>
-<para>The third argument to RexxCreateInterpreter is an options array
-that sets characteristics of the interpreter instance. The
-<emphasis role="bold">options</emphasis>
-argument points to an array of RexxOption structures, and can be NULL if no options are required.
-Each RexxOption instance
-contains information for named options that can be specified in any order and even multiple times.
-The oorexxapi.h include file
-contains a #define for each option name. The information required by an option
-varies with each option type, and is specified using a ValueDescriptor struct to
-handle a variety of data types.
-An entry with a NULL option
-name terminates the option list. The available interpreter options are:</para>
-<variablelist>
-<varlistentry><term>INITIAL_ADDRESS_ENVIRONMENT</term>
-<listitem><para>Contains the ASCII-Z name of the initial address environment
-that will be used for all Rexx programs run under this instance.</para>
-<programlisting>
-RexxOption options[2];
-
-options[0].optionName = INITIAL_ADDRESS_ENVIRONMENT;
-options[0].option = "EDITOR";
-options[1].optionName = NULL;
-</programlisting>
-</listitem></varlistentry>
-<varlistentry><term>APPLICATION_DATA</term>
-<listitem><para>Contains a void * value that will be stored with the interpreter
-instance. The application data can be retrieved using the
-<link linkend="mthGetApplicationData">GetApplicationData()</link> API. The application
-data pointer allows methods, functions, exits, and command handlers to recover
-access to globally defined application data.
-</para>
-<programlisting>
-RexxOption options[2];
-
-options[0].optionName = APPLICATION_DATA;
-options[0].option = (void *)editorInfo;
-options[1].optionName = NULL;
-</programlisting>
-</listitem></varlistentry>
-<varlistentry><term>EXTERNAL_CALL_PATH</term>
-<listitem><para>Contains an ASCII-Z string defining an additional search path that
-is used when searching for Rexx program files. The call path string uses the
-format appropriate for the host platform environment. On Windows, the path elements
-are separated by semicolons (;). On Unix-based systems, a colon (:) is used.
-</para>
-<programlisting>
-RexxOption options[2];
-
-options[0].optionName = EXTERNAL_CALL_PATH;
-options[0].option = myCallPath;
-options[1].optionName = NULL;
-</programlisting>
-</listitem></varlistentry>
-<varlistentry><term>EXTERNAL_CALL_EXTENSIONS</term>
-<listitem><para>Contains an ASCII-Z string defining a list of extensions that will
-be used when searching for Rexx program files. The specified extensions must include
-the extension ".". Multiple extensions are separated by a comma (,).
-</para>
-<programlisting>
-RexxOption options[2];
-
-options[0].optionName = EXTERNAL_CALL_EXTENSIONS;
-options[0].option = ".ed,.mac"; // add ".ed" and ".mac" to search path.
-options[1].optionName = NULL;
-</programlisting>
-</listitem></varlistentry>
-<varlistentry><term>LOAD_REQUIRED_LIBRARY</term>
-<listitem><para>Specifies the name of an external native library that will be loaded
-once the interpreter instance is created. The library name is an ASCII-Z string
-with the library name in the same format used for ::REQUIRED LIBRARY. Multiple libraries
-can be loaded by specifying this option multiple times.
-</para>
-<programlisting>
-RexxOption options[2];
-
-options[0].optionName = LOAD_REQUIRED_LIBRARY;
-options[0].option = "rxmath";
-options[1].optionName = NULL;
-</programlisting>
-</listitem></varlistentry>
-<varlistentry><term>REGISTER_LIBRARY</term>
-<listitem><para>Specifies a package that will be registerd with the Rexx environment
-without loading an external library. The library is specified with a RexxLibraryPackage
-structure that gives the library name and a pointer to the associated
-<link linkend="buildinglibs">RexxPackageEntry</link>
-table that describes the package contents.
-The library name is an ASCII-Z string
-with the library name in the same format used for ::REQUIRED LIBRARY. Multiple libraries
-can be registered by specifying this option multiple times.
-</para>
-<programlisting>
-RexxOption options[2];
-RexxLibraryPackage package;
-
-package.registeredName = "mypackage";
-package.table = packageTable;
-
-options[0].optionName = REGISTER_LIBRARY;
-options[0].option = (void *)&package;
-options[1].optionName = NULL;
-</programlisting>
-</listitem></varlistentry>
-<varlistentry><term>DIRECT_EXITS</term>
-<listitem><para>Specifies a list of system exits that will be used with this interpreter
-instance. The exits are a list of RexxContextExit structs. Each enabled exit is
-specified in a single RexxContextExit struct that identifies exit type and
-handler entry point.
-The list is terminated by an instance using an
-exit type of 0. The direct exits are called using the RexxExitContext calling convention.
-See <link linkend="exitsapi">Rexx Exits Interface</link> for details.
-</para>
-<programlisting>
-
-RexxContextExit exits[2];
-RexxOption options[2];
-
-
-exits[0].handler = functionExit;
-exits[0].sysexit_code = RXOFNC;
-exits[1].sysexit_code = 0;
-
-options[0].optionName = DIRECT_EXITS;
-options[0].option = (void *)exits;
-options[1].optionName = NULL;
-</programlisting>
-</listitem></varlistentry>
-<varlistentry><term>DIRECT_ENVIRONMENTS</term>
-<listitem><para>Registers one or more subcommand handler environments with the interpreter
-instance. The handlers are a list of RexxContextEnvironment structs. Each enabled handler is
-specified in a single RexxContextEnvironment struct identifying the handler name and
-entry point.
-The list is terminated by an instance using a
-handler name of NULL. The direct environment handlers are called using the calling convention
-described in <link linkend="commandapi">Command Handler Interface</link>.
-</para>
-<programlisting>
-
-RexxContextEnvironment environments[2];
-RexxOption options[2];
-
-
-environments[0].handler = editorHandler;
-environments[0].name = "EDITOR";
-environments[1].name = NULL;
-
-options[0].optionName = DIRECT_ENVIRONMENTS;
-options[0].option = (void *)environments;
-options[1].optionName = NULL;
-</programlisting>
-</listitem></varlistentry>
-<varlistentry><term>REGISTERED_EXITS</term>
-<listitem><para>Specifies a list of system exits that will be used with this interpreter
-instance. The exits are a list of RexxContextExit structs. Each enabled exit is
-specified in a single RexxContextExit struct identifying the type of the exit and the
-name of the registered exit handler.
-The list is terminated by an instance using an
-exit type of 0. The registered exits are called using the RexxExitHandler calling convention.
-See <link linkend="sysex">Registered System Exits Interface</link> for details.
-</para>
-<programlisting>
-
-RXSYSEXIT exits[2];
-RexxOption options[2];
-
-
-exits[0].sysexit_name = "MyFunctionExit";
-exits[0].sysexit_code = RXOFNC;
-exits[1].sysexit_code = 0;
-
-options[0].optionName = REGISTERED_EXITS;
-options[0].option = (void *)exits;
-options[1].optionName = NULL;
-</programlisting>
-</listitem></varlistentry>
-<varlistentry><term>REGISTERED_ENVIRONMENTS</term>
-<listitem><para>Registers one or more subcommand handler environments with the interpreter
-instance. The handlers are a list of RexxRegisteredEnvironment structs. Each enabled handler is
-specified in a single RexxRegisteredEnvironment struct identifying the name of the environment and the
-registered subcom handler name.
-The list is terminated by an instance using a
-handler name of NULL. The direct environment handlers are called using the calling convention
-described in <link linkend="subcom">Subcommand Interface</link>.
-</para>
-<programlisting>
-
-RexxRegisteredEnvironment environments[2];
-RexxOption options[2];
-
-
-environments[0].registeredName = "MyEditorName";
-environments[0].name = "EDITOR";
-environments[1].name = NULL;
-
-options[0].optionName = REGISTERED_ENVIRONMENTS;
-options[0].option = (void *)environments;
-options[1].optionName = NULL;
-</programlisting>
-</listitem></varlistentry>
-</variablelist>
-</section>
-</section>
-
-<section id="apitypes"><title>Data Types Used in APIs</title>
-<para>The ooRexx APIs rely on a variety of special C++ types for interfacing with
-the interpreter. Some of these types are specific to the Rexx language, while
-others are standard types defined by C++. Many of the APIs involve conversion
-between types, while others require values of a specific type as arguments.
-This section explains the different types and the rules for using these types.
-</para>
-<section id="objecttypes"><title>Rexx Object Types</title>
-<para>Open Object Rexx is fundamentally an object-oriented language. All data in
-the language (including strings and numbers) are represented by object instances.
-The ooRexx APIs use a number of opaque types that represent instances
-of Rexx built-in objects. The defined object types are:
-</para>
-<informaltable frame="none" colsep="0" rowsep="0">
-<tgroup cols="2">
-<colspec colnum="1" colwidth="1*">
-<colspec colnum="2" colwidth="3*">
-<tbody>
-<row><entry>RexxObjectPtr</entry>
-<entry><para>a reference to a Rexx object instance. This is the root of object
-hierarchy and can represent any type of object.
-</para></entry></row>
-<row><entry>RexxStringObject</entry>
-<entry><para>an instance of the Rexx String class. The API set allows String objects
-to be created and manipulated.
-</para></entry></row>
-<row><entry>RexxBufferStringObject</entry>
-<entry><para>an instance of the Rexx String class that can be written into.
-Buffer strings are used for constructing String objects "in-place" to avoid
-needing to create a String from a separate buffer.
-RexxBufferStringObject instances must be finalized to be converted into a usable
-Rexx String object.
-</para></entry></row>
-<row><entry>RexxArrayObject</entry>
-<entry><para>An instance of a Rexx single-dimension array. Arrays are used
-in many places, and there are interfaces provided for direct array manipulation.
-</para></entry></row>
-<row><entry>RexxDirectoryObject</entry>
-<entry><para>An instance of Rexx Directory class. Like arrays, there are
-APIs provided for access and manipulating data stored in a directory.
-</para></entry></row>
-<row><entry>RexxStemObject</entry>
-<entry><para>An instance of the Rexx Stem class. The APIs include a number of
-utility routines for accessing and manipulating data in Stem objects.
-</para></entry></row>
-<row><entry>RexxSupplierObject</entry>
-<entry><para>An instance of the Rexx Supplier class.
-</para></entry></row>
-<row><entry>RexxClassObject</entry>
-<entry><para>An instance of the Rexx Class class.
-</para></entry></row>
-<row><entry>RexxPackageObject</entry>
-<entry><para>An instance of the Rexx Package class.
-</para></entry></row>
-<row><entry>RexxMethodObject</entry>
-<entry><para>An instance of the Rexx Method class.
-</para></entry></row>
-<row><entry>RexxRoutineObject</entry>
-<entry><para>An instance of the Rexx Routine class. Routine objects
-can be invoked directly from C++ code.
-</para></entry></row>
-<row><entry>RexxPointerObject</entry>
-<entry><para>A wrapper around a pointer value. Pointer objects are designed
-for constructing Rexx classes that interface with native code subsystems.
-</para></entry></row>
-<row><entry>RexxBufferObject</entry>
-<entry><para>An allocatable storage object that can be used for storing native
-C++ data. Buffer objects and the contained data are managed using the Rexx object
-garbage collector.
-</para></entry></row>
-</tbody>
-</tgroup>
-</informaltable>
-</section>
-<section id="numerictypes"><title>Rexx Numeric Types</title>
-<para>The Routine and Method interfaces support a very complete set of C numeric types as
-arguments and return values. In addition, there are also APIs provided for converting between
-Rexx Objects and numeric types (and the reverse transformation as well). It is recommended that
-you allow the Rexx runtime and APIs to handle conversions between Rexx strings and numeric types to
-give behavior consistent with the Rexx built-in methods and functions.
-</para>
-<para>In addition to a full set of standard numeric types, there are two special types
-provided that implement the standard Rexx rules for numbers used internally by Rexx.
-These types are:</para>
-<informaltable frame="none" colsep="0" rowsep="0">
-<tgroup cols="2">
-<colspec colnum="1" colwidth="1*">
-<colspec colnum="2" colwidth="4*">
-<tbody>
-<row><entry>wholenumber_t</entry>
-<entry><para>conversions involving the wholenumber_t conform to the Rexx whole number
-rules. Values are converted using the same internal digits value used by the built-in functions.
-For 32-bit versions, this is numeric digits 9, giving a range of 999,999,999 to -999,999,999.
-On 64-bit systems, numeric digits 18 is used, giving a range of 999,999,999,999,999,999 to
--999,999,999,999,999,999.
-</para></entry></row>
-<row><entry>stringsize_t</entry>
-<entry><para>stringsize_t conversions also conform to the Rexx whole number
-rules, with the added restriction that the value must be a non-negative whole number value. The
-stringsize_t type is useful for arguments such as string lengths where only a non-negative value is
-allowed. The range for 32-bit versions is 999,999,999 to 0, and
-999,999,999,999,999,999 to 0 on 64-bit platforms.
-</para></entry></row>
-<row><entry>logical_t</entry>
-<entry><para>a Rexx logical value. On conversion from a string value, this must be
-either '1' (true) or '0' (false). On conversion back to a string value,
-a non-zero binary value will be converted
-to '1' (true) and zero will become '0' (false).
-</para></entry></row>
-</tbody>
-</tgroup>
-</informaltable>
-<para>A subset of the integer numeric types are of differing sizes depending on the
-addressing mode of the system you are compiling on. These types will be either 32-bits
-or 64-bits. The variable size types are: </para>
-<informaltable frame="none" colsep="0" rowsep="0">
-<tgroup cols="2">
-<colspec colnum="1" colwidth="1*">
-<colspec colnum="2" colwidth="4*">
-<tbody>
-<row><entry>size_t</entry>
-<entry><para>An unsigned "size" value. This is the value type returned by pointer subtraction.
-</para></entry></row>
-<row><entry>ssize_t</entry>
-<entry><para>The signed equivalent to size_t.
-</para></entry></row>
-<row><entry>uintptr_t</entry>
-<entry><para>An unsigned integer value that's guaranteed to be the same size as a pointer value.
-Use an uintptr_t type if you wish to return a pointer value as a Rexx number.
-</para></entry></row>
-<row><entry>intptr_t</entry>
-<entry><para>A signed equivalent to uintptr_t.
-</para></entry></row>
-</tbody>
-</tgroup>
-</informaltable>
-<para>The remainder of the numeric types have fixed sizes regardless of the addressing mode.</para>
-<informaltable frame="none" colsep="0" rowsep="0">
-<tgroup cols="2">
-<colspec colnum="1" colwidth="1*">
-<colspec colnum="2" colwidth="4*">
-<tbody>
-<row><entry>int</entry>
-<entry><para>A 32-bit signed integer.
-</para></entry></row>
-<row><entry>int32_t</entry>
-<entry><para>A 32-bit signed integer. This is equivalent to int.
-</para></entry></row>
-<row><entry>uint32_t</entry>
-<entry><para>An unsigned 32-bit integer.
-</para></entry></row>
-<row><entry>int64_t</entry>
-<entry><para>A signed 64-bit integer.
-</para></entry></row>
-<row><entry>uint64_t</entry>
-<entry><para>An unsigned 64-bit integer.
-</para></entry></row>
-<row><entry>int16_t</entry>
-<entry><para>A signed 16-bit integer.
-</para></entry></row>
-<row><entry>uint16_t</entry>
-<entry><para>An unsigned 16-bit integer.
-</para></entry></row>
-<row><entry>int8_t</entry>
-<entry><para>A signed 8-bit integer.
-</para></entry></row>
-<row><entry>uint8_t</entry>
-<entry><para>An unsigned 8-bit integer.
-</para></entry></row>
-<row><entry>float</entry>
-<entry><para>A 32-bit floating point number. When used as an
-argument to a routine or method, the strings "nan", "+infinity", and
-"-infinity" will be converted into the appropriate floating-point values. The
-reverse conversion is used when converting floating-point values back into
-Rexx objects.
-</para></entry></row>
-<row><entry>double</entry>
-<entry><para>A 64-bit floating point number. The Rexx runtime applies the
-same special processing for nan, +infinity, and -infinity values as float types.
-</para></entry></row>
-</tbody>
-</tgroup>
-</informaltable>
-</section>
-</section>
-
-<section id="apiconcepts"><title>Introduction to API Vectors</title>
-<para>The Rexx APIs operate through a set of interface vectors that define a
-set of interpreter services that are available. There are different interface
-vectors used for different contexts, but they use very similar calling concepts.
-</para>
-<para>The first interface vector you'll encounter with the programming interfaces is
-the RexxInstance value returned by RexxCreateInterpreter. The RexxInstance type is defined
-as a struct when compiled for C code, or a C++ class when compiled for ++. The
-struct version looks like this:</para>
-<programlisting>
-struct RexxInstance_
-{
- RexxInstanceInterface *functions; // the interface function vector
- void *applicationData; // creator defined data pointer
-};
-</programlisting>
-<para>The field <emphasis role="italic">applicationData</emphasis> contains any
-value that was specified via the APPLICATION_DATA option on the RexxCreateInterpreter call.
-This provides easy access any application-specific data needed to interact with the interpreter.
-All other interface contexts will include a pointer to the RexxInstance structure, so it is
-always possible to recover this data pointer.</para>
-<para>The <emphasis role="italic">functions</emphasis> field is a pointer to a second structure
-that defines the RexxInstance programming interfaces. The RexxInstance services are ones that
-may be called from any thread and in any context. The services are called using C function pointer
-fields in the interface structure. The RexxInstanceInterface looks like this:</para>
-<programlisting>
-typedef struct
-{
- wholenumber_t interfaceVersion; // The interface version identifier
-
- void (RexxEntry *Terminate)(RexxInstance *);
- logical_t (RexxEntry *AttachThread)(RexxInstance *, RexxThreadContext **);
- size_t (RexxEntry *InterpreterVersion)(RexxInstance *);
- size_t (RexxEntry *LanguageLevel)(RexxInstance *);
- void (RexxEntry *Halt)(RexxInstance *);
- void (RexxEntry *SetTrace)(RexxInstance *, logical_t);
-} RexxInstanceInterface;
-</programlisting>
-<para>The first thing to note is the interface struct contains a field named
-<emphasis role="italic">interfaceVersion</emphasis>. The interfaceVersion field
-is a version marker that defines the services the called interpreter version supports.
-This interface version is incremented any time new functions are added to the interface.
-Using the interface version allows application code to reliably check that required
-interface functions are available.</para>
-<para>The remainder of the fields are functions that can be called to perform RexxInstance
-operations. Note that the first argument to all of the functions is a pointer to a RexxInstance
-structure. A call to the InterpreterVersion API from C code would look like this:</para>
-<programlisting>
-size_t version = context->functions->InterpreterVersion(context);
-</programlisting>
-<para>When using C++ code, the RexxThreadContext struct has convenience methods that simplify calling
-these functions:</para>
-<programlisting>
-size_t version = context->InterpreterVersion();
-</programlisting>
-<para>Note that in the C++ call, it is no longer necessary to pass the RexxInstance as the
-first object. That's handled automatically be the C++ method.</para>
-<para>The RexxThreadContext pointer returned from RexxCreateInterpreter() functions the same way.
-RexxThreadContext looks like this:</para>
-<programlisting>
-struct RexxThreadContext_
-{
- RexxInstance *instance; // the owning instance
- RexxThreadInterface *functions; // the interface function vector
-}
-</programlisting>
-<para>The RexxThreadContext struct contains an embedded RexxInstance pointer for the instance it is
-associated with. It also contains an interface vector for the functions available with a
-RexxThreadContext. The RexxThreadInterface vector has its own version identifier and
-function pointer for each of the defined services.
-The RexxThreadContext functions all require a RexxThreadContext pointer as
-the first argument. The RexxThreadContext struct also defines C++ convenience methods for accessing its
-own function and the functions for the RexxInstance as well. For example, to call the
-InterpreterVersion() API using a RexxThreadContext from C code, it is necessary to code</para>
-<programlisting>
-size_t version = context->instance->functions->InterpreterVersion(context->instance);
-</programlisting>
-<para>The C++ version is simply</para>
-<programlisting>
-// context is a RexxThreadContext *
-size_t version = context->InterpreterVersion();
-</programlisting>
-<para>When the Rexx interpreter makes calls to native code routines and methods, or invokes
-exit handlers, the call-outs use context structures specific to the callout context. These
-are the <link linkend="callcontext">RexxCallContext</link>,
-<link linkend="methodcontext">RexxMethodContext</link>, and
-<link linkend="exitcontext">RexxExitContext</link> structures. Each structure
-contains a pointer to a RexxThreadContext instance that's valid until the call returns.
-Through the embedded RexxThreadContext, each call may use any of the
-RexxThreadContext or RexxInstance
-functions in addition to the context-specific functions. Each context defines
-C++ methods for the embedded RexxInstance and RexxThreadContext functions.</para>
-<para>Note that the RexxInstance interface can be used at any time and on any thread. The
-RexxThreadContext returned by RexxCreateInterpreter() can only be used on the same thread
-as the RexxCreateInterpreter() call, but is not valid for use in the context of a method, routine,
-or exit call-out. In those contexts, the RexxThreadContext instance passed to the call-out
-must be used. A RexxThreadContext instance created for a call-out is only valid until the
-call returns to the interpreter.</para>
-</section>
-
-<section id="instancethread"><title>Threading Considerations</title>
-<para>When using the <link linkend="createinterpreter">RexxCreateInterpreter()</link> API to create a new
-interpreter instance, a RexxThreadContext pointer is returned with the interpreter instance. The thread
-context vector allows you to perform operations such as running Rexx programs while in the same thread
-context as the RexxCreateInterpreter() call.
-</para>
-<para>A given interpreter instance can process calls from multiple threads, but a RexxThreadContext instance
-must be obtained for each additional thread you wish to use. A new thread context is obtained
-by calling AttachThread() using the RexxInstance API vector returned from RexxCreateInterpreter(). Once
-a valid RexxThreadContext interface has been created for the thread, any of the operations defined
-for a thread context are usable on that thread. Before the thread terminates,
-the <link linkend="mthDetachThread">DetachThread()</link>
-API must be called to remove the attached thread from the interpreter instance.</para>
-<para>The interpreter is capable of asynchronous calls to interpreter APIs from signal or event
-handlers. When called in this manner, it is possible that AttachThread will be called while
-running on a thread that is already attached to the interpreter instance. When a nested
-<link linkend="mthAttachThread"> AttachThread()</link> call is made, the previous thread context is
-suspended and the newly created thread context is now the active one for the source thread. It is very
-important that DetachThread() be called to restore the original thread context before you return from the
-signal handler.
-</para>
-</section>
-<section id="gcmodel"><title>Garbage Collection Considerations</title>
-<para>When any context API has a return result that is a Rexx object instance,
-the source API context will protect that object instance from garbage collection
-for as long as the source API context is valid. Once the API context is destroyed,
-the accessed objects might become eligible for garbage collection and be reclaimed
-by the interpreter runtime.
-These object references are only
-valid until the current context is destroyed. They cannot be stored in native code
-control blocks and be used in other thread contexts. If you wish to store object references so
-that they can be accessed by other thread contexts, you can create a globally valid object
-reference using the <link linkend="mthRequestGlobalReference">RequestGlobalReference()</link>
-API. A global reference will create a global on an object that will protect the
-object from the garbage collector until the interpreter instance is terminated. Protecting
-the object will also protect any objects referenced by the protected object. For example,
-using RequestGlobalReference() to protect a Directory object will also protect all of the
-directory keys and values.
-The global reference can be used with any API context valid for the same interpreter instance. Once you
-are finished with a locked object, <link
-linkend="mthReleaseGlobalReference">ReleaseGlobalReference()</link> cac remove the object lock and make
-the object eligible for garbage collection.
-</para>
-<para>On the flip side of this, sometimes it is desirable to remove the local API context
-protection from an object. For example, if you use the ArrayAt() API to iterate through all
-of the elements of an Array, each object ArrayAt() returns will be added to the API context's protection
-table. There is a small overhead associated with each protected reference, so iterating through a large
-array would accumulate that overhead for each array element. Using <link
-linkend="mthReleaseLocalReference"></link>ReleaseLocalReference() on an object reference you no longer
-require will remove the local lock, and thus limit the overhead.
-</para>
-</section>
-
-<section id="instanceapi"><title>Rexx Interpreter Instance Interface</title>
-<para>The Interpreter Instance API is defined by the RexxInstance interface vector. The RexxInstance
-defines methods that affect the global state of the interpreter instance. Most of the instance APIs can
-be called from any thread without requiring any extra steps to access the instance. The two most
-important instance operations are <link linkend="mthAttachThread">AttachThread()</link> and <link
-linkend="mthTerminate">Terminate()</link>. AttachThread() allows additional externally identified
-threads to be included in the interpreter instance threadpool. AttachThread returns a
-<link linkend="threadcontext">RexxThreadContext</link> interface vector that enables a wider range of
-capability for the attached thread. The Terminate() API shuts down an interpreter instance when it is no
-longer needed.
-</para>
-</section>
-
-<section id="threadcontext"><title>Rexx Thread Context Interface</title>
-<para>The RexxThreadContext interface vector provides a very wide range of functions
-to your application code. There are roughly 125 functions defined on a RexxThreadContext.
-Among the services provided are:
-</para>
-<itemizedlist>
-<listitem><para>Running Rexx programs</para></listitem>
-<listitem><para>Loading Rexx packages</para></listitem>
-<listitem><para>Invoking methods of Rexx objects</para></listitem>
-<listitem><para>Converting between objects and various C++ types</para></listitem>
-<listitem><para>Creating and manipulating common Rexx object types</para></listitem>
-<listitem><para>Raising/handling Rexx syntax errors</para></listitem>
-</itemizedlist>
-<para>The C++ methods defined on a RexxThreadContext C++ object include the methods defined
-by the <link linkend="instanceapi">RexxInstance</link> class,
-so the single context vector is used to access both thread context
-and interpreter instance APIs.</para>
-<para>A RexxThreadContext instance is returned with the original
-<link linkend="createinterpreter">RexxCreateInterpreter()</link> call that create the
-interpreter instance. The <link linkend="mthAttachThread">AttachThread()</link> method
-will create a RexxThreadContext instance for additional threads that you add to an interpreter
-instance. Additionally, the <link linkend="methodcontext">RexxMethodContext</link>,
-<link linkend="callcontext">RexxCallContext</link>,
-and <link linkend="exitcontext">RexxExitContext</link>
-objects embed a RexxThreadContext object the same way that a RexxThreadContext object embeds
-a RexxInstance object.</para>
-</section>
-
-<section id="methodcontext"><title>Rexx Method Context Interface</title>
-<para>A RexxMethodContext object is included as an argument
-to any <link linkend="methodapi">native C++ method</link>
-defined in external libraries. The method context provides services that are specific to
-a method call, including:
-</para>
-<itemizedlist>
-<listitem><para>Accessing method-specific values such as SELF, SUPER, etc.</para></listitem>
-<listitem><para>Manipulating object instance variables</para></listitem>
-<listitem><para>Forwarding messages</para></listitem>
-<listitem><para>Manipulating GUARD state</para></listitem>
-<listitem><para>Locating classes defined in the method's package scope</para></listitem>
-</itemizedlist>
-<para>In addition to the method-specific functions, the RexxMethodContext object has an embedded
-a <link linkend="threadcontext">RexxThreadContext</link>
-object created specifically for this environment. The RexxThreadContext provides a large number of
-additional methods to the method environment.
-</para>
-<para>API calls made using the RexxMethodContext APIs may cause Rexx
-syntax errors or other condition to be raised. These calls
-are invoked as if the current context is operating with SIGNAL ON ALL enabled. Any
-conditions will be trapped and
-held in a pending condition until the current context returns. At the return, if a
-condition is still pending, the appropriate condition is reraised in the caller's context.
-These
-errors can be checked using the <link linkend="mthCheckCondition">CheckCondition()</link> API, and
-pending conditions can be cancelled using <link linkend="mthClearCondition">ClearCondition()</link>.
-</para>
-</section>
-
-<section id="callcontext"><title>Rexx Call Context Interface</title>
-<para>A RexxCallContext object is included as an argument to any
-<link linkend="functionapi">native C++ routine</link>
-defined in external libraries. The call context provides services that are specific to
-a routine call, including:
-</para>
-<itemizedlist>
-<listitem><para>Accessing caller context specific values such as the current numeric settings</para></listitem>
-<listitem><para>Manipulating variables in the caller's variable context</para></listitem>
-<listitem><para>Locating classes defined in the routine's package scope</para></listitem>
-</itemizedlist>
-<para>In addition to the call-specific functions, the RexxCallContext object has an embedded
-a <link linkend="threadcontext">RexxThreadContext</link>
-object created specifically for this environment. The RexxThreadContext provides a large number of
-additional methods to the call environment.</para>
-<para>API calls made using the RexxCallContext APIs may cause Rexx
-syntax errors or other condition to be raised. These calls are invoked
-as if the current context is operating with SIGNAL ON ALL enabled. Any
-conditions will be trapped and
-held in a pending condition until the current context returns. At the return, if a
-condition is still pending, the appropriate condition is reraised in the caller's context.
-These
-errors can be checked using the <link linkend="mthCheckCondition">CheckCondition()</link> API, and
-pending conditions can be cancelled using <link linkend="mthClearCondition">ClearCondition()</link>.
-</para>
-</section>
-
-<section id="exitcontext"><title>Rexx Exit Context Interface</title>
-<para>A RexxExitContext object is included as an argument to any
-<link linkend="contextexitdef">system exit</link> or
-<link linkend="commandapi">command handler</link>.
-The exit context provides services that are specific to
-a exit call, including:
-</para>
-<itemizedlist>
-<listitem><para>Accessing caller context specific values such as the current numeric settings</para></listitem>
-<listitem><para>Manipulating variables in the caller's variable context</para></listitem>
-</itemizedlist>
-<para>In addition to the exit-specific functions, the RexxExitContext object has an embedded
-a <link linkend="threadcontext">RexxThreadContext</link>
-object created specifically for this environment. The RexxThreadContext provides a large number of
-additional methods to the exit environment.</para>
-<para>API calls made using the RexxExitContext APIs may cause Rexx
-syntax errors or other condition to be raised. These calls are invoked
-as if the current context is operating with SIGNAL ON ALL enabled. Any
-conditions will be trapped and
-held in a pending condition until the current context returns. At the return, if a
-condition is still pending, the appropriate condition is reraised in the caller's context.
-These
-errors can be checked using the <link linkend="mthCheckCondition">CheckCondition()</link> API, and
-pending conditions can be cancelled using <link linkend="mthClearCondition">ClearCondition()</link>.
-</para>
-</section>
-
-<section id="buildinglibs"><title>Building an External Native Library</title>
-<para>External libraries written in compiled languages (typically C or C++)
-provide a means to
-interface Rexx programs with other subsystems intended for compiled languages.
-These libraries are packaged as Dynamic Link Libraries on Windows or shared libraries on
-Unix-based systems.
-A named library can be loaded using the ::REQUIRES directive, the
-loadLibrary() method on the Package class, or by using the EXTERNAL keyword on
-a ::ROUTINE or ::METHOD directive.
-</para>
-<para>When the library is loaded, the interpreter searches for an entry point
-in the library named RexxGetPackage(). An external library package is required
-to provide a RexxGetPackage() function that returns a pointer to the descriptor
-structure defining the methods and routines contained within the library.
-The RexxGetPackage() routine takes no arguments and has a RexxPackageEntry *return value.
-This is normally created using the OOREXX_GET_PACKAGE()
-macro defined in the oorexxapi.h include file.</para>
-<programlisting>
-// package loading stub.
-OOREXX_GET_PACKAGE(package);
-</programlisting>
-<para>Where <emphasis role="italic">package</emphasis> is the name
-of the RexxPackageEntry table for this library. The package
-entry table is a descriptor contained within the library.
-Note that on Windows, it is necessary to explicitly export the
-RexxPackageEntry() function when the library is linked. This is the
-only name you are required to export. Calls are made to the library
-routines and methods using addresses stored in the RexxPackageEntry table.</para>
-<para>The RexxPackageEntry structure contains information about the
-package and descriptors of any methods and/or routines defined within
-the package. The structure looks like this:</para>
-<programlisting>
-typedef struct _RexxPackageEntry
-{
- int size; // size of the structure...helps compatibility
- int apiVersion; // version this was compiled with
- int requiredVersion; // minimum required interpreter version (0 means any)
- const char *packageName; // package identifier
- const char *packageVersion; // package version #
- RexxPackageLoader loader; // the package loader
- RexxPackageUnloader unloader; // the package unloader
- struct _RexxRoutineEntry *routines; // routines contained in this package
- struct _RexxMethodEntry *methods; // methods contained in this package
-} RexxPackageEntry;
-</programlisting>
-<para>The fields in the RexxPackageEntry have the following functions:</para>
-<variablelist>
-<varlistentry><term><emphasis role="italic">size</emphasis>
-and <emphasis role="italic">apiVersion</emphasis></term>
-<listitem><para>these fields give the size of the received table and identify
-the interpreter level this library has been compiled against. These indicators
-will allow additional information to be added to the RexxPackageEntry in the future without causing
-compatibility issues for older libraries. Normally, these two fields are defined using the
-STANDARD_PACKAGE_HEADER macro, which sets both values.
-</para></listitem></varlistentry>
-<varlistentry><term><emphasis role="italic">requiredVersion</emphasis></term>
-<listitem><para>a library can specify the minimum interpreter level it requires.
-The interpreter will only load libraries that match the minimum compatibility
-requirement of the library package. A zero value in this field means there's no
-minimum level requirement. The macro REXX_CURRENT_INTERPRETER_VERSION will set
-the level of interpreter you are compiling against. If REXX_CURRENT_INTERPRETER_VERSION
-is specified, then the library package will not load with older releases. The
-API header files will be updated with a macro for each interpreter version. The
-version macros are of the form
-REXX_INTERPRETER_<emphasis role="italic">version</emphasis>_<emphasis role="italic">level</emphasis>_<emphasis role="italic">revision</emphasis>,
-where <emphasis role="italic">version</emphasis>, <emphasis role="italic">level</emphasis>,
-and <emphasis role="italic">revision</emphasis> refer to the corresponding values in an
-interpreter release number. For example, REXX_INTERPRETER_4_0_0 would indicate that the
-4.0.0 interpreter level is the minimum this library requires.
-</para></listitem></varlistentry>
-<varlistentry><term>packageName</term>
-<listitem><para>a descriptive name for this library package.
-</para></listitem></varlistentry>
-<varlistentry><term>packageVersion</term>
-<listitem><para>a version string for this package. The version can be
-in whatever form is appropriate for the package.
-</para></listitem></varlistentry>
-<varlistentry><term>packageLoader</term>
-<listitem><para>a function that will be called when the library package is
-first loaded by the interpreter. The package loader function is passed a
-RexxThreadContext pointer, which will give the package access to Rexx
-interpreter services at initialization time. The package loader is optional
-and is indicated by a NULL value in the descriptor.
-</para></listitem></varlistentry>
-<varlistentry><term>packageUnloader</term>
-<listitem><para>a function that will be called when the library package is
-unloaded by the interpreter. The unloading process happens when the last
-interpreter instance is destroyed during the last cleanup stages. This gives
-the loaded library an opportunity to clean up any global resources such as
-cached Rexx object references.
-The package loader is optional
-and is indicated by a NULL value in the descriptor.
-</para></listitem></varlistentry>
-<varlistentry><term>routines</term>
-<listitem><para>a pointer to an array of RexxRoutineEntry structures that define
-the routines provided by this package. If there are no routines, this field should be NULL.
-See <link linkend="functionapi">Defining Library Routines</link> for details on
-creating the exported routine table.
-</para></listitem></varlistentry>
-<varlistentry><term>method</term>
-<listitem><para>a pointer to an array of RexxMethodEntry structures that define
-the methods provided by this package. If there are no methods, this field should be NULL.
-See <link linkend="methodapi">Defining Library Methods</link> for details on
-creating the exported method table.
-</para></listitem></varlistentry>
-</variablelist>
-<para>Here is an example of a RexxPackageEntry table taken from the rxmath
-library package:</para>
-<programlisting>
-// now build the actual entry list
-RexxRoutineEntry rxmath_functions[] =
-{
- REXX_TYPED_ROUTINE(MathLoadFuncs, MathLoadFuncs),
- REXX_TYPED_ROUTINE(MathDropFuncs, MathDropFuncs),
- REXX_TYPED_ROUTINE(RxCalcPi, RxCalcPi),
- REXX_TYPED_ROUTINE(RxCalcSqrt, RxCalcSqrt),
- REXX_TYPED_ROUTINE(RxCalcExp, RxCalcExp),
- REXX_TYPED_ROUTINE(RxCalcLog, RxCalcLog),
- REXX_TYPED_ROUTINE(RxCalcLog10, RxCalcLog10),
- REXX_TYPED_ROUTINE(RxCalcSinH, RxCalcSinH),
- REXX_TYPED_ROUTINE(RxCalcCosH, RxCalcCosH),
- REXX_TYPED_ROUTINE(RxCalcTanH, RxCalcTanH),
- REXX_TYPED_ROUTINE(RxCalcPower, RxCalcPower),
- REXX_TYPED_ROUTINE(RxCalcSin, RxCalcSin),
- REXX_TYPED_ROUTINE(RxCalcCos, RxCalcCos),
- REXX_TYPED_ROUTINE(RxCalcTan, RxCalcTan),
- REXX_TYPED_ROUTINE(RxCalcCotan, RxCalcCotan),
- REXX_TYPED_ROUTINE(RxCalcArcSin, RxCalcArcSin),
- REXX_TYPED_ROUTINE(RxCalcArcCos, RxCalcArcCos),
- REXX_TYPED_ROUTINE(RxCalcArcTan, RxCalcArcTan),
- REXX_LAST_ROUTINE()
-};
-
-RexxPackageEntry rxmath_package_entry =
-{
- STANDARD_PACKAGE_HEADER
- REXX_INTERPRETER_4_0_0, // anything after 4.0.0 will work
- "RXMATH", // name of the package
- "4.0", // package information
- NULL, // no load/unload functions
- NULL,
- rxmath_functions, // the exported functions
- NULL // no methods in rxmath.
-};
-
-// package loading stub.
-OOREXX_GET_PACKAGE(rxmath);
-</programlisting>
-
-<section id="functionapi"><title>Defining Library Routines</title>
-<para>The RexxRoutineEntry table defines routines that are exported by a library package.
-This table is an array of RexxRoutineEntry structures, terminated by an entry that
-contains nothing but zero values in the fields. The REXX_LAST_ROUTINE() macro
-will generate a suitable table terminator entry.
-</para>
-<para>The remainder of the table will be entries generated via either the
-REXX_CLASSIC_ROUTINE() or REXX_TYPED_ROUTINE() macros. REXX_CLASSIC_ROUTINE()
-entries are for routines created using the older string-oriented function style.
-The classic routines allow packages to be migrated to the new package loading system
-without requiring a rewrite of all of the contained functions.
-See <link linkend="os2xfun">External Function Interface</link> for details on
-creating the functions in the classic style.</para>
-<para>Routine table entries defined using REXX_TYPED_ROUTINE() use the new
-object-oriented interfaces for creating routines. These routines can use
-the interpreter runtime to convert call arguments from Rexx objects into primitive
-types and return values converted from primitive types back into Rexx objects. These
-routines are also given access to a rich set of services through the
-<link linkend="callcontext">RexxCallContext</link>
-interface vector.</para>
-<para>The REXX_CLASSIC_ROUTINE() and REXX_TYPED_ROUTINE() macros take two arguments. The
-first entry is the package table name for this routine. The second argument is the
-entry point name of the real native code routine that implements the function.
-These names are frequently the same, but need not be. The package table name is the
-name this routine will be called with from Rexx code.
-</para>
-<para>Smaller function packages frequently place all of the contained functions
-and the package definition tables in the same file, with the package tables
-placed near the end of the source file so all of the functions are visible. For
-larger packages, it may be desirable to place the functions in more than
-one source file. For functions packaged as multiple source files, it is necessary
-to create prototype declarations so the routine entry table can be generated.
-The oorexxapi.h header file includes REXX_CLASSIC_ROUTINE_PROTOTYPE() and
-REXX_TYPED_ROUTINE_PROTOTYPE() macros to generate the appropriate declarations.
-For example,</para>
-<programlisting>
-// create function declarations for the linker
-REXX_TYPED_ROUTINE_PROTOTYPE(RxCalcPi);
-REXX_TYPED_ROUTINE_PROTOTYPE(RxCalcSqrt);
-
-// now build the actual entry list
-RexxRoutineEntry rxmath_functions[] =
-{
- REXX_TYPED_ROUTINE(RxCalcPi, RxCalcPi),
- REXX_TYPED_ROUTINE(RxCalcSqrt, RxCalcSqrt),
- REXX_LAST_ROUTINE()
-};
-</programlisting>
-
-<section id="routinedcl"><title>Routine Declarations</title>
-<para>Library routines are created using a series of macros that
-create the body of the function. These macros define the routine
-arguments and return value in a form that allows the Rexx runtime
-to perform argument checking and conversions before calling the
-target routine.
-These macros are named "RexxRoutine<emphasis role="italic">n</emphasis>, where
-<emphasis role="italic">n</emphasis> is the number of arguments you wish to
-be passed to your routine. For example,</para>
-<programlisting>
-RexxRoutine2(int, beep, wholenumber_t, frequency, wholenumber_t, duration)
-{
- return Beep(frequency, duration); /* sound beep */
-}
-</programlisting>
-<para>defines a <emphasis role="italic">beep</emphasis> routine that will be
-passed two <emphasis role="italic">wholenumber_t</emphasis> arguments
-(<emphasis role="italic">frequency</emphasis>
-and <emphasis role="italic">duration</emphasis>)...
[truncated message content] |