OS/2 Professional

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 | 13.9 KB | 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.