home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Professional
/
OS2PRO194.ISO
/
os2
/
prgramer
/
rexx
/
rexxea
/
rexxea.inf
(
.txt
)
< prev
Wrap
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.