::METHOD

The ::METHOD directive creates a method object and defines the method attributes.

>>-::METHOD--methodname--+-------+--+-----------+--+----------+--->
                         +-CLASS-+  +-ATTRIBUTE-+  +-ABSTRACT-+

    +-PUBLIC--+  +-GUARDED---+  +-UNPROTECTED-+
 >--+---------+--+-----------+--+-------------+------------------->
    +-PRIVATE-+  +-UNGUARDED-+  +-PROTECTED---+

 >--+---------------+---;-----------------------------------------><
    +-EXTERNAL-spec-+

A ::METHOD directive creates method objects that may be associated with a class instance. The created method may be from Rexx code, mapped to method in an external native library, or automatically generated. The type of method is determined by the combination of options specified.

The methodname is a literal string or a symbol that is taken as a constant. The method is defined as methodname in the class specified in the most recent ::CLASS directive. Only one ::METHOD directive can appear for any methodname in a class.

A ::CLASS directive is not required before a ::METHOD directive. If no ::CLASS directive precedes ::METHOD, the method is not associated with a class but is accessible to the main (executable) part of a program through the .METHODS built-in object. Only one ::METHOD directive can appear for any method name not associated with a class. See .METHODS for more details.

If you specify the CLASS option, the method is a class method. See Objects and Classes. The method is associated with the class specified on the most recent ::CLASS directive. The ::METHOD directive must follow a ::CLASS directive when the CLASS option is used.

If ABSTRACT, ATTRIBUTE, or EXTERNAL is not specified, the ::METHOD directive starts a section of method code which is ended by another directive or the end of the program. The ::METHOD is not included in the source of the created METHOD object.

Example:

r = .rectangle~new(20,10)
say "Area is" r~area       /* Produces "Area is 200" */

::class rectangle

::method area              /* defined for the RECTANGLE class */
  expose width height
  return width*height

::method init
  expose width height
  use arg width, height

::method perimeter
  expose width height
  return (width+height)*2

If you specify the ATTRIBUTE option, method variable accessor methods are created. In addition to generating a method named methodname, another method named methodname= is created. The first method returns the value of object instance variable that matches the method name. The second method assigns a new value to the object instance variable.

For example, the directive

::method name attribute

creates two methods, NAME and NAME=. The NAME and NAME= methods are equivalent to the following code sequences:

::method "NAME="
  expose name
  use arg name

::method name
  expose name
  return name

If you specify the ABSTRACT option, the method creates an ABSTRACT method placeholder. ABSTRACT methods define a method that an implementing subclass is expected to provide a concrete implementation for. Any attempt to invoke an ABSTRACT method directly will raise a SYNTAX condition.

If the EXTERNAL option is specified, then spec identifies a method in an external native library that will be invoked as the named method. The spec is a literal string containing a series of whitespace delimited tokens defining the external method. The first token must be the word LIBRARY, which indicates the method resides in a native library of the type allowed on a ::REQUIRES directive. The second token must identify the name of the external library. The external library is located using platform-specific mechanisms for loading libraries. For Unix-based systems, the library name is case-sensitive. The third token is optional and specifies the name of the method within the library package. If not specified, the ::METHOD name is used. The target package method name is case insensitive.

Example:


-- creates method INIT from method RegExp_Init
-- in library rxregexp
::METHOD INIT EXTERNAL "LIBRARY rxregexp RegExp_Init"

-- creates method INIT from method POS
-- in library rxregexp
::METHOD POS EXTERNAL "LIBRARY rxregexp"

If the ATTRIBUTE option is specified with the EXTERNAL option, then two method objects need to be created. The target method name is appended to the string "GET" to derive the name of the getter attribute method. To generate the setter attribute method, the name is appended to the string "SET".

Example:

-- maps "NAME" method to "GETNAME and
-- "NAME=" to "SETNAME"
::METHOD name ATTRIBUTE EXTERNAL "LIBRARY mylib"

-- maps "ADDRESS" method to "GETMyAddress and
-- "ADDRESS=" to "SETMyAddress"
::METHOD address ATTRIBUTE EXTERNAL "LIBRARY mylib MyAddress"

Notes:

  1. You can specify all options in any order.

  2. If you specify the PRIVATE option, the created methods are private methods. Private methods have restricted access rules on how they can be invoked. See Public versus Private Methods for details of how private methods can be used. If you omit the PRIVATE option or specify PUBLIC, the method is a public method that any sender can activate.

  3. If you specify the UNGUARDED option, the method can be called while other methods are active on the same object. If you do not specify UNGUARDED, the method requires exclusive use of the object variable pool; it can run only if no other method that requires exclusive use of the object variable pool is active on the same object.

  4. If you specify the PROTECTED option, the method is a protected method. (See The Security Manager for more information.) If you omit the PROTECTED option or specify UNPROTECTED, the method is not protected.

  5. If you specify ATTRIBUTE, ABSTRACT, or EXTERNAL, another directive (or the end of the program) must follow the ::METHOD directive.

  6. It is an error to specify ::METHOD more than once within the same class and use the same methodname.