From: <wda...@us...> - 2008-07-24 19:31:49
|
Revision: 2778 http://oorexx.svn.sourceforge.net/oorexx/?rev=2778&view=rev Author: wdashley Date: 2008-07-24 19:31:58 +0000 (Thu, 24 Jul 2008) Log Message: ----------- ArtifactID: None Comment: Initial changes to the PG for 4.0. Lots more later. Modified Paths: -------------- docs/trunk/rexxpg/api.sgml docs/trunk/rexxpg/command.sgml docs/trunk/rexxpg/rexxpg.sgml Added Paths: ----------- docs/trunk/rexxpg/classicapi.sgml Modified: docs/trunk/rexxpg/api.sgml =================================================================== --- docs/trunk/rexxpg/api.sgml 2008-07-24 18:56:16 UTC (rev 2777) +++ docs/trunk/rexxpg/api.sgml 2008-07-24 19:31:58 UTC (rev 2778) @@ -41,21 +41,20 @@ # ######################################################################### --> -<appendix id="os2api"><title>Rexx Application Programming Interfaces</title> +<appendix id="api4x"> +<title>Rexx C++ Application Programming Interfaces</title> <para>This appendix describes how to interface applications to Rexx or extend -the Rexx language by using Rexx application programming interfaces (APIs). +the Rexx language by using Rexx C++ application programming interfaces (APIs). As used here, the term application refers to programs -written in languages other than Rexx. This is usually the C language. Conventions -in this appendix are based on the C language. Refer to a C programming reference -manual if you need a better understanding of these conventions.</para> -<para>The features described here let an application extend many parts of the +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 subcommands, external functions, and system exits. </para> +for Rexx methods, external functions, and system exits. </para> <variablelist> -<varlistentry><term>Subcommands</term> -<listitem><para>are commands issued from a Rexx program. A Rexx expression is evaluated -and the result is passed as a command to the currently addressed subcommand -handler. Subcommands are used in Rexx programs running as application macros. +<varlistentry><term>Rexx methods</term> +<listitem><para>are extensions to ooRexx classes. An ooRexx class can define a +method as being contained in an external shared library. </para></listitem></varlistentry> <varlistentry><term>Functions</term> <listitem><para>are direct extensions of the Rexx language. An application can create @@ -68,4369 +67,37 @@ replacing Rexx system requests. </para></listitem></varlistentry> </variablelist> -<para>Subcommand, function, and system exit handlers have similar coding, compilation, -and packaging characteristics.</para> -<para>In addition, applications can manipulate the variables in Rexx programs -(see <link linkend="os2vpi">Variable Pool Interface</link>), -and execute Rexx routines directly from memory -(see <link linkend="macrosp">Macrospace Interface</link>).</para> +<para>Methods, functions, and system exit handlers have similar coding, +compilation, and packaging characteristics. +</para> +<para>In addition, applications can call methods defined on an ooRexx class and +execute them from externally defined methods and functions.</para> -<section id="apigenc"><title>Handler Characteristics</title> -<para>The basic requirements for subcommand, function, and system exit handlers -are: </para> -<itemizedlist> -<listitem><para>Rexx handlers must use the APIENTRY (_stdcall) linkage convention. -Handler functions should be declared with the appropriate type definition -from the Rexx.H include file. Using <computeroutput>C++</computeroutput>, -the functions must be declared as <computeroutput>extern C</computeroutput>: -<itemizedlist> -<listitem><para>RexxSubcomHandler</para></listitem> -<listitem><para>RexxFunctionHandler</para></listitem> -<listitem><para>RexxExitHandler</para></listitem></itemizedlist></para></listitem> -<listitem><para>A Rexx handler must be packaged as either of the following: -<itemizedlist> -<listitem><para>An exported routine within a dynamic-link library (DLL) -</para></listitem> -<listitem><para>An entry point within an executable (EXE) module -</para></listitem> -</itemizedlist> -</para></listitem> -<listitem><para>A handler must be registered with Rexx before it can be used. Rexx uses -the registration information to locate and call the handler. For example, -external function registration of a dynamic-link library -external function identifies both the dynamic-link library -and routine that contains the external function. Also note: -<itemizedlist> -<listitem><para>Dynamic-link library handlers are global to the system; any -Rexx program can call them.</para></listitem> -<listitem><para>Executable file handlers are local to the registering process; -only a Rexx program running in the same process as an executable module can call -a handler packaged within that executable module.</para></listitem> -</itemizedlist></para></listitem></itemizedlist> +<section id="intertreterapi"><title>Rexx Interpreter API</title> +<para>This section describes how to invoke the Rexx interpreter via the +RexxCreatInterpreter API.</para> </section> -<section id="rxstrings"><title>RXSTRINGs</title> -<indexterm><primary>application programming interfaces</primary> -<secondary>RXSTRING data structure</secondary></indexterm> -<indexterm><primary>application programming interfaces</primary> -<secondary>RXSTRING data structure</secondary> -<tertiary>RXSTRING</tertiary></indexterm> -<indexterm><primary>RXSTRING</primary></indexterm> -<indexterm><primary>RXSTRING</primary> -<secondary>definition</secondary></indexterm> -<para>Many of the Rexx application programming interfaces pass Rexx character -strings to and from a Rexx procedure. The RXSTRING data structure is used -to describe Rexx character strings. An RXSTRING is a content-insensitive, -flat model character string with -a theoretical maximum length of 4 gigabytes. The following structure defines -an RXSTRING:</para> -<programlisting> -<![CDATA[ -typedef struct { - ULONG strlength; /* length of string */ - PCH strptr; /* pointer to string */ -} RXSTRING; - -typedef RXSTRING *PRXSTRING; /* pointer to an RXSTRING */ -]]> -</programlisting> - -<para>Notes:</para> -<orderedlist> -<listitem><para>The Rexx.H include file contains a number of convenient macros -for setting and testing RXSTRING values.</para></listitem> -<listitem><para> -An RXSTRING can have a value (including the null string, -"") or it can be empty. -<itemizedlist> -<listitem><para>If an RXSTRING has a value, the -<emphasis role="italic">strptr</emphasis> field is not null. The -RXSTRING macro RXVALIDSTRING(string) returns TRUE.</para></listitem> -<listitem><para>If an RXSTRING is the Rexx null string (""), the -<emphasis role="italic">strptr</emphasis> field -is not null and the <emphasis role="italic">strlength</emphasis> field is 0. -The RXSTRING macro RXZEROLENSTRING(string) returns TRUE.</para></listitem> -<listitem><para>If an RXSTRING is empty, the field -<emphasis role="italic">strptr</emphasis> is null. The RXSTRING -macro RXNULLSTRING(string) returns TRUE.</para></listitem> -</itemizedlist> -</para></listitem> -<listitem><para>When the Rexx -interpreter passes an RXSTRING to a subcommand handler, external function, -or exit handler, the interpreter adds a -<indexterm><primary>RXSTRING</primary> -<secondary>null terminated</secondary></indexterm> -null character (hexadecimal zero) -at the end of the RXSTRING data. You can use the C string library functions -on these strings. However, the RXSTRING data can also contain null characters. -There is no guarantee that the first null character encountered in an RXSTRING -marks the end of the string. You use the C string functions only when you -do not expect null characters in the RXSTRINGs, such as file names passed -to external functions. The <emphasis role="italic">strlength</emphasis> field -in the RXSTRING does not include the terminating null character.</para></listitem> -<listitem><para>On calls to subcommand -<indexterm><primary>RXSTRING</primary> -<secondary>returning</secondary></indexterm> -and external functions handlers, as well as to some of the exit handlers, -the Rexx interpreter expects that an RXSTRING value is returned. The Rexx -interpreter provides a default RXSTRING with a -<emphasis role="italic">strlength</emphasis> of 256 for -the returned information. If the returned data is shorter than 256 characters, -the handler can copy the data into the default RXSTRING and set the -<emphasis role="italic">strlength</emphasis> field to the length returned.</para> -<para>If the returned data is longer than 256 characters, -a new RXSTRING can be allocated using -<computeroutput>GlobalAlloc(size)</computeroutput>. The -<emphasis role="italic">strptr</emphasis> field must point to the new storage -and the <emphasis role="italic">strlength</emphasis> must -be set to the string length. The Rexx interpreter returns the newly allocated -storage to the system for the handler routine.</para></listitem> -</orderedlist> +<section id="apiconcepts"><title>Introduction to API Vectors</title> +<para>This section provides a general description of API vectors and how to use +them.</para> </section> -<section id="rxinvk"><title>Calling the Rexx Interpreter</title> -<indexterm><primary>application programming interfaces</primary> -<secondary>invoking the Rexx interpreter</secondary></indexterm> -<indexterm><primary>calling the Rexx interpreter</primary></indexterm> -<indexterm><primary>invoking the Rexx interpreter</primary></indexterm> -<indexterm><primary>Rexx interpreter, invoking</primary></indexterm> -<para>A Rexx program can be run directly from the command prompt -of the operating system, or from within an application.</para> - -<section id="invcom"><title>From the Operating System</title> -<para>You can run a Rexx program directly from the operating system -command prompt using Rexx followed by the program name. -See <link linkend="looks">Running a Rexx Program</link>.</para> +<section id="instanceapi"><title>Rexx Instance Interface</title> +<para>This section describes the Rexx instance interface and the methods it +provides.</para> </section> -<section id="fwaa"><title>From within an Application</title> -<para>The Rexx interpreter is a dynamic-link library -(DLL) routine (or Unix/Linux shared object). Any application -can call the Rexx interpreter to run a Rexx program. The interpreter is fully -reentrant and supports Rexx procedures running on several threads within the -same process.</para> -<para>A C-language prototype for calling Rexx is in the Rexx.H include file.</para> +<section id="threadapi"><title>Rexx Thread Interface</title> +<para>This section describes the Rexx thread interface and the methods it +provides.</para> </section> -<section id="rexxstartfu"><title>The RexxStart Function</title> -<indexterm><primary>application programming interfaces</primary> -<secondary>invoking the Rexx interpreter</secondary> -<tertiary>RexxStart</tertiary></indexterm> -<indexterm><primary>RexxStart</primary></indexterm> -<para>RexxStart calls the Rexx interpreter to run a Rexx procedure. </para> -<programlisting> -retc = RexxStart(ArgCount, ArgList, ProgramName, Instore, EnvName, - CallType, Exits, ReturnCode, Result); -</programlisting> - -<section id="rexxstartparm"><title>Parameters</title> -<para></para> -<variablelist> -<varlistentry><term>ArgCount (LONG) - input</term> -<listitem><para>is the number of elements in the -<emphasis role="italic">ArgList</emphasis> array. This is the -value that the <emphasis role="italic">ARG()</emphasis> built-in function in -the Rexx program returns. <emphasis role="italic">ArgCount</emphasis> -includes RXSTRINGs that represent omitted arguments. Omitted -arguments are empty RXSTRINGs (<emphasis role="italic">strptr</emphasis> -is null).</para></listitem></varlistentry> -<varlistentry><term>ArgList (PRXSTRING) - input</term> -<listitem><para>is an array of RXSTRING structures that are the Rexx program arguments. -</para></listitem></varlistentry> -<varlistentry><term>ProgramName (PSZ) - input</term> -<listitem><para>is the address of the ASCII name of the Rexx procedure. If -<emphasis role="italic">Instore</emphasis> is null, -<emphasis role="italic">ProgramName</emphasis> must contain at least the file name of -the Rexx procedure. You can also provide an extension, drive, and path. -If you do not specify a file extension, the -default is .CMD. A Rexx program can use any extension. If you do not -provide the path and the drive, the Rexx interpreter uses the usual file search -(current directory, then environment path).</para> -<para>If <emphasis role="italic">Instore</emphasis> is not null, -<emphasis role="italic">ProgramName</emphasis> is the name used in the -PARSE SOURCE instruction. If <emphasis role="italic">Instore</emphasis> -requests a Rexx procedure from the macrospace, -<indexterm><primary>RexxStart</primary> -<secondary>using macrospace programs</secondary></indexterm> -<emphasis role="italic">ProgramName</emphasis> is the macrospace -function name (see <link linkend="macrosp">Macrospace Interface</link>).</para> -</listitem></varlistentry> -<varlistentry><term>Instore (PRXSTRING) - input</term> -<listitem><para>is -an array of two RXSTRING descriptors for in-storage Rexx procedures. If the -<emphasis role="italic">strptr</emphasis> fields of both RXSTRINGs are null, -the interpreter searches for Rexx procedure -<emphasis role="italic">ProgramName</emphasis> in the Rexx macrospace (see -<link linkend="macrosp">Macrospace Interface</link>). -If the procedure is not in the macrospace, the call to RexxStart terminates -with an error return code. </para> -<para>If either <emphasis role="italic">Instore strptr</emphasis> field -is not null, <emphasis role="italic">Instore</emphasis> is used to run a Rexx -procedure directly from storage.</para> -<variablelist> -<varlistentry><term>Instore[0] -<indexterm><primary>RexxStart</primary> -<secondary>using in-storage programs</secondary></indexterm> -</term> -<listitem><para>is an RXSTRING describing a memory buffer that contains the Rexx procedure -source. The source must be an exact image of a Rexx procedure disk file, complete -with carriage returns, line feeds, and end-of-file characters. -</para></listitem></varlistentry> -<varlistentry><term>Instore[1]</term> -<listitem><para>is an RXSTRING containing the translated image of the Rexx procedure. -If <emphasis role="italic">Instore[1]</emphasis> is empty, the Rexx interpreter returns the -translated image in <emphasis role="italic">Instore[1]</emphasis> when the Rexx procedure -finishes running. The translated image may be used in -<emphasis role="italic">Instore[1]</emphasis> on subsequent RexxStart calls.</para> -<para>If <emphasis role="italic">Instore[1]</emphasis> is -not empty, the interpreter runs the translated image directly. The program -source provided in <emphasis role="italic">Instore[0]</emphasis> is used only if the Rexx -procedure uses the SOURCELINE built-in function. -<emphasis role="italic">Instore[0]</emphasis> can be empty if SOURCELINE -is not used. If <emphasis role="italic">Instore[0]</emphasis> is empty -and the procedure uses the SOURCELINE built-in function, SOURCELINE() -returns no lines and any attempt to access the source returns Error 40.</para> -<para>If <emphasis role="italic">Instore[1]</emphasis> is not empty, -but does not contain a valid Rexx translated image, unpredictable results -can occur. The Rexx interpreter might be able to determine that the translated -image is incorrect and translate the source again.</para> -<para><emphasis role="italic">Instore[1]</emphasis> is both an input and -an output parameter.</para> -</listitem></varlistentry> -</variablelist> -<para>If the procedure is executed from disk, the -<emphasis role="italic">Instore pointer</emphasis> must be null. -If the first argument string in <emphasis role="italic">Arglist</emphasis> -contains the string //T and the <emphasis role="italic">CallType</emphasis> -is RXCOMMAND, the interpreter performs a syntax check on the procedure source, -but does not execute it and does not store any images.</para> -<para>The program calling -RexxStart must release <emphasis role="italic">Instore[1]</emphasis> -using <computeroutput>RexxFreeMemory(ptr)</computeroutput> -when the translated image is no longer needed.</para> -<para>Only the interpreter version that created the image can run the translated -image. Therefore, neither change the format of the translated image of a Rexx -program, nor move a translated image to other systems or save it for later -use. You can, however, use the translated image several times during a single -application execution.</para> -</listitem></varlistentry> -<varlistentry><term>EnvName (PSZ) - input</term> -<listitem><para>is the address of the initial ADDRESS environment name. The ADDRESS -environment is a subcommand handler registered using RexxRegisterSubcomExe -or RexxRegisterSubcomDll. <emphasis role="italic">EnvName</emphasis> is used -as the initial setting for the Rexx ADDRESS instruction. </para> -<para>If <emphasis role="italic">EnvName</emphasis> is null, the file -extension is used as the initial ADDRESS environment. The environment name -cannot be longer than 250 characters.</para> -</listitem></varlistentry> -<varlistentry><term>CallType (LONG) - input</term> -<listitem><para>is the type of the Rexx procedure execution. Allowed execution types -are: -<variablelist> -<varlistentry><term>RXCOMMAND</term> -<listitem><para>The Rexx procedure is a system or application command. Rexx commands -usually have a single argument string. The Rexx PARSE SOURCE instruction -returns <computeroutput>COMMAND</computeroutput> as the second token. -</para></listitem></varlistentry> -<varlistentry><term>RXSUBROUTINE</term> -<listitem><para>The Rexx procedure is a subroutine of another program. The subroutine -can have several arguments and does not need to return a result. The Rexx -PARSE SOURCE instruction returns SUBROUTINE as the second token. -</para></listitem></varlistentry> -<varlistentry><term>RXFUNCTION</term> -<listitem><para>The Rexx procedure is a function called from another program. The subroutine -can have several arguments and must return a result. The Rexx PARSE SOURCE -instruction returns <computeroutput>FUNCTION</computeroutput> as the second -token.</para></listitem></varlistentry> -</variablelist> -</para></listitem></varlistentry> -<varlistentry><term>Exits (PRXSYSEXIT) - input -<indexterm><primary>RexxStart</primary> -<secondary>using exits</secondary></indexterm> -</term> -<listitem><para>is an array of RXSYSEXIT structures defining exits for the Rexx interpreter -to be used. The RXSYSEXIT structures have the following form:</para> -<indexterm><primary>application programming interfaces</primary> -<secondary>RXSTRING data structure</secondary> -<tertiary>RXSYSEXIT</tertiary></indexterm> -<indexterm><primary>application programming interfaces</primary> -<secondary>RXSYSEXIT data structure</secondary></indexterm> -<indexterm><primary>RXSYSEXIT data structure</primary></indexterm> -<programlisting> -<![CDATA[ -typedef struct { - PSZ sysexit_name; /* name of exit handler */ - LONG sysexit_code; /* system exit function code */ -} RXSYSEXIT; -]]> -</programlisting> -<para>The <emphasis role="italic">sysexit_name</emphasis> is the address of an -ASCII exit handler name registered with RexxRegisterExitExe or -RexxRegisterExitDll. <emphasis role="italic">Sysexit_code</emphasis> -is a code identifying the handler exit type. See -<link linkend="sysex">System Exit Interface</link> for exit code -definitions. An RXENDLST entry identifies the system-exit list end. -<emphasis role="italic">Exits</emphasis> must be null if exits are not used.</para> -</listitem></varlistentry> -<varlistentry><term>ReturnCode (PSHORT) - output</term> -<listitem><para>is the integer form of the -<emphasis role="italic">Result</emphasis> string. If the -<emphasis role="italic">Result</emphasis> string is a whole number in the range --(2**15) to 2**15-1, it is converted to an integer and also returned in -<emphasis role="italic">ReturnCode</emphasis>. -</para></listitem></varlistentry> -<varlistentry><term>Result (PRXSTRING) - output</term> -<listitem><para>is the string returned from the Rexx procedure with the Rexx -RETURN or EXIT instruction. A default RXSTRING can be provided for the returned -result. If a default RXSTRING is not provided or the default is too small -for the returned result, the Rexx interpreter allocates an RXSTRING using -<computeroutput>GlobalAlloc(size)</computeroutput>. The caller of RexxStart -is responsible for releasing the RXSTRING storage with -<computeroutput>RexxFreeMemory(ptr)</computeroutput>.</para> -<para>The Rexx interpreter -does not add a terminating null to <emphasis role="italic">Result</emphasis>.</para> -</listitem></varlistentry> -</variablelist> +<section id="buildinglibs"><title>Building an External Library</title> +<para>This section describes how to build an external library.</para> </section> -<section id="rexxstartrc"><title>Return Codes</title> -<para>The possible RexxStart return codes are: </para> -<variablelist> -<varlistentry><term>negative</term> - -<listitem><para>Interpreter errors. See the Appendix in the -<citetitle>Open Object Rexx: Reference</citetitle> for the list of Rexx errors. -</para></listitem></varlistentry> -<varlistentry><term>0</term> -<listitem><para>No errors occurred. The Rexx procedure ran normally. -</para></listitem></varlistentry> -<varlistentry><term>positive</term> -<listitem><para>A system return code that indicates problems finding or loading -the interpreter. See the return codes for the Windows functions -LoadLibrary and GetProcAddress for details. -</para></listitem></varlistentry> -</variablelist> -<para>When a macrospace Rexx procedure (see -<link linkend="macrosp">Macrospace Interface</link>) is not loaded -in the macrospace, the return code is -3 ("Program is unreadable").</para> +<section id="exitsapi"><title>Rexx Exits Interface</title> +<para>This section describes how to define a Rexx exit.</para> </section> - -<section id="rexxstartxmp"><title>Example</title> -<indexterm><primary>RexxStart</primary> -<secondary>example using</secondary></indexterm> -<para></para> -<programlisting> -<![CDATA[ -LONG return_code; /* interpreter return code */ -RXSTRING argv[1]; /* program argument string */ -RXSTRING retstr; /* program return value */ -SHORT rc; /* converted return code */ -CHAR return_buffer[250]; /* returned buffer */ - - /* build the argument string */ - MAKERXSTRING(argv[0], macro_argument, - strlen(macro_argument)); - /* set up default return */ - MAKERXSTRING(retstr, return_buffer, sizeof(return_buffer)); - - return_code = RexxStart(1, /* one argument */ - argv, /* argument array */ - "CHANGE.ED", /* Rexx procedure name */ - NULL, /* use disk version */ - "Editor", /* default address name */ - RXCOMMAND, /* calling as a subcommand */ - NULL, /* no exits used */ - &rc, /* converted return code */ - &retstr); /* returned result */ - - /* process return value */ -... - RexxWaitForTermination(); - /* need to return storage? */ - if (RXSTRPTR(retval) != return_buffer) - GlobalFree(RXSTRPTR(retval)); /* release the RXSTRING */ -]]> -</programlisting> -<para>When RexxStart is executed within an external program (usually -a C program), it runs synchronously with the main Rexx activity (thread) that -it started. That is, when the main activity terminates, RexxStart returns, -and the external program continues running.</para> -<para>To run RexxStart asynchronously, you can start several concurrent -activities from the main activity using START or REPLY (see -<link linkend="concur">Concurrency</link>). -RexxStart is still synchronous to the main activity, that is, it returns when -the main activity terminates, but it is asynchronous to the concurrent activities. -If a concurrent activity runs longer than the main activity, RexxStart returns -when the main activity ends, but the concurrent activity continues to run.</para> -<para>If, however, a concurrent activity is still running when the external program -ends, the activity is terminated. To ensure that all activities finish executing, -use RexxWaitForTermination or a looped RexxDidRexxTerminate in your external -program after RexxStart. The use of RexxWaitForTermination is recommended -also for programs that are not expected to use concurrency.</para> -<para>The following example demonstrates how to call MyCMD.CMD from a Cobol program -(Rexx is running in the same process as the Cobol program).</para> -<programlisting> - PROCESS PGMNAME(MIXED) - * You need to specify Rexx.LIB when you link this program, - * for example on the COB2 command. - * Note that the name RexxStart, used later, is case-sensitive, - * and requires the PGMNAME(MIXED) compiler option. - ************************************************************* - IDENTIFICATION DIVISION. - ************************************************************* - PROGRAM-ID. 'CALLRexx' - AUTHOR. IBM VISUALAGE FOR COBOL. - - ************************************************************* - *NAME: CALLRexx *** - * *** - *FUNCTION: CALL A Rexx PROCEDURE NAME XXXXXXXX, *** - * PASSING ARGUMENT AND GETTING RETURNED DATA. *** - * *** - *EXTERNAL SUBROUTINES: NONE *** - *COPY MEMBERS: NONE *** - * *** - ************************************************************* - - ************************************************************* - ENVIRONMENT DIVISION. - ************************************************************* - CONFIGURATION SECTION. - - ************************************************************* - DATA DIVISION. - ************************************************************* - - WORKING-STORAGE SECTION. - - -</programlisting> -<programlisting> - ************************************************************* - * INTERNAL VARIABLES * - ************************************************************* - - 01 WS-WORK-FIELDS. - 05 WS-RESULT-AREA PIC X(255) VALUE SPACES. - 05 WS-ARGUMENT-AREA PIC X(255) VALUE SPACES. - 05 WS-PARM1 PIC X(50) VALUE '55'. - 05 WS-PARM2 PIC X(8) VALUE '66'. - 01 WS-RexxSTART-PARAMETERS. - 05 WS-Rexx-ARGUMENT-COUNT PIC S9(9) VALUE +1 COMP-5. - 05 WS-Rexx-ARGUMENT-LIST. - 10 WS-ARG-LENGTH PIC 9(9) COMP-5. - 10 WS-ARG-POINTER POINTER. - 05 WS-Rexx-PROGRAM-NAME PIC X(255) VALUE LOW-VALUES. - 05 WS-Rexx-ENV-NAME PIC X(20) VALUE LOW-VALUES. - 05 WS-Rexx-RETURN-CODE PIC S9(9) VALUE 0 COMP-5. - 05 WS-Rexx-RESULT. - 10 WS-RESULT-LENGTH PIC 9(9) COMP-5. - 10 WS-RESULT-POINTER POINTER. - 05 WS-Rexx-INTERPRETER-RC PIC S9(9) COMP-5. - - LINKAGE SECTION. - PROCEDURE DIVISION. - SET WS-ARG-POINTER TO ADDRESS OF WS-ARGUMENT-AREA. - MOVE LENGTH OF WS-ARGUMENT-AREA - TO WS-ARG-LENGTH. - STRING WS-PARM1 DELIMITED BY SPACE - ' ' DELIMITED BY SIZE - WS-PARM2 DELIMITED BY SPACE - INTO WS-ARGUMENT-AREA - END-STRING. - STRING 'MYCMD' DELIMITED BY SIZE - X'00' DELIMITED BY SIZE - INTO WS-Rexx-PROGRAM-NAME - END-STRING. - STRING 'CGISRV' DELIMITED BY SIZE - X'00' DELIMITED BY SIZE - INTO WS-Rexx-ENV-NAME - END-STRING. - SET WS-RESULT-POINTER TO - ADDRESS OF WS-RESULT-AREA. - MOVE LENGTH OF WS-RESULT-AREA TO WS-RESULT-LENGTH. - - -</programlisting> -<programlisting> - * Note that the name RexxStart is case sensitive - CALL 'RexxStart' USING - BY VALUE WS-Rexx-ARGUMENT-COUNT - BY REFERENCE WS-Rexx-ARGUMENT-LIST - BY REFERENCE WS-Rexx-PROGRAM-NAME - BY VALUE 0 - BY REFERENCE WS-Rexx-ENV-NAME - BY VALUE 0 - BY VALUE 0 - BY REFERENCE WS-Rexx-RETURN-CODE - BY REFERENCE WS-Rexx-RESULT - RETURNING WS-Rexx-INTERPRETER-RC. - DISPLAY WS-Rexx-RETURN-CODE ' ' WS-Rexx-INTERPRETER-RC. - DISPLAY WS-RESULT-LENGTH. - DISPLAY WS-RESULT-AREA. - GOBACK. -</programlisting> -</section> -</section> - -<section id="rexxwaitfortermfu"><title>The RexxWaitForTermination Function</title> -<indexterm><primary>application programming interfaces</primary> -<secondary>invoking the Rexx interpreter</secondary> -<tertiary>RexxWaitForTermination</tertiary></indexterm> -<indexterm><primary>RexxWaitForTermination</primary></indexterm> -<para>RexxWaitForTermination waits for the termination of all activities of the -program that were started by RexxStart. This function puts your program into -a wait state. It cannot continue until the activities have finished.</para> -<programlisting> -RexxWaitForTermination(); -</programlisting> -</section> - -<section id="rexxdidtexxtermfu"><title>The RexxDidRexxTerminate Function</title> -<indexterm><primary>application programming interfaces</primary> -<secondary>invoking the Rexx interpreter</secondary> -<tertiary>RexxDidRexxTerminate</tertiary></indexterm> -<indexterm><primary>RexxDidRexxTerminate</primary></indexterm> -<para>RexxDidRexxTerminate checks for the termination of all activities of the -program that were started by RexxStart, and allows your program to continue.</para> -<programlisting> -retc = RexxDidRexxTerminate(); -</programlisting> - -<section id="rexxdidrexxtermrc"><title>Return Codes</title> -<para></para> -<variablelist> -<varlistentry><term>0</term> -<listitem><para>Activities are still running. -</para></listitem></varlistentry> -<varlistentry><term>1</term> -<listitem><para>All activities have been terminated. -</para></listitem></varlistentry> -</variablelist> -</section> - -<section id="rexxdidrexxtermxmp"><title>Example</title> -<programlisting> -<![CDATA[ -while (!RexxDidRexxTerminate()) -{ - /* do your processing */ -} -]]> -</programlisting> -</section> -</section> -</section> - -<section id="subcom"><title>Subcommand Interface</title> -<indexterm><primary>application programming interfaces</primary> -<secondary>subcommand interface</secondary></indexterm> -<indexterm><primary>subcommand interface</primary> -<secondary>description</secondary></indexterm> -<para>An application can create handlers to process commands from a Rexx program. -Once created, the subcommand handler name can be used with the RexxStart function -or the Rexx ADDRESS instruction. Subcommand handlers must be registered with -the RexxRegisterSubcomExe or RexxRegisterSubcomDll function before they are -used.</para> - -<section id="subinv"><title>Registering Subcommand Handlers</title> -<indexterm><primary>application programming interfaces</primary> -<secondary>handler definitions</secondary></indexterm> -<para>A subcommand handler can reside in the same module (executable or DLL) -as an application, or it can reside in a separate dynamic-link library. -It is recommended that an application that runs Rexx procedures -<indexterm><primary>subcommand interface</primary> -<secondary>registering</secondary></indexterm> -with RexxStart uses RexxRegisterSubcomExe to register subcommand handlers. -The Rexx interpreter passes commands to the application subcommand handler -entry point. Subcommand handlers created with RexxRegisterSubcomExe are available -only to Rexx programs called from the registering application.</para> -<para>The RexxRegisterSubcomDll interface creates subcommand handlers that reside -in a dynamic-link library. Any Rexx program using the -Rexx ADDRESS instruction can access a dynamic-link library -subcommand handler. A dynamic-link library subcommand -handler can also be registered directly from a Rexx program using the RXSUBCOM -command.</para> - -<section id="createsubcomhandl"><title>Creating Subcommand Handlers</title> -<indexterm><primary>application programming interfaces</primary> -<secondary>handler interface</secondary> -<tertiary>subcommand handler</tertiary></indexterm> -<indexterm><primary>subcommand interface</primary> -<secondary>definition</secondary></indexterm> -<para> The following example is a sample subcommand handler definition. </para> -<programlisting> -<![CDATA[ -ULONG APIENTRY command_handler( - PRXSTRING Command, /* Command string from Rexx */ - PUSHORT Flags, /* Returned Error/Failure flags */ - PRXSTRING Retstr); /* Returned RC string */ -]]> -</programlisting> -<para>where:</para> -<variablelist> -<varlistentry><term>Command</term> -<listitem><para>is the command string created by Rexx. </para> -<para><emphasis role="italic">command</emphasis> is a null-terminated -RXSTRING containing the issued command.</para> -</listitem></varlistentry> -<varlistentry><term>Flags</term> -<listitem><para>is the subcommand completion status. The subcommand handler can indicate -success, error, or failure status. The subcommand handler can set -<emphasis role="italic">Flags</emphasis> to one of the following values: -<variablelist> -<varlistentry><term>RXSUBCOM_OK</term> -<listitem><para>The subcommand completed normally. No errors occurred during subcommand -processing and the Rexx procedure continues when the subcommand handler returns. -</para></listitem></varlistentry> -<varlistentry><term>RXSUBCOM_ERROR -<indexterm><primary>subcommand interface</primary> -<secondary>subcommand errors</secondary></indexterm> -</term> -<listitem><para>A subcommand error occurred. RXSUBCOM_ERROR indicates a subcommand -error occurred; for example, incorrect command options or syntax.</para> -<para>If the -subcommand handler sets <emphasis role="italic">Flags</emphasis> to -RXSUBCOM_ERROR, the Rexx interpreter -raises an ERROR condition if SIGNAL ON ERROR or CALL ON ERROR traps have been -created. If TRACE ERRORS has been issued, Rexx traces the command when the -subcommand handler returns.</para> -</listitem></varlistentry> -<varlistentry><term>RXSUBCOM_FAILURE -<indexterm><primary>subcommand interface</primary> -<secondary>subcommand failures</secondary></indexterm> -</term> -<listitem><para>A subcommand failure occurred. RXSUBCOM_FAILURE indicates that general -subcommand processing errors have occurred. For example, unknown commands -usually return RXSUBCOM_FAILURE. </para> -<para>If the subcommand handler sets <emphasis role="italic">Flags</emphasis> -to RXSUBCOM_FAILURE, the Rexx interpreter raises a FAILURE condition -if SIGNAL ON FAILURE or CALL ON FAILURE traps have been created. If TRACE -FAILURES has been issued, Rexx traces the command when the subcommand handler -returns.</para> -</listitem></varlistentry> -</variablelist> -</para></listitem></varlistentry> -<varlistentry><term>Retstr -<indexterm><primary>subcommand interface</primary> -<secondary>subcommand return code</secondary></indexterm> -</term> -<listitem><para>is the address of an RXSTRING for the return code. It is a -character string return code that is assigned to the Rexx special variable -RC when the subcommand handler returns to Rexx. The Rexx interpreter provides -a default 256-byte RXSTRING in <emphasis role="italic">Retstr</emphasis>. -A longer RXSTRING can be allocated with -<computeroutput>GlobalAlloc(size)</computeroutput> if the return string is -longer than the default RXSTRING. If the subcommand handler sets -<emphasis role="italic">Retstr</emphasis> to an empty RXSTRING (a null -<emphasis role="italic">strptr</emphasis>), Rexx assigns the string 0 to RC. -</para></listitem></varlistentry> -</variablelist> - -<section id="subcomhandlxmp"><title>Example</title> -<indexterm><primary>subcommand interface</primary> -<secondary>subcommand handler example</secondary></indexterm> -<programlisting> -<![CDATA[ -ULONG APIENTRY Edit_Commands( - PRXSTRING Command, /* Command string passed from the caller */ - PUSHORT Flags, /* pointer too short for return of flags */ - PRXSTRING Retstr) /* pointer to RXSTRING for RC return */ -{ - LONG command_id; /* command to process */ - LONG rc; /* return code */ - PSZ scan_pointer; /* current command scan */ - PSZ target; /* general editor target */ - - scan_pointer = Command->strptr; /* point to the command */ - /* resolve command */ - command_id = resolve_command(&scan_pointer); - - switch (command_id) { /* process based on command */ - - case LOCATE: /* locate command */ - - /* validate rest of command */ - if (rc = get_target(&scan_pointer, &target)) { - *Flags = RXSUBCOM_ERROR; /* raise an error condition */ - break; /* return to Rexx */ - } - rc = locate(target); /* locate target in the file */ - *Flags = RXSUBCOM_OK; /* not found is not an error */ - break; /* finish up */ - -... - - default: /* unknown command */ - rc = 1; /* return code for unknown */ - *Flags = RXSUBCOM_FAILURE; /* this is a command failure */ - break; - } - - sprintf(Retstr->strptr, "%d", rc); /* format return code string */ - /* and set the correct length */ - Retstr->strlength = strlen(Retstr->strptr); - return 0; /* processing completed */ -} -]]> -</programlisting> -</section> -</section> -</section> - -<section id="rxxfin"><title>Subcommand Interface Functions</title> -<para>The following sections explain the functions for registering and using -subcommand handlers.</para> - -<section id="screg"><title>RexxRegisterSubcomDll</title> -<indexterm><primary>application programming interfaces</primary> -<secondary>subcommand interface</secondary> -<tertiary>RexxRegisterSubcomDll</tertiary></indexterm> -<indexterm><primary>RexxRegisterSubcomDll</primary></indexterm> -<indexterm><primary>subcommand interface</primary> -<secondary>RexxRegisterSubcomDll</secondary></indexterm> -<para>RexxRegisterSubcomDll registers a subcommand handler that resides in -a dynamic-link library routine.</para> -<programlisting> -retc = RexxRegisterSubcomDll(EnvName, ModuleName, EntryPoint, - UserArea, DropAuth); -</programlisting> - -<section id="rexxregistersubcomdllparm"><title>Parameters</title> -<para></para> -<variablelist> -<varlistentry><term>EnvName (PSZ) - input</term> -<listitem><para>is the address of an ASCII subcommand handler name. -</para></listitem></varlistentry> -<varlistentry><term>ModuleName (PSZ) - input</term> -<listitem><para>is the address of an ASCII dynamic-link library -name. <emphasis role="italic">ModuleName</emphasis> is the DLL file containing -the subcommand handler routine. -</para></listitem></varlistentry> -<varlistentry><term>EntryPoint (PSZ) - input</term> -<listitem><para>is the address of an ASCII dynamic-link library -procedure name. <emphasis role="italic">EntryPoint</emphasis> is the name of -the exported routine within <emphasis role="italic">ModuleName</emphasis> -that Rexx calls as a subcommand handler. -</para></listitem></varlistentry> -<varlistentry><term>UserArea (PUCHAR) - input</term> -<listitem><para>is the address of an 8-byte area of user-defined information. The 8 -bytes <emphasis role="italic">UserArea</emphasis> addresses are saved with -the subcommand handler registration. <emphasis role="italic">UserArea</emphasis> -can be null if there is no user information to be saved. The -RexxQuerySubcom function can retrieve the saved user information. -</para></listitem></varlistentry> -<varlistentry><term>DropAuth (ULONG) - input</term> -<listitem><para>is the drop authority. -<emphasis role="italic">DropAuth</emphasis> identifies the processes that -can deregister the subcommand handler. The possible -<emphasis role="italic">DropAuth</emphasis> values are: -<variablelist> -<varlistentry><term>RXSUBCOM_DROPPABLE</term> -<listitem><para>Any process can deregister the subcommand handler with RexxDeregisterSubcom. -</para></listitem></varlistentry> -<varlistentry><term>RXSUBCOM_NONDROP</term> -<listitem><para>Only a -<indexterm><primary>thread</primary></indexterm> -thread within the same process as the thread that registered -the handler can deregister the handler with RexxDeregisterSubcom. -</para></listitem></varlistentry> -</variablelist> -</para></listitem></varlistentry> -</variablelist> -</section> - -<section id="rxsubcomrc"><title>Return Codes</title> -<informaltable frame="all"> -<tgroup cols="3"> -<colspec colnum="1" colwidth="4*"> -<colspec colnum="2" colwidth="1*"> -<colspec colnum="3" colwidth="5*"> -<tbody> -<row> -<entry>RXSUBCOM_OK</entry> -<entry>0</entry> -<entry>A subcommand has executed successfully.</entry> -</row> -<row> -<entry>RXSUBCOM_DUP</entry> -<entry>10</entry> -<entry>A duplicate handler name has been successfully registered. -There is either an executable handler with the same name registered in another -process, or a DLL handler with the same name registered in another DLL. (To -address this subcommand, you must specify its library name.)</entry> -</row> -<row> -<entry>RXSUBCOM_NOTREG</entry> -<entry>30</entry> -<entry>Registration was unsuccessful due to duplicate handler -and dynalink names (RexxRegisterSubcomExe or RexxRegisterSubcomDll); the subroutine -environment is not registered (other Rexx subcommand functions).</entry> -</row> -<row> -<entry>RXSUBCOM_NOEMEM</entry> -<entry>1002</entry> -<entry>There is insufficient memory available to complete this -request.</entry> -</row> -</tbody> -</tgroup> -</informaltable> -</section> - -<section id="rxsubcomremark"><title>Remarks</title> -<para><emphasis role="italic">EntryPoint</emphasis> can only be a 32-bit -routine.</para> -</section> -</section> - -<section id="screg2"><title>RexxRegisterSubcomExe</title> -<indexterm><primary>application programming interfaces</primary> -<secondary>subcommand interface</secondary> -<tertiary>RexxRegisterSubcomExe</tertiary></indexterm> -<indexterm><primary>RexxRegisterSubcomExe</primary></indexterm> -<indexterm><primary>subcommand interface</primary> -<secondary>RexxRegisterSubcomExe</secondary></indexterm> -<para>RexxRegisterSubcomExe registers a subcommand handler that resides within -the application code.</para> -<programlisting> -retc = RexxRegisterSubcomExe(EnvName, EntryPoint, UserArea); -</programlisting> - -<section id="rxregsubcomparm"><title>Parameters</title> -<para></para> -<variablelist> -<varlistentry><term>EnvName (PSZ) - input</term> -<listitem><para>is the address of an ASCII subcommand handler name. -</para></listitem></varlistentry> -<varlistentry><term>EntryPoint (PFN) - input</term> -<listitem><para>is the address of the subcommand handler entry point within the -application executable code. -</para></listitem></varlistentry> -<varlistentry><term>UserArea (PUCHAR) - input</term> -<listitem><para>is the address of an 8-byte area of user-defined information. The 8 -bytes <emphasis role="italic">UserArea</emphasis> addresses are saved with -the subcommand handler registration. -<emphasis role="italic">UserArea</emphasis> can be null if there is no user -information to be saved. The RexxQuerySubcom function can retrieve the user -information. -</para></listitem></varlistentry> -</variablelist> -</section> - -<section id="rxsubcomregrc"><title>Return Codes</title> -<informaltable frame="all"> -<tgroup cols="3"> -<colspec colnum="1" colwidth="4*"> -<colspec colnum="2" colwidth="1*"> -<colspec colnum="3" colwidth="5*"> -<tbody> -<row> -<entry>RXSUBCOM_OK</entry> -<entry>0</entry> -<entry>A subcommand has executed successfully.</entry> -</row> -<row> -<entry>RXSUBCOM_DUP</entry> -<entry>10</entry> -<entry>A duplicate handler name has been successfully registered. - There is either an executable handler with the same name registered in another -process, or a DLL handler with the same name registered in another DLL. (To -address this subcommand, you must specify its library name.)</entry> -</row> -<row> -<entry>RXSUBCOM_NOTREG</entry> -<entry>30</entry> -<entry>Registration was unsuccessful due to duplicate handler -and dynalink names (RexxRegisterSubcomExe or RexxRegisterSubcomDll); the subroutine -environment is not registered (other Rexx subcommand functions).</entry> -</row> -<row> -<entry>RXSUBCOM_NOEMEM</entry> -<entry>1002</entry> -<entry>There is insufficient memory available to complete this -request.</entry> -</row> -</tbody> -</tgroup> -</informaltable> -</section> - -<section id="rxsubcomregremark"><title>Remarks</title> -<para>If <emphasis role="italic">EnvName</emphasis> -is the same as a subcommand handler already registered -with RexxRegisterSubcomDll, RexxRegisterSubcomExe returns RXSUBCOM_DUP. -This is not an error condition. It means that RexxRegisterSubcomExe has successfully -registered the new subcommand handler.</para> -<para>A Rexx procedure can register dynamic-link library -subcommand handlers with the RXSUBCOM command. For example: </para> -<programlisting> -<![CDATA[ - /* register Dialog Manager */ - /* subcommand handler */ -"RXSUBCOM REGISTER ISPCIR ISPCIR ISPCIR" -Address ispcir /* send commands to dialog mgr */ -]]> -</programlisting> -<para>The RXSUBCOM command registers the Dialog Manager subcommand handler ISPCIR -as routine ISPCIR in the ISPCIR dynamic-link library.</para> -</section> - -<section id="rxsubcomregxmp"><title>Example</title> -<indexterm><primary>RexxStart</primary> -<secondary>exit example</secondary></indexterm> -<programlisting> -<![CDATA[ -WORKAREARECORD *user_info[2]; /* saved user information */ - -user_info[0] = global_workarea; /* save global work area for */ -user_info[1] = NULL; /* re-entrance */ - -rc = RexxRegisterSubcomExe("Editor", /* register editor handler */ - &Edit_Commands, /* located at this address */ - user_info); /* save global pointer */ - -]]> -</programlisting> -</section> -</section> - -<section id="scdrp"><title>RexxDeregisterSubcom</title> -<indexterm><primary>application programming interfaces</primary> -<secondary>subcommand interface</secondary> -<tertiary>RexxDeregisterSubcom</tertiary></indexterm> -<indexterm><primary>RexxDeregisterSubcom</primary></indexterm> -<indexterm><primary>subcommand interface</primary> -<secondary>RexxDeregisterSubcom</secondary></indexterm> -<para>RexxDeregisterSubcom deregisters a subcommand handler.</para> -<programlisting> -retc = RexxDeregisterSubcom(EnvName, ModuleName); -</programlisting> - -<section id="rxderegsubcomparm"><title>Parameters</title> -<para></para> -<variablelist> -<varlistentry><term>EnvName (PSZ) - input</term> -<listitem><para>is the address of an ASCII subcommand handler name. -</para></listitem></varlistentry> -<varlistentry><term>ModuleName (PSZ) - input</term> -<listitem><para>is the address of an ASCII dynamic-link library -name. <emphasis role="italic">ModuleName</emphasis> -is the name of the dynamic-link library containing the registered -subcommand handler. When <emphasis role="italic">ModuleName</emphasis> -is null, RexxDeregisterSubcom searches the RexxRegisterSubcomExe subcommand -handler list for a handler within the current process. If RexxDeregisterSubcom -does not find a RexxRegisterSubcomExe handler, it searches the RexxRegisterSubcomDll -subcommand handler list. -</para></listitem></varlistentry> -</variablelist> -</section> - -<section id="rxderegsubcomrc"><title>Return Codes</title> -<informaltable frame="all"> -<tgroup cols="3"> -<colspec colnum="1" colwidth="4*"> -<colspec colnum="2" colwidth="1*"> -<colspec colnum="3" colwidth="5*"> -<tbody> -<row> -<entry>RXSUBCOM_OK</entry> -<entry>0</entry> -<entry>A subcommand has executed successfully.</entry> -</row> -<row> -<entry>RXSUBCOM_NOTREG</entry> -<entry>30</entry> -<entry>Registration was unsuccessful due to duplicate handler -and dynalink names (RexxRegisterSubcomExe or RexxRegisterSubcomDll); the subroutine -environment is not registered (other Rexx subcommand functions).</entry> -</row> -<row> -<entry>RXSUBCOM_NOCANDROP</entry> -<entry>40</entry> -<entry>The subcommand handler has been registered as "not -droppable."</entry> -</row> -</tbody> -</tgroup> -</informaltable> -</section> - -<section id="rxderegsubcomremark"><title>Remarks</title> -<para>The handler is removed from the active subcommand handler list.</para> -</section> -</section> - -<section id="scqry"><title>RexxQuerySubcom</title> -<indexterm><primary>application programming interfaces</primary> -<secondary>subcommand interface</secondary> -<tertiary>RexxQuerySubcom</tertiary></indexterm> -<indexterm><primary>RexxQuerySubcom</primary></indexterm> -<indexterm><primary>subcommand interface</primary> -<secondary>RexxQuerySubcom</secondary></indexterm> -<para>RexxQuerySubcom -queries a subcommand handler and retrieves saved user information.</para> -<programlisting> -retc = RexxQuerySubcom(EnvName, ModuleName, Flag, UserWord); -</programlisting> - -<section id="rxquerysubcomparm"><title>Parameters</title> -<para></para> -<variablelist> -<varlistentry><term>EnvName (PSZ) - input</term> -<listitem><para>is the address of an ASCII subcommand handler name. -</para></listitem></varlistentry> -<varlistentry><term>ModuleName (PSZ) - input</term> -<listitem><para>is the address of an ASCII dynamic-link library -name. <emphasis role="italic">ModuleName</emphasis> restricts the query to a -subcommand handler within -the <emphasis role="italic">ModuleName</emphasis> dynamic-link library. When -<emphasis role="italic">ModuleName</emphasis> is null, RexxQuerySubcom -searches the RexxRegisterSubcomExe -subcommand handler list for a handler within the current process. If RexxQuerySubcom -does not find a RexxRegisterSubcomExe handler, it searches the RexxRegisterSubcomDll -subcommand handler list. -</para></listitem></varlistentry> -<varlistentry><term>Flag (PUSHORT) - output</term> -<listitem><para>is the subcommand handler registration flag. -<emphasis role="italic">Flag</emphasis> is the -<emphasis role="italic">EnvName</emphasis> subcommand handler registration -status. When RexxQuerySubcom -returns RXSUBCOM_OK, the <emphasis role="italic">EnvName</emphasis> -subcommand handler is currently -registered. When RexxQuerySubcom returns RXSUBCOM_NOTREG, the -<emphasis role="italic">EnvName</emphasis> subcommand handler is not registered. -</para></listitem></varlistentry> -<varlistentry><term>UserWord (PUCHAR) - output</term> -<listitem><para>is the address of an 8-byte area that receives the user information -saved with RexxRegisterSubcomExe or RexxRegisterSubcomDll. -<emphasis role="italic">UserWord</emphasis> can -be null if the saved user information is not required. -</para></listitem></varlistentry> -</variablelist> -</section> - -<section id="rxquerysubcomrc"><title>Return Codes</title> -<informaltable frame="all"> -<tgroup cols="3"> -<colspec colnum="1" colwidth="4*"> -<colspec colnum="2" colwidth="1*"> -<colspec colnum="3" colwidth="5*"> -<tbody> -<row> -<entry>RXSUBCOM_OK</entry> -<entry>0</entry> -<entry>A subcommand has executed successfully.</entry> -</row> -<row> -<entry>RXSUBCOM_NOTREG</entry> -<entry>30</entry> -<entry>Registration was unsuccessful due to duplicate handler -and dynalink names (RexxRegisterSubcomExe or RexxRegisterSubcomDll); the subroutine -environment is not registered (other Rexx subcommand functions).</entry> -</row> -</tbody> -</tgroup> -</informaltable> -</section> - -<section id="rxquerysubcomxmp"><title>Example</title> -<programlisting> -<![CDATA[ -ULONG APIENTRY Edit_Commands( - PRXSTRING Command, /* Command string passed from the caller */ - PUSHORT Flags, /* pointer too short for return of flags */ - PRXSTRING Retstr) /* pointer to RXSTRING for RC return */ -{ - WORKAREARECORD *user_info[2]; /* saved user information */ - WORKAREARECORD global_workarea; /* application data anchor */ - USHORT query_flag; /* flag for handler query */ - - - rc = RexxQuerySubcom("Editor", /* retrieve application work */ - NULL, /* area anchor from Rexx */ - &query_flag, - user_info); - - global_workarea = user_info[0]; /* set the global anchor */ -]]> -</programlisting> -</section> -</section> -</section> -</section> - -<section id="os2xfun"><title>External Function Interface</title> -<indexterm><primary>application programming interfaces</primary> -<secondary>external function interface</secondary></indexterm> -<indexterm><primary>external function interface</primary> -<secondary>description</secondary></indexterm> -<para>There are two types of Rexx external functions: </para> -<itemizedlist> -<listitem><para>Routines written in Rexx</para></listitem> -<listitem><para>Routines written in other Windows-supported languages -</para></listitem></itemizedlist> -<para>External functions written in Rexx do not need to be registered. These -functions are found by a disk search for a Rexx procedure file that matches -the function name.</para> - -<section id="xffmt"><title>Registering External Functions</title> -<para>An external function can reside in the same module (executable -or DLL) -as an application, or in a separate dynamic-link library. -RexxRegisterFunctionExe registers external functions within an application -module. External functions registered with RexxRegisterFunctionExe are available -only to Rexx programs called from the registering application.</para> -<para>The RexxRegisterFunctionDll interface registers external functions that -reside in a dynamic-link library. Any Rexx program can -access such an external function after it is registered. It can also be registered -directly from a Rexx program using the Rexx RXFUNCADD built-in function.</para> - -<section id="xffmtc"><title>Creating External Functions</title> -<indexterm><primary>external function interface</primary> -<secondary>writing</secondary></indexterm> -<para>The following is a sample external function definition:</para> -<programlisting> -<![CDATA[ -ULONG APIENTRY SysLoadFuncs( - PSZ Name, /* name of the function */ - LONG Argc, /* number of arguments */ - RXSTRING Argv[], /* list of argument strings */ - PSZ Queuename, /* current queue name */ - PRXSTRING Retstr) /* returned result string */ -]]> -</programlisting> -<para>where:</para> -<variablelist> -<varlistentry><term>Name</term> -<listitem><para>is the address of an ASCII function name used to call the -external function. -</para></listitem></varlistentry> -<varlistentry><term>Argc</term> -<listitem><para>is the number of elements in the -<emphasis role="italic">Argv</emphasis> array. -<emphasis role="italic">Argv</emphasis> contains -<emphasis role="italic">Argc</emphasis> RXSTRINGs. -</para></listitem></varlistentry> -<varlistentry><term>Argv</term> -<listitem><para>is an array of null-terminated RXSTRINGs for the function arguments. -</para></listitem></varlistentry> -<varlistentry><term>Queuename</term> -<listitem><para>is the name of the currently defined external Rexx data queue. -</para></listitem></varlistentry> -<varlistentry><term>Retstr</term> -<listitem><para>is the address of an RXSTRING for the returned value. -<emphasis role="italic">Retstr</emphasis> is -a character string function or subroutine return value. When a Rexx program -calls an external function with the Rexx CALL instruction, -<emphasis role="italic">Retstr</emphasis> is -assigned to the special Rexx variable RESULT. When the Rexx program calls -an external function with a function call, -<emphasis role="italic">Retstr</emphasis> is used directly -within the Rexx expression.</para> -<para>The Rexx interpreter provides a default 256-byte -RXSTRING in <emphasis role="italic">Retstr</emphasis>. A longer RXSTRING -can be allocated with <computeroutput>GlobalAlloc(size)</computeroutput> -if the returned string is longer than 256 bytes. -The Rexx interpreter releases <emphasis role="italic">Retstr</emphasis> with -<computeroutput>GlobalFree(ptr)</computeroutput> when -the external function completes.</para> -</listitem></varlistentry> -<varlistentry><term>Returns -<indexterm><primary>external function interface</primary> -<secondary>returned results</secondary></indexterm> -</term> -<listitem><para>is an integer return code from the function. When the external function -returns <computeroutput>0</computeroutput>, the function completed successfully. -<emphasis role="italic">Retstr</emphasis> contains -the return value. When the external function returns a nonzero return code, -the Rexx interpreter raises Rexx error 40, "Incorrect call to routine". -The <emphasis role="italic">Retstr</emphasis> value is ignored. </para> -<para>If the external function does not -have a return value, the function must set -<emphasis role="italic">Retstr</emphasis> to an empty RXSTRING -(null <emphasis role="italic">strptr</emphasis>). When an external function -called as a function does not return a value, the interpreter raises error 44, -"Function or message did not return data". When an external function -called with the Rexx CALL instruction does not return a value, the Rexx -interpreter drops (unassigns) the special variable RESULT.</para> -</listitem></varlistentry> -</variablelist> -</section> -</section> - -<section id="xfclg"><title>Calling External Functions</title> -<para>RexxRegisterFunctionExe external functions are local to the registering -process. Another process can call the RexxRegisterFunctionExe to make these -functions local to this process. RexxRegisterFunctionDll functions, however, -are ava... [truncated message content] |
From: <wda...@us...> - 2009-01-05 16:16:20
|
Revision: 3872 http://oorexx.svn.sourceforge.net/oorexx/?rev=3872&view=rev Author: wdashley Date: 2009-01-05 16:16:16 +0000 (Mon, 05 Jan 2009) Log Message: ----------- Move both of the api sections from the appendix to chapters. Modified Paths: -------------- docs/trunk/rexxpg/api.sgml docs/trunk/rexxpg/classicapi.sgml docs/trunk/rexxpg/rexxpg.sgml Modified: docs/trunk/rexxpg/api.sgml =================================================================== --- docs/trunk/rexxpg/api.sgml 2009-01-05 15:28:00 UTC (rev 3871) +++ docs/trunk/rexxpg/api.sgml 2009-01-05 16:16:16 UTC (rev 3872) @@ -41,7 +41,7 @@ # ######################################################################### --> -<appendix id="api4x"> +<chapter id="api4x"> <title>Rexx C++ Application Programming Interfaces</title> <para>This appendix describes how to interface applications to Rexx or extend the Rexx language by using Rexx C++ application programming interfaces (APIs). @@ -1172,4 +1172,4 @@ </section> -</appendix> +</chapter> Modified: docs/trunk/rexxpg/classicapi.sgml =================================================================== --- docs/trunk/rexxpg/classicapi.sgml 2009-01-05 15:28:00 UTC (rev 3871) +++ docs/trunk/rexxpg/classicapi.sgml 2009-01-05 16:16:16 UTC (rev 3872) @@ -41,7 +41,7 @@ # ######################################################################### --> -<appendix id="classicapi"> +<chapter id="classicapi"> <title>Classic Rexx Application Programming Interfaces</title> <para>This appendix describes how to interface applications to Rexx or extend the Rexx language by using Rexx application programming interfaces (APIs). @@ -4295,4 +4295,4 @@ </section> </section> </section> -</appendix> +</chapter> Modified: docs/trunk/rexxpg/rexxpg.sgml =================================================================== --- docs/trunk/rexxpg/rexxpg.sgml 2009-01-05 15:28:00 UTC (rev 3871) +++ docs/trunk/rexxpg/rexxpg.sgml 2009-01-05 16:16:16 UTC (rev 3872) @@ -82,9 +82,9 @@ &classes; <!-- A Closer Look at Objects --> &command; <!-- Commands --> &rexio; <!-- Input and Output --> -<!-- start of appendix --> &api; <!-- Rexx Application Programming Interfaces --> &classicapi; <!-- Classic Rexx Application Programming Interfaces --> +<!-- start of appendix --> &rxruntime; <!-- Object Rexx Runtime --> &samples; <!-- Sample Rexx Programs --> ¬ices; <!-- Notices --> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <sah...@us...> - 2009-01-21 06:01:58
|
Revision: 3983 http://oorexx.svn.sourceforge.net/oorexx/?rev=3983&view=rev Author: sahananda Date: 2009-01-21 06:01:50 +0000 (Wed, 21 Jan 2009) Log Message: ----------- source for diagram Added Paths: ----------- docs/trunk/rexxpg/rxo90004.odg docs/trunk/rexxpg/rxo90004.png Added: docs/trunk/rexxpg/rxo90004.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxo90004.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxo90004.png =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxo90004.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <bi...@us...> - 2009-01-25 20:01:11
|
Revision: 4016 http://oorexx.svn.sourceforge.net/oorexx/?rev=4016&view=rev Author: bigrixx Date: 2009-01-25 20:01:07 +0000 (Sun, 25 Jan 2009) Log Message: ----------- More API work Modified Paths: -------------- docs/trunk/rexxpg/api.sgml docs/trunk/rexxpg/classicapi.sgml Modified: docs/trunk/rexxpg/api.sgml =================================================================== --- docs/trunk/rexxpg/api.sgml 2009-01-25 19:51:21 UTC (rev 4015) +++ docs/trunk/rexxpg/api.sgml 2009-01-25 20:01:07 UTC (rev 4016) @@ -497,15 +497,67 @@ </programlisting> <section id="functionapi"><title>Defining Library Routines</title> -<para>This section describes the Rexx external function interface and the methods it -provides.</para> +<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 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 from primitive types back into Rexx objects. These +routines are also given access to a rich set of services via the RexxCallContext +interface vector.<?para> +<para>The REXX_CLASSIC_ROUTINE() and REXX_TYPED_ROUTINE() 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.</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 desireable to place the functions in more than +one source file. For functions packaged as multiple source files, it is necessary +to create a 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(RxCalcPi); +REXX_TYPED_ROUTINE(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>This section describes how to define an external routine. +</para> </section> +</section> <section id="methodapi"><title>Defining Library Methods</title> <para>This section describes the Rexx method interface and the methods it provides.</para> + +<section id="routinedcl"><title>Method Declarations</title> +<para>This section describes how to define an external method. +</para> </section> </section> +</section> <section id="exitsapi"><title>Rexx Exits Interface</title> <para>This section describes how to define a Rexx exit.</para> Modified: docs/trunk/rexxpg/classicapi.sgml =================================================================== --- docs/trunk/rexxpg/classicapi.sgml 2009-01-25 19:51:21 UTC (rev 4015) +++ docs/trunk/rexxpg/classicapi.sgml 2009-01-25 20:01:07 UTC (rev 4016) @@ -1046,7 +1046,17 @@ <para>External functions written in Rexx do not need to be registered. These functions are found by a disk search for a Rexx procedure file that matches the function name.</para> - +<para>There are two styles of native code routines supported by Open Object Rexx. +Registered External Functions are an older style of routine that is only capable +of dealing with String data. These routines do not have access to any of the +object-oriented features of the language. The registered external functions +are described here, but should be considered only if compability with older +versions of Object Rexx or other Rexx interpreters is a consideration.</para> +<para>The newer style functions have access to Rexx objects and a fuller set of +APIs for interfacing with the interpreter runtime. These functions are the +preferred method for writing Open Object Rexx extensions are are defined in +<link linkend="buildinglibs">Building an External Native Library</link>. +</para> <section id="xffmt"><title>Registering External Functions</title> <para>An external function can reside in the same module (executable or library) This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <bi...@us...> - 2009-02-01 21:05:42
|
Revision: 4044 http://oorexx.svn.sourceforge.net/oorexx/?rev=4044&view=rev Author: bigrixx Date: 2009-02-01 21:05:38 +0000 (Sun, 01 Feb 2009) Log Message: ----------- RexxOptions docs Modified Paths: -------------- docs/trunk/rexxpg/api.sgml docs/trunk/rexxpg/classicapi.sgml Modified: docs/trunk/rexxpg/api.sgml =================================================================== --- docs/trunk/rexxpg/api.sgml 2009-02-01 12:36:43 UTC (rev 4043) +++ docs/trunk/rexxpg/api.sgml 2009-02-01 21:05:38 UTC (rev 4044) @@ -61,22 +61,201 @@ functions that extend the native Rexx function set. 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 +enabling different command environments for interfacing with different +application environments. +</para></listitem></varlistentry> <varlistentry><term>System exits</term> <listitem><para>are programmer-defined variations of the operating system. The application programmer can tailor the Rexx interpreter behavior by replacing Rexx system requests. </para></listitem></varlistentry> </variablelist> -<para>Methods, functions, and system exit handlers have similar coding, +<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 on an ooRexx class and +<para>In addition, applications can call methods defined on an Rexx objects and execute them from externally defined methods and functions.</para> <section id="intertreterapi"><title>Rexx Interpreter API</title> <para>This section describes how to invoke the Rexx interpreter via the RexxCreatInterpreter API.</para> +<section id="instanceoptions"><title>Interpreter Instance Options</title> +<para>The third argument to RexxCreateInterpreter is an optional list of options +that set characteristics of the of how the interpreter instance behaves. This +argument points to an array of RexxOption structures. Each RexxOption instance +contains information for a different named option. 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 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 enviroment +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.</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>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 identifying the type of the exit and the +exit entry point. +The list is terminated by an instance using an +exit type of 0. The direct exits are called using the RexxExitConext 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 name of the handler and the +handler 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> + +RexxContextEnvironments 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 RXSYSEXIT structs. Each enabled exit is +specified in a single RXSYSEXIT 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> + +RexxRegisteredEnvironments 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 @@ -991,6 +1170,10 @@ <para>This section describes how to define a Rexx exit.</para> </section> +<section id="commandapi"><title>Command Handler Interface</title> +<para>This section describes how to define a Rexx command handler.</para> +</section> + <section id="apilisting"><title>Rexx Methods Listing</title> <para>This section describes each available method and its associated context.</para> Modified: docs/trunk/rexxpg/classicapi.sgml =================================================================== --- docs/trunk/rexxpg/classicapi.sgml 2009-02-01 12:36:43 UTC (rev 4043) +++ docs/trunk/rexxpg/classicapi.sgml 2009-02-01 21:05:38 UTC (rev 4044) @@ -1467,7 +1467,7 @@ </section> </section> -<section id="sysex"><title>System Exit Interface</title> +<section id="sysex"><title>Registered System Exit Interface</title> <indexterm><primary>exits</primary></indexterm> <indexterm><primary>application programming interfaces</primary> <secondary>exit interface</secondary></indexterm> @@ -1490,7 +1490,8 @@ <para>Exit handlers are similar to subcommand handlers and external functions. Applications must register named exit handlers with the Rexx interpreter. Exit handlers can reside in dynamic-link libraries or -within an executable application module.</para> +within an executable application module. +</para> <section id="writesysexithandl"><title>Writing System Exit Handlers</title> <indexterm><primary>SYSEXIT interface</primary> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <sah...@us...> - 2009-02-05 06:15:10
|
Revision: 4074 http://oorexx.svn.sourceforge.net/oorexx/?rev=4074&view=rev Author: sahananda Date: 2009-02-05 06:15:07 +0000 (Thu, 05 Feb 2009) Log Message: ----------- source for diagram Added Paths: ----------- docs/trunk/rexxpg/rxo90008.odg docs/trunk/rexxpg/rxo90008.png docs/trunk/rexxpg/rxo90011.odg docs/trunk/rexxpg/rxo90011.png docs/trunk/rexxpg/rxo90014.odg docs/trunk/rexxpg/rxo90014.png docs/trunk/rexxpg/rxo90017.odg docs/trunk/rexxpg/rxo90017.png docs/trunk/rexxpg/rxo90018.odg docs/trunk/rexxpg/rxo90018.png docs/trunk/rexxpg/rxo90019.odg docs/trunk/rexxpg/rxo90019.png docs/trunk/rexxpg/rxo90020.odg docs/trunk/rexxpg/rxo90020.png Added: docs/trunk/rexxpg/rxo90008.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxo90008.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxo90008.png =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxo90008.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxo90011.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxo90011.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxo90011.png =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxo90011.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxo90014.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxo90014.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxo90014.png =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxo90014.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxo90017.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxo90017.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxo90017.png =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxo90017.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxo90018.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxo90018.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxo90018.png =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxo90018.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxo90019.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxo90019.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxo90019.png =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxo90019.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxo90020.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxo90020.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxo90020.png =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxo90020.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <sah...@us...> - 2009-02-09 09:24:15
|
Revision: 4107 http://oorexx.svn.sourceforge.net/oorexx/?rev=4107&view=rev Author: sahananda Date: 2009-02-09 09:24:13 +0000 (Mon, 09 Feb 2009) Log Message: ----------- picture sources + some tidying up Added Paths: ----------- docs/trunk/rexxpg/rxo90017.odg docs/trunk/rexxpg/rxo90017.png docs/trunk/rexxpg/rxo90018.odg docs/trunk/rexxpg/rxo90018.png docs/trunk/rexxpg/rxo90019.odg docs/trunk/rexxpg/rxo90019.png docs/trunk/rexxpg/rxoq0s01.odg docs/trunk/rexxpg/rxoq0s01.png docs/trunk/rexxpg/rxoq0s02.odg docs/trunk/rexxpg/rxoq0s02.png docs/trunk/rexxpg/rxoq0s03.odg docs/trunk/rexxpg/rxoq0s03.png docs/trunk/rexxpg/rxoq0s04.odg docs/trunk/rexxpg/rxoq0s04.png Added: docs/trunk/rexxpg/rxo90017.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxo90017.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxo90017.png =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxo90017.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxo90018.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxo90018.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxo90018.png =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxo90018.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxo90019.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxo90019.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxo90019.png =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxo90019.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxoq0s01.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxoq0s01.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxoq0s01.png =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxoq0s01.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxoq0s02.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxoq0s02.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxoq0s02.png =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxoq0s02.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxoq0s03.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxoq0s03.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxoq0s03.png =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxoq0s03.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxoq0s04.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxoq0s04.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxoq0s04.png =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxoq0s04.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <sah...@us...> - 2009-02-15 08:13:03
|
Revision: 4162 http://oorexx.svn.sourceforge.net/oorexx/?rev=4162&view=rev Author: sahananda Date: 2009-02-15 08:13:00 +0000 (Sun, 15 Feb 2009) Log Message: ----------- Picture source Added Paths: ----------- docs/trunk/rexxpg/rxoq0s05.odg docs/trunk/rexxpg/rxoq0s05.png Added: docs/trunk/rexxpg/rxoq0s05.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxoq0s05.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxoq0s05.png =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxoq0s05.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <bi...@us...> - 2009-02-15 15:21:14
|
Revision: 4164 http://oorexx.svn.sourceforge.net/oorexx/?rev=4164&view=rev Author: bigrixx Date: 2009-02-15 15:21:10 +0000 (Sun, 15 Feb 2009) Log Message: ----------- editorial updates Modified Paths: -------------- docs/trunk/rexxpg/api.sgml docs/trunk/rexxpg/meet.sgml docs/trunk/rexxpg/preface.sgml docs/trunk/rexxpg/tour.sgml Modified: docs/trunk/rexxpg/api.sgml =================================================================== --- docs/trunk/rexxpg/api.sgml 2009-02-15 12:43:07 UTC (rev 4163) +++ docs/trunk/rexxpg/api.sgml 2009-02-15 15:21:10 UTC (rev 4164) @@ -7653,12 +7653,11 @@ <listitem><para>A pointer to the location used to return the conversion result.</para></listitem> </varlistentry> </variablelist> -<section><title>Returns</title> +<para><emphasis role="bold">Returns</emphasis></para> <para>1 = success, 0 = conversion error. The converted value is stored in the location pointed to by <emphasis role="italic">n</emphasis>. </para> </section> -</section> <section id="mthObjectToIntptr"><title>ObjectToIntptr</title> <indexterm><primary>ObjectToIntptr</primary></indexterm> @@ -7707,12 +7706,11 @@ <listitem><para>A pointer to the location used to return the conversion result.</para></listitem> </varlistentry> </variablelist> -<section><title>Returns</title> +<para><emphasis role="bold">Returns</emphasis></para> <para>1 = success, 0 = conversion error. The converted value is stored in the location pointed to by <emphasis role="italic">n</emphasis>. </para> </section> -</section> <section id="mthObjectToLogical"><title>ObjectToLogical</title> <indexterm><primary>ObjectToLogical</primary></indexterm> Modified: docs/trunk/rexxpg/meet.sgml =================================================================== --- docs/trunk/rexxpg/meet.sgml 2009-02-15 12:43:07 UTC (rev 4163) +++ docs/trunk/rexxpg/meet.sgml 2009-02-15 15:21:10 UTC (rev 4164) @@ -41,7 +41,7 @@ # ######################################################################### --> -<chapter id="meet"><title>Meet Object Rexx</title> +<chapter id="meet"><title>Meet Open Object Rexx (ooRexx)</title> <para>Rexx is a versatile, free-format language. Its simplicity makes it a good first language for beginners. For more experienced users and computer professionals, Rexx offers powerful functions and the ability to issue commands to several @@ -54,15 +54,15 @@ <section id="oop"><title>Object-Oriented Programming</title> <para>Object-oriented extensions have been added to traditional Rexx, but its -existing functions and instructions have not changed. The Object Rexx interpreter -is actually an enhanced version of its predecessor, but with new support for: </para> +existing functions and instructions have not changed. The Open Object Rexx interpreter +is an enhanced version of its predecessor with support for:</para> <itemizedlist> <listitem><para>Classes, objects, and methods</para></listitem> <listitem><para>Messaging and polymorphism</para></listitem> <listitem><para>Inheritance and multiple inheritance</para></listitem></itemizedlist> -<para>Object Rexx supplies the user with a base set of classes: ALARM, CLASS, -ARRAY, LIST, QUEUE, TABLE, SET, DIRECTORY, RELATION, BAG, MESSAGE, -METHOD, MONITOR, STEM, STREAM, STRING, and SUPPLIER. Object Rexx is fully +<para>Object Rexx supplies the user with a base set of built-in classes providing +many useful functions. +Open Object Rexx is fully compatible with earlier versions of Rexx that were not object-oriented.</para> </section> @@ -73,16 +73,14 @@ </section> <section id="crossplat"><title>Cross-Platform Versatility</title> -<para>Versions of Object Rexx are now available for a wide variety +<para>Versions of ooRexx are now available for a wide variety of platforms, and the programs you create with Object Rexx will run on any of these, including -<trademark>Linux</trademark> for <trademark>Intel</trademark>, -<trademark class="registered">Linux for S/390</trademark>, and +<trademark>Linux</trademark>, <trademark class="registered">AIX</trademark>, as well as -<trademark>Windows 95</trademark>, -<trademark>Windows 98</trademark>, -<trademark class="registered">Windows NT</trademark>, and -<trademark class="registered">Windows 2000</trademark>.</para> +<trademark class="registered">Windows XP</trademark>, and +<trademark class="registered">Windows Vista</trademark>. +It is also available in 64-bit versions that can exploit larger address spaces. </section> <section id="fewrule"><title>Fewer Rules</title> @@ -100,8 +98,8 @@ code before they can be run.</para> </section> -<section id="builtin"><title>Built-In Functions and Methods</title> -<para>Rexx has built-in functions and methods that perform various processing, +<section id="builtin"><title>Built-In Classes and Functions</title> +<para>Rexx has built-in classes and functions that perform various processing, searching, and comparison operations for text and numbers and provide formatting capabilities and arithmetic calculations.</para> </section> @@ -128,12 +126,11 @@ </section> <section id="devtool"><title>Impressive Development Tools</title> -<para>The Open Object Rexx Windows places many powerful tools at +<para>The ooRexx places many powerful tools at your disposal. These include a Rexx API to other languages like C/C++ or Cobol, -OLE/ActiveX support, a mathematical functions package, file encryption -functions for the Windows 2000 file system, and Windows Scripting -Host support.</para> +OLE/ActiveX support, a mathematical functions package. +</para> </section> </section> @@ -143,8 +140,8 @@ <indexterm><primary>Rexx</primary> <secondary>and Unix</secondary></indexterm> <para>The most important role Rexx plays is as a programming -language for Windows and Unix. A Rexx program can serve as a -script for the operating system to follow. Using +language for Windows and Unix-based systems. A Rexx program can serve as a +script for the operating system. Using Rexx, you can reduce long, complex, or repetitious tasks to a single command or program.</para> </section> @@ -157,10 +154,8 @@ changing its existing functions and instructions. So you can continue to use Rexx's procedural instructions, and incorporate objects as you become more comfortable with the technology. In general, your current Rexx programs -will work without change. In contrast to the traditional Rexx interpreter, -the Object Rexx interpreter checks <emphasis role="italic">all</emphasis> -the syntax at start-up time, and this means that any syntax errors that -exist will be found.</para> +will work without change. +</para> <para>In object-oriented technology, <indexterm><primary>objects</primary></indexterm> <emphasis role="italic">objects</emphasis> are used in programs to model the @@ -202,17 +197,19 @@ <secondary>traditional</secondary></indexterm> <para>In traditional (classic) Rexx, all data was stored as strings. The strings represented character data as well as numeric data. -From an object-oriented perspective, traditional Rexx had one kind of objects: -strings. In object-oriented terminology, each string variable is an +From an object-oriented perspective, traditional Rexx had just one kind of object: +the string. In object-oriented terminology, each string variable is a <indexterm><primary>strings</primary></indexterm> <indexterm><primary>objects</primary></indexterm> <emphasis role="italic">object</emphasis> that is an <indexterm><primary>instances</primary></indexterm> -instance of the String class.</para> -<para>In -Object Rexx, variables can now reference objects other than strings. In addition -to a string class, Rexx now includes classes for creating arrays, queues, -streams, and many other useful objects. Objects in these new Rexx classes +reference to an instance of the String class.</para> +<para>With +ooRexx, variables can now reference objects other than strings. In addition +to the String class, Rexx includes classes for creating arrays, queues, +streams, and many other useful objects. Additionally, you can create your own +classes that can interoperate seamlessly with the language built-in classes. +Objects in these Rexx classes are manipulated by methods instead of traditional functions. To activate a method, you just send a message to the object.</para> <para>For example, instead of using the SUBSTR function on a string @@ -242,11 +239,17 @@ the Name object is sent the SUBSTR message. The numbers in parentheses (2,3) are arguments sent as part of the message. The SUBSTR method is run for the Name object, and the result is assigned to the -<emphasis role="italic">s</emphasis> string object.</para> +<emphasis role="italic">s</emphasis> string object. +Conceptually, you are "asking" the String object refered to by variable NAME to +give you its substring starting at character 2 for 3 characters. Many String +operations are available as both class methods and built-in functions, but the +String class also provides many method enhancements for which there are no corresponding +built-in functions. +</para> -<para>For the new -classes (such as array or queue), methods are provided, but not equivalent -functions. For example, suppose you want to use a Rexx array object instead +<para>For +classes other than String (such as Array or Queue), methods are provided, but not equivalent +built-in functions. For example, suppose you want to use a Rexx Array object instead of the traditional string-based <indexterm><primary>string</primary></indexterm> <indexterm><primary>stem</primary></indexterm> @@ -259,16 +262,29 @@ ]]> </programlisting> -<para>A new instance, named Myarray, of the Array class is created. A period -and the class name identify the class. The period is necessary because it -precedes the class name in an expression. The Myarray array object has five -elements. Some of the other methods, besides NEW, for array objects are PUT, -AT, REMOVE, SIZE, [], and []=.</para> +<para>A new instance of the Array class is created and reference +to it is stored in the variable MyArray. +A period and the class name identify the class, .Array. The period tells the +interpreter to look in the Rexx environment for a class named "ARRAY". +The Myarray array object has five +elements, but the array itself is currently empty. Items can be added using methods +defined by the array class.</para> +<programlisting> +<![CDATA[ +myarray[1] = "Rick" +myarray[2] = "David" +myarray[3] = "Mark" + +say myarray[1] myarray[2] myarray[3] +]]> +</programlisting> +<para>The Array class implements many more methods. See the ooRexx reference for +details on what additional methods are provided.</para> <para>By adding object technology to its repertoire of traditional programming techniques, Rexx has evolved -into an object-oriented language, like Smalltalk. Object Rexx accommodates +into an object-oriented language, like Smalltalk. Rexx accommodates the programming techniques of traditional Rexx while adding new ones. With -Object Rexx, you can use the new technology as much or as little as you like, +ooRexx, you can use the new technology as much or as little as you like, at whatever pace you like. You can mix classic and object techniques. You can ease into the object world gradually, building on the Rexx skills and knowledge you already have.</para> @@ -293,12 +309,12 @@ <listitem><para>Cost-savings potential</para></listitem> <listitem><para>Increased adaptability and scalability</para></listitem> </itemizedlist> -<para>With Object Rexx, you get the user-friendliness of Rexx in an +<para>With ooRexx, you get the user-friendliness of Rexx in an object-oriented environment.</para> <para>Object Rexx provides a Sockets API for Rexx. -So you can script Object Rexx clients and servers, and run them in the Internet.</para> +So you can script Rexx clients and servers, and run them in the Internet.</para> <para>Object Rexx also provides access to FTP commands by means of -its RxFtp package, and to the use of mathematical functions by means of its +its RxFtp package, and the use of mathematical functions by means of its RxMath utility package. The Sockets, FTP, and mathematical functions packages are each supplied with separate, full documentation.</para> </section> Modified: docs/trunk/rexxpg/preface.sgml =================================================================== --- docs/trunk/rexxpg/preface.sgml 2009-02-15 12:43:07 UTC (rev 4163) +++ docs/trunk/rexxpg/preface.sgml 2009-02-15 15:21:10 UTC (rev 4164) @@ -45,9 +45,7 @@ <para>This book describes the Open Object Rexx, or Object Rexx programming language. In the following, it is called Rexx unless compared to its traditional predecessor.</para> -<para>This book is aimed at developers familiar with -<trademark class="registered">Windows</trademark> and -<trademark class="registered">Unix</trademark> +<para>This book is aimed at developers who want to use Rexx for object-oriented programming, or a mix of traditional and object-oriented programming.</para> <para>This book assumes you are already familiar with the techniques of traditional @@ -75,29 +73,13 @@ know how to: </para> <itemizedlist> <listitem><para>Program with a traditional language like C, Basic, or Pascal.</para></listitem> -<listitem><para>Use basic Windows commands for manipulating files, +<listitem><para>Use basic operating system commands for manipulating files, such as COPY, DELETE, and DIR. -The more familiar you are with Windows, the better.</para></listitem></itemizedlist> -<para>If you have little or no experience with the Windows operating system, -refer to the documentation provided with it. You should also have the -<citetitle pubwork="book">Open Object Rexx: Reference</citetitle> at hand.</para> +</para></listitem></itemizedlist> +<para>You should also have the access to +<citetitle pubwork="book">Open Object Rexx: Reference</citetitle>.</para> </section> -<section id="relatedinfo"><title>Related Information</title> -<para>See also: -<citetitle pubwork="book">Open Object Rexx for Windows: Reference</citetitle></para> -</section> - -<section><title>A Note About Program Examples in this Document</title> -<para>The program examples in this document are rendered in a mono-spaced -font that is not completely compatible for cut-and-paste functionality. -Pasting text into an editor could result in some characters outside of -the standard ASCII character set. Specifically, single-quote and -double-quote characters are sometimes converted incorrectly when -pasted into an editor.</para> - -</section> - &gethelp; </chapter> Modified: docs/trunk/rexxpg/tour.sgml =================================================================== --- docs/trunk/rexxpg/tour.sgml 2009-02-15 12:43:07 UTC (rev 4163) +++ docs/trunk/rexxpg/tour.sgml 2009-02-15 15:21:10 UTC (rev 4164) @@ -61,7 +61,7 @@ for your computer. Rexx programs are interpreted, which means the program is, like a batch file, processed line by line. Consequently, you do not have to compile and link Rexx programs. To run a Rexx program, all -you need is Windows or Unix/Linux, the Object Rexx interpreter, and the ASCII +you need is Windows or Unix/Linux, the ooRexx interpreter, and the ASCII text file containing the program.</para> <para>Rexx is similar to programming languages such as C, Pascal, or Basic. An important difference is that Rexx variables have no data type and are not @@ -78,7 +78,7 @@ <indexterm><primary>Linux commands, issuing</primary></indexterm> Windows, Unix/Linux commands and other applications from a Rexx program. This is similar to what you can do with a Windows Batch -facility program. However, in addition to +facility program or a Unix shell script. However, in addition to executing the command, you can also receive a return code from the command and use any displayed output in your Rexx program. For example, the output displayed by a DIR command can be intercepted by a Rexx program @@ -87,7 +87,7 @@ direct commands to environments other than Windows. Some applications provide an environment to which Rexx can direct subcommands of the application. Or they also provide functions that can be called from -a Rexx program. In these situations, Rexx acts as a macrolanguage for the +a Rexx program. In these situations, Rexx acts as a scripting language for the <indexterm><primary>Rexx</primary> <secondary>as a macro language</secondary></indexterm> application.</para> @@ -99,47 +99,55 @@ <indexterm><primary>Rexx</primary> <secondary>program, running a</secondary></indexterm> <para>Rexx programs should have a -file extension of CMD on Windows, just like Batch facility files, or REX (default to -prevent confusion with Windows NT files). Here is a typical Rexx -program named GREETING.CMD. It prompts the user to type in a name and then +file extension of .rex (the default searched for by the ooRexx interpreter). +Here is a typical Rexx +program named greeting.rex. It prompts the user to type in a name and then displays a personalized greeting: </para> <programlisting> <![CDATA[ -/* GREETING.CMD - a Rexx program to display a greeting. */ +/* greeting.rex - a Rexx program to display a greeting. */ say "Please enter your name." /* Display a message */ pull name /* Read response */ say "Hello" name /* Display greeting */ exit 0 /* Exit with a return code of 0 */ ]]> </programlisting> -<para>The program begins with a comment. This is not a requirement, -but it is recommended to ensure compatibility with other operating systems, -such as OS/2, where the first line in a Rexx program must be a comment line.</para> -<para>The Object Rexx interpreter is invoked by the command </para> +<para> +<para>The ooRexx interpreter is invoked by the command </para> <programlisting> <![CDATA[ rexx ]]> </programlisting> -<para>To run the program MYRexx.CMD, for example, use the command</para> +<para>To run the program greeting.rex, for example, use the command</para> <programlisting> <![CDATA[ -rexx MYRexx.CMD +rexx greeting.rex ]]> </programlisting> +<para>or</para> +<programlisting> +<![CDATA[ +rexx greeting +]]> +</programlisting> +<para>If not provided, an extension of ".rex" is assumed.</para> <para>If you want to run your Rexx program in silent mode without creating a console window on Windows, you can invoke RexxHIDE.EXE followed by the program name and the program arguments from a program item. If RexxHIDE is called -from within a console window, no output is displayed in the console window.</para> +from within a console window, no output is displayed in the console window. +RexxHIDE is only available for the Windows platform. +</para> <para>SAY <indexterm><primary>SAY instruction</primary></indexterm> <indexterm><primary>Rexx</primary> <secondary>SAY instruction</secondary></indexterm> is a Rexx instruction that displays a message (like PRINT in Basic or printf -in C). The message to be displayed follows the SAY keyword. The single quotes -are necessary to delimit a character string. In this case, the character string -is <computeroutput>Please enter your name</computeroutput>. -You can use double quotes (") instead of single quotes.</para> +in C). The message to be displayed follows the SAY keyword. In this case, the +message is the literal string "Please enter your name.". The data between the quotes +is a constant and will appear exactly as typed. You can use either single (') or double +quote (") delimiters for literal strings. +</para> <para>The <indexterm><primary>PULL instruction</primary></indexterm> <indexterm><primary>instructions</primary> @@ -164,11 +172,11 @@ <secondary>EXIT</secondary></indexterm> <indexterm><primary>Rexx</primary> <secondary>EXIT instruction</secondary></indexterm> -EXIT, ends the Rexx program. Control returns to Windows or Unix/Linux. +EXIT, ends the Rexx program. Control returns to the operation system command prompt. EXIT can also return a value. In our example, 0 is returned. The EXIT instruction -is optional.</para> +is optional. Running off the end of the program is equivalent to coding "EXIT 0".</para> <para>You can terminate a running Rexx program by pressing the Ctrl+Break key combination. -Rexx stops running the program and control returns to Windows or Unix/Linux.</para> +Rexx stops running the program and control returns to the command prompt.</para> </section> <section id="element"><title>Elements of Rexx</title> @@ -198,7 +206,7 @@ operating systems. In addition to these system-independent functions, Rexx includes a set of functions for working with Windows itself. These functions, known as the Rexx Utilities, let -you work with resources managed by Windows, such as the display, the desktop, +you work with resources managed by Windows or Linux, such as the display, the desktop, and the file system.</para> <para>Instructions and functions are the building blocks of traditional Rexx programs. To convert Rexx into an object-oriented language, two more elements @@ -212,8 +220,8 @@ <indexterm><primary>Rexx</primary> <secondary>program, writing a</secondary></indexterm> <para>You can create Rexx programs -using any editor that can write straight ASCII files without hidden format -controls. The Windows Notepad is an editor that you can use.</para> +using any editor that can create simple ASCII files without hidden format +controls. Windows Notepad or Linux gedit are a couple widely available editors.</para> <para>Rexx is a free-format programming language. You can indent lines and insert blank lines for readability if you wish. But even free-format languages have some @@ -230,17 +238,24 @@ say "Hello"; say "Goodbye" /* Two clauses on one line */ ]]> </programlisting> -<para>To continue a clause on a second line, put a comma at the end of the line: </para> +<para>To continue a clause on a second line, put a comma (,) or hypen (-) at the end of the line: </para> <indexterm><primary>clauses</primary> <secondary>spanning more than one line</secondary></indexterm> <indexterm><primary>, (comma)</primary></indexterm> +<indexterm><primary>- (hyphen)</primary></indexterm> <indexterm><primary>comma (,)</primary></indexterm> +<indexterm><primary>hyphen (-)</primary></indexterm> <indexterm><primary>splitting clauses</primary></indexterm> <indexterm><primary>continuing a clause</primary></indexterm> <programlisting> say, /* Continuation */ "It isn't so" </programlisting> +<para>or</para> +<programlisting> +say - /* Continuation */ +"It isn't so" +</programlisting> <indexterm><primary>strings</primary></indexterm> <para>If you need to continue a literal string, do it like this: </para> @@ -273,12 +288,11 @@ prompt. REXXTRY is a kind of Rexx mini-interpreter that checks Rexx statements one at a time. If you run REXXTRY with no parameter, or with a question mark as a parameter, REXXTRY also briefly describes itself.</para> -<para>From your current Windows or Unix/Linux window, -open another window and type: </para> +<para>From your command propmpt type:</para> + <programlisting> <![CDATA[ -REXX rexxtry /* on windows the case of the REXX is insignificant */ -rexx rexxtry /* on unix the Rexx command is always specified in lowercase */ +rexx rexxtry /* on windows the case of the REXX is insignificant */ ]]> </programlisting> <para>REXXTRY describes itself and asks you for a Rexx statement @@ -287,8 +301,8 @@ remembers any previous statements you have entered during the session. To continue, just type the next line in your program and REXXTRY will check it for you.</para> -<para>Enter an equal sign (=) to repeat your previous statement, or a question -mark (?) to invoke system-provided online information about the Rexx language.</para> +<para>Enter an equal sign (=) to repeat your previous statement. +</para> <para>When you are done, type: </para> <programlisting> <![CDATA[ @@ -307,20 +321,6 @@ RexxTRY.</para> </section> -<section id="startuptime"><title>Improving Startup Time</title> -<para>If the environment variable RXSAVETOKENS is set to YES, Object Rexx stores -the internal format at the end of the program script. When this program is -executed the next time, the so-called parsing process can be skipped and the -program can be started faster.</para> -<para>Whenever you modify your program script, the image at the end of the file -is discarded by the editor and the modifications are therefore recognized -by the Object Rexx interpreter. Using this mechanism requires an editor that -can handle files terminated by Ctrl+Z (EOF).</para> -<para>If the editor you are using does not discard -the data after EOF, changes within the ASCII code are not reflected in the -tokenized script.</para> -</section> - <section id="strings"><title>Variables, Constants, and Literal Strings</title> <indexterm><primary>strings</primary></indexterm> <indexterm><primary>naming variables</primary></indexterm> @@ -332,8 +332,8 @@ <para>Rexx imposes few rules on variable names. A variable name can be up to 250 characters long, with the following restrictions: </para> <itemizedlist> -<listitem><para>The first character must be A-Z, a-z, !, ?, or _ . Rexx translates -lowercase letters to uppercase before using them.</para></listitem> +<listitem><para>The first character must be A-Z, a-z, !, ?, or _ . +</para></listitem> <listitem><para>The rest of the characters may be A-Z, a-z, !, ?, or _, ., or 0-9.</para></listitem> <listitem><para>The @@ -345,9 +345,14 @@ </itemizedlist> <para>The variable name can be typed and queried in uppercase, mixed-case, or lowercase characters. A variable name in uppercase characters, for example, -can also be queried in lowercase or mixed-case characters. If you query a -variable name that has not yet been set, the name is returned in uppercase -characters.</para> +can also be queried in lowercase or mixed-case characters. +Rexx translates +lowercase letters in variables to uppercase before using them. +Thus the variables names "abc", "Abc", and "ABC" +all refer to the single variable "ABC". +If you reference a +variable name that has not yet been set, the name, in uppercase, is returned. +</para> <indexterm><primary>' (single quotation mark)</primary></indexterm> <indexterm><primary>single quotation mark (')</primary></indexterm> <indexterm><primary>" (double quotation mark)</primary></indexterm> @@ -365,7 +370,7 @@ 'He said, "Bother"' </programlisting> <para>There is another way to do this. Within a literal string, a pair of quotation -marks (the same type that delimits the string) is interpreted as one of that +marks of the same type that starts the string is interpreted as a single character of that type. For example: </para> <programlisting> 'Don''t panic' (same as "Don't panic" ) @@ -412,8 +417,8 @@ <para>Other operands of PARSE indicate the source of the data. PARSE ARG, for example, retrieves command line arguments. PARSE VERSION retrieves the information about the version of the Rexx interpreter being used.</para> -<para>The most powerful feature of PARSE, however, is its ability to parse data -according to a template that you supply. The various pieces of data are assigned +<para>The most powerful feature of PARSE, however, is its ability to break up data +using a template. The various pieces of data are assigned to variables that are part of the template. The following example prompts the user for a date, and assigns the month, day, and year to different variables. (In a real application, you would want to add instructions to verify the input.) </para> @@ -503,23 +508,28 @@ <section id="progcon"><title>Program Control</title> <para>Rexx has instructions such as <indexterm><primary>DO instruction</primary></indexterm> +<indexterm><primary>LOOP instruction</primary></indexterm> <indexterm><primary>IF instruction</primary></indexterm> <indexterm><primary>SELECT instruction</primary></indexterm> <indexterm><primary>instructions</primary> <secondary>DO</secondary></indexterm> <indexterm><primary>instructions</primary> +<secondary>LOOP</secondary></indexterm> +<indexterm><primary>instructions</primary> <secondary>IF</secondary></indexterm> <indexterm><primary>instructions</primary> <secondary>SELECT</secondary></indexterm> <indexterm><primary>Rexx</primary> <secondary>DO instruction</secondary></indexterm> <indexterm><primary>Rexx</primary> +<secondary>LOOP instruction</secondary></indexterm> +<indexterm><primary>Rexx</primary> <secondary>IF instruction</secondary></indexterm> <indexterm><primary>Rexx</primary> <secondary>SELECT instruction</secondary></indexterm> <indexterm><primary>instructions</primary> -<secondary>for program control (DO, IF, SELECT ...)</secondary></indexterm> -DO, IF, and SELECT to control your program. Here is a +<secondary>for program control (DO, LOOP, IF, SELECT ...)</secondary></indexterm> +DO, LOOP, IF, and SELECT to control your program. Here is a typical Rexx IF instruction: </para> <programlisting> <![CDATA[ @@ -529,41 +539,47 @@ exit 99 end </programlisting> -<para>The Rexx relational operator for a logical AND is different from the operator +<para>The Rexx relational operator & for a logical AND is different from the operator in C, which is &&. Other relational operators differ as well, so you may want to review the appropriate section in the <citetitle pubwork="book">Open Object Rexx: Reference</citetitle>.</para> <para>Here is a list of some Rexx comparison operators and operations: </para> <indexterm><primary>operators and operations, partial list of</primary></indexterm> -<variablelist> -<varlistentry><term>=</term> -<listitem><para>True if the terms are equal (numerically, when padded, and so on) -</para></listitem></varlistentry> -<varlistentry><term>\=, ¬=</term> -<listitem><para>True if the terms are not equal (inverse of =) -</para></listitem></varlistentry> -<varlistentry><term>></term> -<listitem><para>Greater than -</para></listitem></varlistentry> -<varlistentry><term><</term> -<listitem><para>Less than -</para></listitem></varlistentry> -<varlistentry><term><></term> -<listitem><para>Greater than or less than (same as not equal) -</para></listitem></varlistentry> -<varlistentry><term>>=</term> -<listitem><para>Greater than or equal to -</para></listitem></varlistentry> -<varlistentry><term><=</term> -<listitem><para>Less than or equal to -</para></listitem></varlistentry> -<varlistentry><term>==</term> -<listitem><para>True if terms are strictly equal (identical) -</para></listitem></varlistentry> -<varlistentry><term>\==, ¬==</term> -<listitem><para>True if the terms are NOT strictly equal (inverse of ==) -</para></listitem></varlistentry> -</variablelist> +<informaltable frame="none" colsep="0" rowsep="0"> +<tgroup cols="2"> +<colspec colnum="1" colwidth="1*"> +<colspec colnum="2" colwidth="4*"> +<tbody> +<row><entry>=</entry> +<entry><para>True if the terms are equal (numerically, when padded, and so on) +</para></entry></row> +<row><entry>\=, ¬=</entry> +<entry><para>True if the terms are not equal (inverse of =) +</para></entry></row> +<row><entry>></entry> +<entry><para>Greater than +</para></entry></row> +<row><entry><</entry> +<entry><para>Less than +</para></entry></row> +<row><entry><></entry> +<entry><para>Greater than or less than (same as not equal) +</para></entry></row> +<row><entry>>=</entry> +<entry><para>Greater than or equal to +</para></entry></row> +<row><entry><=</entry> +<entry><para>Less than or equal to +</para></entry></row> +<row><entry>==</entry> +<entry><para>True if terms are strictly equal (identical) +</para></entry></row> +<row><entry>\==, ¬==</entry> +<entry><para>True if the terms are NOT strictly equal (inverse of ==) +</para></entry></row> +</tbody> +</tgroup> +</informaltable> <note> <para>Throughout the language, the NOT character, ¬, @@ -574,25 +590,31 @@ can appear in the \ (prefix not), \=, and \== operators.</para></note> <para>A character string has the value false if it is 0, and true if it is 1. A logical operator can take at least two values and return 0 or 1 as appropriate:</para> -<variablelist> -<varlistentry><term>&</term> -<listitem><para>AND - returns <computeroutput>1</computeroutput> +<informaltable frame="none" colsep="0" rowsep="0"> +<tgroup cols="2"> +<colspec colnum="1" colwidth="1*"> +<colspec colnum="2" colwidth="4*"> +<tbody> +<row><entry>&</entry> +<entry><para>AND - returns <computeroutput>1</computeroutput> if both terms are true. -</para></listitem></varlistentry> -<varlistentry><term>|</term> -<listitem><para>Inclusive OR - returns <computeroutput>1</computeroutput> +</para></entry></row> +<row><entry>|</entry> +<entry><para>Inclusive OR - returns <computeroutput>1</computeroutput> if either term or both terms are true. -</para></listitem></varlistentry> -<varlistentry><term>&&</term> -<listitem><para>Exclusive OR - returns <computeroutput>1</computeroutput> +</para></entry></row> +<row><entry>&&</entry> +<entry><para>Exclusive OR - returns <computeroutput>1</computeroutput> if either term, but not both terms, is true. -</para></listitem></varlistentry> -<varlistentry><term>Prefix \,¬</term> -<listitem><para>Logical NOT - negates; <computeroutput>1</computeroutput> +</para></entry></row> +<row><entry>Prefix \,¬</entry> +<entry><para>Logical NOT - negates; <computeroutput>1</computeroutput> becomes <computeroutput>0</computeroutput>, and <computeroutput>0</computeroutput> becomes <computeroutput>1</computeroutput>. -</para></listitem></varlistentry> -</variablelist> +</para></entry></row> +</tbody> +</tgroup> +</informaltable> <note> <para>On ASCII systems, Rexx recognizes the ASCII character @@ -685,8 +707,9 @@ end /* select */ </programlisting> <para>Many Basic implementations have several different instructions for loops. -Rexx only knows the DO/END pair. All of the traditional looping variations -are incorporated into the DO instruction: </para> +Rexx has knows the DO/END and LOOP/END pair. All of the traditional looping variations +are incorporated into the DO and LOOP instructions, which +can be used interchangeably for looping: </para> <programlisting> do i=1 to 10 /* Simple loop */ say i @@ -708,6 +731,28 @@ say "Until loop" /* evaluated at the end of the loop. */ end </programlisting> +<para>or, using LOOP</para> +<programlisting> +loop i=1 to 10 /* Simple loop */ + say i +end + +loop i=1 to 10 by 2 /* Increment count by two */ + say i +end + +b=3; a=0 /* LOOP WHILE - the conditional expression*/ +loop while a<b /* is evaluated before the instructions */ + say a /* in the loop are executed. If the */ + a=a+1 /* expression isn't true at the outset, */ +end /* instructions are not executed at all. */ + +a=5 /* LOOP UNTIL - like many other languages,*/ +b=4 /* a Rexx LOOP UNTIL block is executed at */ +do until a>b /* least once. The expression is */ + say "Until loop" /* evaluated at the end of the loop. */ +end +</programlisting> <para>Rexx also has a FOREVER keyword. Use the LEAVE, RETURN, or EXIT instructions to break out of the loop:</para> <programlisting> @@ -733,7 +778,7 @@ instructions in that iteration of the loop: </para> <programlisting> <![CDATA[ -do i=1 to 100 +loop i=1 to 100 /* Iterate when the "special case" value is reached */ if i=5 then iterate @@ -747,7 +792,7 @@ <![CDATA[ /* Say hello ten times if I is equal to 1 */ if i=1 then - do j=1 to 10 + loop j=1 to 10 say "Hello!" end ]]> @@ -763,7 +808,7 @@ ]]> </programlisting> <para>As with GOTO, you need to be careful about how you use SIGNAL. -In particular, do not place SIGNAL in the middle of a DO/END block or +In particular, do not use SIGNAL to jump to the the middle of a DO/END block or into a SELECT structure.</para> </section> @@ -883,8 +928,8 @@ instruction, the program would loop indefinitely. On each iteration the value of <computeroutput>i</computeroutput> would be reset to some value less than 100, which means the loop would never end. If a programming error -causes your procedure to loop indefinitely, use the Ctrl+Break key combination -or close the Windows session to end the procedure.</para> +causes your procedure to loop indefinitely, use the Ctrl+C key combination +or close the command window to end the procedure.</para> <para>To access variables outside the routine, add an EXPOSE operand to the PROCEDURE instruction. List the desired variables after the <indexterm><primary>EXPOSE keyword</primary></indexterm> @@ -923,11 +968,11 @@ ]]> </programlisting> <para>In the routine, use the -<indexterm><primary>PARSE ARG instructions</primary></indexterm> +<indexterm><primary>USE ARG instructions</primary></indexterm> <indexterm><primary>instructions</primary> -<secondary>PARSE ARG</secondary></indexterm> +<secondary>USE ARG</secondary></indexterm> <indexterm><primary>Rexx</primary> -<secondary>PARSE ARG instruction</secondary></indexterm> -PARSE ARG instruction to retrieve the argument.</para> +<secondary>USE ARG instruction</secondary></indexterm> +USE ARG instruction to retrieve the argument.</para> </section> </chapter> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <bi...@us...> - 2009-02-15 15:25:48
|
Revision: 4165 http://oorexx.svn.sourceforge.net/oorexx/?rev=4165&view=rev Author: bigrixx Date: 2009-02-15 15:25:47 +0000 (Sun, 15 Feb 2009) Log Message: ----------- fix syntax errors Modified Paths: -------------- docs/trunk/rexxpg/meet.sgml docs/trunk/rexxpg/tour.sgml Modified: docs/trunk/rexxpg/meet.sgml =================================================================== --- docs/trunk/rexxpg/meet.sgml 2009-02-15 15:21:10 UTC (rev 4164) +++ docs/trunk/rexxpg/meet.sgml 2009-02-15 15:25:47 UTC (rev 4165) @@ -81,6 +81,7 @@ <trademark class="registered">Windows XP</trademark>, and <trademark class="registered">Windows Vista</trademark>. It is also available in 64-bit versions that can exploit larger address spaces. +</para> </section> <section id="fewrule"><title>Fewer Rules</title> Modified: docs/trunk/rexxpg/tour.sgml =================================================================== --- docs/trunk/rexxpg/tour.sgml 2009-02-15 15:21:10 UTC (rev 4164) +++ docs/trunk/rexxpg/tour.sgml 2009-02-15 15:25:47 UTC (rev 4165) @@ -112,7 +112,6 @@ exit 0 /* Exit with a return code of 0 */ ]]> </programlisting> -<para> <para>The ooRexx interpreter is invoked by the command </para> <programlisting> <![CDATA[ This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <bi...@us...> - 2009-02-15 17:05:12
|
Revision: 4166 http://oorexx.svn.sourceforge.net/oorexx/?rev=4166&view=rev Author: bigrixx Date: 2009-02-15 17:05:09 +0000 (Sun, 15 Feb 2009) Log Message: ----------- editorial updates Modified Paths: -------------- docs/trunk/rexxpg/concept.sgml docs/trunk/rexxpg/ooRexxClasses7.png docs/trunk/rexxpg/provide.sgml Added Paths: ----------- docs/trunk/rexxpg/ooRexxClasses8.png docs/trunk/rexxpg/ooRexxClasses9.png Modified: docs/trunk/rexxpg/concept.sgml =================================================================== --- docs/trunk/rexxpg/concept.sgml 2009-02-15 15:25:47 UTC (rev 4165) +++ docs/trunk/rexxpg/concept.sgml 2009-02-15 17:05:09 UTC (rev 4166) @@ -42,8 +42,8 @@ ######################################################################### --> <chapter id="concept"><title>Into the Object World</title> -<para>Object Rexx includes features typical of an object-oriented language--features -like subclassing, polymorphism, and data encapsulation. Object Rexx is an +<para>Open Object Rexx includes features typical of an object-oriented language—features +like subclassing, polymorphism, and data encapsulation. Object Rexx is new version extension of the traditional Rexx language, which has been expanded to include classes, objects, and methods. These extensions do not replace traditional Rexx functions, or preclude the development or running @@ -87,7 +87,7 @@ And each data module includes its own operations for performing actions directly related to its data.</para> -<figure><title>Modular Data--a Report Object</title> +<figure><title>Modular Data—a Report Object</title> <mediaobject> <imageobject> <!-- Note! - if we include a /imagedata tag we get an error for DSSSL! --> @@ -98,8 +98,8 @@ <para>In the case of report, the report object would contain its own built-in PRINT, SEND, ERASE, and FILE operations.</para> -<para>Object-oriented programming lets you model real-world objects--even -very complex ones--precisely and elegantly. As a result, object manipulation +<para>Object-oriented programming lets you model real-world objects—even +very complex ones—precisely and elegantly. As a result, object manipulation becomes easier and computer instructions become simpler and can be modified later with minimal effort.</para> <para>Object-oriented programming hides any information @@ -114,8 +114,8 @@ <secondary>kinds of</secondary></indexterm> <para>In object-oriented programming, objects are modeled to real-world objects. A real-world object has actions related to it and characteristics of its own.</para> -<para>Take a ball, for example. A ball can be acted on--rolled, tossed, -thrown, bounced, caught. But it also has its own physical characteristics--size, +<para>Take a ball, for example. A ball can be acted on—rolled, tossed, +thrown, bounced, caught. But it also has its own physical characteristics—size, shape, composition, weight, color, speed, position. An accurate data model of a real ball would define not only the physical characteristics but all related actions and characteristics in one package:</para> @@ -130,10 +130,10 @@ </figure> <para>In object-oriented programming, -objects are the basic building blocks--the fundamental units of data.</para> +objects are the basic building blocks—the fundamental units of data.</para> <para>There are many kinds of objects; for example, character -strings, collections, and input and output streams. An object--such as -a character string--always consists of two parts: the possible actions +strings, collections, and input and output streams. An object—such as +a character string—always consists of two parts: the possible actions or operations related to it, and its characteristics or variables. A variable has a variable name, and an associated data value that can change over time. These actions and characteristics are so closely @@ -171,13 +171,8 @@ </mediaobject> </figure> -<para>Rexx comes with a basic set of classes for creating objects (see -<link linkend="provide">The Basics of Classes</link>). Therefore, you can -create objects that exactly match the needs of a particular application.</para> -</section> - <section id="interac"><title>How Objects Interact</title> -<para>The actions within an object +<para>The actions defined by an object are its only interface to other objects. Actions form a kind of "wall" that encapsulates the object, and shields its internal information from outside objects. This shielding is called information hiding. @@ -185,10 +180,12 @@ objects, and also protects outside objects from relying on another object's private data, which can change without warning.</para> <para>One object can act upon another (or -cause it to act) only by calling that object's actions, namely by sending -messages. Objects respond to these messages by performing -<indexterm><primary>messages</primary></indexterm> -an action, returning data, or both. A message to an object must specify:</para> +cause it to act) only by calling that object's actions. Actions are invoked +by sending messages. +messages. Objects respond to these messages by invoking +<indexterm><primary>methods</primary></indexterm> +<link linkend="methods">methods</link> +that perform an action, return data, or both. A message to an object must specify:</para> <itemizedlist> <listitem><para>A receiving object</para></listitem> <listitem><para>The "message send" symbol ~, which is called the @@ -198,7 +195,7 @@ <indexterm><primary>twiddle (~)</primary></indexterm> <indexterm><primary>message-send operator (~)</primary></indexterm> </para></listitem> -<listitem><para>The action and, optionally in parentheses, any parameters +<listitem><para>The name of the action and, optionally in parentheses, any parameters required</para></listitem></itemizedlist> <para>So the message format looks like this:</para> <programlisting> @@ -263,6 +260,26 @@ <para>The ability to hide the various implementations of a method while leaving the interface the same illustrates polymorphism at its lowest level. On a higher level, polymorphism permits extensive code reuse.</para> +<para>Polymorpism involves a form of contract between two objects. +One object will send a message to another object expecting a particular result. +Different types of objects can implement different versions of this message as +long as it fulfills the expectations of the the invoking object. For example, +the LOOP instruction has a form called OVER. Loop OVER will iterate over a number of +elements provided by an object. For example,</para> +<programlisting> +myarray = .array~of("Rick", "David", "Mark") +loop name over myarray + say name +end +</programlisting> +<para>Will display the strings "Rick", "David", and "Mark", in that sequence. The +LOOP OVER instruction will work with Arrays, Lists, stem variables, streams, etc. +The LOOP instruction itself does not know anything about Arrays or Lists or stems or streams. +The LOOP instruction specifies a contract. LOOP will send the target object the message +MAKEARRAY and expects the target object to return an Array object that is used for +the LOOP iteration. Any object can participate in LOOP iteration by implementing this contract. +Objects that do implement the MAKEARRAY contract are polymorphic with the LOOP instruction. +</para> </section> <section id="xclass"><title>Classes and Instances</title> @@ -273,8 +290,8 @@ they define the methods and variables that a group of similar objects have in common and store them in one place.</para> <para>If you write a program to manipulate some screen icons, for example, you -might create an Icon class. In that Icon class you can include all the icon -objects with similar actions and characteristics:</para> +might create an Icon class. All Icon objects will share the actions and characteristics +defined by the class:</para> <figure><title>A Simple Class</title> <mediaobject> @@ -285,12 +302,12 @@ </mediaobject> </figure> -<para>All the icon objects might use common methods like DRAW or ERASE. They -might contain common variables like position, color, or size. What makes each +<para>All the icon objects will use common methods like DRAW or ERASE. They +might will common variables like position, color, or size. What makes each icon object different from one another is the data assigned to its variables. -For the Windows system icon, it might be -<computeroutput>position="20,20"</computeroutput> while for the shredder it is -<computeroutput>"20,30"</computeroutput> and for information it is +For the Windows System icon, it might be +<computeroutput>position="20,20"</computeroutput> while for the Shredder it is +<computeroutput>"20,30"</computeroutput> and for Information it is <computeroutput>"20,40"</computeroutput></para> <figure><title>Icon Class</title> @@ -306,17 +323,17 @@ <indexterm><primary>methods</primary> <secondary>instance</secondary></indexterm> instances of that class. As instances of the Icon class, -the Windows system icon, shredder icon, and -information icon acquire the methods and variables +the Windows System icon, Shredder icon, and +Information icon acquire the methods and variables <indexterm><primary>acquisition</primary></indexterm> <indexterm><primary>instances methods</primary></indexterm> <indexterm><primary>variables</primary> <secondary>acquiring</secondary></indexterm> <indexterm><primary>variables</primary> <secondary>in objects</secondary></indexterm> -of that class. Instances behave as if they each had their own methods and +of the class. Instances behave as if they each had their own methods and variables of the same name. All instances, however, have their own unique -properties--the data associated with the variables. +properties—the data associated with the variables. Everything else can be stored at the class level.</para> <figure><title>Instances of the Icon Class</title> @@ -365,7 +382,7 @@ <indexterm><primary>subclasses</primary></indexterm> <para> When you write your first object-oriented program, you do not have to begin your real-world modeling from scratch. Rexx provides predefined classes -and methods. From there you can create additional classes and methods of your +and methods. From there you can create additional classes of your own, according to your needs.</para> <para>Rexx classes are hierarchical. The original class Modified: docs/trunk/rexxpg/ooRexxClasses7.png =================================================================== (Binary files differ) Added: docs/trunk/rexxpg/ooRexxClasses8.png =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/ooRexxClasses8.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: docs/trunk/rexxpg/ooRexxClasses9.png =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/ooRexxClasses9.png ___________________________________________________________________ Added: svn:mime-type + image/png Modified: docs/trunk/rexxpg/provide.sgml =================================================================== --- docs/trunk/rexxpg/provide.sgml 2009-02-15 15:25:47 UTC (rev 4165) +++ docs/trunk/rexxpg/provide.sgml 2009-02-15 17:05:09 UTC (rev 4166) @@ -78,15 +78,19 @@ Array List Queue + CircularQueue + IdentityTable Table Set Directory + Stem Relation Bag Message Method + Routine + Package Monitor - Stem Stream String Supplier @@ -161,34 +165,35 @@ <section id="msgcl"><title>The Message Class</title> <indexterm><primary>classes</primary> <secondary>Message class</secondary></indexterm> -<para>To manipulate message -objects, you use the Message class. Methods created -for this class are used, for example, to send a message, to notify the sender -object when an error occurs or when message processing is complete, to return -the results of that processing to the sender or to some other object, or to -process the message object concurrently with the sender object.</para> +<para>Message objects allow you to run concurrently methods on other threads or to +invoke dynamically calculated messages. +Methods of +for this class are used, for example, to start a message on another thread, to notify the sender +object when an error occurs or when message processing is complete, or to return +the results of that processing to the sender or to some other object. +</para> </section> <section id="moncl"><title>The Monitor Class</title> <indexterm><primary>classes</primary> <secondary>Monitor class</secondary></indexterm> <para>The Monitor class provides a way to forward messages to a specified destination. -Monitor methods let you initialize a monitor object, specify a destination -object or use a previously specified one, and obtain the name of the current -destination object.</para> +The Monitor creates a proxy that can route dynamically route messages to different destinations. +Monitor methods change or restore a destination object. +</para> </section> <section id="stemcl"><title>The Stem Class</title> <indexterm><primary>classes</primary> <secondary>Stem class</secondary></indexterm> -<para>A stem is a symbol that +<para>A stem variable is a symbol that must start with a letter and end with a period, like "FRED." or "A.". -The value of a stem is a stem object by default. A stem object is a collection -of unique indexes that are character strings. Stem objects are automatically +The value of a stem variable is a Stem <emphasis role="italic">object</emphasis>. A stem object is a collection +of unique character string indexes. Stem objects are automatically created when a Rexx stem variable or Rexx compound variable is used. In addition to the items assigned to the collection indexes, a stem object also has a default value that is used for all uninitialized indexes of the collection. -You can assign a default value to a stem object and later retrieve this value.</para> +</para> </section> <section id="streacl"><title>The Stream Class</title> @@ -224,16 +229,12 @@ <section id="supplcl"><title>The Supplier Class</title> <indexterm><primary>classes</primary> <secondary>Supplier class</secondary></indexterm> -<para>Some collections -have suppliers: a bakery, for example, can supply certain breads, cookies, -cakes and pies; a financial report can supply certain data, statistics, tables, -and reports. The Supplier class is used to enumerate -items that a collection contained when the supplier was created. For example, -this class contains methods to verify if an item is available from a supplier -(Does the Pie-by-Night Bakery sell chocolate cake?). Another method returns -the index of the current item in a collection (What is the position of the -apple pie record?). Others return the current collection item in a collection -object, and the next item in the collection.</para> +<para>All collections +have suppliers +The Supplier class is used to enumerate +items that a collection contained when the supplier was created. The supplier +gives access to each index/value pair stored in the collection as a sequence. +</para> </section> </section> @@ -242,16 +243,16 @@ hierarchies.</para> <section id="objcl"><title>The Object Class</title> -<para>Because the topmost class in the hierarchy, or the root class, +<para>Because the root class in the hierarchy, is the Object class, everything below it is an object. To interact with each other, objects require their own actions, called methods. These methods, which encode actions that are needed by all objects, belong to the Object class.</para> <para>Every other class in the hierarchy inherits the methods of the root class. Inheritance is the handing down of methods from a "parent" -class--called a superclass--to -all of its "descendent" classes--called subclasses. Finally, -instances acquire methods from their classes. Any method created for the Object +class—called a superclass—to +all of its "descendent" classes—called subclasses. Finally, +instances acquire methods from their own classes. Any method created for the Object class is automatically made available to every other class in the hierarchy.</para> </section> @@ -264,9 +265,8 @@ in Class, to be used by all classes.</para> <para>A class that can be used to create another class is called a <indexterm><primary>metaclasses</primary></indexterm> -metaclass. The Class class -is unique among Rexx classes in that it is the only metaclass that Rexx provides -(see <link linkend="meta">Metaclasses</link>). +<link linkend="meta">metaclass</link>. The Class class +is unique among Rexx classes in that it is the only metaclass that Rexx provides. As such, the Class's methods not only make new classes, they make methods for use by the new class and its instances. They also make methods that only the new class itself can use, but not its @@ -292,11 +292,9 @@ <para>As a programmer, you typically create classes by using directives, rather than the methods of the Class class. In particular, you'll use the ::CLASS directive, described later in this section. The -::CLASS directive is a kind of Rexx clause that allows class definitions to -be saved permanently, in a file, where they can be reused by other programs. -Creating classes by using Class methods sent as messages is not recommended -if permanency or reuse is required. At any rate, directives have class-creating -powers similar to the Class methods.</para> +::CLASS directive is a kind of Rexx clause that declares class definitions in a +simple, static form in your programs. +</para> </section> </section> @@ -306,7 +304,7 @@ <para>The following are the supplied Rexx classes.</para> <figure float="1"> -<title id="meths1">Classes and Inheritance (part 1 of 7)</title> +<title id="meths1">Classes and Inheritance (part 1 of 9)</title> <mediaobject> <imageobject> <!-- Note! - if we include a /imagedata tag we get an error for DSSSL! --> @@ -316,7 +314,7 @@ </figure> <figure float="1"> -<title id="meths2">Classes and Inheritance (part 2 of 7)</title> +<title id="meths2">Classes and Inheritance (part 2 of 9)</title> <mediaobject> <imageobject> <!-- Note! - if we include a /imagedata tag we get an error for DSSSL! --> @@ -326,7 +324,7 @@ </figure> <figure float="1"> -<title id="meths3">Classes and Inheritance (part 3 of 7)</title> +<title id="meths3">Classes and Inheritance (part 3 of 9)</title> <mediaobject> <imageobject> <!-- Note! - if we include a /imagedata tag we get an error for DSSSL! --> @@ -336,7 +334,7 @@ </figure> <figure float="1"> -<title id="meths4">Classes and Inheritance (part 4 of 7)</title> +<title id="meths4">Classes and Inheritance (part 4 of 9)</title> <mediaobject> <imageobject> <!-- Note! - if we include a /imagedata tag we get an error for DSSSL! --> @@ -346,7 +344,7 @@ </figure> <figure float="1"> -<title id="meths5">Classes and Inheritance (part 5 of 7)</title> +<title id="meths5">Classes and Inheritance (part 5 of 9)</title> <mediaobject> <imageobject> <!-- Note! - if we include a /imagedata tag we get an error for DSSSL! --> @@ -356,7 +354,7 @@ </figure> <figure float="1"> -<title id="meths6">Classes and Inheritance (part 6 of 7)</title> +<title id="meths6">Classes and Inheritance (part 6 of 9)</title> <mediaobject> <imageobject> <!-- Note! - if we include a /imagedata tag we get an error for DSSSL! --> @@ -366,7 +364,7 @@ </figure> <figure float="1"> -<title id="meths7">Classes and Inheritance (part 7 of 7)</title> +<title id="meths7">Classes and Inheritance (part 7 of 9)</title> <mediaobject> <imageobject> <!-- Note! - if we include a /imagedata tag we get an error for DSSSL! --> @@ -374,6 +372,26 @@ </imageobject> </mediaobject> </figure> + +<figure float="1"> +<title id="meths7">Classes and Inheritance (part 8 of 9)</title> +<mediaobject> +<imageobject> +<!-- Note! - if we include a /imagedata tag we get an error for DSSSL! --> +<imagedata fileref="ooRexxClasses8.png" align="left" scale="90"> +</imageobject> +</mediaobject> +</figure> + +<figure float="1"> +<title id="meths7">Classes and Inheritance (part 9 of 9)</title> +<mediaobject> +<imageobject> +<!-- Note! - if we include a /imagedata tag we get an error for DSSSL! --> +<imagedata fileref="ooRexxClasses9.png" align="left" scale="90"> +</imageobject> +</mediaobject> +</figure> </section> <section id="created"><title>Creating Your Own Classes Using Directives</title> @@ -383,8 +401,8 @@ can determine what classes need to be created. You can create a class using messages or directives. Directives are a new kind of Rexx clause, and they are preferred over messages because the code is easier to read and understand, -especially in large programs. They also provide an easy way for you to save -your class definitions and share them with others using the PUBLIC option.</para> +especially in large programs. They also provide an easy way for you to +your class definitions with others using the PUBLIC option.</para> <section id="whatdir"><title>What Are Directives?</title> <indexterm><primary>directives</primary> @@ -465,44 +483,50 @@ <para>Some classes you define have an INIT method. INIT is called whenever a NEW message is sent to a class. The INIT method must contain whatever code is needed to initialize the object.</para> -<para>It is not required that a ::METHOD directive be preceded by a ::CLASS directive. -However, without it the method is only accessible by the executable part of -the program through Rexx's .METHODS environment symbol. This symbol identifies -a directory of methods that you can refer to by name. For each method name -only one method directive can appear that is not associated with a class.</para> <para>The ::METHOD directive can be used for: </para> <itemizedlist> <listitem><para>Creating a class method for the most-recent ::CLASS directive (the CLASS option).</para></listitem> <listitem><para>Creating a private method; that is, a method that works like a subroutine and can only be activated by the objects of the same type it belongs -to--otherwise the method is public by default, and any sender can activate +to—otherwise the method is public by default, and any sender can activate it.</para></listitem> <listitem><para>Creating a method that can be called while other methods are active on the same object, as described in <link linkend="activat">Activating Methods</link> (the UNGUARDED option). </para></listitem> -<listitem><para>Creating the instance methods -<emphasis role="italic">method_name</emphasis> and -<emphasis role="italic">method_name</emphasis>= for the preceding ::CLASS -directive (the ATTRIBUTE option).</para></listitem> </itemizedlist> </section> +<section id="attrdir"><title>The ::ATTRIBUTE Directive</title> +<indexterm><primary>directives</primary> +<secondary>::ATTRIBUTE</secondary></indexterm> +<para>A ::CLASS directive can also be followed by ::ATTRIBUTE directives, which +are used to create methods that directly access internal attributes of an object. +For example, the Account class could define</para> +<programlisting> +::attribute balance +</programlisting> +<para>Which would allow the account balance to be set or retrieved.</para> +<programlisting> + anAccount~balance = 10000 -- set a new account balance + say anAccount~balance -- display the current account balance +</programlisting> +<para>The access methods can created as read-only, or given private scope.</para> +</section> + <section id="routdir"><title>The ::ROUTINE Directive</title> <indexterm><primary>directives</primary> <secondary>::ROUTINE</secondary></indexterm> <para>You use the ::ROUTINE directive to create a named routine within a program. The ::ROUTINE directive starts the named routine and another directive (or the end of the program) ends the routine.</para> -<para>The ::ROUTINE directive is useful for defining lower-level routines that -are called by several methods. These methods might be in unrelated classes -or in different applications. You use ::ROUTINE when you have a utility that -you do not want to appear as a method.</para> +<para>The ::ROUTINE directive is useful organizing functions that are not specific to +a particular class type. +</para> <para>The ::ROUTINE directive includes a PUBLIC option for making the routine available to programs outside its containing Rexx program. The outside program must reference the routine by using a ::REQUIRES directive.</para> -<para>Only one ::ROUTINE directive can appear for a routine name within a program.</para> </section> <section id="requdir"><title>The ::REQUIRES Directive</title> @@ -517,13 +541,13 @@ ::REQUIRES program_name ]]> </programlisting> -<para>The ::REQUIRES directive must precede all other directives, and the order +<para>::REQUIRES directives are processed before other directives and the order of the ::REQUIRES directives determines the search order for the classes and routines defined in the named programs.</para> <para>Local routine or class definitions within a program override routines or -classes of the same name in programs that are accessed through ::REQUIRES -directives. Another directive (or the end of the program) must follow a ::REQUIRES -directive.</para> +classes of imported through ::REQUIRES +directives. +</para> </section> </section> @@ -555,16 +579,14 @@ ::class Account /* directives begin ... */ - ::method "TYPE" + ::method type return "an account" - ::method "NAME=" - expose name - use arg name + ::attribute name ::class Savings subclass Account - ::method "TYPE" + ::method type return "a savings account" /* ... directives end */ ]]> </programlisting> @@ -574,27 +596,22 @@ subclass. In the <computeroutput>::class Account</computeroutput> expression, the ::CLASS directive precedes the name of the new class, Account.</para> -<para>The example program also uses the ::METHOD directive to create TYPE and -NAME= methods for Account. In the -<computeroutput>::method "TYPE"</computeroutput> expression, the +<para>The example program also uses the ::METHOD directive to create a TYPE method and +::ATTRIBUTE to create NAME and NAME= methods for Account. In the +<computeroutput>::method type</computeroutput> instruction, the ::METHOD directive precedes the method name, and is immediately followed by the code for the method. Methods for any new class follow its ::CLASS directive in the program, and precede the next ::CLASS directive.</para> -<para>In the <computeroutput>::method "NAME="</computeroutput> -method, the USE ARG instruction retrieves the argument. -<indexterm><primary>USE ARG instruction</primary></indexterm> -<indexterm><primary>EXPOSE instruction</primary></indexterm> -<indexterm><primary>variables</primary> -<secondary>exposing</secondary></indexterm> -The EXPOSE instruction, which must immediately follow the ::METHOD directive, -makes the value (here, "John Smith") available for use by other methods. -A variable in an EXPOSE instruction is called an object -variable.</para> +<para>In the <computeroutput>::attribute name</computeroutput> +directive, we're creating a pair of methods. The NAME method returns the +current value of the NAME object variable. The NAME= method can assign +a new value to the NAME object variable. +</para> <para>You do not have to associate object variables with a specific object. Rexx keeps track of object variables for you. Whenever you send a message to savings account Asav, which points to the Name object, Rexx knows what internal object value to use. If you assign another value to Asav (such as "Mary Smith"), -Rexx deletes the object that was associated with Asav ("John Smith") +Rexx recovers the object that was associated with Asav ("John Smith") as part of its normal garbage-collection operations.</para> <para>In the Savings subclass, a second TYPE method is created that supersedes the TYPE method Savings would otherwise have inherited from Account. Note @@ -663,68 +680,6 @@ </section> </section> -<section id="createm"><title>Creating Classes Using Messages</title> -<indexterm><primary>creating classes</primary></indexterm> -<indexterm><primary>classes</primary> -<secondary>creating with messages</secondary></indexterm> -<indexterm><primary>messages</primary> -<secondary>creating classes with</secondary></indexterm> -<para>You can create a class using messages as well as directives. -Though classes are available only to the program that creates them, there -are occasions when this is useful and public availability is not required. -The following sections demonstrate the message technique using the Savings -Account example previously shown with directives.</para> - -<section id="definec"><title>Defining a New Class</title> -<para>To define a new class using messages, you send a SUBCLASS message to the -new class's superclass. That is, you send the message to the class that -precedes the new class in the hierarchy. To define a subclass of the Object -class called Account, you enter: </para> -<programlisting> -<![CDATA[ -account = .object~subclass("Account") -]]> -</programlisting> -<para>Here, <computeroutput>.object</computeroutput> is a reference to the -Rexx Object class. <computeroutput>.object</computeroutput> is an environment -symbol indicating the intention to create -a new class that is a subclass of the Object class. Environment symbols represent -objects in a directory of public objects, called the Environment -object. These public objects are available to all other objects, and -include all the classes that Rexx provides. Environment symbols begin with -a period and are followed by the class name. Thus the Object class is represented -by <computeroutput>.object,</computeroutput> the Alarm class by -<computeroutput>.alarm,</computeroutput> the Array class -by <computeroutput>.array,</computeroutput> and so on.</para> -<para>The twiddle (~) is the "message send" symbol, -<computeroutput>subclass</computeroutput> is a method of Class, and the string -identifier in parentheses is an -argument of SUBCLASS that names the new class, Account.</para> -</section> - -<section id="definem"><title>Adding a Method to a Class</title> -<para>You use the DEFINE method to define methods for your new class. To define -a TYPE method and a NAME= method, you enter: </para> -<programlisting> -<![CDATA[ -account~define("TYPE", "return ""an account""") -account~define("NAME=", "expose name; use arg name") -]]> -</programlisting> -</section> - -<section id="defines"><title>Defining a Subclass of the New Class</title> -<para>Using the SUBCLASS method, you can define a subclass for your new class -and then a method for that subclass. To define a Savings subclass for the -Account class, and a TYPE method for Savings, you enter: </para> -<programlisting> -<![CDATA[ -savings = account~subclass("Savings Account") -savings~define("TYPE", "return ""a savings account""") -]]> -</programlisting> -</section> - <section id="definei"><title>Defining an Instance</title> <para>You use the NEW method to define an instance of the new class, and then call methods that the instance inherited from its superclass. To @@ -741,13 +696,15 @@ </section> <section id="types"><title>Types of Classes</title> -<para>In Rexx there are three class types: </para> +<para>In Rexx there are four class types: </para> <itemizedlist> <listitem><para>Object classes</para></listitem> <listitem><para>Abstract classes</para></listitem> -<listitem><para>Mixin classes</para></listitem></itemizedlist> +<listitem><para>Metaclasses</para></listitem> +<listitem><para>Mixin classes</para></listitem> +</itemizedlist> <para>An object class (the default) can create instances -of the object in response to receiving a NEW or ENHANCED message. An abstract +of the object in response to receiving a NEW. An abstract class serves mainly to organize other classes in the hierarchy and define their message interface. A mixin class, through multiple inheritance, is an additional superclass to a class. The @@ -828,7 +785,7 @@ <para>The classes Rexx provides do not permit changes or additions to their method definitions. As a result, all new factories inherit these unchangeable actions from the Class class, and thus operate the same way. So if you want to create -a new class--a new factory--that behaves +a new class—a new factory—that behaves differently from the others, you can do either of the following: </para> <itemizedlist> <listitem><para>Write additional class methods for the new class, using This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <mie...@us...> - 2009-04-07 21:30:18
|
Revision: 4347 http://oorexx.svn.sourceforge.net/oorexx/?rev=4347&view=rev Author: miesfeld Date: 2009-04-07 21:30:09 +0000 (Tue, 07 Apr 2009) Log Message: ----------- [1826806] ReWrite Section 3.2 of The Programming Guide Modified Paths: -------------- docs/trunk/rexxpg/Makefile docs/trunk/rexxpg/tour.sgml Modified: docs/trunk/rexxpg/Makefile =================================================================== --- docs/trunk/rexxpg/Makefile 2009-04-07 21:18:22 UTC (rev 4346) +++ docs/trunk/rexxpg/Makefile 2009-04-07 21:30:09 UTC (rev 4347) @@ -133,6 +133,6 @@ clean: - rm *.log *.aux *.out *.fmt *.pdf genindex.sgml *.htm *.zip \ + rm -f *.log *.aux *.out *.fmt *.pdf genindex.sgml *.htm *.zip \ HTML.index *.tmp Modified: docs/trunk/rexxpg/tour.sgml =================================================================== --- docs/trunk/rexxpg/tour.sgml 2009-04-07 21:18:22 UTC (rev 4346) +++ docs/trunk/rexxpg/tour.sgml 2009-04-07 21:30:09 UTC (rev 4347) @@ -98,11 +98,11 @@ <secondary>running</secondary></indexterm> <indexterm><primary>Rexx</primary> <secondary>program, running a</secondary></indexterm> -<para>Rexx programs should have a -file extension of .rex (the default searched for by the ooRexx interpreter). -Here is a typical Rexx -program named greeting.rex. It prompts the user to type in a name and then -displays a personalized greeting: </para> +<para> + Rexx programs should have a file extension of .rex (the default searched for by the ooRexx + interpreter). Here is a typical Rexx program named greeting.rex. It prompts the user to type in a name + and then displays a personalized greeting: +</para> <programlisting> <![CDATA[ /* greeting.rex - a Rexx program to display a greeting. */ @@ -112,70 +112,152 @@ exit 0 /* Exit with a return code of 0 */ ]]> </programlisting> -<para>The ooRexx interpreter is invoked by the command </para> +<para> + SAY + <indexterm><primary>SAY instruction</primary></indexterm> + <indexterm><primary>Rexx</primary> + <secondary>SAY instruction</secondary></indexterm> + is a Rexx instruction that displays a message (like PRINT in Basic or printf in C). The message to be + displayed follows the SAY keyword. In this case, the message is the literal string "Please enter your + name.". The data between the quotes is a constant and will appear exactly as typed. You can use + either single (') or double quote (") delimiters for literal strings. +</para> +<para> + The + <indexterm><primary>PULL instruction</primary></indexterm> + <indexterm><primary>instructions</primary> + <secondary>PULL</secondary></indexterm> + <indexterm><primary>Rexx</primary> + <secondary>PULL instruction</secondary></indexterm> + PULL instruction reads a line of text from the standard input (the keyboard), and returns the text in + the variable specified with the instruction. In our example, the text is returned in the variable + name. +</para> +<para> + The next SAY instruction provides a + <indexterm><primary>instructions</primary> + <secondary>SAY</secondary></indexterm> + glimpse of what can be done with Rexx strings. It displays the word + <computeroutput>Hello</computeroutput> followed by the name of the user, which is stored in variable + name. Rexx substitutes the value of name and displays the resulting string. You do not need a separate + format + <indexterm><primary>strings</primary></indexterm> + string as you do with C or Basic. +</para> +<para> + The final instruction, + <indexterm><primary>EXIT instruction</primary></indexterm> + <indexterm><primary>instructions</primary> + <secondary>EXIT</secondary></indexterm> + <indexterm><primary>Rexx</primary> + <secondary>EXIT instruction</secondary></indexterm> + EXIT, ends the Rexx program. Control returns to the operation system command prompt. EXIT can also + return a value. In our example, 0 is returned. The EXIT instruction is optional. Running off the end + of the program is equivalent to coding "EXIT 0". +</para> +<para> + You can terminate a running Rexx program by pressing the Ctrl+Break key combination. Rexx stops running + the program and control returns to the command prompt. +</para> +<para> + The ooRexx interpreter is invoked by the command +</para> <programlisting> <![CDATA[ rexx ]]> </programlisting> -<para>To run the program greeting.rex, for example, use the command</para> +<para> + To run the program <computeroutput>greeting.rex</computeroutput>, for example, use the command +</para> <programlisting> <![CDATA[ rexx greeting.rex ]]> </programlisting> -<para>or</para> +<para> + or +</para> <programlisting> <![CDATA[ rexx greeting ]]> </programlisting> -<para>If not provided, an extension of ".rex" is assumed.</para> -<para>If you want to run your Rexx program in silent mode without -creating a console window on Windows, you can invoke RexxHIDE.EXE followed by the program -name and the program arguments from a program item. If RexxHIDE is called -from within a console window, no output is displayed in the console window. -RexxHIDE is only available for the Windows platform. +<para> + If not provided, an extension of ".rex" is assumed. </para> -<para>SAY -<indexterm><primary>SAY instruction</primary></indexterm> -<indexterm><primary>Rexx</primary> -<secondary>SAY instruction</secondary></indexterm> -is a Rexx instruction that displays a message (like PRINT in Basic or printf -in C). The message to be displayed follows the SAY keyword. In this case, the -message is the literal string "Please enter your name.". The data between the quotes -is a constant and will appear exactly as typed. You can use either single (') or double -quote (") delimiters for literal strings. +<para> + On <emphasis role="italic">Windows only</emphasis> there are these additional ways to run your Rexx + programs: </para> -<para>The -<indexterm><primary>PULL instruction</primary></indexterm> -<indexterm><primary>instructions</primary> -<secondary>PULL</secondary></indexterm> -<indexterm><primary>Rexx</primary> -<secondary>PULL instruction</secondary></indexterm> -PULL instruction reads a line of text from the standard input (the keyboard), -and returns the text in the variable specified with the instruction. In our -example, the text is returned in the variable name.</para> -<para>The next SAY instruction provides a -<indexterm><primary>instructions</primary> -<secondary>SAY</secondary></indexterm> -glimpse of what can be done with Rexx strings. It displays the word -<computeroutput>Hello</computeroutput> followed by the name of the user, which -is stored in variable name. Rexx substitutes the value of name and displays the -resulting string. You do not need a separate format -<indexterm><primary>strings</primary></indexterm> -string as you do with C or Basic.</para> -<para>The final instruction, -<indexterm><primary>EXIT instruction</primary></indexterm> -<indexterm><primary>instructions</primary> -<secondary>EXIT</secondary></indexterm> -<indexterm><primary>Rexx</primary> -<secondary>EXIT instruction</secondary></indexterm> -EXIT, ends the Rexx program. Control returns to the operation system command prompt. -EXIT can also return a value. In our example, 0 is returned. The EXIT instruction -is optional. Running off the end of the program is equivalent to coding "EXIT 0".</para> -<para>You can terminate a running Rexx program by pressing the Ctrl+Break key combination. -Rexx stops running the program and control returns to the command prompt.</para> +<itemizedlist> + <listitem><para> + The installation program on Windows sets up a file association for the + <computeroutput>.rex</computeroutput> file extension. This association allows the ooRexx programs to + be run from Windows Explorer by double-clicking on the icon of the program file. In addition, the + program can be run from a command prompt in a console window by simply typing the file name. The + <computeroutput>.rex</computeroutput> extension is not needed. For example, simply type + <computeroutput>greeting</computeroutput> to execute the <emphasis + role="italic">greeting.rex</emphasis> program: +<programlisting> +<![CDATA[ +C:\>greeting +Please enter your name. +Mark +Hello MARK + +C:\> +]]> +</programlisting> + </para></listitem> + <listitem><para> + A Rexx program can be run in <emphasis role="italic">silent mode</emphasis> by using + <computeroutput>rexxhide</computeroutput>. This executes the program without creating a console + window. This is most useful when creating a program shortcut. For the shortcut target, enter + <emphasis role="italic">rexxhide.exe</emphasis> followed by the program name and the program + arguments. Double-clicking on the shortcut then runs the program without creating a console window. + <emphasis role="bold">Note</emphasis> that <emphasis role="italic">silent</emphasis> means there is + no output from the Rexx program. When your program is run by + <computeroutput>rexxhide</computeroutput>, either by double clicking on its icon, or from within a + console window, there is no output displayed. Therefore <computeroutput>rexxhide</computeroutput> + would not normally be used for programs like <emphasis role="italic">greeting.rex</emphasis>. This is + what the <emphasis role="italic">greeting.rex</emphasis> program would look like when executed + through <computeroutput>rexxhide</computeroutput>: +<programlisting> +<![CDATA[ +C:\>rexxhide greeting.rex + +C:\> +]]> +</programlisting> + </para></listitem> + <listitem><para> + As a compliment to <computeroutput>rexxhide</computeroutput> is the + <computeroutput>rexxpaws</computeroutput> program. When a Rexx program is executed through + <computeroutput>rexxpaws</computeroutput>, at completion of the Rexx program, there will be a pause + waiting for the user to hit the enter key. For example, using the <emphasis + role="italic">greeting.rex</emphasis> program, <computeroutput>rexxpaws</computeroutput> would + produce the following: +<programlisting> +<![CDATA[ +C:\>rexxpaws greeting.rex +Please enter your name. +Mark +Hello MARK + +Press ENTER key to exit... + +C:\> +]]> +</programlisting> + <computeroutput>rexxpaws</computeroutput> is useful for running a Rexx program from a shortcut, where + the program <emphasis role="italic">does</emphasis> produce output. On Windows, when double-clicking on + the program file icon, a console window opens, the program is run, and then the console window + immediately closes. <computeroutput>rexxpaws</computeroutput> prevents the console window from closing + until the user hits the enter key. This allows the user to see what output the program produced. + </para></listitem> +</itemizedlist> + </section> <section id="element"><title>Elements of Rexx</title> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <mie...@us...> - 2009-09-23 20:00:55
|
Revision: 5205 http://oorexx.svn.sourceforge.net/oorexx/?rev=5205&view=rev Author: miesfeld Date: 2009-09-23 20:00:44 +0000 (Wed, 23 Sep 2009) Log Message: ----------- 2865196 Typos in Programmers Guide Patch supplied by Walter Pachel. Thanks Walter Modified Paths: -------------- docs/trunk/rexxpg/classes.sgml docs/trunk/rexxpg/classicapi.sgml docs/trunk/rexxpg/rexio.sgml docs/trunk/rexxpg/tour.sgml Modified: docs/trunk/rexxpg/classes.sgml =================================================================== --- docs/trunk/rexxpg/classes.sgml 2009-09-23 12:45:45 UTC (rev 5204) +++ docs/trunk/rexxpg/classes.sgml 2009-09-23 20:00:44 UTC (rev 5205) @@ -66,7 +66,7 @@ in the hierarchy is a superclass. And any class below is a subclass.</para> <para>From a class you can create instances of the class. Instances are merely similar objects that fit the template -of the class; they are "of" the the class, but are not classes themselves. +of the class; they are "of" the class, but are not classes themselves. </para> <para>Both the classes and their instances contain variables and methods. The methods a class provides @@ -219,7 +219,7 @@ <indexterm><primary>INIT method</primary></indexterm> INIT method, which can use them to set the initial state of object variables.</para> -<para>If a class overrides the INIT method it inhertits from a superclass, +<para>If a class overrides the INIT method it inherits from a superclass, the new INIT method must forward the INIT message up the hierarchy, to properly initialize the instance. An example in the next section demonstrates the use of INIT.</para> @@ -1092,7 +1092,7 @@ scope to achieve concurrency. To explain, the object's instance variables are contained in a collection of variable pools. Each pool is at a different scope in the object's inheritance chain. Methods defined at different class scopes do not directly share data and -can run simultaneiously.</para> +can run simultaneously.</para> <para>Scopes, like objects, hide and protect data from outside manipulation. Methods of the same scope share the variable pool of that scope. The scope shields the variable pool from methods operating at other scopes. Thus, Modified: docs/trunk/rexxpg/classicapi.sgml =================================================================== --- docs/trunk/rexxpg/classicapi.sgml 2009-09-23 12:45:45 UTC (rev 5204) +++ docs/trunk/rexxpg/classicapi.sgml 2009-09-23 20:00:44 UTC (rev 5205) @@ -1050,17 +1050,17 @@ Registered External Functions are an older style of routine that is only capable of dealing with String data. These routines do not have access to any of the object-oriented features of the language. The registered external functions -are described here, but should be considered only if compability with older +are described here, but should be considered only if compatibility with older versions of Object Rexx or other Rexx interpreters is a consideration.</para> <para>The newer style functions have access to Rexx objects and a fuller set of APIs for interfacing with the interpreter runtime. These functions are the -preferred method for writing Open Object Rexx extensions are are defined in +preferred method for writing Open Object Rexx extensions are defined in <link linkend="buildinglibs">Building an External Native Library</link>. </para> <section id="xffmt"><title>Registering External Functions</title> <para>An external function can reside in the same module (executable or library) -as an application, or in a separate lodable library library. +as an application, or in a separate loadable library. RexxRegisterFunctionExe registers external functions within an application module. External functions registered with RexxRegisterFunctionExe are available only to Rexx programs called from the registering application.</para> @@ -3215,7 +3215,7 @@ <listitem><para>is the address of an ASCII queue name. If no queue of that name exists, a queue is created with the requested name. and the CreatedFlag will be set to TRUE. If the name already exists, this -will just return a succesful return code. +will just return a successful return code. The maximum length for a queue name is 1024 characters.</para> </listitem></varlistentry> <varlistentry><term>CreateFlag (size_t *) - output</term> Modified: docs/trunk/rexxpg/rexio.sgml =================================================================== --- docs/trunk/rexxpg/rexio.sgml 2009-09-23 12:45:45 UTC (rev 5204) +++ docs/trunk/rexxpg/rexio.sgml 2009-09-23 20:00:44 UTC (rev 5205) @@ -54,7 +54,7 @@ with special new-line characters marking the end of each line of text in the stream. A binary file is a stream of characters without an inherent line structure. A Rexx stream object allows you read from a data stream using either the text-file -line methods or using a continous data stream method. +line methods or using a continuous data stream method. </para> <para>The Rexx Stream class is the mechanism for accessing I/O streams. To input or output data, you first create an instance of the Stream @@ -86,7 +86,7 @@ <para>Stream objects can be transient or persistent. An example of a transient (or dynamic) stream object is a serial interface. Data can be sent or received from serial interfaces, but the data is not stored permanently by the serial -interface itself. Consequently, you cannot, for example,read from a random position +interface itself. Consequently, you cannot, for example, read from a random position in the data stream—it can only be read as a sequential stream of characters. Once you write to the stream, the data cannot be read again.</para> <para>A disk file is an example of a persistent stream object. Because the data @@ -454,9 +454,9 @@ <section id="directfileaccess"><title>Direct File Access</title> <indexterm><primary>direct file access</primary></indexterm> <indexterm><primary>binary files</primary> -<secondary>direct acess</secondary></indexterm> +<secondary>direct access</secondary></indexterm> <indexterm><primary>text files</primary> -<secondary>direct acess</secondary></indexterm> +<secondary>direct access</secondary></indexterm> <para> Rexx provides several ways for you to read records of a file directly (that is, in random order). The following example, DIRECT.CMD, shows several cases that illustrate some of your options.</para> Modified: docs/trunk/rexxpg/tour.sgml =================================================================== --- docs/trunk/rexxpg/tour.sgml 2009-09-23 12:45:45 UTC (rev 5204) +++ docs/trunk/rexxpg/tour.sgml 2009-09-23 20:00:44 UTC (rev 5205) @@ -191,8 +191,8 @@ If not provided, an extension of ".rex" is assumed. </para> <para> - The <computeroutput>-v</computeroutput> option produces the version and copyright infomation. For - example: + The <computeroutput>-v</computeroutput> option produces the version and copyright information. +For example: <programlisting> <![CDATA[ C:\Rexx>rexx -v @@ -418,7 +418,7 @@ prompt. REXXTRY is a kind of Rexx mini-interpreter that checks Rexx statements one at a time. If you run REXXTRY with no parameter, or with a question mark as a parameter, REXXTRY also briefly describes itself.</para> -<para>From your command propmpt type:</para> +<para>From your command prompt type:</para> <programlisting> <![CDATA[ @@ -938,7 +938,7 @@ ]]> </programlisting> <para>As with GOTO, you need to be careful about how you use SIGNAL. -In particular, do not use SIGNAL to jump to the the middle of a DO/END block or +In particular, do not use SIGNAL to jump to the middle of a DO/END block or into a SELECT structure.</para> </section> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <jfa...@us...> - 2009-12-09 13:15:57
|
Revision: 5395 http://oorexx.svn.sourceforge.net/oorexx/?rev=5395&view=rev Author: jfaucher Date: 2009-12-09 13:15:46 +0000 (Wed, 09 Dec 2009) Log Message: ----------- rexxpg : Use pdf images when generating pdf documentation Modified Paths: -------------- docs/trunk/rexxpg/Makefile docs/trunk/rexxpg/classes.sgml docs/trunk/rexxpg/concept.sgml docs/trunk/rexxpg/provide.sgml Added Paths: ----------- docs/trunk/rexxpg/BallObject.pdf docs/trunk/rexxpg/BallObjectData.pdf docs/trunk/rexxpg/BillingApplication.pdf docs/trunk/rexxpg/EncapsulatedObject.pdf docs/trunk/rexxpg/IconClass.pdf docs/trunk/rexxpg/IconClassInstances.pdf docs/trunk/rexxpg/InstanceMethods.pdf docs/trunk/rexxpg/Modules.pdf docs/trunk/rexxpg/MultipleInheritance.pdf docs/trunk/rexxpg/PartClass.pdf docs/trunk/rexxpg/ReportObject.pdf docs/trunk/rexxpg/ScreenObject.pdf docs/trunk/rexxpg/SimpleClass.pdf docs/trunk/rexxpg/SubclassInheritance.pdf docs/trunk/rexxpg/Subclasses.pdf docs/trunk/rexxpg/rxo90017.pdf docs/trunk/rexxpg/rxo90018.pdf docs/trunk/rexxpg/rxo90019.pdf docs/trunk/rexxpg/rxoq0s05.pdf Added: docs/trunk/rexxpg/BallObject.pdf =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/BallObject.pdf ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/BallObjectData.pdf =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/BallObjectData.pdf ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/BillingApplication.pdf =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/BillingApplication.pdf ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/EncapsulatedObject.pdf =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/EncapsulatedObject.pdf ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/IconClass.pdf =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/IconClass.pdf ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/IconClassInstances.pdf =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/IconClassInstances.pdf ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/InstanceMethods.pdf =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/InstanceMethods.pdf ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Modified: docs/trunk/rexxpg/Makefile =================================================================== --- docs/trunk/rexxpg/Makefile 2009-12-09 13:04:29 UTC (rev 5394) +++ docs/trunk/rexxpg/Makefile 2009-12-09 13:15:46 UTC (rev 5395) @@ -65,7 +65,7 @@ ../shared/gethelp.sgml \ ../shared/CPLv1.0.sgml -IMAGE_FILES = ReportObject.png \ +HTML_IMAGE_FILES = ReportObject.png \ BallObject.png \ BallObjectData.png \ EncapsulatedObject.png \ @@ -95,6 +95,36 @@ docbook-1.png \ new_rexxla.jpg +PDF_IMAGE_FILES = ReportObject.pdf \ + BallObject.pdf \ + BallObjectData.pdf \ + EncapsulatedObject.pdf \ + SimpleClass.pdf \ + IconClass.pdf \ + IconClassInstances.pdf \ + Subclasses.pdf \ + ScreenObject.pdf \ + MultipleInheritance.pdf \ + Modules.pdf \ + BillingApplication.pdf \ + SubclassInheritance.pdf \ + InstanceMethods.pdf \ + PartClass.pdf \ + rxoq0s05.pdf \ + rxoq0s06.jpg \ + rxoq0s07.jpg \ + rxoq0s09.jpg \ + ooRexxClasses1.png \ + ooRexxClasses2.png \ + ooRexxClasses3.png \ + ooRexxClasses4.png \ + ooRexxClasses5.png \ + ooRexxClasses6.png \ + ooRexxClasses7.png \ + oorexx.jpg \ + docbook-1.png \ + new_rexxla.jpg + JADETEXFMT = ./pdfjadetex.fmt HYPERREFCFG = ./hyperref.cfg TEXMF = /usr/share/texmf @@ -108,10 +138,10 @@ html: rexxpg-html.zip -rexxpg.pdf: $(IMAGE_FILES) $(STYLESHEET) $(JADETEXFMT) genindex.sgml svnrev.tmp +rexxpg.pdf: $(PDF_IMAGE_FILES) $(STYLESHEET) $(JADETEXFMT) genindex.sgml svnrev.tmp docbook2pdf -d ../shared/oorexx.print.dsl rexxpg.sgml -book1.htm: $(IMAGE_FILES) $(HTML_STYLESHEET) genindex.sgml svnrev.tmp +book1.htm: $(HTML_IMAGE_FILES) $(HTML_STYLESHEET) genindex.sgml svnrev.tmp docbook2html -d ../shared/oorexx.html.dsl rexxpg.sgml rexxpg-html.zip: book1.htm @@ -133,6 +163,6 @@ clean: - rm -f *.log *.aux *.out *.fmt *.pdf genindex.sgml *.htm *.zip \ + rm -f *.log *.aux *.out *.fmt rexxpg.pdf genindex.sgml *.htm *.zip \ HTML.index *.tmp Added: docs/trunk/rexxpg/Modules.pdf =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/Modules.pdf ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/MultipleInheritance.pdf =================================================================== --- docs/trunk/rexxpg/MultipleInheritance.pdf (rev 0) +++ docs/trunk/rexxpg/MultipleInheritance.pdf 2009-12-09 13:15:46 UTC (rev 5395) @@ -0,0 +1,265 @@ +%PDF-1.4 +%äüöß +2 0 obj +<</Length 3 0 R/Filter/FlateDecode>> +stream +x\x9C\x95QMKA\xBDϯȹ\xB0c\x92\xF9\xD8),[\xDD +\xBDU<\x887\xAD"\xAD`/\xFD\xFB&\xB3\xDB +\xD5\xF5\x83aB\x92y\xEF\xE5\x91AKp0\xEF\x80P\xA1\xA4\x8E\xA3\xC4$\xEC\x9F\xE0no\x86@\xCF\xFE٠\xF4ag\xA2\xC9V\xB1B\xDB\xCAbi\xBE\x98ͬ\xC8\xE9Ң7u\xB0 "C\xFFK\xD1J\xD0o\xEE\xA4\Q\x83\x8C}\x8E +zsh\xB0Ε\x94 \xE7Zx\xB4\xB88\xC68\x91\x9F:\x97%w#/u\xC8|\x98ť\xD3\xE6\x87~e\xBAެ\xCF +[\xDE\xD6熯 +\x8B\xB1S\x89\xF0\x8B\x89\xBF\xBF.5'\xC4 \xB2D\xD8gN\xFF\x97\xF9\xF1\x95\xDC0DWږ\x86\xA72/~\xEE`\xD8\xC0͵,\x83mrp\x90j%?\xFFj\xD8\xC9\xBA\xB9legأ\x8DC\xB1\x85\xDBM\xF7 +Mq\xA4$\x8C֍\x8C\xAF@ϊLE\x9E\x81IHPr$\xB8\xC4\xC3n,(I\x98R\x8E\x8AapQ +\x81\xAD\xAF\xE141\x9F\xE8 +endstream +endobj + +3 0 obj +303 +endobj + +5 0 obj +<</Length 6 0 R/Filter/FlateDecode/Length1 27424>> +stream +x\x9C\xED}{\T\xC7\xD9\xF0̜s\xF6\xEC}\xCF.\xB0\xBB\xB0{p\xD9EYA"\x8B\xC6\xBC\xA2#\x91VY\xE5&\xBB\x88\xE6\x8Am\xD5\xC4\xDClژ\xDBۚ[sm\x9AѢI?mc\x93\xE6b\xB5m\x9A4iRmk\x9A\xE4m\xA96Mms\x81\xFD\x9E\x99s0I\xFB\xF6}\xBF\xEF\x8F\xEF\xF7\xFB\xB2\x87\x99yf\xE6\x99\xDBs\x9Bg\xE6,\xEB\xE9 +##\xEAG +\xB6t\x84\xBAW]2\xF7R\x84\xD0+a[\xCB֘|\xE7[3\xDE\xF8B\x9A\x99\xBA7v\xD7o[\x81\x90V\x82|\xE7\xC6\xF6\xEDF\xB0\xBD!s?B9\xB7\x85C\xADK\xBA\xA7[*ʁ>\xE6\xB4AAx\xEC+"\xE4\xD7B>\xA7\xAD#\xB6m\xB16\xB1 +\xF2\x80\x8Fִw\xB5\x846\xB4\xDDI\xF3oA~fGh[\xF7&\xFD\xD7y\x84\x8A\x8D\x90\x97;C\xE1Kpd\xE4\xA7#\xF8YwW4\xB6\xE5%jF\xB4\xBE\xBB'\xDC}\xE4\xD0\xDF\x81\xBC\x8C\x90\xCA\x86\x87~\xA0=\xD6\xD0<\xE1xA#juz\x83\xD1d\xB6HV[Jj\x9A\xFD\xFF\xF3\x8E\xA0t£(\x9D\xF7#'B\x89w!\xBCGӱH\xE2=ZOS\xF2\x9F\x80<\xAC\x84CO\xE1z +E?\xC2\xE7\xA1\xD5\xD3\xE80B?AT\x85\xFE]\x8B\xBE\x89v# +Z%7\xA1\xF0P\xFEM\x9C\x9EB\xE8\x90\xA5\xD0 \xC0\xBD]\x8F\x8E ;v&\xDEG7\xA0\x9D\xDC/\xA0\xD5NdBSP%Z\x86\xBAЭ\xF8\xF2D/Z\x8BN\xF3_E%\xE8rԉ\xBAq\xA2!q[\xE2\x8E\xC4\xC3\xE8;\xE80\xF7\x93\xC4(2\xA0\xD4ωğ\x85_%\xDEB\xF9\xD0\xE2Nt:\x8D\xEF\xD0DA\xA50\xBF\x85zн\\x8F\xC3\xB2Q́Gu\xE8>F\xD0{\xBD\x8B\x9D\xF8Zn!\xF4\xF2P"\x9E8XnԄ\xDAн\xE8\x9E\x8D\x91lam\xA2.q\xD9a\x8Cm\xD0\xEB=h\x82g\xFD |
From: <jfa...@us...> - 2009-12-19 16:21:34
|
Revision: 5442 http://oorexx.svn.sourceforge.net/oorexx/?rev=5442&view=rev Author: jfaucher Date: 2009-12-19 16:21:26 +0000 (Sat, 19 Dec 2009) Log Message: ----------- rexxpg : reuse (by copy) the odg/png/pdf files of rexxref for the 9 "Classes and Inheritance" pictures Modified Paths: -------------- docs/trunk/rexxpg/ooRexxClasses1.png docs/trunk/rexxpg/ooRexxClasses2.png docs/trunk/rexxpg/ooRexxClasses3.png docs/trunk/rexxpg/ooRexxClasses4.png docs/trunk/rexxpg/ooRexxClasses5.png docs/trunk/rexxpg/ooRexxClasses6.png docs/trunk/rexxpg/ooRexxClasses7.png docs/trunk/rexxpg/ooRexxClasses8.png docs/trunk/rexxpg/ooRexxClasses9.png docs/trunk/rexxpg/provide.sgml Added Paths: ----------- docs/trunk/rexxpg/ooRexxClasses1.odg docs/trunk/rexxpg/ooRexxClasses1.pdf docs/trunk/rexxpg/ooRexxClasses2.odg docs/trunk/rexxpg/ooRexxClasses2.pdf docs/trunk/rexxpg/ooRexxClasses3.odg docs/trunk/rexxpg/ooRexxClasses3.pdf docs/trunk/rexxpg/ooRexxClasses4.odg docs/trunk/rexxpg/ooRexxClasses4.pdf docs/trunk/rexxpg/ooRexxClasses5.odg docs/trunk/rexxpg/ooRexxClasses5.pdf docs/trunk/rexxpg/ooRexxClasses6.odg docs/trunk/rexxpg/ooRexxClasses6.pdf docs/trunk/rexxpg/ooRexxClasses7.odg docs/trunk/rexxpg/ooRexxClasses7.pdf docs/trunk/rexxpg/ooRexxClasses8.odg docs/trunk/rexxpg/ooRexxClasses8.pdf docs/trunk/rexxpg/ooRexxClasses9.odg docs/trunk/rexxpg/ooRexxClasses9.pdf Added: docs/trunk/rexxpg/ooRexxClasses1.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/ooRexxClasses1.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/ooRexxClasses1.pdf =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/ooRexxClasses1.pdf ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Modified: docs/trunk/rexxpg/ooRexxClasses1.png =================================================================== (Binary files differ) Added: docs/trunk/rexxpg/ooRexxClasses2.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/ooRexxClasses2.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/ooRexxClasses2.pdf =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/ooRexxClasses2.pdf ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Modified: docs/trunk/rexxpg/ooRexxClasses2.png =================================================================== (Binary files differ) Added: docs/trunk/rexxpg/ooRexxClasses3.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/ooRexxClasses3.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/ooRexxClasses3.pdf =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/ooRexxClasses3.pdf ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Modified: docs/trunk/rexxpg/ooRexxClasses3.png =================================================================== (Binary files differ) Added: docs/trunk/rexxpg/ooRexxClasses4.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/ooRexxClasses4.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/ooRexxClasses4.pdf =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/ooRexxClasses4.pdf ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Modified: docs/trunk/rexxpg/ooRexxClasses4.png =================================================================== (Binary files differ) Added: docs/trunk/rexxpg/ooRexxClasses5.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/ooRexxClasses5.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/ooRexxClasses5.pdf =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/ooRexxClasses5.pdf ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Modified: docs/trunk/rexxpg/ooRexxClasses5.png =================================================================== (Binary files differ) Added: docs/trunk/rexxpg/ooRexxClasses6.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/ooRexxClasses6.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/ooRexxClasses6.pdf =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/ooRexxClasses6.pdf ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Modified: docs/trunk/rexxpg/ooRexxClasses6.png =================================================================== (Binary files differ) Added: docs/trunk/rexxpg/ooRexxClasses7.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/ooRexxClasses7.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/ooRexxClasses7.pdf =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/ooRexxClasses7.pdf ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Modified: docs/trunk/rexxpg/ooRexxClasses7.png =================================================================== (Binary files differ) Added: docs/trunk/rexxpg/ooRexxClasses8.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/ooRexxClasses8.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/ooRexxClasses8.pdf =================================================================== --- docs/trunk/rexxpg/ooRexxClasses8.pdf (rev 0) +++ docs/trunk/rexxpg/ooRexxClasses8.pdf 2009-12-19 16:21:26 UTC (rev 5442) @@ -0,0 +1,246 @@ +%PDF-1.4 +%äüöß +2 0 obj +<</Length 3 0 R/Filter/FlateDecode>> +stream +x\x9C\xAD\x94MO\xE40\x86\xEF\xF9>#\xB5\xD8I\xDA$R va%n\xC0H{@\xDCv\xA1 .\xFC\xFDu\x9C4-\xED0ˡ\xAA&}\x9D\xF1G\xF241\xB6\xEA +\x90\x95\xED\xBA6@xx\xFF\xBFO\xE0U\xA4\xE7\xFDQ!\xF4/*\xB9\xF8$\xF7\x90%\xB6\x9A5ַ\xFC\xF5\xA4N\xB6)\xF4\xB0|s2\xAD\x87\x9A\xC01/J\x8FrIvN\xA4\xEDV\xC6\xE84\xEFU\xAE\x94\xEA\xC3\xCD/\xD9\xC8\xFF\xAEx\xCDϛV\xB9U\xD7?\xBC\x81\xF3\x9D\xD2\xE8\xDA\xACi-\xEC\xFE\xC0\xE9%sb\xF5p7 \xC5F\xA8cC\x9Aȃ\xD9\xC5\xC6 +\xD8\xC7\xFBݕ\xBA\xD8q\xBE#\x80\xAC\x9F^IdX\xEA\xECQ\xC3\xC6Op\xCC\xD9\xD7@Bۃ[\xD3p\x89\x80!\xDA\xCFb\xE3<\x97\x89i"ˌ\xEB\xA70\xB2\xA3\xCF7~\xFA\xA0\xA2\xCB"o\x8FӤ\xDE\xD6 +\x93\xF6uY\x97qi\xAF}\xFC\xB8mYeM\x97,\xB6\xEEߋ\xE8G\xBE\x972\xF6\xB1 !c'\x92\x89/q\x96\x9A\x99g6\xBET{\x9AN\x90\xE9\xA73$\xBA\xE40ze\xAF\xFD\x9F\xFB\xBBa\x95\xF7\xD7\xF7\xB9\x83@\xC7+K:\x92M\xA3K\xC7x\xC4\\xA8 +\xE6\xB9\xDF\xFCj/6\xE2\xF4\xC49\xDF\xE3l\x82\xAF\x8C\xAD\xB2.9r\xDB\xFAd\xAF}\x9C\xF3\x96U֜\x8D\xF5\xCCx͙\xA3\xB3cs\x94&@V\xAE\xFF\xECt\xD2Jmi\x8D\xE7i\xD6Q\xBF\xEEa\xDE.¢_\\xC3?uhj\xC5 +endstream +endobj + +3 0 obj +457 +endobj + +5 0 obj +<</Length 6 0 R/Filter/FlateDecode/Length1 27192>> +stream +x\x9C\xED|y|S\xC7\xD5\xE8\xCC\xDCE\xBBt%˖,\xC9ֵe\xB0\xC0\xDB`l,\x83 +!f3\xC4&8X\xB6x\x95lmӄ@\xC8F\xD3f#m!K\xB3\xB6\x8DljH\xFA\xE2&4i\xB3\xDA,mi\x92\x904iK\xA1mJ\x9A\xE9\x9D]y \xB4_\xBF\xEF\xBD?\xDE\xEF\xF7\xA2\xEB\x999s\xE6\xCC̙sΜ9s-\xBB7\xDCDz4\x808\xE4o\xE9t\xAF\xBEhn!B\xE8%\x84\xB0\xA5eK\xAF|\xFB\xF9\xC7>\x81\x908sC\xF7\xC6}\xF3֕\xA9%\xA8wnl߶\xE1S\xA9VF\xC88\x80\x90g\xB4-h\xAD\xED\x9EnB\xA8\xD0c\xCCiD0\xF6 +ԷB=\xA7\xAD\xA3wk\x8D\xE6\xDBuP\xFF\xD4\xEBۻZ\xB5\xF5\xC1F\xA8\xF5\xFC\x8E\xC0\xD6\xEEM\xDA[y\x84\x8Ar\xA0.w:\x82\xFF\xE40\xF4-\xAAB\xC8\xF7\xAB\xEE\xAEH\xEF(/\x8E\xD0z;m\xEF\xBB\xFC\xE4A\xA8\xCFEHx\x84\xE1\xA1=\x80"\xAD\x8ED\x95Z\xA3\xD5\xE9 +F\x93d\xB6\xA4XS\xD1\xFFG\xE10J\x87\xE4B\xE9\xBC\x81\xDC\xE2\x80\xF4!-c\xA1\xF8\x87\xB4\x9D\x96\xE4\x8F@<\xA2$\x84F?\xC4!\xF4C\xF44z\x9F\x81^\x8F\xA3Ch\xFD\xD9P\xFA\xBA}\xEDD"Z\x98\xD0Jx\xC0\xA7LJQ\xBAl\xE9^\xF42\xD0^\x86\xAEF\x87Q\xB6\xC7?Bנ\xDC+\xD0k2\xA0lT\x89\x96\xA3.t3\xBE4އ֡\xB7\xF9kQ \xBAu\xA2n<\xAF\x8F\xDF\xBF-\xFE |
From: <jfa...@us...> - 2009-12-19 17:40:36
|
Revision: 5443 http://oorexx.svn.sourceforge.net/oorexx/?rev=5443&view=rev Author: jfaucher Date: 2009-12-19 17:40:29 +0000 (Sat, 19 Dec 2009) Log Message: ----------- rexxpg : replace rxoq0s06.jpg by rxoq0s06.odg/png/pdf Modified Paths: -------------- docs/trunk/rexxpg/classes.sgml Added Paths: ----------- docs/trunk/rexxpg/rxoq0s06.odg docs/trunk/rexxpg/rxoq0s06.pdf docs/trunk/rexxpg/rxoq0s06.png Removed Paths: ------------- docs/trunk/rexxpg/rxoq0s06.jpg Modified: docs/trunk/rexxpg/classes.sgml =================================================================== --- docs/trunk/rexxpg/classes.sgml 2009-12-19 16:21:26 UTC (rev 5442) +++ docs/trunk/rexxpg/classes.sgml 2009-12-19 17:40:29 UTC (rev 5443) @@ -830,7 +830,7 @@ <mediaobject> <imageobject> <!-- Note! - if we include a /imagedata tag we get an error for DSSSL! --> -<imagedata fileref="rxoq0s06.jpg" scale="60"> +<imagedata fileref="rxoq0s06" scale="60"> </imageobject> </mediaobject> </figure> Deleted: docs/trunk/rexxpg/rxoq0s06.jpg =================================================================== (Binary files differ) Added: docs/trunk/rexxpg/rxoq0s06.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxoq0s06.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxoq0s06.pdf =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxoq0s06.pdf ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxoq0s06.png =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxoq0s06.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <jfa...@us...> - 2009-12-19 22:17:00
|
Revision: 5444 http://oorexx.svn.sourceforge.net/oorexx/?rev=5444&view=rev Author: jfaucher Date: 2009-12-19 22:16:52 +0000 (Sat, 19 Dec 2009) Log Message: ----------- rexxpg : replace rxoq0s07.jpg by rxoq0s07.odg/png/pdf (idem for rxoq0s09) Modified Paths: -------------- docs/trunk/rexxpg/Makefile docs/trunk/rexxpg/classes.sgml docs/trunk/rexxpg/command.sgml Added Paths: ----------- docs/trunk/rexxpg/rxoq0s07.odg docs/trunk/rexxpg/rxoq0s07.pdf docs/trunk/rexxpg/rxoq0s07.png docs/trunk/rexxpg/rxoq0s09.odg docs/trunk/rexxpg/rxoq0s09.pdf docs/trunk/rexxpg/rxoq0s09.png Removed Paths: ------------- docs/trunk/rexxpg/rxoq0s07.jpg docs/trunk/rexxpg/rxoq0s09.jpg Modified: docs/trunk/rexxpg/Makefile =================================================================== --- docs/trunk/rexxpg/Makefile 2009-12-19 17:40:29 UTC (rev 5443) +++ docs/trunk/rexxpg/Makefile 2009-12-19 22:16:52 UTC (rev 5444) @@ -80,10 +80,10 @@ SubclassInheritance.png \ InstanceMethods.png \ PartClass.png \ - rxoq0s05.jpg \ - rxoq0s06.jpg \ - rxoq0s07.jpg \ - rxoq0s09.jpg \ + rxoq0s05.png \ + rxoq0s06.png \ + rxoq0s07.png \ + rxoq0s09.png \ ooRexxClasses1.png \ ooRexxClasses2.png \ ooRexxClasses3.png \ @@ -111,9 +111,9 @@ InstanceMethods.pdf \ PartClass.pdf \ rxoq0s05.pdf \ - rxoq0s06.jpg \ - rxoq0s07.jpg \ - rxoq0s09.jpg \ + rxoq0s06.pdf \ + rxoq0s07.pdf \ + rxoq0s09.pdf \ ooRexxClasses1.png \ ooRexxClasses2.png \ ooRexxClasses3.png \ Modified: docs/trunk/rexxpg/classes.sgml =================================================================== --- docs/trunk/rexxpg/classes.sgml 2009-12-19 17:40:29 UTC (rev 5443) +++ docs/trunk/rexxpg/classes.sgml 2009-12-19 22:16:52 UTC (rev 5444) @@ -830,7 +830,7 @@ <mediaobject> <imageobject> <!-- Note! - if we include a /imagedata tag we get an error for DSSSL! --> -<imagedata fileref="rxoq0s06" scale="60"> +<imagedata fileref="rxoq0s06"> </imageobject> </mediaobject> </figure> Modified: docs/trunk/rexxpg/command.sgml =================================================================== --- docs/trunk/rexxpg/command.sgml 2009-12-19 17:40:29 UTC (rev 5443) +++ docs/trunk/rexxpg/command.sgml 2009-12-19 22:16:52 UTC (rev 5444) @@ -628,7 +628,7 @@ <mediaobject> <imageobject> <!-- Note! - if we include a /imagedata tag we get an error for DSSSL! --> -<imagedata fileref="rxoq0s07.jpg" scale="50"> +<imagedata fileref="rxoq0s07"> </imageobject> </mediaobject> </section> @@ -640,7 +640,7 @@ <mediaobject> <imageobject> <!-- Note! - if we include a /imagedata tag we get an error for DSSSL! --> -<imagedata fileref="rxoq0s09.jpg" scale="50"> +<imagedata fileref="rxoq0s09"> </imageobject> </mediaobject> </section> Deleted: docs/trunk/rexxpg/rxoq0s07.jpg =================================================================== (Binary files differ) Added: docs/trunk/rexxpg/rxoq0s07.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxoq0s07.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxoq0s07.pdf =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxoq0s07.pdf ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxoq0s07.png =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxoq0s07.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Deleted: docs/trunk/rexxpg/rxoq0s09.jpg =================================================================== (Binary files differ) Added: docs/trunk/rexxpg/rxoq0s09.odg =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxoq0s09.odg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxoq0s09.pdf =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxoq0s09.pdf ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: docs/trunk/rexxpg/rxoq0s09.png =================================================================== (Binary files differ) Property changes on: docs/trunk/rexxpg/rxoq0s09.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
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] |
From: <jfa...@us...> - 2011-02-20 13:01:06
|
Revision: 6788 http://oorexx.svn.sourceforge.net/oorexx/?rev=6788&view=rev Author: jfaucher Date: 2011-02-20 13:01:00 +0000 (Sun, 20 Feb 2011) Log Message: ----------- rexxpg : Picture 5.10 : Added File and Package Modified Paths: -------------- docs/trunk/rexxpg/ooRexxClasses9.odg docs/trunk/rexxpg/ooRexxClasses9.pdf Modified: docs/trunk/rexxpg/ooRexxClasses9.odg =================================================================== (Binary files differ) Modified: docs/trunk/rexxpg/ooRexxClasses9.pdf =================================================================== (Binary files differ) This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |