OS/2 Shareware BBS: 18 REXX/18-REXX.zip/REXXEA.ZIP/REXXEA.INF

OS/2 Help File | 1992-11-10 | 14KB | 545 lines

ΓòÉΓòÉΓòÉ 1. Introduction ΓòÉΓòÉΓòÉ


                Copyright 1992 Ammonoosuc Technology, Inc.

This document describes the REXXEA package, a set of functions accessible to a
REXX program for processing extended attributes associated with a file or a
subdirectory. Extended attributes are available only when the underlying file
system explicitly supports them. Currently, in the OS/2 environment, the only
file system which supports extended attributes is the HPFS file system. For a
complete description of extended attributes, the user is referred to Chapter 5
of the Programming Guide, Volume 1 of the OS/2 2.0 Technical Library. This
package subsumes the extended attribute functions included with the distributed
REXX function package REXXUTIL. This was done because the functions in the
REXXUTIL package do not support operations on extended attributes associated
with subdirectories (the HPFS file system does not support extended attributes
associated with the root directory of a partition).


ΓòÉΓòÉΓòÉ 2. General considerations ΓòÉΓòÉΓòÉ

The individual functions listed below all have some general requirements for
use. These are as follows:

 1. All functions must be loaded before they can be invoked.

    All the functions listed here must be loaded before they can be used.
    Loading is performed by invoking the RxFuncAdd function. Thus, to load one
    of the functions in this package would require the following call in the
    REXX program:

        Call RxFuncAdd 'FetchEA', 'RexxEA', 'FetchEA'
    Note that the third parameter, although redundant, is required.
    Additionally, each function that has been loaded should be deleted by
    invoking RxFuncDrop before the REXX procedure that used them exits.

 2. Pathnames must be fully specified.

    All the functions in this package require as one of their parameters a
    pathname specifying either a file name or a subdirectory name. This must be
    the fully qualified name including the drive letter where this is
    appropriate. Failure to fully specify the pathname will result in an error
    message from the invoked function.


ΓòÉΓòÉΓòÉ 3. Function descriptions. ΓòÉΓòÉΓòÉ

The functions provided in this package and their parameters and returns are as
follows:


ΓòÉΓòÉΓòÉ 3.1. FetchEA ΓòÉΓòÉΓòÉ

Call FetchEA pathname, 'names', 'strings'

or

result = FetchEA( pathname, 'names', 'strings')

This function will return a list of names for each extended attributes
associated with a file or subdirectory. It will also return an array of strings
representing the data associated with each extended attribute. The parameter
list for invocation of this function must consist of 3 parameters. These
parameters are as follows:

pathname
          The fully qualified name of the file or subdirectory whose extended
          attributes will be returned. The only limitation on the length of
          this string is that imposed by the file system.

namestem
          A string containing the name of a REXX stem variable which will
          contain the names of the extended attributes upon return. Thus, if
          the value of this parameter is 'names', upon successful return, the
          REXX variable names.0 will contain the count of the number of
          extended attributes associated with the file or subdirectory. Note
          that this value may be 0 if there are no extended attributes. If
          names.0 is nonzero, then names.i will contain the name of the i'th
          extended attribute. The order in which the names are returned is
          generally unpredictable.

stringstem
          A string containing the name of a REXX stem variable which will
          contain the values of the extended attributes upon return. Thus, if
          the value of this parameter is 'strings', then, upon successful
          return, the REXX variable strings.0 will contain the count of the
          number of extended attributes. Note that this information is
          redundant. If this count is nonzero then strings.i will contain the
          data associated with the i'th extended attribute.

Return values

Normally this function will return a zero length string either in the special
REXX variable RESULT or in the explicit result variable, depending on how it is
invoked. However if errors are encountered during execution of this function,
an error message is returned. In this case, the returned variables specified in
arguments 2 and 3 will be invalid. Thus a typical sequence for invoking this
function might appear as follows:


call FetchEA arg1, arg2, arg3
if length(RESULT) <> 0 then do;
   say 'Error encountered. Error message is' RESULT
   exit
   end;

The possible error messages and their explanations are as follows:

Mismatched function name at invocation of FetchEA
Should never occur. If it does, it is an internal error in the REXX processor.

Incorrect argument count to FetchEA, received n, expected 3.
In this message, n is a number other than 3. This corrective action required is
self-explanatory.

Argument n to FetchEA is NULL.
In this message, n may be 1 through 3. It indicates that the n'th argument to
this function is a zero length string.

Return code from DosQueryPathInfo is n.
Refer to the Control Program Programming Reference for the meaning of the
return code.

Return code from DosOpen is n.
Refer to the Control Program Programming Reference for the meaning of the
return code.

Return code from DosEnumAttribute is n.
Refer to the Control Program Programming Reference for the meaning of the
return code.

Return code from RexxVariablePool is n.
Refer to the REXX Reference for the meaning of the return code. If this message
occurs, it is probably indicative of an internal error in FetchEA.


ΓòÉΓòÉΓòÉ 3.2. EAType ΓòÉΓòÉΓòÉ

type = EAType(EA_Data_String)

This function returns the type of an extended attribute, given the data string
associated with the extended attribute. The possible types of an extended
attribute are described in Chapter 4 of the Programming Guide, Volume I. The
type is returned as a character string and is the return value returned by the
function. The possible returned types are as follows:

BINARY
ASCII
BITMAP
METAFILE
ICON
EA
MVMT
MVST
ASN1
UNKNOWN
USER_DEFINED

Return values

Normally, this function returns the type of the extended attribute data in its
return value. However, if an error is an encountered, an error message is
returned. Error messages are always prefaced by the string 'Error:' separated
from the error message text by a blank character. Thus a typical use of this
function might look like the following:

retval = EAType(string_value)
parse var retval x errormsg
if x = 'Error:' then do;
   say 'Error in EAType, error message is' errormsg
   exit
   end;

The possible error messages and their explanations are as follows:

Mismatched function name at invocation of EAType.
Should never occur. If it does, it is an internal error in the REXX processor.

Incorrect argument count to EAType, received %d, expected 1.
In this message, n is a number other than 1. This corrective action required is
self-explanatory.

Input argument is NULL.
This message indicates that the argument to this function is a zero length
string.


ΓòÉΓòÉΓòÉ 3.3. MVSTEA ΓòÉΓòÉΓòÉ

Call MVSTEA EA_value_string, codepage_var, numvalues_var, EAtype_var

or

result = MVSTEA(EA_value_string, codepage_var, numvalues_var, EAtype_var)

This function will process an extended attribute data value with a type of
MVST. An MVST data value consists of an array of individual data values, all of
the same type. Invoking this function will return the codepage of the data, a
count of the number of data items, and the type of each data item (in the
extended attribute sense). This function takes 4 arguments.

EA_value_string
          The data string of the MVST extended attribute.

codepage_var
          A string containing the name of a REXX variable which, upon return,
          will contain the codepage of the extended attribute data.

numvalues_var
          A string containing the name of a REXX variable which, upon return,
          will contain the number of data items associated with the MVST data
          value.

EAtype_var
          A string containing the name of a REXX variable which, upon return,
          will contain the type of the data items. This type will be expressed
          as a string with the same values returned by the EAType function.

Return values

Normally this function will return a zero length string either in the special
REXX variable RESULT or in the explicit result variable, depending on how it is
invoked. However if errors are encountered during execution of this function,
an error message is returned. In this case, the returned variables specified in
arguments 2, 3, and 4 will be invalid. Thus a typical sequence for invoking
this function might appear as follows:


call MVSTEA arg1, arg2, arg3, arg4
if length(RESULT) <> 0 then do;
   say 'Error encountered. Error message is' RESULT
   exit
   end;

The possible error messages and their explanations are as follows:

Mismatched function name at invocation of MVSTEA
Should never occur. If it does, it is an internal error in the REXX processor.

Incorrect argument count to MVSTEA, received n, expected 4.
In this message, n is a number other than 4. The corrective action required is
self-explanatory.

Argument n to MVSTEA is NULL.
In this message, n may be 1 through 4. It indicates that the n'th argument to
this function is a zero length string.

Return code from RexxVariablePool is n.
Refer to the REXX Reference for the meaning of the return code. If this message
occurs, it is probably indicative of an internal error in MVSTEA.


ΓòÉΓòÉΓòÉ 3.4. MVSTASC ΓòÉΓòÉΓòÉ

Call MVSTASC EAdata_string, string_var

or

result = MVSTASC( EAdata_string, string_var)

This function may be invoked to decompose an MVST extended attribute where the
data type of the individual items is ASCII. The argument list for invocation of
this function must consist of 2 parameters. These parameters are as follows:

EAdata_string
          A string containing the data for the MVST extended attribute.

string_var
          A string containing the name of a REXX stem variable which, upon
          return, will contain the individual ASCII strings. Specifically, the
          variable string_var.0 will contain the count of the number of ASCII
          strings returned. The variable string_var.i will contain the i'th
          ASCII string.

Return values

Normally this function will return a zero length string either in the special
REXX variable RESULT or in the explicit result variable, depending on how it is
invoked. However if errors are encountered during execution of this function,
an error message is returned. In this case, the returned variable specified in
argument 2 will be invalid. Thus a typical sequence for invoking this function
might appear as follows:


call MVSTASC arg1, arg2
if length(RESULT) <> 0 then do;
   say 'Error encountered. Error message is' RESULT
   exit
   end;

The possible error messages and their explanations are as follows:

Mismatched function name at invocation of MVSTASC
Should never occur. If it does, it is an internal error in the REXX processor.

Incorrect argument count to MVSTASC, received n, expected 2.
In this message, n is a number other than 2. The corrective action required is
self-explanatory.

Argument n to MVSTASC is NULL.
In this message, n may be 1 through 2. It indicates that the n'th argument to
this function is a zero length string.

Input data to MVSTASC does not have ASCII data in it.
The input data to MVSTASC is an MVST extended attribute but the data type is
not ASCII.

Return code from RexxVariablePool is n.
Refer to the REXX Reference for the meaning of the return code. If this message
occurs, it is probably indicative of an internal error in MVSTASC.


ΓòÉΓòÉΓòÉ 3.5. ASCIIEA ΓòÉΓòÉΓòÉ

string = ASCIIEA(EA_Data_String)

This function returns a string which is the data associated with an extended
attribute whose type is ASCII. It strips off all the headers and returns only
the actual ASCII data. The input parameter to this function is:

EA_Data_String
          A string containing the data for the ASCII extended attribute.

Return values

Normally, this function returns the ASCII data associated with the extended
attribute in its return value. However, if an error is an encountered, an error
message is returned. Error messages are always prefaced by the string 'Error:'
separated from the error message text by a blank character. Thus a typical use
of this function might look like the following:

retval = EAType(string_value)
parse var retval x errormsg
if x = 'Error:' then do;
   say 'Error in ASCIIEA, error message is' errormsg
   exit
   end;

The possible error messages and their explanations are as follows:

Mismatched function name at invocation of ASCIIEA.
Should never occur. If it does, it is an internal error in the REXX processor.

Incorrect argument count to ASCIIEA, received n, expected 1.
In this message, n is a number other than 1. This corrective action required is
self-explanatory.

Input argument is NULL.
This message indicates that the argument to this function is a zero length
string.

Input argument is not a valid ASCII Extended Attribute.
The input argument is not a valid ASCII Extended Attribute.


ΓòÉΓòÉΓòÉ 3.6. MVMTEA ΓòÉΓòÉΓòÉ

Call MVMTEA EA_value_string, codepage_var, EAtype_var, EAdata_var

or

result = MVMTEA(EA_value_string, codepage_var, EAtype_var, EAdata_var)

This function will process an extended attribute data value with a type of
MVMT. An MVMT data value consists of an array of individual data values. These
data items are of heterogeneous type. Invoking this function will return the
codepage of the data, the type of each data item (in the extended attribute
sense), and the actual string associated with each item. This function takes 4
arguments.

EA_value_string
          The data string of the MVMT extended attribute.

codepage_var
          A string containing the name of a REXX variable which, upon return,
          will contain the codepage of the extended attribute data.

EAtype_var
          A string containing the name of a REXX stem variable which, upon
          return, will contain the number of data items associated with the
          MVMT extended attribute and the type of each data item. Specifically
          upon return, the variable EAtype_var.0 will contain the number of
          data items associated with the MVMT extended attribute. The
          variable(s) EAtype_var.i will contain the data type of the i'th data
          item in the same format as returned by the EAType function.

EAdata_var
          A string containing the name of a REXX stem variable which, upon
          return, will contain the number of data items and the actual data
          strings for each item. Specifically, EAdata_var.0 will contain the
          number of data items associated with the MVMT extended attribute
          (redundantly). The variables(s) EAdata_var.i will contain the actual
          data strings for each data item, will all headers removed.

Return values

Normally this function will return a zero length string either in the special
REXX variable RESULT or in the explicit result variable, depending on how it is
invoked. However if errors are encountered during execution of this function,
an error message is returned. In this case, the returned variables specified in
arguments 2, 3, and 4 will be invalid. Thus a typical sequence for invoking
this function might appear as follows:


call MVMTEA arg1, arg2, arg3, arg4
if length(RESULT) <> 0 then do;
   say 'Error encountered. Error message is' RESULT
   exit
   end;

The possible error messages and their explanations are as follows:

Mismatched function name at invocation of MVMTEA
Should never occur. If it does, it is an internal error in the REXX processor.

Incorrect argument count to MVMTEA, received n, expected 4.
In this message, n is a number other than 4. The corrective action required is
self-explanatory.

Argument n to MVMTEA is NULL.
In this message, n may be 1 through 4. It indicates that the n'th argument to
this function is a zero length string.

Data value passed to MVMTEA is not an MVMT Extended Attribute
The input data string does not correspond to an MVMT extended attribute.


ΓòÉΓòÉΓòÉ 3.7. DeleteEA ΓòÉΓòÉΓòÉ

Call DeleteEA pathname, EAname

or

result = DeleteEA(pathname, EAname)

This function will delete a single extended attribute associated with a file or
subdirectory. The extended attribute named as an argument must exist.
Otherwise, this function will return an error message. The arguments to this
function are as follows:

pathname
          The fully qualified name of the file or subdirectory which will have
          an extended attribute deleted. The only limitation on the length of
          this string is that imposed by the file system.

EAname
          The name of the extended attribute to be deleted.

Return values

Normally this function will return a zero length string either in the special
REXX variable RESULT or in the explicit result variable, depending on how it is
invoked. However if errors are encountered during execution of this function,
an error message is returned. Thus a typical sequence for invoking this
function might appear as follows:


call DeleteEA arg1, arg2
if length(RESULT) <> 0 then do;
   say 'Error encountered. Error message is' RESULT
   exit
   end;

The possible error messages and their explanations are as follows:

Mismatched function name at invocation of DeleteEA
Should never occur. If it does, it is an internal error in the REXX processor.

Incorrect argument count to DeleteEA, received n, expected 2.
In this message, n is a number other than 2. The corrective action required is
self-explanatory.

Argument n to DeleteEA is NULL.
In this message, n may be 1 through 2. It indicates that the n'th argument to
this function is a zero length string.

Return code from DosSetPathInfo is n.
Refer to the documentation for the control program function DosSetPathInfo for
the meaning of n. Some of the causes for this message include an invalid
pathname and a nonexistent extended attribute name.


ΓòÉΓòÉΓòÉ 3.8. PutEA ΓòÉΓòÉΓòÉ

Call PutEA pathname, EAname, EAdata

or

result = PutEA(pathname, EAname, EAdata)

This function will either create or update a single extended attribute
associated with a file or subdirectory. The extended attribute named as the
second argument need not exist. If it does, the data for an existing extended
attribute will be updated. Otherwise, a new extended attribute will be created.
The arguments to this function are as follows:

pathname
          The fully qualified name of the file or subdirectory which will have
          an extended attribute updated or created. The only limitation on the
          length of this string is that imposed by the file system.

EAname
          The name of the extended attribute to be updated or created.

EAdata
          A string containing the data for the extended attribute, including
          all headers. Note that since this data is a character string, bytes
          contained in a word must be swapped before this function is invoked.
          This function simply passes through the data string to the
          appropriate control program function call. This data string must have
          nonzero length.

Return values

Normally this function will return a zero length string either in the special
REXX variable RESULT or in the explicit result variable, depending on how it is
invoked. However if errors are encountered during execution of this function,
an error message is returned. Thus a typical sequence for invoking this
function might appear as follows:


call PutEA arg1, arg2, arg3
if length(RESULT) <> 0 then do;
   say 'Error encountered. Error message is' RESULT
   exit
   end;

The possible error messages and their explanations are as follows:

Mismatched function name at invocation of PutEA
Should never occur. If it does, it is an internal error in the REXX processor.

Incorrect argument count to PutEA, received n, expected 3.
In this message, n is a number other than 3. The corrective action required is
self-explanatory.

Argument n to PutEA is NULL.
In this message, n may be 1 through 3. It indicates that the n'th argument to
this function is a zero length string.

Return code from DosSetPathInfo is n.
Refer to the documentation for the control program function DosSetPathInfo for
the meaning of n. One of the causes for this message is an invalid pathname.